O programa de token SPL
No Solana, os ativos fungíveis (e muitos do tipo NFT) não são saldos armazenados nas carteiras dos usuários da mesma forma que um livro-razão bancário armazena uma única linha por cliente.
São contas de propriedade do programa SPL Token, que controla o fornecimento de moedas, quem pode movimentar fundos e como os valores são armazenados.
SPL Token Basics mostra receitas create-mint e ATA; Contas de Token Associadas (ATAs), Authorities, Decimais e Quantidades, Minting & Burning e SPL Token in Programs ampliam cada um em uma camada.
Esta página é a camada abaixo: o modelo único que faz com que essas páginas pareçam um sistema, em vez de uma pilha de sinalizadores CLI.
Resumo
- Ideia principal: O clássico programa SPL Token (
TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA) possui contas mint (definição e fornecimento de token) e contas de token (saldos para uma casa da moeda sob uma autoridade), e apenas as modifica através de suas instruções. - Por que é importante: Autoridade errada, quantidade bruta errada, ATA ausente ou CPI sem o ID do programa de token são os bugs usuais de "tokens desaparecidos/fornecimento errado/falha na transferência" - não o próprio consenso de Solana.
- Conceitos principais: mint, conta de token, ATA, autoridade mint, autoridade de congelamento, decimais, quantidade bruta, mint / queimar / transferir, delegar, CPI do programa de token, Token-2022 como padrão irmão.
- Quando usar: Lançar ou integrar tokens fungíveis, construir carteiras e dapps que mantenham saldos, escrever cofres/escrows de anchor ou ensinar como Solana representa ativos antes das extensões do Token-2022.
- Limitações/Compensações: O Classic SPL Token tem um layout de conta fixo e sem extensões (taxas de transferência, juros, transferências confidenciais ao vivo no Token-2022). ATAs são o padrão UX, mas qualquer conta de token válida ainda pode manter saldos se você permitir.
- Tópicos relacionados: Programa de token associado, tamanho da conta isenta de aluguel,
transfer_checked, autoridades de mint/cofre de PDA, ID do programa Token-2022.
Fundações
SPL Token separa o que é um token de quem detém quanto.
Uma conta mint é a definição de tipo para um token: decimais, fornecimento total, autoridade mint (que pode aumentar o fornecimento) e autoridade de congelamento (que pode congelar contas de token para esse mint).
A casa da moeda não armazena saldos por carteira. Criar uma casa da moeda não dá tokens a ninguém até que uma instrução mint credite uma conta de token.
Uma conta de token mantém um saldo de exatamente uma casa da moeda sob uma autoridade (geralmente uma carteira ou um PDA).
Seu estado inclui o mint pubkey, o proprietário/autoridade, o valor bruto, o delegado opcional e o valor delegado e o estado de congelamento.
As carteiras “têm USDC” apenas no sentido de que controlam uma conta de token cuja cunhagem é a cunhagem de USDC e cujo valor é diferente de zero.
Essa divisão é a razão pela qual você nunca envia tokens SPL para o "endereço mint" como se fosse uma conta bancária, e por que listar apenas uma chave pública da carteira fica incompleta sem o contexto mint.
Contas Token Associadas (ATAs) são a convenção social e de ferramentas que elimina o caos de endereços.
Para um determinado triplo (carteira, mint, programa de token), o programa Associated Token deriva um PDA determinístico como a conta de token preferencial.
Carteiras, exploradores e indexadores assumem esse endereço quando um usuário diz “envie-me este token”.
Você ainda pode criar contas de token não ATA; o UX de produção quase sempre cria ou usa o ATA.
Autoridades são a superfície de confiança de uma casa da moeda e de cada conta de token.
- Autoridade da Casa da Moeda (na casa da moeda): pode cunhar mais suprimentos em contas de token até ser definido como
None. - Autoridade de congelamento (na casa da moeda): pode congelar ou descongelar contas de token dessa casa da moeda até ser definido como
None. - Autoridade da conta de token (proprietário): pode transferir, queimar (daquela conta), aprovar um delegado ou fechar a conta quando vazia (sujeito ao estado de congelamento e às regras do programa).
- Delegado (opcional em uma conta token): pode transferir ou queimar até um valor bruto aprovado sem ser o proprietário.
A revogação das autoridades de cunhagem e congelamento é um sinal de lançamento comum: fornecimento fixo ou controlado pela comunidade e sem poder de congelamento.
Decimais e valores fecham a base.O armazenamento na cadeia é sempre um número inteiro bruto (u64). Os decimais na casa da moeda definem apenas a escala humana: com 6 decimais, UI 1.5 é 1_500_000 bruto.
Clientes, CLIs e programas que misturam flutuações de UI com campos brutos sem conversão são uma das principais fontes de bugs 1000x e 1e6x.
ID do programa SPL Token clássico:
TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
As contas de token para token SPL clássico têm 165 bytes e devem permanecer isentas de aluguel; Os ATAs ainda são apenas contas simbólicas em um endereço derivado.
Mecânica e interações
O ciclo de vida produtivo do token é ordenado: definir a casa da moeda, criar uma conta titular, alterar o fornecimento ou movimentar saldos e, em seguida, (opcionalmente) bloquear autoridades.
mint account token account / ATA ops
------------ ------------------- ---
create mint ──► set decimals + ──► create ATA (or ──► mint_to
(Token prog) authorities token account) transfer
│ │ │ burn
│ │ │ approve
▼ ▼ ▼ freeze
supply on mint authority keys balance, delegate set_authority
(raw total) mint / freeze freeze state close account
1. Crie e configure o mint
Uma casa da moeda é criada como uma conta de propriedade do programa Token, inicializada com decimais e autoridades (e geralmente financiada com isenção de aluguel por um pagador de taxas).
spl-token create-token --decimals 6 (pilha Solana CLI 3.0.10) é o caminho do operador; @solana/kit 7.0.0 e @solana-program/token criam as mesmas instruções de inicialização para aplicativos.
Até você cunhar, a oferta é zero; os decimais nunca mudam após a inicialização no token SPL clássico.
2. Crie uma conta token ou ATA para cada titular
Os saldos precisam de uma conta de destino para essa casa da moeda.
A criação de ATA é normalmente uma instrução (ou uma criação idempotente) que deriva o endereço, cria a conta se estiver faltando e a inicializa para a casa da moeda e o proprietário.
Os clientes que transferem sem garantir a existência do ATA do destinatário falham com erros de conta ausente; os fluxos de produção usam criar-idempotente ou verificar e criar.
3. Cubra, transfira, queime
- Mint (mint_to): requer assinatura de autoridade mint (ou sinal de PDA via CPI). Aumenta o suprimento de moedas e credita uma conta simbólica para essa casa da moeda.
- Transferência: requer autoridade da conta token (ou um delegado dentro do limite). Move o valor bruto entre duas contas de token da mesma casa da moeda. Não altera a oferta total.
- Burn: requer autoridade (ou delegado) da conta de token. Diminui o saldo da conta e o supply do mint.
Prefira instruções de estilo transfer_checked / mint_to_checked quando disponíveis, para que o mint e os decimais sejam explícitos na instrução, detectando erros de incompatibilidade de mint antecipadamente.
Apenas valores brutos: se a casa da moeda tiver 9 casas decimais e você quiser 5 tokens inteiros, o valor da instrução é 5_000_000_000, não 5.
4. Autoridades ao longo do ciclo de vida
Antecipado: a autoridade mint é uma chave de implantação ou multisig; autoridade de congelamento é opcional.
Após a distribuição: muitos projetos desativam a autoridade da moeda (sem mais inflação) e congelam a autoridade (sem risco de congelamento), ou os movem para um DAO/PDA com política documentada.
A propriedade da conta de token pode ser uma carteira de usuário ou um PDA para que um programa possa assinar transferências e queimar com sementes (cofres, escrows, staking).
5. Clientes e programas compartilham uma superfície de instrução
Fora da cadeia: CLI, clientes de kit e carteiras incorporam instruções do programa Token em transações (pagador de taxas, blockhash recente, assinaturas) como qualquer outro trabalho de Solana.
On-chain: seu programa nunca “escreve saldos de tokens” em seu próprio layout de conta para ativos SPL; ele CPIs no programa Token com as contas, valores e privilégios de assinante corretos.
Anchor 0.32.1 Os tipos anchor-spl (Mint, TokenAccount, Token, Transfer / TransferChecked, MintTo, Burn) validam a propriedade e os campos e, em seguida, emitem esses CPIs.
Um caminho mínimo de fumaça do operador (não uma receita completa do produto):
spl-token create-token --decimals 6
spl-token create-account <MINT>
spl-token mint <MINT> 1000000
spl-token display <MINT>
ânica a ser mantida: **mint define tipo e fornecimento; Os ATAs mantêm saldos; as autoridades controlam mutações; os valores são brutos.
**
Considerações e aplicações avançadas
| Preocupação | Abordagem clássica do token SPL | Por que é importante | Página mais profunda |
|---|---|---|---|
| Endereço do destinatário UX | Prefira ATAs por carteira+mint | Carteiras e indexadores concordam em um endereço | ATAs |
| Política de abastecimento | Autoridade da Casa da Moeda então revoga ou DAO | Confiança e economia de tokens | Authorities, Minting & Burning |
| UI vs matemática em cadeia | Sempre converta com decimais | Evita bugs catastróficos de unidades | Decimais e Quantidades |
| Cofres do programa | Autoridade PDA no vault ATA; transferência via CPI | Garantia sem custódia de carteiras quentes | Token SPL em programas |
| Instruções verificadas | Passe mint + decimais na transferência/mint | Rejeita contas erradas do Mint | Em programas e construtores de clientes |
| Extensões (taxas, ganchos) | Use Token-2022, não o Token clássico | Diferentes IDs de programas e layouts de contas | Seção Token-2022 (irmão) |
Autoridades de PDA são a forma como os programas DeFi custodiam ativos com segurança: a autoridade do vault ATA é um PDA que seu programa pode assinar com invoke_signed, não uma chave humana em um servidor.
Valide mint, derivação ATA e valor na mesma instrução que movimenta fundos.
create_idempotent Os caminhos ATA reduzem falhas de corrida quando dois txs tentam criar o mesmo ATA.
Delegados permitem subsídios de gastos limitados (aprovações) sem transferir propriedade; limpe ou substitua com cuidado para que as sobras não surpreendam os usuários.
Wrapped SOL é um token SPL clássico usado como ponte: o SOL nativo é agrupado em uma conta de token para que os programas possam tratar o SOL como qualquer outro mint em caminhos CPI. Os fluxos mint e wrap/unwrap são ferramentas especiais baseadas no mesmo modelo de conta de token.
Token-2022 é um programa separado com extensões de conta mint/token. Não presuma que as contas Tokenkeg e as contas Token-2022 sejam intercambiáveis; ID do programa, ATAs (programa de token em sementes) e conjuntos de instruções devem corresponder.
Os clientes no @solana/kit 7.0.0 devem usar construtores de instruções específicos do programa e auxiliares PDA em vez de layouts de bytes rolados manualmente.
Os programas em Anchor 0.32.1 / Rust 1.91.1 devem fixar anchor-spl na mesma linha de lançamento e preferir macros de restrição (token::mint, associated_token::...) para que contas inválidas falhem antes do CPI.
Equívocos comuns
- "O saldo da minha carteira está armazenado na minha conta do sistema." SOL lamports ativos na conta do sistema; Os saldos SPL residem em contas de token de propriedade do Token codificadas pela mint.
- "Envie tokens para o endereço da casa da moeda." A casa da moeda é o livro-razão de tipo e fornecimento, não uma caixa de entrada de saldo do usuário. Envie para a conta de token do destinatário (geralmente seu ATA).
- "Os decimais alteram quantos bytes o valor usa." O valor é sempre
u64unidades brutas; decimais apenas escalam exibição e conversão. - "Criar uma casa da moeda cunha o suprimento." A inicialização define metadados; a oferta aumenta apenas por meio de instruções da casa da moeda (ou permanece zero).
- "Qualquer conta de token para essa carteira é adequada para UX." Contas não ATA funcionam na cadeia, mas quebram as suposições da carteira e do explorador; prefira ATAs.
- "Meu programa pode atribuir saldos de tokens gravando dados de contas." Somente o programa Token pode alterar dados de contas de tokens; você CPI com autoridade adequada.
- "transfer e transfer_checked têm o mesmo perfil de risco." As variantes verificadas exigem o mint e os decimais, reduzindo erros de confusão do mint.
- "Classic SPL Token e Token-2022 são substitutos imediatos." Diferentes IDs de programa, ATAs e capacidades; integrar deliberadamente.
Perguntas frequentes
O que é o programa SPL Token em uma frase?
O programa on-chain que possui contas mint e token e impõe cunhagem, queima, transferências, congelamentos e autoridades para tokens Solana clássicos.
Qual é a diferença entre uma conta mint e uma conta token?
Um mint define o tipo de token, decimais, fornecimento e autoridades mint/freeze; uma conta token mantém um saldo bruto de uma casa da moeda sob um proprietário/autoridade.
O que é um ATA?
Uma conta de token associada é a conta de token PDA canônica para uma carteira e um mint (e um programa de token), derivada para que todos concordem onde reside o saldo do usuário.Quem pode cunhar mais tokens?
Somente a autoridade atual da casa da moeda (um par de chaves, multisig ou PDA que assina a instrução da casa da moeda) e somente enquanto essa autoridade ainda estiver definida na casa da moeda.
Quem pode congelar uma conta token?
A autoridade de congelamento da casa da moeda, se houver; se a autoridade de congelamento estiver desativada, as contas desse mint não poderão ser congeladas por meio do programa Token.
Por que CLIs e exploradores mostram grandes quantidades de números inteiros?
Eles geralmente mostram unidades brutas. Divida por 10^decimals para valores de IU ou use ferramentas que formatem com os decimais da casa da moeda.
Uma transferência altera a oferta total?
A transferência movimenta o valor bruto entre contas simbólicas da mesma casa da moeda. Mint aumenta oferta; queimar diminui isso.
Duas casas da moeda diferentes podem compartilhar uma conta de token?
Não. Cada conta de token é inicializada para exatamente uma casa da moeda. Uma carteira usa uma conta de token separada (geralmente um ATA separado) por moeda.
Como os programas on-chain movem tokens SPL?
Por CPI no programa Token com as contas e autoridade corretas (assinatura do usuário ou PDA invoke_signed), normalmente por meio de auxiliares anchor-spl no Anchor 0.32.1.
Quando devo revogar a autoridade da casa da moeda?
Quando você deseja uma oferta máxima fixa e nenhuma inflação adicional sob essa autoridade - uma etapa comum pós-distribuição ou de endurecimento do lançamento. Consulte Authorities.
Qual é o tamanho de uma conta de token SPL clássica?
165 bytes de dados, alocados com isenção de aluguel para que a conta não seja coletada como lixo; Os ATAs usam o mesmo layout de conta de token em um endereço derivado.
Como o @solana/kit 7.0.0 se ajusta a esse modelo?
Ele constrói e envia as mesmas instruções de Token e Token Associado contra RPC; o modelo de conta não muda, apenas a ergonomia do cliente.
Onde cabe o SOL empacotado?
Wrapped SOL usa um SPL mint e contas de token para que o SOL possa participar de CPIs de token; envolver e desembrulhar lamports nativos da ponte e saldos de tokens.
Os novos ativos devem usar o token SPL clássico ou o Token-2022?
Use o token SPL clássico quando precisar de compatibilidade máxima e sem extensões; escolha Token-2022 quando precisar de recursos de extensão e puder exigir seu ID de programa e derivação ATA em qualquer lugar.
O que devo aprender depois desta página?
Trabalhe com SPL Token Basics e, em seguida, ATAs, mint/burn, autoridades, decimais e padrões de CPI na cadeia na lista relacionada abaixo.
Relacionado
- SPL Token Basics - crie mints, ATAs e primeiros saldos
- Contas de Token Associadas (ATAs) - derivação, criação e UX idempotente
- Authorities - autoridade cunhada, autoridade congelada, revogação de padrões
- Decimais e Quantidades - matemática bruta vs UI sem erros de decimais
- Minting & Burning - a oferta aumenta e queima
- Token SPL em programas - CPI anchor, cofres e restrições
Versões Stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.