Refuconnect transforma Pix em cripto em segundos, oferecendo depósitos instantâneos, custódia segura e suporte a múltiplas redes para que refugiados e migrantes possam gerenciar seus ativos digitais com a mesma agilidade de uma conta tradicional.

• Visão Geral
• Features & Motivação
• Arquitetura
• Getting Started
• API Reference
• Operação & Observabilidade
• Roadmap
• Contribuindo

Refuconnect é um backend Express focado em on/off ramp para comunidades que dependem de Pix no Brasil. O serviço integra Woovi/OpenPix para gerar cobranças, interage com um contrato ERC-20 (BRLR) em redes de teste Base/Arbitrum Sepolia e prepara o terreno para adoção de FHE (Fhenix) em fluxos sensíveis.

• Node.js + Express
• Ethers v6 para interações on-chain
• Jest + Supertest
• Integração Woovi/OpenPix para Pix automático

Deposite com Pix e receba criptomoedas instantaneamente, com uma experiência simples, rápida e segura que conecta sua wallet a múltiplas redes e mantém seus ativos protegidos pelas melhores práticas de infraestrutura cripto.

• Depósitos instantâneos: converte Pix em BRLR em segundos mediante webhooks da Woovi.
• Seguro & confiável: validações de payload, logs estruturados e possibilidade de rodar com chaves isoladas.
• Multichain-ready: suporte atual a Base/Arbitrum Sepolia com planos para Coinbase, Ethereum Sepolia e Fhenix FHERC20.
• Fluxos claros: endpoints de mint, burn, consulta de saldo e geração de QR Code Pix.
• Pronto para dashboard: expõe status de contrato, saldos e transações para integrar com UI/analytics.

crypto-onramp-server/
├─ src/
│  ├─ index.js               # Servidor Express principal (rotas HTTP)
│  ├─ contracts/
│  │  ├─ BRLRRefuconnect.sol # Contrato ERC-20 custom BRLR
│  │  └─ ERC20.json          # ABI utilizada para interagir com o contrato
│  └─ services/
│     ├─ blockchain.js       # Conexão com provider e informações do contrato
│     ├─ burn.js             # Regras de validação/execução de burn (placeholder)
│     ├─ mint.js             # Validações e mint on-chain
│     ├─ transactions.js     # Consulta de transações via API externa
│     └─ woovi.js            # Integração com API Woovi (PIX)
├─ test/
│  └─ server.test.js         # Testes com Jest e Supertest
├─ test-dummy/
│  └─ webhook-payload.json   # Payload de exemplo para testes do webhook
├─ jest.config.js            # Configuração de testes
├─ Makefile                  # Atalhos para testar endpoints com curl
└─ ...

Fluxo principal

1. UI/usuário cria um pedido Pix (POST /get_qrcode).
2. Woovi dispara webhook OPENPIX:CHARGE_COMPLETED com metadados da wallet.
3. Backend valida o evento, executa mint via Ethers e retorna detalhes da transação.

• Node.js >= 18
• npm (instalado com Node)
• Endpoint RPC Base/Arbitrum ou Ethereum Sepolia
• Conta Woovi/OpenPix ativa e chave de API

npm install

Crie um .env com base na configuração simplificada:

# .env
PORT=3000

# Escolha a rede: 'base-sepolia' ou 'ethereum-sepolia'
NETWORK=base-sepolia

# Credenciais on-chain
PRIVATE_KEY=sua_chave_privada_aqui
CONTRACT_ADDRESS=0x...

# Integração Woovi
WOOVI_API_KEY=your_woovi_api_key_here
WOOVI_API_URL=https://api.woovi.com

# CORS
CORS_ORIGINS=*

# RPC customizado
RPC_URL=https://seu-rpc-customizado.com

# Chain ID customizado
CHAIN_ID=84532

Para ethereum-sepolia, forneça seu próprio RPC_URL com chave Infura/Alchemy.

# Rodar servidor
npm start

# Hot reload
npm run dev

npm test

Use o Makefile para cURLs de exemplo:

make list               # Lista comandos disponíveis
make ping               # Verifica disponibilidade da API
make webhook SAMPLE=1   # Dispara payload de webhook de exemplo

Retorna estado atual da aplicação, rede e informações do contrato (wallet, saldo, token).

• Evento esperado: OPENPIX:CHARGE_COMPLETED.
• charge.comment precisa conter o endereço Ethereum do beneficiário.
• valueWithDiscount (fallback para value) em centavos vira o montante BRLR.
• Resposta traz hash da transação, block number, gas usado, amount e explorer.

