🔷 Integração Blockchain Cardano

Explorador completo da blockchain Cardano integrado ao Crypto Dashboard

Visão Geral

O Que É?

A integração Cardano permite consultar informações em tempo real da blockchain Cardano diretamente no dashboard, sem necessidade de usar explorers externos para operações comuns.

Principais Recursos

✅ Consulta de Saldo: Balance de ADA e tokens nativos
✅ Staking Info: Delegação, pool, recompensas
✅ Histórico de Transações: Completo com análise automática
✅ Metadados Automáticos: Nomes e decimais de tokens
✅ Multi-Wallet: Suporte a múltiplas wallets por utilizador
✅ Configuração DB: APIs e wallets geridas via interface

Por Que Integrar?

Antes:

Abrir CardanoScan em browser
Copiar/colar endereços manualmente
Consultar múltiplas páginas
Sem histórico ou cache

Agora:

Tudo no dashboard
Wallets salvas e acessíveis
Cache de metadados
Análise automática de transações
Ordenação inteligente (recentes primeiro)

Arquitetura

Componentes

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Streamlit)                     │
│  pages/cardano.py - Interface do explorador                 │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                Service Layer (Business Logic)               │
│  services/cardano_api.py - Cliente CardanoScan API          │
│  └─ Cache de metadados (in-memory)                          │
│  └─ Análise de transações                                   │
│  └─ Resolução de nomes/decimais                             │
└─────────────────────┬───────────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │                           │
┌───────▼─────────┐       ┌─────────▼──────────┐
│  Database Layer │       │  External API      │
│  ├─ t_wallet    │       │  CardanoScan v1    │
│  ├─ t_banco     │       │  api.cardanoscan.io│
│  └─ t_api_cardano│       └────────────────────┘
└─────────────────┘

Funcionalidades

1️⃣ Saldo e Tokens

Informações Exibidas

💰 Balance ADA: Saldo total em Lovelace convertido para ADA
📊 Total de Transações: Contador de TXs confirmadas
🪙 Tokens Nativos: Lista completa de tokens no endereço

Resolução de Metadados

Problema Original: Tokens aparecem como hex (ex: "Token 6df63e2f...")

Solução Implementada:

Metadata API Lookup (prioritário)
- Consulta endpoint /asset/{policyId}{assetName} do CardanoScan
- Extrai name, decimals de metadados on-chain
Fallback para Campos Diretos
- Usa assetNameAscii se disponível
- Decodifica hex de assetName para ASCII
Último Recurso
- Mostra policyId truncado se nada funcionar

2️⃣ Staking

Estados Possíveis

1. Delegado a Pool

✅ Delegado
Pool: POOL1 - Example Stake Pool
Taxa: 2.5% | Margem: 340 ADA
Recompensas Totais: 1,250.50 ADA
Disponíveis: 50.25 ADA
Levantadas: 1,200.25 ADA
Stake Controlado: 10,500 ADA

2. Não Delegado (Mas Tem Conta)

⚠️ Não Delegado
Conta de staking existe mas não está delegada a nenhum pool

3. Sem Conta de Staking

ℹ️ Sem Conta de Staking
Este endereço não possui conta de staking registada

3️⃣ Transações

Carregamento Inteligente

Problema: API retorna páginas da antiga para recente

Solução: Busca reversa

# Se total de páginas = 42 e max_pages = 5
# Buscar páginas: 42, 41, 40, 39, 38
start_page = max(1, page_count - max_pages + 1)
for page in range(page_count, start_page - 1, -1):
    fetch_page(page)

Resultado: Com 1 página já vê transações recentes!

Análise Automática

Cada transação é classificada como:

Enviado (Sent) ↗: ADA saiu do endereço (cor vermelha)
Recebido (Received) ↙: ADA entrou no endereço (cor verde)
Contrato (Contract) ↔: Interação com smart contract (cor azul/neutra)

Configuração

Tabelas de Base de Dados

t_api_cardano

CREATE TABLE t_api_cardano (
    api_id SERIAL PRIMARY KEY,
    api_name VARCHAR(100) NOT NULL UNIQUE,
    api_key TEXT NOT NULL,
    base_url TEXT NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    default_address TEXT,
    rate_limit INTEGER,
    timeout INTEGER DEFAULT 10,
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

t_wallet

CREATE TABLE t_wallet (
    wallet_id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES t_users(user_id),
    wallet_name VARCHAR(100) NOT NULL,
    wallet_type VARCHAR(20) NOT NULL,
    blockchain VARCHAR(50) NOT NULL,
    address TEXT NOT NULL,
    stake_address TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    is_primary BOOLEAN DEFAULT FALSE,
    balance_last_sync NUMERIC(20,8),
    last_sync_at TIMESTAMP,
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Tipos de Wallet:

hot: Online, acesso frequente
cold: Offline, armazenamento seguro
hardware: Ledger, Trezor
exchange: Wallet de exchange
defi: Protocolos DeFi

API CardanoScan

Endpoints Utilizados

1. Address Summary

GET /address/summary?address={hex_address}

2. Transaction List

GET /transaction/list?address={hex_address}&pageNo={page}

3. Account Info (Staking)

GET /account/info?address={bech32_address}

4. Asset Metadata

GET /asset/{policyId}{assetName}

Rate Limits

CardanoScan Free Tier:

60 requests/minute
~1 request/second

Casos de Uso

Uso 1: Verificar Saldo de Wallet

Cenário: Admin quer verificar saldo da wallet do fundo antes de fazer swap.

Passos:

Ir para Atividade → Cardano
Endereço já pré-preenchido (default_address da API)
Tab 💰 Saldo e Tokens
Ver ADA disponível e tokens nativos

Uso 2: Acompanhar Recompensas de Staking

Cenário: Utilizador quer saber quanto ganhou de staking.

Passos:

Atividade → Cardano
Inserir endereço da wallet
Tab 🎯 Staking
Ver pool delegado e recompensas

Troubleshooting

Problema: "Nenhuma API Cardano configurada"

Causa: Tabela t_api_cardano vazia ou todas APIs inativas.

Solução:

Ir para Configurações → APIs Cardano
Adicionar nova API:
- Obter key gratuita em: https://cardanoscan.io/api
- Nome: "CardanoScan"
- URL: https://api.cardanoscan.io/api/v1
Verificar que is_active = TRUE

Problema: Erro 429 (Rate Limit)

Causa: Muitas requests em pouco tempo.

Soluções:

Aumentar timeout entre requests
Usar cache mais agressivo
Adicionar segunda API key

Recursos Externos

APIs e Documentação

Tools

← Transaction Model V2 Voltar ao Dashboard →