CommunityProgramación y desarrollogithub.com

mohit-1710/andamio-hook-de-transferencia

Genera un hook de transferencia Token-2022 seguro, o audita uno existente. Una referencia compilable en Anchor, un generador de andamios y pruebas de ataque LiteSVM. Construido para el AI Kit de Solana.

¿Qué es andamio-hook-de-transferencia?

Esta habilidad está diseñada para desarrolladores que trabajan con la extensión Token-2022 de Solana, específicamente con los hooks de transferencia, que son una de las funcionalidades más complejas y propensas a errores. A diferencia de otras habilidades que tratan los hooks como una característica más, esta proporciona una herramienta dedicada para generar un hook seguro desde cero mediante un script (`scaffold.sh`), y también permite auditar un programa de hook existente para detectar vulnerabilidades comunes. La habilidad incluye un programa de referencia que compila con Anchor 1.0, implementa un whitelist, un contador por mint, un enrutador `fallback` y una guarda `is_transferring` para prevenir llamadas externas maliciosas. También incluye pruebas de ataque con LiteSVM que verifican que el hook funcione correctamente en una transferencia real, que un usuario no autorizado sea rechazado y que las invocaciones directas al `Execute` sean bloqueadas. El paquete completo viene con andamios, documentación detallada y reglas no negociables de seguridad, todo preparado para el AI Kit de Solana. Soporta Anchor, LiteSVM y las herramientas estándar del ecosistema Solana.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add mohit-1710/transfer-hook-scaffold

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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 ExtraAccountMetaList con 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-extensions tratan 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)

  1. Un programa de hook implementa Execute (la interfaz SPL transfer-hook), que Token-2022 llama mediante CPI en cada transferencia. Anchor despacha por sha256("global:<ix>"), lo que NO coincide con el discriminador de la interfaz — por lo que agrega un fallback que decodifica la instrucción de la interfaz y despacha en proceso (nunca un self-CPI). → program.md
  2. El hook puede requerir cuentas adicionales. Las declara una vez en un ExtraAccountMetaList PDA (["extra-account-metas", mint]); Token-2022 lo lee y pasa esas cuentas a Execute, resolviendo PDAs basadas en semillas en el momento de la transferencia. El orden es crítico. → extra-account-metas.md
  3. El cliente debe construir la transferencia con createTransferCheckedWithTransferHookInstruction (un transferChecked simple omite las cuentas adicionales y revierte). → client-wiring.md
  4. Un hook es alcanzable por atacantes: protéjalo. → security.md
  5. 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 opacasextra-account-metas.md
Cableando el mint + la transferencia del clienteclient-wiring.md
Endureciendo / auditando un hook para seguridadsecurity.md
Escribiendo pruebas para un hooktesting.md
Creando un espacio de trabajo de hook nuevoejecute /transfer-hook:scaffold
Auditando un programa de hook existenteejecute /transfer-hook:audit
Fuentes / lecturas adicionalesresources.md

Lo que incluye esta habilidad

ArtefactoRutaQué es
Programa de hook de referenciaexamples/hook/Un hook Anchor 1.0 que compila: lista blanca + contador por mint, el enrutador fallback y la guarda is_transferring.
Pruebas de ataqueexamples/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 andamioscripts/scaffold.shGenera 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 fallback que decodifique TransferHookInstruction::Execute y despache en proceso (__private::__global::transfer_hook) — nunca invoke su propio programa.
  • Inicialice el ExtraAccountMetaList antes de la primera transferencia, y mantenga el orden de Vec<ExtraAccountMeta> idéntico al de la estructura de cuentas de su Execute.
  • Proteja Execute con is_transferring — rechace llamadas fuera de una transferencia real.
  • Vincule cada cuenta inyectada a semillas de PDA (Account<T> + seeds), nunca un UncheckedAccount desnudo, 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.

Skills relacionados