Guarda de Integración Token-2022

¿Qué hace Guarda de Integración Token-2022?

Autor/inspector vs consumidor. El material token-2022 del kit y las habilidades generales de extensiones de tokens (solana-token-extensions, token-2022-extensions) son para el autor del token: elegir extensiones, crear la moneda y un inspector de moneda de solo lectura. Esta habilidad es el lado opuesto: cómo un programa consume de forma segura una moneda de terceros que no controla. Una moneda es una entrada no confiable. Donde esas habilidades dicen "los integradores deberían usar el monto neto", esta habilidad impone y prueba eso: una bóveda de guardia que demuestra el peligro de insolvencia de acciones y lo bloquea en cadena. Estrictamente complementaria; instálela junto a ellas.

Cuándo usar esta habilidad

Úsela cuando el usuario esté en el lado consumidor de una moneda Token-2022:

• Agregando soporte Token-2022 a un AMM, bóveda, mercado de préstamos, depósito en garantía, staking o flujo de pagos.
• Decidiendo si listar / agrupar / aceptar un token específico ("¿esta moneda es segura para integrar?").
• Depurando matemáticas de acciones/LP/depósitos que "no cuadran" (casi siempre es un error de tarifa de transferencia).
• Revisando un programa Anchor/nativo que mueve tokens SPL por seguridad Token-2022.
• Escribiendo pruebas que demuestren que tu integración sobrevive a monedas hostiles.

Si el usuario quiere crear un token con extensiones, ese es el lado del emisor: remítase a la habilidad principal de token-2022.

El modelo de amenaza en un párrafo

Una moneda Token-2022 puede llevar extensiones que cambian el comportamiento de transferencia. Como integrador, debes asumir que el autor de la moneda es adversarial. Las peligrosas: una tarifa de transferencia hace que el monto acreditado sea menor que el monto enviado (rompe las matemáticas 1:1 de acciones); un gancho de transferencia ejecuta código controlado por el emisor en cada transferencia (reentrancia, DoS, inyección de cuentas); un delegado permanente puede mover/quemar tokens desde tu bóveda en cualquier momento; estado de cuenta predeterminado = congelado hace que tus nuevas cuentas de token sean inutilizables; transferencias confidenciales ocultan el saldo real de tu contabilidad; pausable permite al emisor congelar tus retiros. Denegación por defecto.

Procedimiento operativo

1. Escanear primero. Identifica cada extensión en la moneda y su impacto en el integrador. → scanning.md (CLI t22-scan ejecutable) y extension-risk-matrix.md (qué significa cada extensión).
2. Decidir por perfil. AMM, bóveda, préstamo y depósito en garantía toleran diferentes extensiones. Usa los veredictos de la matriz (ALLOW / HANDLE / REJECT).
3. Endurecer el programa. Aplica los patrones para lo que elijas soportar:
   • Tarifa de transferencia → transfer-fee-accounting.md
   • Gancho de transferencia → transfer-hook-reentrancy.md
   • Delegado permanente / congelar → permanent-delegate-and-freeze.md
   • Aplicar una lista blanca de denegación por defecto en cadena → extension-allowlist-pattern.md
4. Probar con pruebas. Escribe pruebas LiteSVM que carguen el programa Token-2022 real y afirmen que tus guardias bloquean el ataque. → testing.md
5. Citar fuentes / profundizar. → resources.md

Tabla de enrutamiento

El usuario está tratando con…	Leer
"¿Esta moneda es segura para integrar?" / escanear un token	scanning.md, extension-risk-matrix.md
Montos de acciones/LP/depósitos incorrectos, "la tarifa se come mis depósitos"	transfer-fee-accounting.md
Ganchos de transferencia, reentrancia, ExtraAccountMetaList, CPI en transferencia	transfer-hook-reentrancy.md
Delegado permanente, autoridad de congelación, predeterminado congelado, reembolso	permanent-delegate-and-freeze.md
"¿Cómo rechazo monedas peligrosas en mi programa?"	extension-allowlist-pattern.md
Escribir/ejecutar pruebas para casos extremos de Token-2022	testing.md
Qué extensiones existen y qué tan riesgosa es cada una	extension-risk-matrix.md
Fuentes, auditorías, políticas DEX, lectura adicional	resources.md

Lo que incluye esta habilidad

Artefacto	Ruta	Qué es
CLI de escáner	tools/t22-scan/	t22-scan <moneda> --profile=vault → veredicto de riesgo por extensión + código de salida para CI. Verificado contra monedas principales en vivo.
Programa de guardia	examples/guard/	Una bóveda Anchor 1.0 real: lista blanca de extensiones en cadena + depósito seguro con medición de delta (tarifa) + retiro consciente de reentrancia.
Pruebas de ataque	examples/guard/tests/	Pruebas LiteSVM que cargan el programa spl_token_2022 real, demostrando el peligro y que el guardia lo bloquea.

Comandos y agente

Disparador	Qué hace
/scan-mint	Escanea una dirección de moneda e informa el riesgo de integración para un perfil elegido.
/audit-t22-integration	Audita el código fuente de un programa en busca de errores de integración Token-2022.
Agente: token2022-integration-auditor	Genera un revisor enfocado que escanea monedas configuradas y busca en el programa transfer vs transfer_checked, matemáticas que confían en el monto y verificaciones de extensión faltantes.

Reglas no negociables (aplicar en cada integración)

• Denegación por defecto. Rechaza cualquier extensión que no manejes explícitamente. TLV desconocido = rechazar.
• Nunca confíes en el argumento amount para acreditar valor. Mide el delta recibido (reload() + diferencia de saldo) o lee la configuración de tarifa; acredita el monto recibido.
• Siempre usa transfer_checked (moneda + decimales), nunca el obsoleto transfer.
• Fija el programa de tokens. Configura token::token_program / associated_token::token_program para que un atacante no pueda mezclar una cuenta de token clásico en una CPI Token-2022.
• Revalida en el uso, no solo al listar: el programa de gancho de transferencia de una moneda y las tarifas pueden cambiar.
• Pruébalo. Envía una prueba LiteSVM que falle sin tu guardia y pase con él.