Apenas registra a intenção de burn no log enquanto o fluxo on-chain completa é desenvolvido.

Consulta saldo formatado (balance) e valor bruto (balanceRaw) diretamente do contrato ERC-20.

Gera cobrança Pix via Woovi, retornando QR Code, BR Code, link de pagamento, taxas e expiração.

Payloads de exemplo estão em test-dummy/webhook-payload.json e no Makefile.

curl http://localhost:3000/

{
  "status": "OK",
  "message": "Refuconnect API ativa",
  "blockchain": {
    "network": "Base Sepolia",
    "contract": "0x...",
    "wallet": "0x...",
    "walletBalance": "0.10 ETH",
    "token": {
      "name": "BRLR Token",
      "symbol": "BRLR",
      "decimals": 18,
      "totalSupply": "1234.56"
    }
  }
}

curl -X POST http://localhost:3000/webhook/charge_completed \
  -H "Content-Type: application/json" \
  -d '{
        "event": "OPENPIX:CHARGE_COMPLETED",
        "charge": {
          "comment": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
          "valueWithDiscount": 250,
          "transactionID": "a98a3ab821b0468ca5ad450f8745bfb3",
          "status": "COMPLETED"
        }
      }'

{
  "success": true,
  "message": "Mint executado a partir do charge_completed",
  "data": {
    "txHash": "0x123...",
    "blockNumber": 123456,
    "gasUsed": "55000",
    "walletAddress": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
    "amount": "2.50",
    "wooviTransactionID": "a98a3ab821b0468ca5ad450f8745bfb3",
    "wooviCorrelationID": "correlation-id",
    "explorer": "https://sepolia.basescan.org/tx/0x123..."
  }
}

curl -X POST http://localhost:3000/burn \
  -H "Content-Type: application/json" \
  -d '{
        "from": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
        "amount": "50"
      }'

{
  "success": true,
  "message": "Burn executado com sucesso!",
  "data": {
    "txHash": "0x456...",
    "blockNumber": 123789,
    "gasUsed": "60000",
    "from": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
    "amount": "50",
    "method": "burn",
    "explorer": "https://sepolia.basescan.org/tx/0x456..."
  }
}

curl http://localhost:3000/balance/0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b

{
  "success": true,
  "data": {
    "address": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
    "balance": "150.00",
    "balanceRaw": "150000000000000000000"
  }
}

curl -X POST http://localhost:3000/get_qrcode \
  -H "Content-Type: application/json" \
  -d '{
        "wallet_address": "0x846489b48bf8a7e2ef602bdcbc6beeefd6c9082b",
        "value": 250
      }'

{
  "success": true,
  "message": "PIX charge criado com sucesso via Woovi!",
  "data": {
    "qrCodeImage": "https://woovi.com/qrcode/...",
    "brCode": "0002012658...",
    "transactionId": "transaction-id",
    "value": 250,
    "fee": 0,
    "status": "ACTIVE",
    "paymentLinkUrl": "https://checkout.woovi.com/...",
    "expiresDate": "2025-11-08T12:00:00.000Z"
  }
}

• Logs estruturados com timestamp, payload recebido e resultado das transações.
• Redirecione stdout/stderr para sua stack de observabilidade (Datadog, Loki, Splunk, etc.).
• Monitore falhas na Woovi, transações revertidas e saldo insuficiente do deployer.

• Webhook não chega: valide URL pública e WOOVI_API_KEY.
• Mint falhou: confira saldo da carteira (GET /) e permissões do PRIVATE_KEY.
• CORS bloqueando: ajuste CORS_ORIGINS para incluir domínios do dashboard.

1. Construir API Express com endpoints de mint e burn. ✅
2. Integrar com contrato ERC-20 em testnet Base/Arbitrum Sepolia. ✅
3. Validar fluxo completo de on/off ramp com usuários reais. 🚧
4. Migrar para FHERC20 da Fhenix quando disponível. 🗓️
5. Expandir suporte multi-chain (Coinbase, Optimism) e dashboards analíticos. 🗓️

1. Faça fork do repositório.
2. Crie uma branch (feature/refactor-mint-service).
3. Rode testes e linter antes do PR.
4. Abra PR descrevendo problema, solução e resultados dos testes.

Sugestões do ETH Latam ou feedbacks de campo são super bem-vindos via Issues.

• Hackathon ETH Latam 2025 — Equipe Refuconnect.
• Comunidade Fhenix e Woovi pelo suporte técnico.

ISC