Tokenização de Crédito

Pré-requisitos de acesso

• Permissão (módulo): viewCredits (acesso à tela e às listagens). Operações de configuração/escrita de projeto de token seguem a trava de creditConfigManage; mint/burn/deploy são ações on-chain sensíveis.
• Licença/Feature: CREDIT_INVESTMENTS habilitada na licença do tenant (Vault).
• Contêiner do menu: TOKENIZAÇÃO → grupo Crédito Tokenizado

O que é / quando usar

A Tokenização de Crédito é onde a operação de crédito vira ativo on-chain. A tela reúne três áreas:

• Projetos de Token — cadastra e implanta (deploy) os contratos que representam o crédito na blockchain (ERC-20 para posições fungíveis, ERC-1155 para recebíveis/cargas).
• Posições de Investidor — acompanha quantas unidades cada investidor tem alocadas, mintadas e queimadas por deal, e permite mintar tokens.
• Transações On-chain — razão de todas as transações blockchain (mint, burn, deploy) com hash, bloco e gás, com link para o explorer.

Use esta tela depois que o deal está aprovado e desembolsado, para emitir os tokens que dão lastro on-chain à posição dos investidores e ao recebível.

Pré-condições

• Permissão: viewCredits para visualizar; a escrita depende do gate de configuração/ação de crédito (permissão dupla — enum CPM + módulo dinâmico no DB).
• Licença/Feature: CREDIT_INVESTMENTS habilitada.
• Dependências: o deal correspondente deve existir e estar no estado adequado; para mintar posição de investidor é preciso um projeto de token implantado (com contractAddress). A carteira de mint/deploy precisa estar configurada para a chain escolhida.

Aba 1 — Projetos de Token

Cada projeto representa um contrato a ser implantado. Filtros: Tipo de Projeto, Padrão e Status.

Campos do projeto

Campo	O que é	Obrigatório?	Efeito no sistema/backend
Tipo de Projeto	INVESTOR_POSITION, RECEIVABLE_ASSET, CHARGE_ASSET ou POOL_ASSET	Sim	Gravado em projectType; define o papel do token (posição de investidor, recebível, cobrança ou pool).
Padrão	ERC20 ou ERC1155	Sim	Gravado em standard. Determina qual contrato é implantado: ERC-20 (fungível, ex.: posição) ou ERC-1155 (multi-token, ex.: recebíveis).
Chain	Rede de destino (Ethereum, Polygon, BSC, Avalanche, Arbitrum, Optimism)	Sim	Gravado em chainId. Define para qual rede o deploy e os mints ocorrem e qual explorer é usado nos links.
Nome do Token	Nome do token	Não	Gravado em tokenName.
Símbolo do Token	Ticker do token	Não	Gravado em tokenSymbol.
Endereço do Contrato	Endereço on-chain	Não (preenchido no deploy)	Gravado em contractAddress. Quando já existe, o projeto é considerado implantado e o deploy não roda de novo.
URI de Metadados	URI de metadados (ex.: IPFS)	Não	Gravado em metadataUri.
Whitelist obrigatória	Restringe transferências a endereços em whitelist	Não (default Sim)	Gravado em whitelistRequired. Controle de compliance: só carteiras autorizadas operam o token.
Transferência restrita	Bloqueia transferências livres	Não (default Sim)	Gravado em transferRestricted. Token "preso" ao circuito custodiado até liberação.
Pausável	Permite pausar o contrato	Não (default Sim)	Gravado em pausable. Habilita o kill-switch de emergência no contrato.
Status	DRAFT, DEPLOYED, ACTIVE, PAUSED, ARCHIVED	Condicional (em edição)	Gravado em status. Em criação, o status inicial é DRAFT.

Ações da aba Projetos

• Criar / Editar / Visualizar projeto: o formulário grava via createTokenProject / updateTokenProject. Visualizar abre em modo somente leitura.
• Deploy (implantar contrato): habilitado quando o projeto ainda não tem contractAddress e está em DRAFT ou ACTIVE. Dispara deployTokenProject, que implanta o contrato ERC-20 ou ERC-1155 na chain, retornando contractAddress, hash de deploy e deployedAt. Se o contrato já estiver implantado, o sistema retorna o endereço existente em vez de reimplantar.

Aba 2 — Posições de Investidor

Mostra, por deal: número do deal, investidor, unidades alocadas / mintadas / queimadas, status e o hash do mint (com link para o explorer). Pode ser filtrada por deal (rota .../investor-positions/deal/:dealId).

Ação de mint

• Mintar tokens: o operador informa um valor (prompt); se for maior que zero, dispara mintInvestorTokens(dealId, amount). O backend emite os tokens on-chain e registra a transação.

