Tokenización de Crédito

Requisitos previos de acceso

• Permiso (módulo): viewCredits (acceso a la pantalla y a los listados). Las operaciones de configuración/escritura de proyecto de token siguen el gate de creditConfigManage; mint/burn/deploy son acciones on-chain sensibles.
• Licencia/Feature: CREDIT_INVESTMENTS habilitada en la licencia del tenant (Vault).
• Contenedor del menú: TOKENIZACIÓN → grupo Crédito Tokenizado

Qué es / cuándo usar

La Tokenización de Crédito es donde la operación de crédito se convierte en un activo on-chain. La pantalla reúne tres áreas:

• Proyectos de Token — registra e implementa (deploy) los contratos que representan el crédito en la blockchain (ERC-20 para posiciones fungibles, ERC-1155 para cuentas por cobrar/cobros).
• Posiciones de Inversor — hace seguimiento de cuántas unidades tiene cada inversor asignadas, acuñadas y quemadas por deal, y permite acuñar tokens.
• Transacciones On-chain — libro mayor de todas las transacciones blockchain (mint, burn, deploy) con hash, bloque y gas, con enlace al explorer.

Use esta pantalla después de que el deal esté aprobado y desembolsado, para emitir los tokens que dan respaldo on-chain a la posición de los inversores y a la cuenta por cobrar.

Requisitos previos

• Permiso: viewCredits para visualizar; la escritura depende del gate de configuración/acción de crédito (permiso doble — enum CPM + módulo dinámico en la BD).
• Licencia/Feature: CREDIT_INVESTMENTS habilitada.
• Dependencias: el deal correspondiente debe existir y estar en el estado adecuado; para acuñar una posición de inversor se requiere un proyecto de token implementado (con contractAddress). La billetera de mint/deploy debe estar configurada para la chain elegida.

Tab 1 — Proyectos de Token

Cada proyecto representa un contrato a implementar. Filtros: Tipo de Proyecto, Estándar y Estado.

Campos del proyecto

Campo	Qué es	¿Obligatorio?	Efecto en el sistema/backend
Tipo de Proyecto	INVESTOR_POSITION, RECEIVABLE_ASSET, CHARGE_ASSET o POOL_ASSET	Sí	Guardado en projectType; define el rol del token (posición de inversor, cuenta por cobrar, cobro o pool).
Estándar	ERC20 o ERC1155	Sí	Guardado en standard. Determina qué contrato se implementa: ERC-20 (fungible, p. ej.: posición) o ERC-1155 (multi-token, p. ej.: cuentas por cobrar).
Chain	Red de destino (Ethereum, Polygon, BSC, Avalanche, Arbitrum, Optimism)	Sí	Guardado en chainId. Define en qué red ocurren el deploy y los mints y qué explorer se usa en los enlaces.
Nombre del Token	Nombre del token	No	Guardado en tokenName.
Símbolo del Token	Ticker del token	No	Guardado en tokenSymbol.
Dirección del Contrato	Dirección on-chain	No (se completa en el deploy)	Guardado en contractAddress. Cuando ya existe, el proyecto se considera implementado y el deploy no vuelve a ejecutarse.
URI de Metadatos	URI de metadatos (p. ej.: IPFS)	No	Guardado en metadataUri.
Whitelist obligatoria	Restringe las transferencias a direcciones en whitelist	No (default Sí)	Guardado en whitelistRequired. Control de compliance: solo billeteras autorizadas operan el token.
Transferencia restringida	Bloquea transferencias libres	No (default Sí)	Guardado en transferRestricted. Token "bloqueado" en el circuito custodiado hasta su liberación.
Pausable	Permite pausar el contrato	No (default Sí)	Guardado en pausable. Habilita el kill-switch de emergencia en el contrato.
Estado	DRAFT, DEPLOYED, ACTIVE, PAUSED, ARCHIVED	Condicional (en edición)	Guardado en status. En creación, el estado inicial es DRAFT.

Acciones de la pestaña Proyectos

• Crear / Editar / Visualizar proyecto: el formulario guarda vía createTokenProject / updateTokenProject. Visualizar abre en modo solo lectura.
• Deploy (implementar contrato): habilitado cuando el proyecto aún no tiene contractAddress y está en DRAFT o ACTIVE. Dispara deployTokenProject, que implementa el contrato ERC-20 o ERC-1155 en la chain, devolviendo contractAddress, el hash de deploy y deployedAt. Si el contrato ya está implementado, el sistema devuelve la dirección existente en lugar de reimplementar.

Tab 2 — Posiciones de Inversor

Muestra, por deal: número del deal, inversor, unidades asignadas / acuñadas / quemadas, estado y el hash del mint (con enlace al explorer). Puede filtrarse por deal (ruta .../investor-positions/deal/:dealId).

Acción de mint

• Acuñar tokens: el operador indica un valor (prompt); si es mayor que cero, dispara mintInvestorTokens(dealId, amount). El backend emite los tokens on-chain y registra la transacción.

