Guardião de Integração Token-2022
Autor/inspetor vs consumidor. O material
token-2022do kit e os skills de extensões de tokens (solana-token-extensions,token-2022-extensions) são para o autor do token — escolhendo extensões, criando o mint e um inspetor somente leitura. Este skill é o lado oposto: como um programa consome com segurança um mint de terceiros que não controla. Um mint é entrada não confiável. Onde aqueles skills dizem "integradores devem usar o valor líquido", este skill aplica e testa — um vault guardião que prova a vulnerabilidade de insolvência de cotas e a bloqueia on-chain. Estritamente complementar; instale junto com eles.
Quando usar este skill
Use-o quando o usuário estiver do lado consumidor de um mint Token-2022:
- Adicionar suporte a Token-2022 a um AMM, vault, mercado de empréstimos, escrow, staking ou fluxo de pagamentos.
- Decidir se deve listar / colocar em pool / aceitar um token específico ("este mint é seguro para integrar?").
- Depurar matemática de cotas/LP/escrow que "não fecha" (quase sempre um bug de taxa de transferência).
- Revisar um programa Anchor/nativo que movimenta tokens SPL quanto à segurança com Token-2022.
- Escrever testes que provam que sua integração sobrevive a mints hostis.
Se o usuário quiser criar um token com extensões, esse é o lado do emissor — encaminhe para o skill core token-2022.
O modelo de ameaça em um parágrafo
Um mint Token-2022 pode carregar extensões que alteram o comportamento de transferência. Como integrador, você deve assumir que o autor do mint é adversário. As perigosas: uma taxa de transferência faz com que o valor creditado seja menor que o valor enviado (quebra matemática 1:1 de cotas); um hook de transferência executa código controlado pelo emissor em cada transferência (reentrância, DoS, injeção de conta); um delegado permanente pode mover/queimar tokens do seu vault a qualquer momento; estado de conta padrão = congelado torna suas contas de token recém-criadas inutilizáveis; transferências confidenciais ocultam o saldo real da sua contabilidade; pausável permite que o emissor congele seus saques. Negação por padrão.
Procedimento operacional
- Escaneie primeiro. Identifique cada extensão no mint e seu impacto como integrador.
→ scanning.md (CLI executável
t22-scan) e extension-risk-matrix.md (o que cada extensão significa). - Decida por perfil. AMM, vault, empréstimo e escrow toleram extensões diferentes.
Use os veredictos da matriz (
PERMITIR/TRATAR/REJEITAR). - Fortaleça o programa. Aplique os padrões para o que você escolher suportar:
- Taxa de transferência → transfer-fee-accounting.md
- Hook de transferência → transfer-hook-reentrancy.md
- Delegado permanente / congelamento → permanent-delegate-and-freeze.md
- Aplicar uma lista de permissões on-chain com negação por padrão → extension-allowlist-pattern.md
- Prove com testes. Escreva testes LiteSVM que carregam o programa Token-2022 real e afirmam que seus guardiões bloqueiam o ataque. → testing.md
- Cite fontes / aprofunde-se. → resources.md
Tabela de roteamento
| O usuário está lidando com… | Leia |
|---|---|
| "Este mint é seguro para integrar?" / escanear um token | scanning.md, extension-risk-matrix.md |
| Quantidades de cotas/LP/escrow erradas, "taxa comendo meus depósitos" | transfer-fee-accounting.md |
| Hooks de transferência, reentrância, ExtraAccountMetaList, CPI na transferência | transfer-hook-reentrancy.md |
| Delegado permanente, autoridade de congelamento, congelamento padrão, clawback | permanent-delegate-and-freeze.md |
| "Como rejeitar mints perigosos no meu programa?" | extension-allowlist-pattern.md |
| Escrevendo/executando testes para casos extremos de Token-2022 | testing.md |
| Quais extensões existem e quão arriscadas são | extension-risk-matrix.md |
| Fontes, auditorias, políticas de DEX, leitura adicional | resources.md |
O que vem neste skill
| Artefato | Caminho | O que é |
|---|---|---|
| CLI Scanner | tools/t22-scan/ | t22-scan <mint> --profile=vault → veredicto de risco por extensão + código de saída para CI. Verificado contra mints reais na mainnet. |
| Programa Guardião | examples/guard/ | Um vault real Anchor 1.0: lista de permissões de extensão on-chain + depósito seguro com medição delta + saque ciente de reentrância. |
| Testes de ataque | examples/guard/tests/ | Testes LiteSVM carregando o programa real spl_token_2022, provando a vulnerabilidade e que o guardião a bloqueia. |
Comandos e agente
| Gatilho | O que faz |
|---|---|
/scan-mint | Escaneia um endereço de mint e relata o risco de integração para um perfil escolhido. |
/audit-t22-integration | Audita o código fonte de um programa quanto a bugs de integração Token-2022. |
Agente: token2022-integration-auditor | Cria um revisor focado que escaneia mints configurados e examina o programa em busca de transfer vs transfer_checked, matemática que confia no valor e verificações de extensão ausentes. |
Regras inegociáveis (aplicar em toda integração)
- Negação por padrão. Rejeite qualquer extensão que você não trate explicitamente. TLV desconhecido = rejeitar.
- Nunca confie no argumento
amountpara creditar valor. Meça o delta recebido (reload()+ diferença de saldo) ou leia a configuração de taxa; credite o valor recebido. - Sempre
transfer_checked(mint + decimais), nunca otransferobsoleto. - Fix o programa de token. Defina
token::token_program/associated_token::token_programpara que um atacante não possa misturar uma conta de token clássico em uma CPI Token-2022. - Revalide no uso, não apenas na listagem — o programa de hook de transferência e as taxas de um mint podem mudar.
- Prove. Envie um teste LiteSVM que falhe sem seu guardião e passe com ele.