Andamio de Hook de Transferencia Token-2022
Los hooks de transferencia son la extensión Token-2022 más difícil de implementar correctamente: el programa debe exponer un discriminador de interfaz que Anchor no genera, diseñar un
ExtraAccountMetaListcon un orden exacto de bytes, y resistir invocaciones fuera de banda. Pequeños errores se manifiestan como errores de ejecución opacos. Esta habilidad es el camino seguro por defecto, respaldado por un programa que compila y pruebas de ataque LiteSVM.vs las habilidades de extensiones de token:
solana-token-extensions/token-2022-extensionstratan los hooks como una característica (un ejemplo estático único, más una lista de verificación de auditoría en un caso). Esta es la herramienta de hook dedicada — la única que genera un hook seguro nuevo bajo demanda (scaffold.sh) y respalda su auditor con pruebas de ataque que pasan. Complementaria: instálela junto con ellas cuando esté construyendo o endureciendo un hook.
Cuándo usar esta habilidad
- Construyendo un hook de transferencia: lista blanca/control KYC, aplicación de regalías, enrutamiento de tarifas, contabilidad/límites por transferencia, reglas similares a soulbound.
- Depurando un hook:
AccountNotFound,NotEnoughAccountKeys,IncorrectAccountAddress, o "la transferencia funciona sin el hook pero falla con él". - Revisando/auditando un programa de hook existente para detectar los errores comunes.
- Creando un mint Token-2022 que apunta a un hook, y cableando la transferencia del cliente.
Nota para integradores: si está en el lado consumidor (aceptando un mint de terceros que tiene un hook), ese es un problema diferente — la mayoría de los integradores deberían rechazar mints con hook desconocidos. Consulte la habilidad complementaria token2022-integration-guard.
El modelo mental (lea esto primero)
- Un programa de hook implementa
Execute(la interfaz SPL transfer-hook), que Token-2022 llama mediante CPI en cada transferencia. Anchor despacha porsha256("global:<ix>"), lo que NO coincide con el discriminador de la interfaz — por lo que agrega unfallbackque decodifica la instrucción de la interfaz y despacha en proceso (nunca un self-CPI). → program.md - El hook puede requerir cuentas adicionales. Las declara una vez en un
ExtraAccountMetaListPDA (["extra-account-metas", mint]); Token-2022 lo lee y pasa esas cuentas aExecute, resolviendo PDAs basadas en semillas en el momento de la transferencia. El orden es crítico. → extra-account-metas.md - El cliente debe construir la transferencia con
createTransferCheckedWithTransferHookInstruction(untransferCheckedsimple omite las cuentas adicionales y revierte). → client-wiring.md - Un hook es alcanzable por atacantes: protéjalo. → security.md
- Pruébelo con pruebas que transfieran a través del hook. → testing.md
Tabla de enrutamiento
| El usuario está… | Lea |
|---|---|
| Escribiendo el programa de hook (Execute, fallback, init meta list) | program.md |
| Combatiendo errores de ExtraAccountMetaList / cuentas opacas | extra-account-metas.md |
| Cableando el mint + la transferencia del cliente | client-wiring.md |
| Endureciendo / auditando un hook para seguridad | security.md |
| Escribiendo pruebas para un hook | testing.md |
| Creando un espacio de trabajo de hook nuevo | ejecute /transfer-hook:scaffold |
| Auditando un programa de hook existente | ejecute /transfer-hook:audit |
| Fuentes / lecturas adicionales | resources.md |
Lo que incluye esta habilidad
| Artefacto | Ruta | Qué es |
|---|---|---|
| Programa de hook de referencia | examples/hook/ | Un hook Anchor 1.0 que compila: lista blanca + contador por mint, el enrutador fallback y la guarda is_transferring. |
| Pruebas de ataque | examples/hook/tests/ | Pruebas LiteSVM que transfieren a través del hook: lista blanca pasa (contador incrementa), no incluido en lista blanca falla cerrado, Execute directo rechazado. |
| Script de andamio | scripts/scaffold.sh | Genera un espacio de trabajo de hook nuevo a partir de la referencia. |
Stack fijo (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 (nativo del kit,
Token-2022 precargado). El programa de referencia compila y sus pruebas pasan en este stack.
Reglas no negociables
- Agregue un
fallbackque decodifiqueTransferHookInstruction::Executey despache en proceso (__private::__global::transfer_hook) — nuncainvokesu propio programa. - Inicialice el
ExtraAccountMetaListantes de la primera transferencia, y mantenga el orden deVec<ExtraAccountMeta>idéntico al de la estructura de cuentas de suExecute. - Proteja
Executeconis_transferring— rechace llamadas fuera de una transferencia real. - Vincule cada cuenta inyectada a semillas de PDA (
Account<T>+seeds), nunca unUncheckedAccountdesnudo, o un atacante falsificará su lista blanca. - Mantenga el hook mínimo y total — se ejecuta en cada transferencia; un pánico/CU alto rompe el token.
- Pruebe la ruta de transferencia, no solo la lógica unitaria — un hook que compila aún puede fallar al momento de resolverse.