El Programa SPL Token
En Solana, los activos fungibles (y muchos de estilo NFT) no son saldos almacenados dentro de las billeteras de los usuarios de la manera en que un libro mayor bancario almacena una sola fila por cliente.
Son cuentas propiedad del programa SPL Token, que aplica la oferta de acuñación (mint), quién puede mover fondos y cómo se almacenan las cantidades.
Conceptos básicos de SPL Token muestra recetas de creación de acuñaciones y ATAs; Cuentas de Token Asociadas (ATAs), Autoridades, Decimales y Cantidades, Acuñación y Quema, y SPL Token en Programas se centran en una capa cada vez.
Esta página es la capa subyacente: el modelo único que hace que esas páginas se sientan como un solo sistema en lugar de un montón de flags de CLI.
Resumen
- El programa clásico SPL Token (
TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA) posee cuentas de acuñación (mint) (definición de token y oferta) y cuentas de token (saldos para una acuñación bajo una autoridad), y solo las muta a través de sus instrucciones. - Por Qué Importa: Autoridad incorrecta, cantidad bruta incorrecta, ATA faltante o CPI sin el ID del programa Token son los errores habituales de "tokens desaparecidos / oferta incorrecta / transferencia fallida", no el consenso de Solana en sí.
- Conceptos Clave: mint (acuñación), token account (cuenta de token), ATA, mint authority (autoridad de acuñación), freeze authority (autoridad de congelación), decimals (decimales), raw amount (cantidad bruta), mint / burn / transfer (acuñar / quemar / transferir), delegate (delegado), Token program CPI (CPI del programa Token), Token-2022 como estándar hermano.
- Cuándo Usar: Lanzar o integrar tokens fungibles, construir billeteras y dapps que mantengan saldos, escribir bóvedas/escrows de Anchor, o enseñar cómo Solana representa activos antes de Token-2022.
- Limitaciones / Compensaciones: El SPL Token clásico tiene un diseño de cuenta fijo y sin extensiones (tasas de transferencia, intereses, transferencias confidenciales residen en Token-2022). Las ATAs son el estándar de UX, pero cualquier cuenta de token válida aún puede mantener saldos si lo permites.
- Temas Relacionados: Programa de Tokens Asociados, tamaño de cuenta exenta de alquiler,
transfer_checked, autoridades de acuñación/bóveda de PDA, ID del programa Token-2022.
Fundamentos
SPL Token separa qué es un token de quién tiene cuánto.
Una cuenta de acuñación (mint account) es la definición de tipo para un token: decimales, oferta total, autoridad de acuñación (quién puede aumentar la oferta) y autoridad de congelación (quién puede congelar cuentas de token para esa acuñación).
La acuñación no almacena saldos por billetera. Crear una acuñación no otorga tokens a nadie hasta que una instrucción de mint acredite una cuenta de token.
Una cuenta de token (token account) mantiene un saldo para exactamente una acuñación bajo una autoridad (generalmente una billetera o una PDA).
Su estado incluye la clave pública de la acuñación, el propietario/autoridad, la cantidad bruta, un delegado opcional y la cantidad delegada, y el estado de congelación.
Las billeteras "tienen USDC" solo en el sentido de que controlan una cuenta de token cuya acuñación es la acuñación de USDC y cuya cantidad no es cero.
Esa división es la razón por la que nunca envías tokens SPL a "la dirección de la acuñación" como si fuera una cuenta bancaria, y por qué listar solo una clave pública de billetera es incompleto sin el contexto de la acuñación.
Las Cuentas de Token Asociadas (ATAs) son la convención social y de herramientas que elimina el caos de direcciones.
Para un triple dado (billetera, acuñación, programa de token), el programa de Tokens Asociados deriva una PDA determinista como la cuenta de token preferida.
Las billeteras, exploradores e indexadores asumen esa dirección cuando un usuario dice "envíame este token".
Aún puedes crear cuentas de token no ATA; la UX de producción casi siempre crea o usa la ATA.
Las autoridades son la superficie de confianza de una acuñación y de cada cuenta de token.
- Autoridad de acuñación (en la acuñación): puede acuñar más oferta en cuentas de token hasta que se establezca en
None. - Autoridad de congelación (en la acuñación): puede congelar o descongelar cuentas de token para esa acuñación hasta que se establezca en
None. - Autoridad de cuenta de token (propietario): puede transferir, quemar (desde esa cuenta), aprobar un delegado o cerrar la cuenta cuando esté vacía (sujeto al estado de congelación y las reglas del programa).
- Delegado (opcional en una cuenta de token): puede transferir o quemar hasta una cantidad bruta aprobada sin ser el propietario.
Revocar las autoridades de acuñación y congelación es una señal común de lanzamiento: oferta fija o controlada por la comunidad y sin poder de congelación.
Decimales y cantidades cierran la base.
El almacenamiento en cadena es siempre un entero bruto (u64). Los decimales en la acuñación solo definen la escala humana: con 6 decimales, la UI 1.5 es bruta 1_500_000.
Los clientes, CLIs y programas que mezclan flotantes de UI con campos brutos sin convertir son una fuente principal de errores de 1000x y 1e6x.
ID del programa clásico SPL Token:
TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Las cuentas de token para el SPL Token clásico tienen 165 bytes y deben permanecer exentas de alquiler; las ATAs siguen siendo solo cuentas de token en una dirección derivada.
Mecánicas e Interacciones
El ciclo de vida productivo del token está ordenado: definir la acuñación, crear una cuenta de tenedor, cambiar la oferta o mover saldos, luego (opcionalmente) bloquear autoridades.
cuenta de acuñación cuenta de token / ATA ops
-------------------- --------------------- ---
crear acuñación ──► establecer decimales + ──► crear ATA (o ──► mint_to
(Prog. Token) autoridades cuenta de token) transfer
│ │ │ burn
│ │ │ approve
▼ ▼ ▼ freeze
oferta en acuñación claves de autoridad saldo, delegado set_authority
(total bruto) acuñación / congelación estado de congelación cerrar cuenta1. Crear y configurar la acuñación
Una acuñación se crea como una cuenta propiedad del programa Token, inicializada con decimales y autoridades (y generalmente financiada exenta de alquiler por un pagador de tarifas).
spl-token create-token --decimals 6 (pila de Solana CLI 3.0.10) es la ruta del operador; @solana/kit 7.0.0 y @solana-program/token construyen las mismas instrucciones de inicialización de acuñación para aplicaciones.
Hasta que acuñes, la oferta es cero; los decimales nunca cambian después de la inicialización en el SPL Token clásico.
2. Crear una cuenta de token o ATA para cada tenedor
Los saldos necesitan una cuenta de destino para esa acuñación.
La creación de ATA es típicamente una instrucción (o una creación idempotente) que deriva la dirección, crea la cuenta si falta y la inicializa para la acuñación y el propietario.
Los clientes que transfieren sin asegurarse de que la ATA del destinatario exista fallan con errores de cuenta faltante; los flujos de producción usan create-idempotent o check-then-create.
3. Acuñar, transferir, quemar
- Acuñar (mint_to): requiere la firma de la autoridad de acuñación (o PDA firma vía CPI). Aumenta la oferta de la acuñación y acredita una cuenta de token para esa acuñación.
- Transferir: requiere la autoridad de la cuenta de token (o un delegado dentro de la asignación). Mueve la cantidad bruta entre dos cuentas de token de la misma acuñación. No cambia la oferta total.
- Quemar: requiere la autoridad de la cuenta de token (o delegado). Disminuye el saldo de la cuenta y la oferta de la acuñación.
Prefiere las instrucciones de estilo transfer_checked / mint_to_checked cuando estén disponibles para que la acuñación y los decimales sean explícitos en la instrucción, capturando errores de desajuste de acuñación temprano.
Solo cantidades brutas: si la acuñación tiene 9 decimales y deseas 5 tokens enteros, la cantidad de la instrucción es 5_000_000_000, no 5.
4. Autoridades sobre el ciclo de vida
Temprano: la autoridad de acuñación es una clave de despliegue o multisig; la autoridad de congelación es opcional.
Después de la distribución: muchos proyectos deshabilitan la autoridad de acuñación (sin más inflación) y la autoridad de congelación (sin riesgo de congelación), o las mueven a una DAO/PDA con política documentada.
La propiedad de la cuenta de token puede ser una billetera de usuario o una PDA para que un programa pueda firmar transferencias y quemas con semillas (bóvedas, escrows, staking).
5. Clientes y programas comparten una superficie de instrucciones
Fuera de la cadena: CLI, clientes de kit y billeteras construyen instrucciones del Programa Token en transacciones (pagador de tarifas, hash de bloque reciente, firmas) como cualquier otro trabajo de Solana.
En la cadena: tu programa nunca "escribe saldos de token" en su propio diseño de cuenta para activos SPL; hace CPI al programa Token con las cuentas, cantidades y privilegios de firma correctos.
Anchor 0.32.1 los tipos anchor-spl (Mint, TokenAccount, Token, Transfer / TransferChecked, MintTo, Burn) validan la propiedad y los campos, y luego emiten esas CPIs.
Una ruta mínima de operación de humo (no una receta completa del producto):
spl-token create-token --decimals 6
spl-token create-account <MINT>
spl-token mint <MINT> 1000000
spl-token display <MINT>Mecánicas a mantener: la acuñación define el tipo y la oferta; las ATAs contienen saldos; las autoridades controlan las mutaciones; las cantidades son brutas.
Consideraciones Avanzadas y Aplicaciones
| Preocupación | Enfoque del SPL Token clásico | Por qué importa | Página más profunda |
|---|---|---|---|
| UX de dirección del destinatario | Preferir ATAs por billetera+acuñación | Las billeteras y los indexadores acuerdan una dirección | ATAs |
| Política de oferta | Autoridad de acuñación y luego revocar o DAO | Confianza y tokenomics | Autoridades, Acuñación y Quema |
| Matemáticas de UI vs cadena | Siempre convertir con decimales | Previene errores catastróficos de unidad | Decimales y Cantidades |
| Bóvedas de programas | Autoridad PDA en la ATA de la bóveda; CPI transfer | Escrow sin billeteras calientes de custodia | SPL Token en Programas |
| Instrucciones verificadas | Pasar acuñación + decimales en transferencias/acuñaciones | Rechaza cuentas de acuñación incorrectas | Constructores de clientes y en programas |
| Extensiones (tasas, hooks) | Usar Token-2022, no Token clásico | ID de programa y diseños de cuenta diferentes | Sección Token-2022 (hermana) |
Las autoridades PDA son cómo los programas DeFi custodian activos de forma segura: la ATA de la bóveda tiene como autoridad una PDA que tu programa puede firmar con invoke_signed, no una clave humana en un servidor.
Valida la acuñación, la derivación de la ATA y la cantidad en la misma instrucción que mueve los fondos.
Las rutas de ATA create_idempotent reducen los fallos de concurrencia cuando dos transacciones intentan crear la misma ATA.
Los delegados permiten una asignación de gasto limitada (aprobaciones) sin transferir la propiedad; limpia o sobrescribe con cuidado para que las asignaciones restantes no sorprendan a los usuarios.
SOL envuelto (Wrapped SOL) es el SPL Token clásico utilizado como puente: el SOL nativo se envuelve en una cuenta de token para que los programas puedan tratar el SOL como cualquier otra acuñación en rutas de CPI. Los flujos de acuñación y envoltura/desenvoltura son herramientas especializadas sobre el mismo modelo de cuenta de token.
Token-2022 es un programa separado con extensiones de acuñación/cuenta de token. No asumas que las cuentas de Tokenkeg y las cuentas de Token-2022 son intercambiables; el ID del programa, las ATAs (programa de token en las semillas) y los conjuntos de instrucciones deben coincidir.
Los clientes en @solana/kit 7.0.0 deben usar constructores de instrucciones específicos del programa y ayudantes de PDA en lugar de diseños de bytes hechos a mano.
Los programas en Anchor 0.32.1 / Rust 1.91.1 deben fijar anchor-spl a la misma línea de lanzamiento y preferir macros de restricción (token::mint, associated_token::...) para que las cuentas inválidas fallen antes de la CPI.
Conceptos Erróneos Comunes
- "El saldo de mi billetera se almacena en mi cuenta del sistema." Los lamports de SOL residen en la cuenta del sistema; los saldos SPL residen en cuentas de token propiedad de Token, indexadas por acuñación.
- "Envía tokens a la dirección de la acuñación." La acuñación es el tipo y el libro de registro de la oferta, no una bandeja de entrada de saldos de usuario. Envía a la cuenta de token del destinatario (generalmente su ATA).
- "Los decimales cambian cuántos bytes usa la cantidad." La cantidad son siempre unidades brutas
u64; los decimales solo escalan la visualización y la conversión. - "Crear una acuñación acuña la oferta." La inicialización establece metadatos; la oferta aumenta solo a través de instrucciones de acuñación (o permanece en cero).
- "Cualquier cuenta de token para esa billetera está bien para la UX." Las cuentas no ATA funcionan en la cadena pero rompen las suposiciones de billeteras y exploradores; prefiere las ATAs.
- "Mi programa puede asignar saldos de token escribiendo datos de cuenta." Solo el Programa Token puede mutar los datos de la cuenta de token; haces CPI con la autoridad adecuada.
- "transfer y transfer_checked tienen el mismo perfil de riesgo." Las variantes verificadas requieren la acuñación y los decimales, reduciendo los errores de confusión de acuñación.
- "SPL Token clásico y Token-2022 son reemplazos directos." Diferentes IDs de programa, ATAs y capacidades; integra deliberadamente.
Preguntas Frecuentes
¿Qué es el programa SPL Token en una oración?
El programa en cadena que posee cuentas de acuñación y de token y aplica la acuñación, quema, transferencias, congelaciones y autoridades para los tokens clásicos de Solana.
¿Cuál es la diferencia entre una acuñación (mint) y una cuenta de token?
Una acuñación define el tipo de token, decimales, oferta y autoridades de acuñación/congelación; una cuenta de token mantiene un saldo bruto para una acuñación bajo un propietario/autoridad.
¿Qué es una ATA?
Una Cuenta de Token Asociada es la cuenta de token PDA canónica para una billetera y acuñación (y programa de token), derivada para que todos acuerden dónde reside el saldo de ese usuario.
¿Quién puede acuñar más tokens?
Solo la autoridad de acuñación actual (un par de claves, multisig o PDA que firma la instrucción de acuñación), y solo mientras esa autoridad esté configurada en la acuñación.
¿Quién puede congelar una cuenta de token?
La autoridad de congelación de la acuñación, si está configurada; si la autoridad de congelación está deshabilitada, las cuentas para esa acuñación no pueden ser congeladas a través del Programa Token.
¿Por qué las CLIs y los exploradores muestran enormes cantidades enteras?
A menudo muestran unidades brutas. Divide por 10^decimales para las cantidades de UI, o usa herramientas que formatean con los decimales de la acuñación.
¿Una transferencia cambia la oferta total?
No. La transferencia mueve la cantidad bruta entre cuentas de token de la misma acuñación. La acuñación aumenta la oferta; la quema la disminuye.
¿Pueden dos acuñaciones diferentes compartir una cuenta de token?
No. Cada cuenta de token se inicializa para exactamente una acuñación. Una billetera usa una cuenta de token separada (generalmente una ATA separada) por acuñación.
¿Cómo mueven los programas en cadena los tokens SPL?
Mediante CPI al Programa Token con las cuentas y la autoridad correctas (firma de usuario o invoke_signed de PDA), típicamente a través de ayudantes de anchor-spl en Anchor 0.32.1.
¿Cuándo debo revocar la autoridad de acuñación?
Cuando deseas una oferta máxima fija y sin inflación adicional bajo esa autoridad, un paso común posterior a la distribución o de endurecimiento del lanzamiento. Ver Autoridades.
¿Qué tamaño tiene una cuenta de token SPL clásica?
165 bytes de datos, asignados exentos de alquiler para que la cuenta no sea recolectada como basura; las ATAs usan ese mismo diseño de cuenta de token en una dirección derivada.
¿Cómo encaja @solana/kit 7.0.0 en este modelo?
Construye y envía las mismas instrucciones de Token y Token Asociado contra RPC; el modelo de cuenta no cambia, solo la ergonomía del cliente.
¿Dónde encaja el SOL envuelto (Wrapped SOL)?
SOL envuelto usa una acuñación y cuentas de token SPL para que SOL pueda participar en CPIs de tokens; los flujos de envolver y desenvolver conectan lamports nativos y saldos de tokens.
¿Deberían los nuevos activos usar SPL Token clásico o Token-2022?
Usa SPL Token clásico cuando necesites máxima compatibilidad y sin extensiones; elige Token-2022 cuando necesites características de extensión y puedas requerir su ID de programa y derivación de ATA en todas partes.
¿Qué debo aprender a continuación después de esta página?
Repasa Conceptos básicos de SPL Token, luego ATAs, acuñación/quema, autoridades, decimales y patrones de CPI en cadena en la lista de Relacionados a continuación.
Relacionados
- Conceptos básicos de SPL Token - crear acuñaciones, ATAs y primeros saldos
- Cuentas de Token Asociadas (ATAs) - derivación, creación y UX idempotente
- Autoridades - autoridad de acuñación, autoridad de congelación, patrones de revocación
- Decimales y Cantidades - matemáticas brutas vs UI sin errores de desplazamiento de decimales
- Acuñación y Quema - aumentos de oferta y quemas
- SPL Token en Programas - CPI de Anchor, bóvedas y restricciones
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, y @solana/kit 7.0.0.