# NORIA Protocol · primeira etapa onchain

Protótipo Solidity para compras programadas na **Robinhood Chain Testnet (46630)**. Compilado e testado em EVM local. Ainda não publicado na testnet, não auditado e não habilitado para valores reais. O construtor do agendador recusa redes diferentes de 46630 e 31337.

## O que funciona

- Plano criado pelo dono da carteira com datas absolutas, valor por compra, taxa fixa do executor, limite de preço e tolerância de slippage.
- Os recursos permanecem na carteira até a execução. A autorização ERC-20 é separada; o SDK calcula o teto exato de compras + taxas. Não há autorização ilimitada automática.
- Qualquer executor pode chamar uma parcela elegível. O contrato fixa o destinatário como dono do plano, calcula o mínimo de recebimento e verifica o saldo efetivamente recebido.
- Oráculo imutável com feeds USD dos dois tokens, validação de atualização, round e sequenciador. O preço do token de entrada não é presumido como US$ 1.
- Pausa, retomada e cancelamento pertencem apenas ao dono. Cancelar preserva o plano; não faz transferência nem revoga automaticamente a autorização ERC-20 existente.
- Falhas revertem a compra inteira, inclusive taxas e avanço do calendário. Eventos bem-sucedidos permitem construir um histórico com recibos verdadeiros.
- Executor sequencial com modo de leitura por padrão, simulação antes de enviar, limite operacional de gas, confirmação de recibo e interrupção quando uma transmissão tem resultado incerto.

## Regras que diferem da demonstração visual

A demonstração usa cotações inventadas e pode simular qualquer data. O contrato usa o relógio da blockchain e uma janela de execução por parcela (60 segundos a 24 horas). Preço acima do limite, saldo insuficiente ou rota indisponível deixam a parcela aguardando dentro dessa janela. Depois dela, `expire` registra a data perdida sem cobrar. O executor não pode pular uma parcela válida inventando uma cotação ruim.

A pausa não desloca datas. Após retomar, parcelas vencidas expiram; não existe compra acumulada de períodos antigos. Datas mensais são calculadas no cliente e congeladas em timestamps UTC. A interface de demonstração não cria planos onchain automaticamente.

A taxa fixa de execução é denominada no token de entrada, limitada a 10% da compra neste protótipo e paga apenas em compra concluída. O gas nativo é pago pelo executor e tem teto separado no processo. Não há reembolso variável de gas em dólar.

## Estrutura

- `contracts/LucentScheduler.sol`: planos, permissões, calendário, execução e eventos.
- `contracts/ChainlinkPairOracle.sol`: razão entre dois feeds e guarda de sequenciador.
- `contracts/UniswapV3Adapter.sol`: par e router imutáveis, aprovação exata por execução.
- `contracts/test/Mocks.sol`: tokens com mint livre, feeds e router controláveis para testes.
- `scripts/keeper-core.mjs`: motor testado do executor; `keeper.mjs`: processo de operação.
- `sdk/client.mjs`: conversão do plano visual para calldata e autorização exata, sem assinatura.
- `reports/test-results.txt`: saída real dos testes; `reports/network-check.json`: verificação de conectividade.

## Executar localmente

Requer Node.js 24 e pnpm. As versões estão fixadas no lockfile.

```sh
pnpm install --frozen-lockfile
pnpm compile
pnpm test
pnpm check:testnet
pnpm deploy:testnet
```

Os testes iniciam uma EVM isolada em memória, implantam os contratos e enviam transações locais. Não precisam de carteira pessoal, saldo ou conexão com a Robinhood Chain. O comando de deploy sem `--broadcast` apenas apresenta a implantação planejada.

## Implantar a primeira versão na testnet

1. Obter um RPC acessível para chain ID 46630 e uma carteira dedicada com ETH de teste. O endpoint público oficial não resolveu DNS neste ambiente durante esta entrega.
2. Configurar `RH_RPC_URL` e `DEPLOYER_PRIVATE_KEY` localmente. Não colocar chaves no site, no Git ou na conversa. O arquivo `.env.example` é apenas um exemplo; os comandos leem variáveis de ambiente. Para carregar um `.env` com Node, usar `node --env-file=.env scripts/deploy-testnet.mjs --broadcast`.
3. Rodar `pnpm compile`, `pnpm check:testnet` e então `pnpm deploy:testnet --broadcast`.
4. Salvar o manifesto gerado em `deployments/`. Ele contém os endereços e hashes das nove implantações. Se houver falha parcial, conferir a carteira no explorer antes de repetir.
5. A implantação inicial cria um **par de teste próprio tUSD/tETH e mocks**. Os tokens precisam ser mintados, o router abastecido e os feeds atualizados para realizar compras. Esses controles são públicos e servem somente para testes; qualquer pessoa pode alterar os mocks. As referências de preços vencem após uma hora.
6. Criar um plano e aprovar seu orçamento exato pela carteira de teste. A aprovação autoriza o agendador a gastar esse token conforme planos ativos; revogá-la impede compras futuras.
7. Configurar `LUCENT_SCHEDULER_ADDRESS`, `KEEPER_PRIVATE_KEY` de uma segunda carteira e seu saldo de gas. Começar com `pnpm keeper`. Para enviar uma rodada, `pnpm keeper --broadcast`. Para operação contínua, `pnpm keeper --broadcast --watch` em um processo supervisionado.

O executor não foi iniciado como serviço permanente. O lock local evita dois processos nesse checkout; não substitui coordenação entre máquinas. Após queda, confira a transação pendente e o nonce antes de remover um lock antigo. Requer RPC confiável, saldo de teste e supervisão. Com uma confirmação, um recibo ainda pode sofrer reorganização: nenhum resultado deve ser apresentado como finalidade econômica definitiva.

## Dependências pendentes para mercado real

O adaptador implementa o **ISwapRouter original do Uniswap V3**, cuja struct inclui `deadline`. Não é compatível por simples troca de endereço com SwapRouter02, Universal Router ou RFQ. Nenhum endereço de DEX da Robinhood Chain foi adotado sem validação. Ainda faltam contratos verificados, interface exata, pool, liquidez, feeds e seus heartbeats/sequenciador na rede escolhida, além de testes em fork e revisão independente.

O suporte desta etapa é a ERC-20 comum, sem taxas de transferência nem rebase, em um único par por implantação. Stock Tokens reais precisam de integração específica para disponibilidade, pausas e eventos corporativos; não estão habilitados. Os feeds de teste não representam dados Chainlink reais. Não há upgrade nem chave administrativa no agendador, mas a segurança depende do comportamento dos contratos externos imutavelmente configurados.

Antes de mainnet são necessários análise de ameaças, fuzz/invariantes adicionais, auditoria, política de ativos/rotas e teste de operação/reorganização. O bloqueio de mainnet é intencional nesta versão.

## Referências verificadas em 12/09/2026

- [Rede e RPC oficiais](https://docs.robinhood.com/chain/connecting/)
- [Implantação de contratos](https://docs.robinhood.com/chain/deploy-smart-contracts/)
- [Oráculos e preços](https://docs.robinhood.com/chain/oracles-and-price-feeds/)
- [Integração com Stock Tokens](https://docs.robinhood.com/chain/building-with-stock-tokens/)
- [Uniswap V3: swaps de um par](https://developers.uniswap.org/docs/protocols/v3/guides/swapping/single-hop-swapping)
- [OpenZeppelin ERC-20 / SafeERC20](https://docs.openzeppelin.com/contracts/5.x/api/token/erc20)