Hemos desplegado e interactuado con SPL tokens, pero ninguno de ellos tenía un nombre, símbolo o cualquier metadata adjunta. En su lugar, identificábamos cada token por la dirección de su cuenta mint (mint account). Por el contrario, los tokens ERC20 incluyen funciones para leer el nombre y el símbolo del token (pero vale la pena señalar que estas son solo comodidades legibles por humanos, no hay nada que impida que diferentes tokens tengan el mismo nombre o símbolo). ERC721 y ERC1155 también incluyen una función tokenURI que devuelve un URI que apunta a metadata fuera de la cadena (off-chain).
Pero como hemos visto hasta ahora, la cuenta mint de SPL no tiene un campo de nombre, símbolo o URI.
Hay dos soluciones principales para esto en Solana:
- El Metaplex Token Metadata Standard
- El SPL Token-2022
El Metaplex Token Metadata Standard: Este es el enfoque más utilizado para agregar metadata a los tokens en Solana. Cuando ves NFTs con imágenes o tokens con nombres y símbolos (como la famosa memecoin “dog wif hat”), es probable que estén usando este estándar. Funciona a través de una cuenta de metadata separada que está vinculada a tu token. Esto es lo opuesto a cómo funciona ERC-721: en ERC-721, el contrato del token apunta a la metadata, pero en Metaplex, la cuenta de metadata apunta a la cuenta mint del token.
Esta imagen muestra la relación entre un SPL Token Mint, una cuenta de metadata y un JSON off-chain para metadata adicional.
El SPL Token-2022: Este es un programa separado del programa SPL Token original que incluye soporte integrado para la metadata de tokens y otras funciones avanzadas. Aunque es más moderno, en el momento de escribir este artículo aún no está tan ampliamente adoptado como el estándar de Metaplex.
Hoy nos centraremos en la solución de Metaplex y cubriremos Token-2022 en un artículo separado.
Dividiremos nuestra cobertura de la solución de Metaplex en dos partes: En este artículo, introduciremos Metaplex y discutiremos cómo maneja la metadata para los SPL tokens. En el siguiente, implementaremos la metadata de Metaplex para un SPL token utilizando Anchor.
¿Qué es Metaplex y cómo proporciona metadata a los tokens?
Metaplex es un conjunto de estándares abiertos y herramientas construidas en Solana. Estos estándares son mantenidos por la Metaplex Foundation y se han convertido en la forma principal de crear y gestionar activos digitales en Solana.
En términos prácticos:
- Cuando ves un NFT o token con una imagen en tu billetera Phantom, es probable que el enlace de esa imagen provenga de la metadata de Metaplex.
- Cuando un token tiene un nombre y un símbolo en tu billetera en lugar de solo una dirección, lo más probable es que esté usando la metadata de Metaplex.
- Las colecciones populares de NFT en Solana (como DeGods u Okay Bears) usan los estándares de Metaplex.
Así es como se ve: https://explorer.solana.com/address/EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm/metadata
Metaplex proporciona varias herramientas, pero nuestro enfoque por ahora es el Token Metadata Program, que te permite adjuntar metadata a cualquier SPL token.
Metaplex Token Metadata Program
El Metaplex Token Metadata Program, con la dirección metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s, se usa para agregar metadata adicional como nombre, símbolo, imagen y descripción a los SPL tokens. Crea y gestiona las cuentas de metadata (metadata accounts), que almacenan metadata estructurada vinculada a un mint de SPL específico.
Al igual que el SPL Token Program es propietario de todas las cuentas mint y ATAs, el Metaplex Token Metadata Program es propietario de todas las cuentas de metadata bajo él. Es un programa ejecutable y actualizable.
A un alto nivel, el programa nos permite:
- Crear una cuenta de metadata para un SPL token mint para almacenar datos estructurados como el nombre, el símbolo y el URI en esta cuenta.
- Actualizar estos datos con instrucciones específicas.
Profundizaremos en los detalles sobre estas instrucciones en la sección “Instrucciones del Metaplex Token Metadata Program” más abajo.
Ahora veamos cómo se estructuran y crean estas cuentas de metadata.
Cuenta de Metadata de Metaplex
Una cuenta de metadata de Metaplex es una Program Derived Address (PDA) creada a través del Metaplex Token Metadata Program para adjuntar datos adicionales a un SPL token. La PDA se deriva usando tres semillas (seeds): la cadena "metadata", el token_metadata_program_id, y la mint_account_address.
Solo varía la dirección del mint; la cadena "metadata" y el ID del programa son fijos. Esto garantiza que solo se pueda derivar una cuenta de metadata para una cuenta mint dada.
Si bien la cuenta de metadata almacena información básica del token en la cadena (on-chain), también puede contener un URI que apunte a recursos fuera de la cadena (off-chain). Por ejemplo, la cuenta de metadata de un NFT podría almacenar el nombre y el símbolo del token en la cadena, mientras que el URI apunta a un archivo JSON que contiene la descripción completa, la imagen y atributos adicionales almacenados en IPFS, Arweave o un servidor web.
El diagrama a continuación muestra la relación entre el Metaplex Token Metadata Program y la cuenta de metadata.
La imagen a continuación muestra los campos relevantes para nuestra discusión sobre una cuenta de metadata, no te preocupes si no todos tienen sentido todavía, los explicaremos más adelante.
La cuenta de metadata almacena la metadata (nombre, símbolo, imagen, etc.) sobre una cuenta mint. Dado que la dirección de la cuenta de metadata se puede derivar directamente de la dirección de la cuenta mint, las billeteras pueden descubrir fácilmente la cuenta de metadata si existe.
A partir de la imagen de arriba, esto es lo que representa cada clave:
key: Este es un discriminador de cuenta (actualmente MetadataV1). Si bien el nombre de la variablekeyno es el más descriptivo (un nombre más preciso seríaversionodiscriminator), esto es lo que usa Metaplex en su código base. Indica la versión de la estructura de metadata que se está utilizando actualmente y permite que las billeteras y las herramientas analicen la cuenta correctamente. Cada mint solo puede tener una cuenta de metadata debido al mecanismo de derivación de la PDA que usa la dirección del mint como la única semilla que no tiene un valor fijo.update_authority: La dirección de la billetera con la autoridad para actualizar la cuenta de metadata. Esta autoridad de actualización (update authority) se establece durante la creación de la cuenta de metadata, y solo esta autoridad puede modificar la metadata posteriormente. La autoridad de actualización puede transferir estos derechos a otra dirección o renunciar permanentemente al control estableciendo la autoridad en null, haciendo que la metadata sea inmutable. Cada operación de actualización requiere una firma válida de la dirección de la autoridad actual, y esto evita cambios no autorizados en la metadata del token. Discutiremos las instrucciones específicas para actualizar y transferir la autoridad más adelante en este artículo.mint: Esto apunta a la cuenta mint del SPL token descrita por esta metadata. Esto vincula la metadata con el token real.data: Este campo representa los datos del activo del SPL token. Contiene lo siguiente:name: El nombre del token (por ejemplo, “Circle US Dollar Stablecoin”). Limitado a 32 bytes, por lo que los nombres deben ser concisos. Como se define aquí.symbol: Un identificador corto para el token (por ejemplo, “USDC”). Limitado a 10 bytes y típicamente en mayúsculas.uri: Un enlace a un archivo JSON off-chain que contiene la metadata extendida, similar a cómo funcionan los URIs de los NFT en ERC721 y ERC1155. Este JSON se adhiere a un formato estandarizado e incluye campos para descripción, imagen, URL de animación, atributos y más. El URI tiene un límite de tamaño de 200 bytes. Profundizaremos en este JSON con más detalle más adelante.seller_fee_basis_points: Esto representa la tarifa de regalías que se aplicará a las ventas secundarias del token, expresada en puntos básicos (basis points) (donde el 1% equivale a 100 puntos básicos). Los marketplaces usan esta información para determinar la cantidad que deben remitir a los creadores al vender el token. La información de regalías es una sugerencia para los marketplaces en lugar de una regla impuesta, y el rango permitido para estos valores es de 0 a 10,000 (es decir, del 0% al 100%).creators: Un vector de hasta 5 direcciones que sirve como creador(es) del token, con cada dirección asignada a un porcentaje de la tarifa del vendedor (regalías). El total de estos porcentajes debe ser igual a 100. El uso de este campocreatorses una recomendación para los marketplaces, no una regla estricta.- Además,
datapuede incluir un campo opcionalcollectionpara NFTs. Este campo contiene dos piezas de información: una clave pública y una bandera booleana. La clave pública es la dirección mint de otro NFT que sirve como identificador de la colección. A diferencia de Ethereum, donde las colecciones suelen basarse en contratos, Metaplex utiliza un NFT especial para representar una colección completa. Este “NFT de colección” utiliza la misma cuenta de metadata que los NFTs regulares, pero su cuenta de metadata incluye un campo adicionalcollection_detailsque lo identifica como una colección. La bandera booleana (la segunda pieza de información) es establecida por la autoridad de actualización de la colección para verificar que el NFT pertenece legítimamente a esa colección. Este sistema de verificación en la cadena permite a las billeteras y marketplaces agrupar y mostrar los NFTs por su colección.
primary_sale_happened: Esta es una bandera booleana que rastrea si se produjo la venta inicial. Una vez establecida en true, no se puede revertir. Esto afecta las distribuciones de regalías en algunos marketplaces, porque la mayoría de los marketplaces comienzan a aplicar regalías solo después de que ha ocurrido la venta primaria.is_mutable: Determina si la metadata se puede actualizar después de la creación. Si se establece en false, la metadata queda permanentemente congelada (lo que significa que no son posibles más actualizaciones, ni siquiera por parte de la autoridad de actualización).edition_nonce: Un campo opcional utilizado para Master Editions, una función avanzada que permite crear copias de edición limitada de NFTs. Esto no es esencial para entender cómo funciona la metadata. Si estás interesado en esta característica, puedes obtener más información en la documentación de Metaplex.token_standard: Un enum que identifica el tipo de token, puede ser cualquiera de los siguientes:Fungible(SPL tokens estándar),NonFungible(NFTs únicos sin ediciones),FungibleAsset(tokens fungibles con metadata, pueden ser artículos de juegos con un caso de uso similar al ERC1155)
Instrucciones del Metaplex Token Metadata Program
El Metaplex Token Metadata Program tiene varias instrucciones que podemos llamar desde un programa o un cliente. Con ellas, creamos y gestionamos la metadata para los SPL tokens.
Las instrucciones son:
CreateMetadataAccountV3: Esta instrucción crea una nueva cuenta de metadata para un SPL token mint. Adjunta metadata como el nombre, el símbolo, el URI y la información del creador al token. Esta es la forma principal de darle a tu token una identidad más allá de su simple dirección de mint.V3aquí solo significa que es la tercera versión de esta instrucción. Solo la autoridad del mint del token puede crear metadata para él, lo que evita que cualquiera adjunte metadata no autorizada a tokens que no controla.UpdateMetadataAccountV2: Esta instrucción actualiza la metadata de un token existente. Puede modificar campos como el nombre, el símbolo, el URI, los creadores, transferir la autoridad a una nueva dirección y otros atributos, siempre que la metadata esté marcada como mutable y la autoridad de actualización firme la transacción. Solo la autoridad de actualización designada puede modificar la metadata; esta autoridad se establece cuando la metadata se crea por primera vez.UpdatePrimarySaleHappenedViaToken: Esta instrucción marca que ha ocurrido la venta primaria de un NFT. Una vez establecida en true, no se puede revertir. Esto afecta a las distribuciones de regalías en algunos marketplaces, ya que la mayoría empiezan a aplicar regalías solo después de la venta primaria. Solo la autoridad de actualización puede invocar esta instrucción.SignMetadata: Esta instrucción permite a los creadores listados en la metadata verificar su identidad firmando la metadata. Cuando un creador firma, su estado de “verificado” se convierte en true, lo que ayuda a los compradores a confirmar la autenticidad del token.CreateMasterEditionV3: Esta instrucción crea una cuenta de edición maestra (master edition) para un NFT. Solo se puede llamar una vez por mint, y solo si el suministro es exactamente 1. Transforma un NFT regular en una edición maestra que puede producir copias de edición limitada. Como se mencionó anteriormente, solo la autoridad de actualización del mint puede invocar esta instrucción.MintNewEditionFromMasterEditionViaToken: Esta instrucción crea un nuevo NFT de edición limitada a partir de una edición maestra. La nueva edición tiene su propio mint y metadata, pero está vinculada a la edición maestra.SetAndVerifyCollection: Esta instrucción vincula un NFT a una colección y lo verifica en un solo paso. Requiere que la autoridad de actualización de la colección firme la transacción, confirmando que el NFT es una parte oficial de la colección.VerifySizedCollectionItem: Esta instrucción verifica que un NFT pertenece a una colección con tamaño especificado. Las colecciones con tamaño especificado rastrean el número exacto de artículos que contienen, lo que ayuda con la representación precisa en los marketplaces.VerifyCollection: Esta instrucción verifica que un NFT pertenece a una colección. Requiere que la autoridad de actualización de la colección firme, confirmando la pertenencia del NFT a la colección.UnverifyCollection: Esta instrucción elimina el estado de verificación de un NFT de una colección. Requiere que firme la autoridad de actualización de la colección o la autoridad de actualización del NFT.Utilize: Esta instrucción rastrea el uso de un NFT que tiene activada la función “usos”. Esto permite que los NFTs tengan un número limitado de usos antes de expirar o cambiar de estado.ApproveUseAuthority: Esta instrucción delega la autoridad para utilizar un NFT a otra dirección, permitiendo a otra persona usar el NFT un número específico de veces.RevokeUseAuthority: Esta instrucción revoca una autoridad de uso concedida previamente, impidiendo que el delegado siga utilizando el NFT.ApproveCollectionAuthority: Esta instrucción delega a otra dirección la autoridad para verificar artículos de la colección.RevokeCollectionAuthority: Esta instrucción revoca una autoridad de colección delegada previamente.BurnNft: Esta instrucción quema un NFT, destruyendo tanto el token como su metadata. Esto es irreversible y elimina el NFT de la circulación.
Instrucciones de Metaplex Token Metadata Menos Utilizadas
Las siguientes instrucciones se utilizan con menos frecuencia, pero siguen formando parte del Metaplex Token Metadata Program:
CreateMetadataAccount: Versión heredada deCreateMetadataAccountV3.CreateMetadataAccountV2: Versión heredada deCreateMetadataAccountV3.UpdateMetadataAccount: Versión heredada deUpdateMetadataAccountV2.CreateMasterEdition: Versión heredada deCreateMasterEditionV3.CreateMasterEditionV2: Versión heredada deCreateMasterEditionV3.VerifySizedCollectionItem: Verifica un artículo como parte de una colección de NFT.SetAndVerifySizedCollectionItem: Establece y verifica un artículo como parte de una colección de NFT en una sola instrucción.FreezeDelegatedAccount: Congela una cuenta delegada.ThawDelegatedAccount: Descongela una cuenta delegada previamente congelada.RemoveCreatorVerification: Elimina la verificación de un creador de un NFT.PuffMetadata: Extiende la cuenta de metadata a su tamaño máximo rellenando los campos más cortos con bytes nulos. Cuando los campos de metadata (como nombre, símbolo, URI) son más cortos que su longitud máxima permitida, esta instrucción llena el espacio restante con ceros. Los tamaños máximos son: nombre (32 bytes), símbolo (10 bytes) y URI (200 bytes).
Conclusión
Para resumir: el Metaplex Token Metadata Program da a los SPL tokens una identidad, como un nombre, un símbolo y una imagen, a través de una cuenta de metadata separada y vinculada al mint. Esta cuenta es un PDA y almacena campos estructurados, incluyendo un URI que apunta a un JSON off-chain. Hemos desglosado lo que significa cada campo y cómo afecta la manera en que las billeteras y los marketplaces manejan el token. Por último, repasamos las instrucciones que proporciona el programa y lo que hace cada una.
En el próximo tutorial, crearemos metadata para un SPL token.
Este artículo es parte de una serie de tutoriales sobre Solana.