Integração Blockchain

Guia completo para integração com a infraestrutura blockchain do Ekonavi, incluindo contratos inteligentes, tokens ERC1155, e integração multi-chain.

Visão Geral

Arquitetura Blockchain

┌─────────────────────────────────────────────────────────────────┐
│                    Blockchain Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│  Application Layer (Frontend + API)                             │
│  ├── ekonavi.com        ├── admin.ekonavi.com                   │
│  ├── Web3 Wallet Integration (MetaMask, WalletConnect)          │
│  └── ABCI Routes (/abci/contracts/*)                            │
├─────────────────────────────────────────────────────────────────┤
│  Smart Contract Layer                                           │
│  ├── EkosisTokens.sol (ERC1155 Main Contract)                   │
│  ├── EkosisTokenManager.sol (Workflow Helper)                   │
│  ├── Upgradeable Proxy (UUPS Pattern)                           │
│  └── Access Control (Role-based permissions)                    │
├─────────────────────────────────────────────────────────────────┤
│  Blockchain Networks                                            │
│  ├── Ethereum Mainnet (Production)                              │
│  ├── Polygon (Low-cost operations)                              │
│  ├── Ethereum Sepolia (Testing)                                 │
│  └── Hardhat Local Network (Development)                        │
└─────────────────────────────────────────────────────────────────┘

Token Economics

Token Ranges e Tipos

// Role Tokens (Soulbound) - Range: 10000-19999
uint256 public constant PRODUCER_ROLE_TOKEN = 10000;
uint256 public constant VERIFIER_ROLE_TOKEN = 10100;
uint256 public constant VALUATOR_ROLE_TOKEN = 10200;
uint256 public constant CERTIFIER_ROLE_TOKEN = 10300;
uint256 public constant ADMIN_ROLE_TOKEN = 10400;

// Entity Tokens (Transferable) - Range: 1000-9999
uint256 public constant REPORT_TOKEN = 1000;
uint256 public constant VERIFICATION_TOKEN = 1100;
uint256 public constant VALUATION_TOKEN = 1200;
uint256 public constant CERTIFICATE_TOKEN = 1300;
uint256 public constant PROJECT_TOKEN = 1400;

// System Tokens - Range: 20000+
uint256 public constant CARBON_CREDIT_TOKEN = 20000;
uint256 public constant METHODOLOGY_TOKEN = 20100;

Token Metadata Structure

interface TokenMetadata {
  tokenId: number;
  tokenType: 'role' | 'entity' | 'system';
  name: string;
  description: string;
  image: string;
  attributes: Array<{
    trait_type: string;
    value: string | number;
  }>;
  external_url?: string;
}

Contratos Inteligentes

EkosisTokens.sol - Contrato Principal

Contrato ERC1155 upgradável com suporte a tokens soulbound (não-transferíveis) para papéis e tokens transferíveis para entidades ESG.

Funcionalidades:

mintRoleToken() - Minta tokens de papel (soulbound)
mintEntityToken() - Minta tokens de entidade (transferíveis)
Prevenção de transferência de tokens soulbound
Controle de acesso baseado em papéis (MINTER_ROLE, UPGRADER_ROLE)
Padrão de proxy UUPS para upgrades

EkosisTokenManager.sol - Helper de Workflows

Automação de workflows ESG:

createProject() - Cria projeto e minta token
submitReport() - Submete relatório e minta token
completeVerification() - Completa verificação e minta token
issueCertificate() - Emite certificado e minta token

ABCI Routes - Abstração Blockchain

As rotas ABCI (Application Blockchain Interface) fornecem abstração blockchain para que a API possa interagir com qualquer rede sem conhecer detalhes específicos.

Endpoints ABCI

Endpoint	Método	Descrição
`/abci/contracts/mint-role-token`	POST	Mintar token de papel na carteira do usuário
`/abci/contracts/mint-entity-token`	POST	Mintar token de entidade
`/abci/contracts/transfer-token`	POST	Transferir token entre carteiras
`/abci/contracts/revoke-token`	POST	Revogar token
`/abci/blockchains/list`	GET	Listar redes blockchain suportadas
`/abci/contracts/token-balance`	GET	Consultar saldo de tokens
`/abci/tokens/user-balance`	GET	Recuperar todos os tokens de um usuário

Integração com Carteiras Web3

MetaMask Integration

A plataforma suporta conexão com MetaMask para:

Autenticação via assinatura de mensagem
Visualização de tokens na carteira
Troca de rede blockchain

WalletConnect Integration

Suporte a WalletConnect para carteiras móveis e desktop.

Wallet Authentication Flow

sequenceDiagram
    participant U as User
    participant W as Wallet (MetaMask)
    participant F as Frontend
    participant API as API
    participant BC as Blockchain

    U->>F: Click "Connect Wallet"
    F->>W: Request wallet connection
    W->>U: Prompt for approval
    U->>W: Approve connection
    W->>F: Return account address

    F->>API: Request authentication challenge
    API->>F: Return nonce + challenge message
    F->>W: Request message signature
    W->>U: Prompt to sign message
    U->>W: Sign message
    W->>F: Return signature

    F->>API: Submit address + signature
    API->>API: Verify signature
    API->>BC: Check role tokens
    BC->>API: Return token balances
    API->>F: Return JWT + user roles
    F->>U: Authenticated session

Multi-Chain Support

Redes Suportadas

Rede	Chain ID	Uso	Block Explorer
Ethereum Mainnet	1	Produção	etherscan.io
Polygon	137	Operações low-cost	polygonscan.com
Ethereum Sepolia	11155111	Testes	sepolia.etherscan.io
Hardhat	31337	Desenvolvimento local	—

Segurança ABCI

Middleware de Segurança

Todas as rotas ABCI requerem autenticação JWT
Permissões elevadas (admin ou sistema) necessárias
Logging de todas as operações para auditoria de segurança

Rate Limiting

10 requests por minuto para operações ABCI
Rate limiting por usuário ou IP

Validação de Transações

Pre-flight checks antes de cada operação de minting:

Validar formato do endereço Ethereum
Verificar associação do usuário com o endereço
Validar se a blockchain é suportada e ativa
Verificar duplicidade de tokens de papel
Verificar status do contrato

Workflows de Integração

Fluxo de Aprovação de Papel

sequenceDiagram
    participant A as Admin
    participant API as API
    participant ABCI as ABCI Layer
    participant BC as Blockchain

    A->>API: PUT /v1/admin/role-requests/{id}/approve
    API->>API: Update role request status
    API->>ABCI: POST /abci/contracts/mint-role-token
    ABCI->>BC: Call mintRoleToken()
    BC->>BC: Mint token to user wallet
    BC->>ABCI: Return transaction receipt
    ABCI->>API: Return transaction details
    API->>API: Update user roles in database
    API->>A: Return success response

Fluxo de Certificação ESG

sequenceDiagram
    participant C as Certifier
    participant API as API
    participant ABCI as ABCI Layer
    participant IPFS as IPFS
    participant BC as Blockchain

    C->>API: POST /v1/certifiers/certificates
    API->>IPFS: Store certificate metadata
    IPFS->>API: Return IPFS hash
    API->>ABCI: POST /abci/contracts/mint-entity-token
    ABCI->>BC: Call mintEntityToken()
    BC->>BC: Mint certificate NFT
    BC->>ABCI: Return transaction receipt
    ABCI->>API: Return token details
    API->>API: Update database with token info
    API->>C: Return certificate with NFT details

Visão Geral​

Arquitetura Blockchain​

Token Economics​

Token Ranges e Tipos​

Token Metadata Structure​

Contratos Inteligentes​

EkosisTokens.sol - Contrato Principal​

EkosisTokenManager.sol - Helper de Workflows​

ABCI Routes - Abstração Blockchain​

Endpoints ABCI​

Integração com Carteiras Web3​

MetaMask Integration​

WalletConnect Integration​

Wallet Authentication Flow​

Multi-Chain Support​

Redes Suportadas​

Segurança ABCI​

Middleware de Segurança​

Rate Limiting​

Validação de Transações​

Workflows de Integração​

Fluxo de Aprovação de Papel​

Fluxo de Certificação ESG​