Introducción al protocolo ERC-3643
Contenido
- Visión general
- Cinco conceptos fundamentales
- Arquitectura general de contratos
- Responsabilidades de los contratos y estado en cadena
- Interacciones entre contratos
- Permisos y multifirma
- Conclusiones de la investigación y la demostración
- Límites de seguridad
- Glosario
1. Visión general
ERC-3643 es un marco de emisión ERC-20 con verificación de identidad y controles de cumplimiento. Define quién puede mantener un token, si una transferencia puede ejecutarse, cómo las partes autorizadas congelan, transfieren de forma forzosa o recuperan activos, y cómo se actualizan las implementaciones de manera coherente.
| Dimensión | ERC-20 convencional | ERC-3643 |
|---|---|---|
| Quién puede recibir | Cualquier dirección | Solo identidades verificadas |
| Transferencias | No admiten rechazo por reglas de negocio | Los módulos de cumplimiento pueden rechazarlas |
| Congelación, transferencia forzosa y recuperación de cartera | No disponibles | Disponibles |
| Cambios de reglas | Suelen requerir otro contrato | Se modifica la configuración o los módulos |
2. Cinco conceptos fundamentales
| Concepto | Significado |
|---|---|
| ONCHAINID | Identidad de usuario en cadena separada de la cartera; una identidad puede vincular varias carteras |
| Claim | Afirmación de cualificación firmada y asociada a una identidad |
| Claim Emisor | Contrato institucional autorizado para emitir o revocar Claims |
| Identity Registry | Determina si una dirección pertenece a un inversor apto: la comprobación de la persona |
| Compliance module | Determina si una transacción cumple las reglas: la comprobación de la transacción |
Ambas puertas deben superarse. Un inversor aprobado por KYC aún puede ser rechazado por un límite de tenencia u otra regla de cumplimiento.
3. Arquitectura general de contratos
3.1 Cuatro capas
| Capa | Número de instancias | Propósito |
|---|---|---|
| Plataforma | Normalmente una por red | Acceso de emisión, creación de identidades y actualizaciones compartidas |
| Suite | Seis contratos por activo | Saldos, identidad, cumplimiento y gobernanza |
| ONCHAINID | Uno por usuario | Claves y Claims |
| Módulo de cumplimiento | Se despliega por regla y se reutiliza | Reglas de transacción ejecutables |
Los contratos se separan para que cada responsabilidad evolucione de forma independiente: Token gestiona el libro mayor; IR, IRS, CTR y TIR gestionan las cualificaciones de identidad; MC gestiona las reglas de transacción. Las direcciones de los proxies permanecen estables: el proxy almacena el estado y la implementación aporta la lógica.
3.2 Tres mecanismos de actualización
| Objeto | Mecanismo | Punto de actualización | Alcance |
|---|---|---|---|
| Seis contratos TREX | Proxy con puntero a IA | TREX IA | Activos que aún referencian esa IA |
| ONCHAINID | IA de ONCHAINID | updateImplementation | Identidades que referencian esa IA |
| Módulo de cumplimiento | ERC1967 + UUPS | Propietario del módulo, upgradeTo | Activos vinculados a ese módulo |
4. Responsabilidades de los contratos y estado en cadena
La cadena almacena el estado de negocio y la configuración de reglas. Los nombres, números de identidad, imágenes de documentos y demás datos sensibles permanecen en el sistema KYC fuera de cadena. La cadena registra conclusiones como tipos de cualificación, tenencias y aptitud para transferir.
4.1 Contratos de plataforma de toda la red
| Contrato | Propósito | Estado principal en cadena | Límite importante |
|---|---|---|---|
TREXImplementationAuthority | Selecciona la versión de implementación usada por los activos RWA | Versión actual y seis direcciones de implementación por versión | Las seis implementaciones deben registrarse juntas |
IAFactory | Crea una autoridad de actualización independiente para un activo | Activos que recibieron una autoridad independiente | Solo el administrador de la autoridad global puede crearla |
TREXFactory | Despliega e inicializa una Suite RWA completa | Salts usados, autoridad, fábrica de identidades y desplegadores autorizados | Configuración inicial: máximo 5 Topics, emisores y agentes; 30 operaciones de módulos |
TREXGateway | Controla emisores, emisión pública, comisiones y descuentos | Configuración pública, token/importe/destinatario de comisión, lista de emisores, descuentos y administradores | Máximo 5 Suites por lote |
IdFactory | Crea perfiles de identidad en cadena y asociaciones de carteras | Asociaciones cartera-identidad e identidad-cartera | Máximo 101 carteras por identidad |
ONCHAINID ImplementationAuthority | Selecciona la versión de implementación de identidad | Implementación actual y autoridad de actualización | Un cambio afecta a todas las identidades que la referencian |
ONCHAINID Gateway | Permite crear identidades con firmas autorizadas por la plataforma | Firmantes autorizados y firmas revocadas | Normalmente queda fuera del flujo principal de la demostración |
4.2 Seis contratos fundamentales por activo RWA
| Contrato | Propósito | Estado principal en cadena | Límite importante |
|---|---|---|---|
Token | Libro mayor, transferencias, acuñación, quema, pausa, congelación, transferencia forzosa y recuperación de cartera | Saldos, autorizaciones, suministro, metadatos, pausa, congelaciones totales y parciales, IR/MC asociados, propietarios y agentes | decimals de 0 a 18 |
IdentityRegistry | Comprueba la aptitud del destinatario antes de transferir o acuñar | Referencias a CTR, TIR, IRS y administradores del registro | Más requisitos y emisores aumentan el coste de gas |
IdentityRegistryStorage | Almacena la identidad y el país de la cartera; puede compartirse | Cartera → identidad + país y registros que usan el almacenamiento | Máximo 300 IdentityRegistries; un registro por cartera |
ClaimTopicsRegistry | Define las cualificaciones exigidas para mantener el activo | Topics requeridos y administradores | Máximo 15 Topics únicos |
TrustedIssuersRegistry | Define los emisores aceptados y sus Topics permitidos | Emisores y tipos de cualificación | Máximo 50 emisores y 15 Topics por emisor |
ModularCompliance | Aplica reglas de importe, país, bloqueo temporal y otras reglas de transacción | Token vinculado, módulos asociados y administradores | Un Token y un máximo de 25 módulos |
4.3 Identidades de usuario y módulos de reglas
| Contrato | Propósito | Estado principal en cadena |
|---|---|---|
ONCHAINID / Identity | Una identidad en cadena reutilizable por persona; las carteras son herramientas reemplazables | Claves de gestión, acción y Claim; Claims recibidos |
ClaimIssuer | Contrato de la institución KYC/AML que emite y revoca certificaciones | Claves de identidad y firmas revocadas |
ModuleProxy | Punto de entrada estable para una regla de negocio | Implementación actual y parámetros por activo |
Ubicaciones del código fuente: los contratos de plataforma están en contracts/factory/ y proxy/authority/; los contratos de activos están en token/, registry/ y compliance/modular/; las capacidades de identidad proceden de @onchain-id/solidity.
5. Interacciones entre contratos
5.1 Dependencias
5.3 Emisión
El salt de Gateway suele ser la dirección hexadecimal del propietario más el nombre del Token. Cuando las comisiones están activadas, autorice primero el token de comisión.
5.4 Incorporación del inversor: identidad, firma KYC y Claim en cadena
La incorporación consta de cuatro etapas: creación del contrato de identidad, firma de la cualificación, envío del Claim y registro en el activo. Mantenga claras estas diferencias:
- Crear un ONCHAINID es una transacción en cadena que despliega el contrato de identidad del inversor.
- La firma KYC de ClaimSigner se genera fuera de cadena y no crea una transacción ni un coste de gas.
addClaimes una transacción en cadena que guarda la firma de ClaimSigner y la conclusión KYC en el ONCHAINID del inversor.
5.4.1 Flujo de producción: creación autoservicio de identidad mediante ONCHAINID Gateway
IdFactory.createIdentity es onlyOwner, por lo que los inversores carecen de acceso directo a la fábrica. En producción, despliegue el Gateway.sol oficial, transfiera a este la propiedad de IdFactory y permita que los inversores llamen a Gateway.deployIdentityForWallet(investor). Gateway llama a IdFactory.createIdentity como propietario, mientras el inversor envía la transacción y paga el gas.
5.4.2 Invocador y pagador de gas por etapa
| Etapa | Acción | Iniciador | En cadena | Pagador de gas | Notas |
|---|---|---|---|---|---|
| 1 | Revisión KYC | Inversor y sistema de revisión | No | Ninguno | La información personal en claro permanece fuera de cadena |
| 2 | Crear ONCHAINID | El inversor llama a Gateway.deployIdentityForWallet | Sí | Inversor | Gateway llama a IdFactory.createIdentity |
| 3 | Firmar KYC | ClaimSigner firma hash(identity, topic, data) | No | Ninguno | Firma EOA/HSM/MPC fuera de transacción |
| 4 | Enviar Claim KYC | El inversor llama a Identity.addClaim | Sí | Inversor | El contrato llama a ClaimIssuer.isClaimValid |
| 5 | Registrar en el activo | El agente de IR llama a IdentityRegistry.registerIdentity | Sí | Agente de IR | Registra cartera, identidad y país en una Suite |
| 6 | Verificar resultado | Cualquiera llama a IdentityRegistry.isVerified | No, view | Ninguno | Debe devolver true antes de recibir una acuñación o transferencia |
5.4.3 ¿La firma KYC de ClaimSigner está en cadena?
La firma se genera fuera de cadena:
digest = keccak256(abi.encode(identity, topic, data))
signature = ClaimSigner.signMessage(digest)
La siguiente transacción addClaim almacena estos argumentos:
Identity.addClaim(
topic,
1,
claimEmisor,
signature,
data,
uri
)
El inversor envía addClaim, mientras el contrato de identidad llama a ClaimIssuer.isClaimValid(...) para comprobar que el emisor es de confianza, que la firma procede de una clave Claim registrada, que sigue vigente y que el Topic es obligatorio. La confianza procede de la firma de ClaimSigner, con independencia del remitente de addClaim.
5.5 Matriz de transferencia, acuñación y quema
| Operation | Invocador | Paused check | Freeze check | Identity check | Compliance check | Auto-unfreeze |
|---|---|---|---|---|---|---|
| Transferencia / transferencia delegada | Titular / autorizado | Sí | Ambas partes | Destinatario | Sí | No |
| Acuñación | Agente | No | No | Destinatario | Sí | No |
| Quema | Agente | No | No | No | No | Sí |
| Transferencia forzosa | Agente | No | No | Destinatario | No, aun llama a transferred | Sí |
| Recuperación de cartera | Agente | No | No | Usa transferencia forzosa | No | Sí |
La puerta 1 valida solo al destinatario. La pausa permite que continúen las operaciones administrativas. La transferencia forzosa omite canTransfer y las congelaciones parciales permiten actuar al agente.
5.7 Interacciones de actualización
| Objeto | Cadena de llamadas | Impacto |
|---|---|---|
| TREX contracts | IA owner → addTREXVersion → useTREXVersion | Proxies que referencian la IA de referencia |
| Detach one asset | La misma dirección posee los seis → changeImplementationAuthority | Solo el activo objetivo |
| ONCHAINID | OID IA owner → updateImplementation | Todas las identidades que la referencian |
| Compliance module | Module owner → upgradeTo | MC vinculados a ese módulo |
6. Permisos y multifirma
6.1 Cuatro modelos de permisos
| Modelo | Autorización | Propósito | Compatibilidad con Safe |
|---|---|---|---|
| Owner | msg.sender == owner | Gobernanza, sustitución de componentes, actualizaciones y reglas | Compatible, sin restricción EOA |
| Agent | Agent list | Operaciones frecuentes de acuñación, congelación y registro | Compatible técnicamente; la multifirma resulta ineficiente para cada acción frecuente |
| onlyToken / onlyComplianceCall | Dirección del contrato vinculado | Callbacks automáticos y reenvío de parámetros | No es una cuenta humana |
| ONCHAINID Key | keccak256(address) basado en propósito | Gestión de claves, llamadas externas y Claims | Safe puede gestionar claves de acción; no firma Claims de forma nativa |
El protocolo carece de Timelock nativo. transferOwnership puede asignar la propiedad a un Safe. renounceOwnership elimina permanentemente al propietario y debe protegerse en producción.
6.2 Matriz de permisos
| Contrato | Rol | Capacidad crítica | Recomendación para Safe |
|---|---|---|---|
| TREX IA / ONCHAINID IA | Owner | Actualizaciones globales | Safe de máxima seguridad + Timelock |
| TREXFactory | Owner | Desplegar Suites y recuperar contratos que aún pertenecen a Factory | Suele pertenecer a Gateway |
| TREXGateway | Owner / Agent | Acceso, comisiones, propiedad de Factory y desplegadores | Owner → Safe; Agent → cuenta de servicio |
| Token | Owner / Agent | Sustituir IR/MC, gestionar agentes, acuñar, quemar, congelar, transferir de forma forzosa y recuperar | Owner → Safe; separar las funciones de Agent |
| IR | Owner / Agent | Sustituir CTR/TIR/IRS y gestionar registros de inversores | Owner → Safe; Agent → cuenta KYC |
| IRS | Owner / Agent | Vincular IR y escribir datos maestros de identidad | Definir primero el modelo de propiedad |
| CTR / TIR / MC | Owner | Topics, emisores, módulos y parámetros | Safe de cumplimiento + Timelock |
| Upgradeable Module | Module owner | Actualización UUPS | Safe + Timelock |
| IdFactory | Owner | Crear identidades | Safe de plataforma |
| Identity | Management/action/Claim keys | Gestionar claves, ejecutar llamadas y gestionar Claims | Safe puede mantener claves de gestión/acción |
| ClaimIssuer | Management + Claim keys | Revocar y emitir | Gestión → Safe; emisión → EOA/HSM/MPC |
6.3 Conclusiones sobre Safe
Safe funciona directamente para: propietarios de Suite y plataforma, propietarios de actualización de módulos, claves de gestión/acción de ONCHAINID y sustitución de IA por activo cuando el mismo Safe posee los seis contratos.
Safe no firma Claims de forma nativa: la validación usa ecrecover, que recupera una EOA. Use Safe para administrar el emisor y un firmante independiente para Purpose 3.
Las acciones frecuentes deben usar cuentas de servicio restringidas: registro de inversores, acuñación/quema rutinaria, mantenimiento de desplegadores, pausa/congelación rápida, transferencia forzosa y recuperación. Aplique aprobación y alertas fuera de cadena, con doble aprobación o multifirma dedicada para riesgos excepcionales.
6.4 Capas recomendadas y tres riesgos
- La propiedad de IRS se transfiere por separado de los otros cinco contratos. Permanece en Factory, normalmente propiedad de Gateway, hasta llamar a
recoverContractOwnership. - Cambiar la IA de un activo exige que los seis valores
owner()coincidan con el mismomsg.sender. Los Safes separados carecen de aprobación independiente para esta operación. - Safe y Timelock proporcionan controles distintos. Las actualizaciones globales, la sustitución de IR/MC y los cambios de Topic, emisor o módulo requieren un retraso de ejecución externo.
7. Conclusiones de la investigación y la demostración
| Conclusión | Hecho del código |
|---|---|
| Los Topics carecen de números fijos | No existe 1=KYC codificado; la demostración usa keccak256("KYC_APPROVED"), por lo que debe mantenerse un registro de Topics de red |
| Identity no es un Beacon | ONCHAINID usa ImplementationAuthority de npm 2.2.1 |
| Faltan módulos de cumplimiento para producción | Solo existen DemoCountryAllowlistModule y TestModule sin auditar; las funciones heredadas no son módulos desplegables |
| Punto de entrada de transferencias | Los inversores llaman directamente a Token; IdentityProxy.execute resulta innecesario |
| Código de país | uint16, ISO 3166-1 numérico, como 156 y 702; el módulo de demostración solo comprueba al destinatario |
| Parámetros de módulos | Aislados por dirección de MC, por lo que un módulo puede servir a varios activos |
| Reutilización de identidad | Los emisores compartidos evitan repetir KYC; un IRS compartido añade reutilización con una superficie de gobernanza mayor |
| Versión de dependencia | package.json usa ^2.0.0 y la versión instalada es 2.2.1; fije la versión de producción |
Prioridad recomendada de módulos personalizados tras la demostración: acceso por país, límite por titular, límite de suministro total, número de titulares → bloqueo temporal, clase de inversor, límites de importe → transferencias condicionales y restricciones por centro de negociación.
Los emisores KYC/AML y los parámetros de módulos determinan directamente la configuración en cadena. La custodia, la auditoría y los canales fiduciarios afectan principalmente a las aprobaciones. Nunca incluya PII en texto claro en data de un Claim.
8. Límites de seguridad
- La vulneración de Owner, Agent, IA o ClaimIssuer puede modificar directamente los activos o la elegibilidad. Separe los firmantes de larga duración de Owner y Agent.
- La transferencia forzosa y la quema pueden descongelar unidades automáticamente; la pausa permite las operaciones administrativas.
- Eliminar un emisor de confianza o vaciar Topics cambia la aptitud de muchos usuarios a la vez.
- Una actualización global de IA tiene un impacto amplio y exige multifirma, Timelock, validación del layout de almacenamiento y ensayo de reversión.
- Los contratos carecen de medios para establecer la autenticidad del activo subyacente, la titularidad legal, el reembolso o la legalidad entre jurisdicciones; defina estos aspectos en una matriz de reglas separada.
9. Glosario
| Término | Significado |
|---|---|
| T-REX / Suite | Implementación de referencia ERC-3643 / seis contratos de negocio para un activo |
| ONCHAINID / Claim / Topic / Emisor | Contrato de identidad / afirmación de cualificación / tipo de afirmación / institución emisora |
| IR / IRS / CTR / TIR / MC | Registro de identidad / almacenamiento de identidad / registro de Topics / registro de emisores / coordinador de cumplimiento |
| Owner / Agent | Autoridad de gobernanza de configuración / autoridad operativa |
| Implementation Authority | Autoridad de versiones que selecciona la implementación activa del proxy |
| TREXFactory / Gateway / IdFactory | Fábrica de activos / gateway de acceso de emisión / fábrica de identidades |