Tab 3 — Transacciones On-chain

Libro mayor de solo lectura de todas las transacciones blockchain. Filtros: Estado, Tipo de Transacción, Tipo de Entidad.

Columna	Qué muestra	Origen del dato
Hash de la Transacción	Hash on-chain	txHash
Tipo de Entidad / ID	A qué entidad hace referencia la tx	entityType / entityId
Tipo de Transacción	Mint, burn, deploy, etc.	txType
Estado	Estado de confirmación on-chain	status
Bloque / Gas	Número de bloque y gas consumido	blockNumber / gasUsed
Creada en	Fecha/hora del registro	createdAt
Acción (ver)	Abre el explorer de la chain en ese hash	getExplorerUrl(txHash, chainId)

Reglas de negocio / precauciones

Atención

• El deploy se ejecuta solo una vez por proyecto. Si ya existe contractAddress, el sistema devuelve la dirección actual sin reimplementar — no hay "redeploy" por botón. Para un nuevo contrato, cree un nuevo proyecto.
• Los flags de compliance importan. whitelistRequired, transferRestricted y pausable definen el comportamiento del contrato implementado. Implementar con estos flags incorrectos implica un contrato con una regla de transferencia no deseada — revise antes del deploy.
• La chain define el explorer y la billetera de mint. Cambiar la chain cambia a qué red se emite todo; la billetera de mint/deploy debe existir para esa chain, o la operación falla.

Irreversible (on-chain)

• Deploy, mint y burn son operaciones on-chain. Una vez confirmadas, no hay rollback: el contrato queda implementado, los tokens acuñados/quemados permanecen en la blockchain. Trate cada acción como definitiva y verifique valores, deal y chain antes de confirmar.
• Mint/burn/deploy son acciones sensibles y pueden requerir step-up (re-auth contraseña + MFA, header X-Step-Up-Token, ventana de 5 min) según el entorno.

• Valores financieros: las cantidades de unidades (asignadas/acuñadas/quemadas) y el valor indicado en el mint se tratan como BigNumber — verifique los decimales del token antes de acuñar.
• Idempotencia: mint, burn y deploy están protegidos por idempotencyKey — una transacción ya registrada con la misma clave no se vuelve a ejecutar (el sistema reutiliza la existente). Reprocesar tras un crash es seguro; una respuesta "ya procesado" debe leerse como éxito, no como error.

Ejemplos

Escenario 1 — Stablecoin de posición con bloqueo cambiario (ERC-20 restringido)

Objetivo: tokenizar la posición fungible de un pool de inversores en BRL, sin permitir transferencias libres fuera del circuito custodiado.

1. Pestaña Proyectos de Token → Crear.
2. Tipo: INVESTOR_POSITION. Estándar: ERC20. Chain: Polygon.
3. Nombre/Símbolo: "Pool Crédito BRL" / "pCRD".
4. Whitelist obligatoria: Sí. Transferencia restringida: Sí. Pausable: Sí.
5. Guardar → proyecto creado en DRAFT.
6. Hacer clic en Deploy → contrato ERC-20 implementado, contractAddress completado, el estado pasa a DEPLOYED.
7. En la pestaña Posiciones de Inversor, Acuñar las unidades correspondientes a la posición de cada inversor.

Resultado: token fungible transferible solo entre billeteras autorizadas (bloqueo de compliance), con posibilidad de pausa de emergencia.

Escenario 2 — Importar contrato existente por dirección

Objetivo: registrar en el sistema un contrato ya implementado (sin reimplementar).

1. Pestaña Proyectos de Token → Crear.
2. Defina Tipo, Estándar y Chain acordes con el contrato real.
3. En el campo Dirección del Contrato, pegue la dirección on-chain existente.
4. Guardar.

Resultado: como el proyecto ya tiene contractAddress, el botón Deploy no está disponible (el sistema lo considera implementado) y los mints usan el contrato indicado. Garantiza que la operación apunte al contrato correcto sin generar uno nuevo.

Escenario 3 — Cuenta por cobrar como activo multi-token (ERC-1155)

Objetivo: tokenizar un lote de cuentas por cobrar como activos distintos bajo un mismo contrato.

1. Pestaña Proyectos de Token → Crear.
2. Tipo: RECEIVABLE_ASSET. Estándar: ERC1155. Chain: Polygon.
3. URI de Metadatos: apunte al JSON/IPFS de las cuentas por cobrar.
4. Guardar → Deploy.

Resultado: contrato ERC-1155 implementado, capaz de representar múltiples cuentas por cobrar (IDs distintos) bajo el mismo contrato, con metadatos por cuenta por cobrar.

Pantallas relacionadas

• Guía de Crédito — la fase de tokenización en el flujo completo.
• Políticas de Crédito
• Templates de Cascada (Waterfall)
• Crédito Tokenizado (índice del grupo)