mohit-1710/token2022-integration-guard

Token-2022 Integrations-Guard

Autor/Inspektor vs. Konsument. Das token-2022-Material des Kits und die breiten Token-Erweiterungs-Skills (solana-token-extensions, token-2022-extensions) sind für den Autor des Tokens gedacht – Auswahl von Erweiterungen, Erstellen des Mints und einen schreibgeschützten Mint-Inspektor. Diese Fähigkeit ist die gegenteilige Seite: Wie ein Programm sicher einen Drittanbieter-Mint konsumiert, den es nicht kontrolliert. Ein Mint ist eine nicht vertrauenswürdige Eingabe. Wo jene Skills sagen „Integratoren sollten den Nettobetrag verwenden“, erzwingt und testet diese Fähigkeit dies – ein Guard-Vault, der die Share-Insolvenz-Falle beweist und sie on-chain blockiert. Streng komplementär; daneben installieren.

Wann diese Fähigkeit verwenden

Verwende sie, wenn der Benutzer auf der konsumierenden Seite eines Token-2022-Mints steht:

• Hinzufügen von Token-2022-Unterstützung zu einem AMM, Vault, Kreditmarkt, Treuhandkonto, Staking- oder Zahlungsflow.
• Entscheiden, ob ein bestimmtes Token gelistet / gepoolt / akzeptiert werden soll („Ist dieser Mint sicher zu integrieren?“).
• Debuggen von Share-/LP-/Treuhand-Mathematik, die „nicht aufgeht“ (fast immer ein Transfergebühren-Fehler).
• Überprüfen eines Anchor-/nativem Programms auf Token-2022-Sicherheit bei der Bewegung von SPL-Token.
• Schreiben von Tests, die beweisen, dass deine Integration feindliche Mints übersteht.

Wenn der Benutzer einen Token mit Erweiterungen erstellen möchte, ist das die Emittentenseite – verweise auf den Kern-Token-2022-Skill.

Das Ein-Paragraph-Bedrohungsmodell

Ein Token-2022-Mint kann Erweiterungen tragen, die das Transferverhalten ändern. Als Integrator musst du annehmen, dass der Mint-Autor feindselig ist. Die gefährlichen: Eine Transfergebühr macht den gutgeschriebenen Betrag geringer als den gesendeten Betrag (bricht die 1:1-Share-Mathematik); ein Transfer-Hook führt bei jedem Transfer vom Emittenten kontrollierten Code aus (Wiedereintritt, DoS, Kontoinjektion); ein dauerhafter Delegat kann jederzeit Token aus deinem Vault verschieben/verbrennen; Standard-Kontostatus = frozen macht deine frischen Token-Konten unbrauchbar; vertrauliche Transfers verstecken den tatsächlichen Saldo vor deiner Buchhaltung; pausierbar lässt den Emittenten deine Abhebungen einfrieren. Standardmäßig verweigern.

Betriebsanleitung

1. Zuerst scannen. Identifiziere jede Erweiterung auf dem Mint und ihre Auswirkungen auf den Integrator. → scanning.md (ausführbare t22-scan-CLI) und extension-risk-matrix.md (was jede Erweiterung bedeutet).
2. Pro Profil entscheiden. AMM, Vault, Lending und Treuhandkonto tolerieren verschiedene Erweiterungen. Verwende die Matrix-Urteile (ALLOW / HANDLE / REJECT).
3. Das Programm härten. Wende die Muster für das an, was du unterstützen möchtest:
   • Transfergebühr → transfer-fee-accounting.md
   • Transfer-Hook → transfer-hook-reentrancy.md
   • Permanenter Delegat / Einfrieren → permanent-delegate-and-freeze.md
   • Standardmäßig verweigernde Allowlist on-chain erzwingen → extension-allowlist-pattern.md
4. Mit Tests beweisen. Schreibe LiteSVM-Tests, die das echte Token-2022-Programm laden und behaupten, dass deine Guards den Angriff blockieren. → testing.md
5. Quellen zitieren / tiefer eintauchen. → resources.md

Routingtabelle

Der Benutzer beschäftigt sich mit…	Lies
„Ist dieser Mint sicher zu integrieren?" / einen Token scannen	scanning.md, extension-risk-matrix.md
Shares/LP/Treuhandbeträge falsch, „Gebühr frisst meine Einzahlungen"	transfer-fee-accounting.md
Transfer-Hooks, Wiedereintritt, ExtraAccountMetaList, CPI bei Transfer	transfer-hook-reentrancy.md
Permanenter Delegat, Freeze-Autorität, standardmäßig eingefroren, Clawback	permanent-delegate-and-freeze.md
„Wie lehne ich gefährliche Mints in meinem Programm ab?"	extension-allowlist-pattern.md
Schreiben/Ausführen von Tests für Token-2022-Grenzfälle	testing.md
Welche Erweiterungen existieren und wie riskant jede ist	extension-risk-matrix.md
Quellen, Audits, DEX-Richtlinien, weiterführende Literatur	resources.md

Was in dieser Fähigkeit enthalten ist

Artefakt	Pfad	Was es ist
Scanner-CLI	tools/t22-scan/	t22-scan <mint> --profile=vault → Erweiterungs-spezifisches Risikourtel + Exit-Code für CI. Verifiziert gegen aktive Mainnet-Mints.
Guard-Programm	examples/guard/	Ein echter Anchor 1.0-Vault: on-chain Erweiterungs-Allowlist + delta-gemessene gebührensichere Einzahlung + wiedereintrittsbewusste Auszahlung.
Angriffstests	examples/guard/tests/	LiteSVM-Tests, die das echte spl_token_2022-Programm laden, die Sicherheitslücke beweisen und dass der Guard sie blockiert.

Befehle & Agent

Auslöser	Was es tut
/scan-mint	Scanne eine Mint-Adresse und melde das Integrator-Risiko für ein gewähltes Profil.
/audit-t22-integration	Überprüfe den Quellcode eines Programms auf Token-2022-Integrationsfehler.
Agent: token2022-integration-auditor	Erzeugt einen fokussierten Prüfer, der konfigurierte Mints scannt und das Programm auf transfer vs. transfer_checked, betragsvertrauende Mathematik und fehlende Erweiterungsprüfungen durchsucht.

Unverhandelbare Regeln (auf jede Integration anwenden)

• Standardmäßig verweigern. Jede Erweiterung ablehnen, die du nicht explizit behandelst. Unbekanntes TLV = ablehnen.
• Dem amount-Argument niemals vertrauen für die Gutschrift von Wert. Miss das empfangene Delta (reload() + Saldodifferenz) oder lies die Gebührenkonfiguration; schreibe den erhaltenen Betrag gut.
• Immer transfer_checked (Mint + Dezimalstellen) verwenden, niemals das veraltete transfer.
• Das Token-Programm festlegen. Setze token::token_program / associated_token::token_program, damit ein Angreifer kein klassisches Token-Konto in einen Token-2022-CPI mischen kann.
• Bei Nutzung erneut validieren, nicht nur beim Listing – das Transfer-Hook-Programm und die Gebühren eines Mints können sich ändern.
• Beweise es. Liefere einen LiteSVM-Test, der ohne deinen Guard fehlschlägt und mit ihm besteht.