Aba 3 — Transações On-chain

Razão somente-leitura de todas as transações blockchain. Filtros: Status, Tipo de Transação, Tipo de Entidade.

Coluna	O que mostra	Origem do dado
Hash da Transação	Hash on-chain	txHash
Tipo de Entidade / ID	A que entidade a tx se refere	entityType / entityId
Tipo da Transação	Mint, burn, deploy etc.	txType
Status	Estado da confirmação on-chain	status
Bloco / Gás	Número do bloco e gás consumido	blockNumber / gasUsed
Criada em	Data/hora do registro	createdAt
Ação (ver)	Abre o explorer da chain naquele hash	getExplorerUrl(txHash, chainId)

Regras de negócio / cuidados

Atenção

• Deploy só roda uma vez por projeto. Se já houver contractAddress, o sistema devolve o endereço atual sem reimplantar — não há "redeploy" pelo botão. Para um novo contrato, crie um novo projeto.
• As flags de compliance importam. whitelistRequired, transferRestricted e pausable definem o comportamento do contrato implantado. Implantar com essas flags erradas significa um contrato com regra de transferência indesejada — revise antes do deploy.
• Chain define explorer e carteira de mint. Trocar a chain muda para qual rede tudo é emitido; a carteira de mint/deploy precisa existir para aquela chain, ou a operação falha.

Irreversível (on-chain)

• Deploy, mint e burn são operações on-chain. Uma vez confirmados, não há rollback: o contrato fica implantado, os tokens emitidos/queimados permanecem na blockchain. Trate cada ação como definitiva e confira valores, deal e chain antes de confirmar.
• Mint/burn/deploy são ações sensíveis e podem exigir step-up (re-auth senha + MFA, header X-Step-Up-Token, janela de 5 min) conforme o ambiente.

• Valores financeiros: as quantidades de unidades (alocadas/mintadas/queimadas) e o valor informado no mint são tratados como BigNumber — confira casas decimais do token antes de mintar.
• Idempotência: mint, burn e deploy são protegidos por idempotencyKey — uma transação já registrada com a mesma chave não é reexecutada (o sistema reaproveita a existente). Reprocessar após crash é seguro; um retorno "já processado" deve ser lido como sucesso, não erro.

Exemplos

Cenário 1 — Stablecoin de posição com trava cambial (ERC-20 restrito)

Objetivo: tokenizar a posição fungível de um pool de investidores em real, sem permitir transferência livre fora do circuito custodiado.

1. Aba Projetos de Token → Criar.
2. Tipo: INVESTOR_POSITION. Padrão: ERC20. Chain: Polygon.
3. Nome/Símbolo: "Pool Crédito BRL" / "pCRD".
4. Whitelist obrigatória: Sim. Transferência restrita: Sim. Pausável: Sim.
5. Salvar → projeto criado em DRAFT.
6. Clicar em Deploy → contrato ERC-20 implantado, contractAddress preenchido, status passa a DEPLOYED.
7. Na aba Posições de Investidor, Mintar as unidades correspondentes à posição de cada investidor.

Resultado: token fungível só transferível entre carteiras autorizadas (trava de compliance), com possibilidade de pausa de emergência.

Cenário 2 — Importar contrato existente via endereço

Objetivo: registrar no sistema um contrato já implantado (não reimplantar).

1. Aba Projetos de Token → Criar.
2. Defina Tipo, Padrão e Chain condizentes com o contrato real.
3. No campo Endereço do Contrato, cole o endereço on-chain existente.
4. Salvar.

Resultado: como o projeto já tem contractAddress, o botão Deploy não fica disponível (o sistema o considera implantado) e os mints passam a usar o contrato informado. Garante que a operação aponte para o contrato correto sem gerar um novo.

Cenário 3 — Recebível como ativo multi-token (ERC-1155)

Objetivo: tokenizar um lote de recebíveis como ativos distintos sob um mesmo contrato.

1. Aba Projetos de Token → Criar.
2. Tipo: RECEIVABLE_ASSET. Padrão: ERC1155. Chain: Polygon.
3. URI de Metadados: aponte para o JSON/IPFS dos recebíveis.
4. Salvar → Deploy.

Resultado: contrato ERC-1155 implantado, capaz de representar múltiplos recebíveis (IDs distintos) sob o mesmo contrato, com metadados por recebível.

Telas relacionadas

• Guia de Crédito — a fase de tokenização no fluxo completo.
• Políticas de Crédito
• Templates de Cascata (Waterfall)
• Crédito Tokenizado (índice do grupo)