Guide d'intégration Token-2022
Auteur/inspecteur contre consommateur. Le kit contient du matériel
token-2022et des compétences générales sur les extensions de tokens (solana-token-extensions,token-2022-extensions) destinés à l'auteur du token — choix des extensions, création du mint et un inspecteur en lecture seule. Cette compétence est le côté opposé : comment un programme consomme en toute sécurité un mint tiers qu'il ne contrôle pas. Un mint est une entrée non fiable. Là où ces compétences disent « les intégrateurs doivent utiliser le montant net », cette compétence applique et teste ce principe — un coffre de garde qui démontre le piège de l'insolvabilité des parts et le bloque on-chain. Strictement complémentaire ; installez-les côte à côte.
Quand utiliser cette compétence
Utilisez-la lorsque l'utilisateur est du côté consommateur d'un mint Token-2022 :
- Ajout du support Token-2022 à un AMM, coffre, marché de prêt, séquestre, staking ou flux de paiement.
- Décision de lister / mettre en pool / accepter un token spécifique (« ce mint est-il sûr à intégrer ? »).
- Débogage de calculs de parts/LP/séquestre qui « ne tombent pas juste » (presque toujours un bug de frais de transfert).
- Revue d'un programme Anchor/natif qui déplace des tokens SPL pour la sécurité Token-2022.
- Écriture de tests prouvant que votre intégration survit à des mints hostiles.
Si l'utilisateur souhaite créer un token avec des extensions, c'est le côté émetteur — reportez-vous à la compétence Token-2022 principale.
Le modèle de menace en un paragraphe
Un mint Token-2022 peut porter des extensions qui modifient le comportement des transferts. En tant qu'intégrateur, vous devez supposer que l'auteur du mint est hostile. Les plus dangereuses : un frais de transfert réduit le montant crédité par rapport au montant envoyé (casse la mathématique 1:1 des parts) ; un hook de transfert exécute du code contrôlé par l'émetteur à chaque transfert (réentrance, déni de service, injection de comptes) ; un délégué permanent peut déplacer/brûler des tokens depuis votre coffre à tout moment ; état de compte par défaut = gelé rend vos nouveaux comptes token inutilisables ; les transferts confidentiels masquent le solde réel à votre comptabilité ; pausable permet à l'émetteur de geler vos retraits. Refus par défaut.
Procédure opérationnelle
- Scannez d'abord. Identifiez chaque extension sur le mint et son impact sur l'intégrateur.
→ scanning.md (CLI exécutable
t22-scan) et extension-risk-matrix.md (signification de chaque extension). - Décidez par profil. AMM, coffre, prêt et séquestre tolèrent différentes extensions. Utilisez les verdicts de la matrice (
ALLOW/HANDLE/REJECT). - Durcissez le programme. Appliquez les modèles pour ce que vous choisissez de supporter :
- Frais de transfert → transfer-fee-accounting.md
- Hook de transfert → transfer-hook-reentrancy.md
- Délégué permanent / gel → permanent-delegate-and-freeze.md
- Appliquez une liste blanche de refus par défaut on-chain → extension-allowlist-pattern.md
- Prouvez-le avec des tests. Écrivez des tests LiteSVM qui chargent le vrai programme Token-2022 et vérifient que vos garde-fous bloquent l'attaque. → testing.md
- Citez les sources / approfondissez. → resources.md
Table de routage
| L'utilisateur traite… | Lisez |
|---|---|
| « Ce mint est-il sûr à intégrer ? » / scanner un token | scanning.md, extension-risk-matrix.md |
| Montants de parts/LP/séquestre erronés, « les frais mangent mes dépôts » | transfer-fee-accounting.md |
| Hooks de transfert, réentrance, ExtraAccountMetaList, CPI sur transfert | transfer-hook-reentrancy.md |
| Délégué permanent, autorité de gel, gel par défaut, clawback | permanent-delegate-and-freeze.md |
| « Comment rejeter les mints dangereux dans mon programme ? » | extension-allowlist-pattern.md |
| Écrire/exécuter des tests pour les cas limites Token-2022 | testing.md |
| Quelles extensions existent et leur niveau de risque | extension-risk-matrix.md |
| Sources, audits, politiques DEX, lectures complémentaires | resources.md |
Ce qui est fourni dans cette compétence
| Artéfact | Chemin | Description |
|---|---|---|
| Scanner CLI | tools/t22-scan/ | t22-scan <mint> --profile=vault → verdict de risque par extension + code de sortie pour CI. Vérifié sur des mints mainnet réels. |
| Programme de garde | examples/guard/ | Un véritable coffre Anchor 1.0 : liste blanche d'extensions on-chain + dépôt sécurisé avec mesure de delta des frais + retrait protégé contre la réentrance. |
| Tests d'attaque | examples/guard/tests/ | Tests LiteSVM chargeant le vrai programme spl_token_2022, prouvant le piège et que le garde-fou le bloque. |
Commandes et agent
| Déclencheur | Action |
|---|---|
/scan-mint | Scanne une adresse de mint et rapporte le risque d'intégration pour un profil choisi. |
/audit-t22-integration | Audite le source d'un programme pour les bugs d'intégration Token-2022. |
Agent : token2022-integration-auditor | Crée un réviseur ciblé qui scanne les mints configurés et cherche dans le programme transfer vs transfer_checked, les mathématiques qui font confiance au montant, et les vérifications d'extension manquantes. |
Règles non négociables (appliquées à chaque intégration)
- Refus par défaut. Rejetez toute extension que vous ne gérez pas explicitement. TLV inconnu = rejet.
- Ne faites jamais confiance à l'argument
amountpour créditer une valeur. Mesurez le delta reçu (reload()+ différence de solde) ou lisez la configuration des frais ; créditez le montant reçu. - Utilisez toujours
transfer_checked(mint + décimales), jamais l'ancientransfer. - Épinglez le programme de tokens. Définissez
token::token_program/associated_token::token_programpour qu'un attaquant ne puisse pas mélanger un compte Token classique dans un CPI Token-2022. - Re-validez à l'utilisation, pas seulement au listing — le programme de hook de transfert et les frais d'un mint peuvent changer.
- Prouvez-le. Fournissez un test LiteSVM qui échoue sans votre garde-fou et passe avec.