mohit-1710/transfer-hook-scaffold

Token-2022 Transfer-Hook Scaffold

Transfer-Hooks sind die schwierigste Token-2022-Erweiterung korrekt umzusetzen: Das Programm muss einen Interface-Diskriminator bereitstellen, den Anchor nicht generiert, eine ExtraAccountMetaList mit bytegenauer Reihenfolge anlegen und Out-of-Band-Aufrufe abwehren. Kleine Fehler führen zu undurchschaubaren Laufzeitfehlern. Dieses Skill ist der sichere Standardpfad, untermauert von einem kompilierenden Programm und LiteSVM-Angriffstests.

Im Vergleich zu den Token-Extensions-Skills: solana-token-extensions / token-2022-extensions behandeln Hooks als eine Funktion (ein statisches Beispiel, plus in einem Fall eine Checkliste für Audits). Dies ist das dedizierte Hook-Werkzeug – das einzige, das auf Anfrage einen neuen sicheren Hook generiert (scaffold.sh) und seinen Auditor mit bestandenen Angriffstests untermauert. Ergänzend: Installieren Sie es zusammen mit den anderen, wenn Sie tatsächlich einen Hook bauen oder härten.

Wann dieses Skill verwenden

• Transfer-Hook bauen: Whitelist-/KYC-Gating, Lizenzgebühren-Durchsetzung, Gebühren-Routing, Kontingente/Buchhaltung pro Transfer, Soulbound-ähnliche Regeln.
• Hook debuggen: AccountNotFound, NotEnoughAccountKeys, IncorrectAccountAddress, oder „Transfer funktioniert ohne Hook, aber nicht damit.“
• Vorhandenes Hook-Programm auf Standard-Fallstricke prüfen/auditieren.
• Token-2022-Mint erstellen, das auf einen Hook zeigt, und den Client-Transfer verdrahten.

Integrator-Hinweis: Wenn Sie auf der konsumierenden Seite sind (einen Drittanbieter-Mint akzeptieren, der einen Hook hat), ist das ein anderes Problem – die meisten Integratoren sollten unbekannte Hook-Mints ablehnen. Siehe das begleitende Skill token2022-integration-guard.

Das mentale Modell (zuerst lesen)

1. Ein Hook-Programm implementiert Execute (das SPL-Transfer-Hook-Interface), das Token-2022 bei jeder Überweisung per CPI aufruft. Anchor dispatched über sha256("global:<ix>"), was NICHT mit dem Interface-Diskriminator übereinstimmt – daher fügt man einen fallback hinzu, der die Interface-Instruktion dekodiert und im Prozess dispatched (niemals eine Selbst-CPI). → program.md
2. Der Hook kann zusätzliche Konten benötigen. Sie deklarieren sie einmal in einer ExtraAccountMetaList-PDA (["extra-account-metas", mint]); Token-2022 liest sie und übergibt diese Konten an Execute, wobei Seed-basierte PDAs zur Transferzeit aufgelöst werden. Die Reihenfolge ist entscheidend. → extra-account-metas.md
3. Der Client muss den Transfer mit createTransferCheckedWithTransferHookInstruction aufbauen (ein einfaches transferChecked lässt die zusätzlichen Konten aus und reverts). → client-wiring.md
4. Ein Hook ist für Angreifer erreichbar: schützen Sie ihn. → security.md
5. Beweisen Sie es mit Tests, die durch den Hook überweisen. → testing.md

Routing-Tabelle

Der Benutzer…	Lesen
Schreibt das Hook-Programm (Execute, Fallback, Init-Meta-Liste)	program.md
Kämpft mit ExtraAccountMetaList / undurchschaubaren Kontofehlern	extra-account-metas.md
Verdrahtet den Mint + den Client-Transfer	client-wiring.md
Härtet / auditiert einen Hook auf Sicherheit	security.md
Schreibt Tests für einen Hook	testing.md
Erstellt ein neues Hook-Workspace	Führen Sie /transfer-hook:scaffold aus
Auditiert ein bestehendes Hook-Programm	Führen Sie /transfer-hook:audit aus
Quellen / weiterführende Lektüre	resources.md

Was in diesem Skill enthalten ist

Artefakt	Pfad	Beschreibung
Referenz-Hook-Programm	examples/hook/	Ein kompilierender Anchor 1.0 Hook: Whitelist-Gate + Zähler pro Mint, der Fallback-Router und die is_transferring-Absicherung.
Angriffstests	examples/hook/tests/	LiteSVM-Tests, die durch den Hook überweisen: Whitelist-bestehen (Zähler erhöht), nicht-Whitelist-fehlschlagen geschlossen, direkter Execute-Aufruf abgewiesen.
Scaffold-Skript	scripts/scaffold.sh	Generiert ein neues Hook-Workspace aus der Referenz.

Fester Stack (2026)

Anchor 1.0, anchor-spl 1.0.2, spl-transfer-hook-interface =2.1.0, spl-tlv-account-resolution 0.11, @solana/spl-token 0.4.14, litesvm 1.2 (kit-nativ, Token-2022 vorinstalliert). Das Referenzprogramm baut und seine Tests bestehen auf diesem Stack.

Unverhandelbare Regeln

• Fügen Sie einen fallback hinzu, der TransferHookInstruction::Execute dekodiert und im Prozess dispatched (__private::__global::transfer_hook) – niemals invoke auf das eigene Programm.
• Initialisieren Sie die ExtraAccountMetaList vor dem ersten Transfer, und behalten Sie die Vec<ExtraAccountMeta>-Reihenfolge identisch zur Execute-Kontenstruktur.
• Schützen Sie Execute mit is_transferring – lehnen Sie Aufrufe außerhalb eines echten Transfers ab.
• Binden Sie jedes injizierte Konto an PDA-Seeds (Account<T> + seeds), niemals ein nacktes UncheckedAccount, sonst fälscht ein Angreifer die Whitelist.
• Halten Sie den Hook minimal und total – er läuft bei jedem Transfer; ein Panic/hohe CU sperrt den Token.
• Testen Sie den Transfer-Pfad, nicht nur Unit-Logik – ein Hook, der compiliert, kann zur Auflösungszeit trotzdem fehlschlagen.