Especificação Técnica

Protocolo de Liquidez e Eficiência Tributária (BWB V2)

Objetivo Implementar Ganho de Capital com automação de isenção fiscal (R$ 35k).
Premissa Não-Custódia
Arquitetura Convex + React + Smart Contracts + Avenia

Leitura Obrigatória

Para compreender as propostas de implementação e a lógica dos Smart Contracts descritos abaixo, é essencial ler o Relatório Técnico primeiro. Ele contém o detalhamento jurídico e os diagramas de sequência da operação.

Baixar Relatório Completo (PDF)

1 Visão Geral da Arquitetura

O sistema migrará de um modelo de "Distribuição de Dividendos" para um Protocolo de Recompra P2P (Peer-to-Peer). A BWB atuará como orquestradora tecnológica, não como custodiante financeira.

Oráculo de Ativos

Admin da BWB que informa ao sistema a venda física da unidade (input de m²).

Motor Fiscal (Convex)

Backend Web2 que calcula a proporção de queima e gerencia a fila de saques.

Protocolo de Liquidação

Smart Contracts que executam a troca atômica (Tokens ↔ BRLA) de forma global.

Cofres (Smart Lockers)

Contratos individuais que gerenciam o fluxo de saída para maximizar a isenção de R$ 35k.

2 Modelagem de Dados (Convex Schema)

Atualização do arquivo app/src/server/schema.ts.

A. Tabela offerings (Atualização)

Campos imutáveis para a "Trava de Valor".

schema.ts
Copiado! 
offerings: defineTable({
  // ... campos existentes ...
  
  /** METRO QUADRADO (Trava de Ganho de Capital) */
  totalM2: v.number(),          // Área total vendável (Ex: 330.00)
  costPerM2: v.number(),        // Custo travado (Ex: 10000.00)
  remainingM2: v.number(),      // Saldo físico atual
  
  /** Configuração do Token */
  tokenDecimals: v.number(),    // Padrão 18
  smartContractVersion: v.string(), // Controle de versão
}).index('by_status', ['status']),

B. Tabela liquidations (Eventos)

Registro macro do evento de venda física.

schema.ts
Copiado! 
liquidations: defineTable({
  offeringId: v.id('offerings'),
  unitIdentifier: v.string(),   // Ex: "Apt 101"
  m2Sold: v.number(),           // Metragem liquidada
  totalBurnAmount: v.number(),  // Tokens a remover do supply
  brlaDeposited: v.number(),    // Valor depositado no contrato
  
  status: v.union(
    v.literal('pending_fiat'),  // Aguardando Avenia
    v.literal('on_chain_processing'),
    v.literal('completed'),
    v.literal('failed')
  ),
  txHash: v.optional(v.string()),
}).index('by_offering', ['offeringId']),

C. Tabela tax_vaults (Intenções)

Gerencia a inteligência da isenção. Não guarda dinheiro, apenas estado.

schema.ts
Copiado! 
tax_vaults: defineTable({
  userId: v.id('users'),
  walletAddress: v.string(),
  
  /** Controle de Isenção Mensal */
  currentMonthAlienation: v.number(), // Total alienado no mês
  lastUpdateMonth: v.string(),        // "2026-02"
  
  /** Fila de Saques Agendados (Smart Locker) */
  pendingWithdrawals: v.array(v.object({
    amountBrla: v.number(),
    releaseDate: v.number(),          // Timestamp de liberação
    liquidationId: v.id('liquidations'),
    status: v.union(v.literal('locked'), v.literal('ready'), v.literal('claimed'))
  })),
}).index('by_user', ['userId']),

3 Lógica de Smart Contracts (Web3)

A. Mecanismo de Queima: "Rebase Negativo Global"

Iterar por milhares de carteiras para queimar tokens é inviável devido ao custo de gás. A solução é matemática.

  • Lógica: O contrato mantém um índice global liquidationIndex.
  • Evento: Quando 10% do imóvel é vendido, o índice ajusta o saldo visível de todos os usuários em -10%.
  • Vantagem: Custo de Gás O(1) (Constante), independente do número de investidores.

B. Smart Locker (Cofre Individual)

O BRLA não vai direto para a carteira (evitando o gatilho fiscal imediato). Ele vai para um contrato de propriedade do usuário.

  • Função claim(amount): Permite o saque.
  • Regra de Intenção: O Backend da BWB (via Account Abstraction) só assina a liberação de saque até o limite de R$ 34.900,00 por mês.

4 Integração Web2 <> Web3 (Zero Fricção)

A

Onboarding: Assinatura de Intenção

No cadastro, o usuário assina digitalmente (Privy/Notus):

"Autorizo a automação de saques mensais respeitando o limite de isenção."

Implementação: Session Key na Smart Wallet.

B

Fluxo de Liquidação

  1. 1.
    Admin (BWB): Registra venda de 20m² por R$ 300k.
  2. 2.
    Sistema (Avenia): Detecta depósito de R$ 300k no Escrow.
  3. 3.
    Smart Contract: Executa executeGlobalLiquidation.
    • Tokens reduzidos virtualmente (Rebase).
    • R$ 300k movidos para o Distributor.
  4. 4.
    Locker: Saldo alocado nos contratos individuais.
  5. 5.
    Automação (Cron): Verifica limites diariamente.
    if (sacado_mes < 35k) -> sacar_restante();
    else -> aguardar_proximo_mes();

5 Frontend & UX

Painel Administrativo

Assistente de Venda
Simulação: Isso queimará 5.2% do supply total.

Dashboard do Investidor

Gestão de Liquidez
Limite de Isenção (Mês) R$ 15k / R$ 35k
Smart Locker
R$ 15.100,00
Agendado para 01/Fev

7 Plano de Implementação (Roadmap)

Fase 1 Até 15/Fev

Fundação

  • [Backend] Schema Convex (offerings com m²)
  • [Contracts] Token Rebase/Burnable
  • [Frontend] Wizard de Oferta
Fase 2 Até 15/Mar

Motor de Liquidação

  • [Contracts] SmartLocker & Distributor
  • [Integr.] Conexão Avenia (Fiat)
  • [Frontend] Painel de Registro de Venda
Fase 3 Pós-V1

Automação Fiscal

  • [Backend] Cron Jobs para fila de saques
  • [UX] Dashboard de gestão de isenção