> ## Documentation Index > Fetch the complete documentation index at: https://docs.levery.io/llms.txt > Use this file to discover all available pages before exploring further. # Arquitetura > Um aprofundamento no design on-chain de Levery: permissionamento, taxas dinâmicas guiadas por oráculo e posições de liquidez soulbound. Levery é uma infraestrutura de mercado on-chain permissionada, projetada para instituições reguladas. Em vez de depender de front-ends ou middleware off-chain para aplicar políticas, Levery embute controles de compliance e operacionais diretamente na execução dos smart contracts. Cada caminho de transação, da admissão de carteira às ações do ciclo de vida de liquidez e à execução de swaps, executa verificações determinísticas antes de qualquer mudança de estado. Chamadas não conformes revertem com motivos explícitos; ações conformes executam normalmente. Isso dá às instituições aplicação uniforme, resultados auditáveis e governança resistente a adulteração em todas as interações de usuário. A arquitetura on-chain de Levery é organizada em domínios modulares que trabalham juntos para oferecer: permissionamento, validação de identidade, integridade de preços, controles econômicos, governança, aplicação do ciclo de vida e operações de tesouraria transparentes. As instituições podem ajustar o comportamento do ambiente por meio de parâmetros governados (por pool ou globais) sem enfraquecer as garantias de segurança centrais. *** ## Domínios Principais ### Permissionamento e Controle de Admissão Levery aplica “quem pode fazer o quê” na camada de execução. Antes de swaps ou ações de liquidez, os contratos validam se a conta iniciadora está autorizada e atende aos requisitos de política do pool (por exemplo, acesso baseado em papéis, regras da instituição e permissões derivadas de KYC/KYB). Isso garante que apenas agentes verificados possam acessar pools, adicionar/remover liquidez ou negociar, mantendo o sistema não custodial. ### Pontos de Entrada Controlados para Swaps e Liquidez Levery separa os pontos de entrada de transação por intenção: #### Swap **A entrada de swap** é roteada por um caminho de execução em conformidade que vincula a identidade do usuário à chamada e evita o recebimento acidental ou não autorizado de tokens.
```mermaid theme={null} --- config: theme: neutral --- flowchart TD S_A["Requisição de swap"] --> S_B{"Verificações de admissão + acesso"} S_B -->|Rejeitado| S_X["Rejeitar swap"] S_B -->|Permitido| S_C["Resolver contexto de preços (referência de mercado + estado do pool)"] S_C --> S_D["Calcular taxas (taxa base + ajuste dinâmico se habilitado)"] S_D --> S_E["Executar swap + atualizar estado do pool"] S_E --> S_F["Liquidar resultados + aplicar taxa de serviço (momento: BEFORE ou AFTER; cobrada sobre deltas reais)"] S_F --> S_G["Emitir eventos (política, taxas, execução, taxa de serviço)"] ```
```mermaid theme={null} --- config: theme: dark --- flowchart TD S_A["Requisição de swap"] --> S_B{"Verificações de admissão + acesso"} S_B -->|Rejeitado| S_X["Rejeitar swap (motivo de retorno)"] S_B -->|Permitido| S_C["Resolver contexto de preços (referência de mercado + estado do pool)"] S_C --> S_D["Calcular taxas (taxa base + ajuste dinâmico se habilitado)"] S_D --> S_E["Executar swap + atualizar estado do pool"] S_E --> S_F["Liquidar resultados + aplicar taxa de serviço (momento: BEFORE ou AFTER; cobrada sobre deltas reais)"] S_F --> S_G["Emitir eventos (política, taxas, execução, taxa de serviço)"] ```
As taxas de serviço são sempre denominadas no **token de entrada**. O momento da cobrança depende do tipo de swap: * **Swaps de entrada exata:** coletadas no `beforeSwap` (BEFORE). * **Swaps de saída exata:** coletadas no `afterSwap` (AFTER). As taxas são direcionadas para o cofre divisor de pagamentos, que permite compartilhamento transparente de receita entre provedor e instituição. #### Liquidez **A entrada de liquidez** é mediada por um gerenciador de posições que executa verificações do ciclo de vida em mint, aumento, redução e burn, de modo que o permissionamento permaneça aplicado em toda a jornada do LP, e não apenas no momento da criação. Essa estrutura torna a aplicação de políticas consistente, mantendo a experiência do usuário previsível e adequada às instituições.
```mermaid theme={null} --- config: theme: neutral --- flowchart TD L_A["Requisição de ação de liquidez (criar, adicionar, remover, encerrar)"] --> L_B{"Verificações de admissão + acesso ao pool"} L_B -->|Rejeitado| L_X["Rejeitar ação"] L_B -->|Permitido| L_C["Validar autoridade (vincular proprietário na criação; verificar proprietário/destinatário na alteração)"] L_C --> L_D["Calcular deltas de ativos + validar limites (prazos, valores mínimos, restrições de política)"] L_D --> L_E["Executar via ponto de entrada do ciclo de vida de liquidez"] L_E --> L_F["Liquidar ativos conforme necessário (entradas, saídas, reembolsos; regras de política + ativos)"] L_F --> L_G["Atualizar posição + estado do pool"] L_G --> L_H["Emitir eventos estruturados (posição, deltas, taxas, resultados)"] ```
```mermaid theme={null} --- config: theme: dark --- flowchart TD L_A["Requisição de ação de liquidez (criar, adicionar, remover, encerrar)"] --> L_B{"Verificações de admissão + acesso ao pool"} L_B -->|Rejeitado| L_X["Rejeitar ação (motivo de retorno)"] L_B -->|Permitido| L_C["Validar autoridade (vincular proprietário na criação; verificar proprietário/destinatário na alteração)"] L_C --> L_D["Calcular deltas de ativos + validar limites (prazos, valores mínimos, restrições de política)"] L_D --> L_E["Executar via ponto de entrada do ciclo de vida de liquidez"] L_E --> L_F["Liquidar ativos conforme necessário (entradas, saídas, reembolsos; regras de política + ativos)"] L_F --> L_G["Atualizar posição + estado do pool"] L_G --> L_H["Emitir eventos estruturados (posição, deltas, taxas, resultados)"] ```
### Integridade de Preços Guiada por Oráculo e Taxas Dinâmicas Levery integra oráculos descentralizados de feed de preços para ancorar a execução a referências externas de mercado e calcular taxas dinâmicas. Os pools podem ser configurados com uma referência de oráculo e regras de comparação, e o protocolo ajusta as taxas em resposta à divergência entre oráculo e pool para reduzir fluxo tóxico e proteger provedores de liquidez, mantendo preços competitivos para traders. Para preservar a integridade de preços, a camada de oráculos inclui salvaguardas como: * **Consultas sob demanda:** feeds de preço são invocados apenas em hooks de swap, minimizando o overhead de gas para operações de liquidez. * **Normalização de decimais:** ajustes seguros para alinhar decimais do feed com os decimais do token, evitando precificação incorreta. * **Proteção contra preço zero:** reversão imediata em valores de oráculo zero ou obsoletos para evitar cálculos de taxa errôneos. #### Integração de Oráculo de Feed de Preços Levery oferece suporte à configuração de oráculo por pool via `setPoolOracle()`. * **Adaptadores e decimais** – Cada pool armazena `{oracle, compareWithPrice0}`. O valor retornado do feed é escalado para corresponder aos decimais do token antes da comparação. * **Lógica de desvio** – `beforeSwap` calcula `price0 / price1` on-chain, busca o preço de mercado `M` e aplica a fórmula: $$ F_{swap}=F_{base}+\bigl|\tfrac{P_{onchain}-M}{M}\bigr|\times \texttt{deviationFeeFactor} $$ * **Multiplicador limitado** – `deviationFeeFactor` (ppm) é limitado a $0,1$, garantindo que a taxa nunca ultrapasse o delta absoluto de preço. Considere: * $P_0$ e $P_1$ como os preços atuais do ativo 0 e do ativo 1, respectivamente. * $M$ como o preço de mercado em tempo real do Oráculo. * $\alpha$ `deviationFeeFactor` como o multiplicador de taxa do provedor de liquidez. * $F_{\text{base}}$ como a taxa base para o swap. * $F_{\text{pool}}$ como a taxa específica do pool para o swap, que tem precedência sobre $F_{\text{base}}$ se definida. #### Definição Inicial da Taxa de Swap A taxa inicial de swap $F_{\text{swap}}$ é definida como: $$ F_{\text{swap}} = \begin{cases} F_{\text{pool}} & \text{se } F_{\text{pool}} \neq 0 \\ F_{\text{base}} & \text{caso contrário} \end{cases} $$ #### Comparação de Preço e Ajuste de Taxa Se um oráculo de preço de mercado estiver definido, ajustamos $F_{\text{swap}}$ com base na comparação de preços: **Se `compareWithPrice0` for verdadeiro:** $$ F_{\text{swap}} = \begin{cases} F_{\text{swap}} + \left( \frac{P_0 - M}{M} \times \alpha \right) & \text{se } P_0 > M \text{ e } \text{params.zeroForOne} \\ F_{\text{swap}} + \left( \frac{M - P_0}{M} \times \alpha \right) & \text{se } P_0 < M \text{ e não } \text{params.zeroForOne} \\ F_{\text{swap}} & \text{caso contrário} \end{cases} $$ **Caso contrário:** $$ F_{\text{swap}} = \begin{cases} F_{\text{swap}} + \left( \frac{M - P_1}{M} \times \alpha \right) & \text{se } P_1 < M \text{ e } \text{params.zeroForOne} \\ F_{\text{swap}} + \left( \frac{P_1 - M}{M} \times \alpha \right) & \text{se } P_1 > M \text{ e não } \text{params.zeroForOne} \\ F_{\text{swap}} & \text{caso contrário} \end{cases} $$ #### Atualização Final da Taxa A taxa de swap atualizada é usada para atualizar a taxa dinâmica de LP: $$ \text{poolManager.updateDynamicLPFee}(key, F_{\text{swap}}) $$ ### Posições de Liquidez Intransferíveis As posições de liquidez são representadas como tokens ERC-721 intransferíveis vinculados ao proprietário verificado. Esse design impede transferências não autorizadas, preserva o status de conformidade ao longo de todo o ciclo de vida e simplifica relatórios de conformidade ao garantir que a titularidade do LP permaneça rastreável e imutável no nível do protocolo. Os metadados da posição podem ser gerados em um formato padronizado e amigável para auditores, permitindo revisões transparentes do estado da posição (propriedade, faixas e outras propriedades relevantes) sem depender de interpretação off-chain. ### Taxa de Serviço Configurável e Tesouraria Transparente Levery oferece suporte a uma taxa de serviço programável que é direcionada para um cofre on-chain. A taxa de serviço pode ser aplicada de forma previsível nos fluxos de swap e é acumulada de forma transparente para fins contábeis. A lógica de distribuição do cofre é executada por contrato e registrada on-chain, permitindo visibilidade clara da tesouraria e modelos opcionais de compartilhamento de receita entre stakeholders (por exemplo, provedor/instituição).
```mermaid theme={null} --- config: theme: neutral --- flowchart TD F_A["Swap executado"] --> F_B["Calcular taxa de serviço (com base nos deltas reais do swap)"] F_B --> F_C["Transferir taxa para Cofre de Taxa de Serviço (PaymentSplitter)"] F_C --> F_D["Distribuir aos beneficiários (conforme participações configuradas)"] ```
```mermaid theme={null} --- config: theme: dark --- flowchart TD F_A["Swap executado"] --> F_B["Calcular taxa de serviço (com base nos deltas reais do swap)"] F_B --> F_C["Transferir taxa para Cofre de Taxa de Serviço (PaymentSplitter)"] F_C --> F_D["Distribuir aos beneficiários (conforme participações configuradas)"] ```
### Governança, Administração e Segurança Operacional A administração on-chain permite que instituições: * atualizem administradores e funções privilegiadas, * ajustem parâmetros de taxa globalmente ou por pool, * atualizem referências de oráculo e configurações de pool, * substituam o gerenciador de permissões sob procedimentos controlados. Levery também inclui controles operacionais robustos, como pausas globais e por pool. Esses controles permitem que instituições isolem incidentes, respondam a eventos de risco e cumpram solicitações procedimentais, sem comprometer garantias não custodiadas (o protocolo restringe ações, mas não apreende fundos dos usuários). ### Auditabilidade por Design Cada decisão e etapa de execução emite eventos on-chain estruturados que vinculam a aplicação de políticas ao ciclo de vida da transação. Isso torna as auditorias diretas: as instituições podem reconstruir “quem tentou o quê, sob qual política e o que aconteceu” diretamente a partir de dados da cadeia. O resultado é uma trilha de auditoria determinística e orientada a evidências, alinhada às expectativas de conformidade institucional. *** ## Modelo de Permissionamento e Governança As permissões são representadas como habilitações explícitas e consultáveis. Isso mantém a aplicação determinística e facilita auditorias. ### Ciclo de vida das permissões A pilha de compliance da instituição avalia KYC/KYB/AML e produz uma decisão. O registro de permissões é atualizado (conceder/revogar) para ações de trade e liquidez. Chamadas de trade e liquidez verificam habilitações antes de prosseguir. ### Controles de emergência Um disjuntor de nível de provedor pode interromper a atividade do protocolo em todos os mercados durante incidentes sistêmicos. Operadores podem isolar um único mercado (pool) sem impactar os demais. Ações de pausa/retomada são registradas como eventos e indexadas, permitindo revisão pós-incidente. *** ## Por Que Este Design Levery é construída em torno de um princípio simples: a garantia regulatória deve estar embutida na lógica do protocolo, não adicionada depois. Ao realocar controles de compliance, verificações de risco, regras de integridade de preços e governança para dentro dos smart contracts, Levery alcança aplicação consistente, forte auditabilidade e flexibilidade operacional, mantendo os mercados não custodiados e prontos para instituições. Identidade, permissões e regras de risco são aplicadas por meio de uma camada explícita de permissões, além de controles operacionais auditados. Indexação orientada a eventos, canonização e snapshots determinísticos sustentam trilhas de auditoria, relatórios e análises de risco. Os usuários mantêm controle direto de fundos e chaves por padrão, minimizando risco de contraparte e custódia. A política é aplicada no momento da execução (e não em monitoramento pós-trade). Para instituições que exigem custódia, Levery também pode integrar armazenamento de chaves e fluxos de assinatura baseados em HSM sem alterar garantias de liquidação on-chain. *** ## Arquitetura Off-chain: Indexação, Snapshots e Relatórios Levery usa um pipeline de indexação orientado a eventos, projetado para **correção sob reorgs**, **idempotência** e **consultas rápidas de UI**. ### Indexadores A camada de workers executa vários indexadores em paralelo. As principais responsabilidades incluem: * **Indexador de configuração do protocolo:** captura configuração global e atualizações de política por mercado em um modelo de snapshot `System` e `Pool`. * **Indexador de permissões:** materializa as permissões mais recentes por conta em um modelo de snapshot `Permission`. * **Indexador de atividade de mercado:** canoniza swaps e mudanças de liquidez, atribui taxas de serviço e grava fatos normalizados. * **Indexador de preços:** ingere atualizações de feed de oráculo e produz preços tanto *latest* quanto *time-slot* para valuation histórico. * **Indexadores de saldo:** criam snapshots diários e “atuais” de saldo de tokens para cada conta. * **Indexador de portfólio:** avalia saldos + posições + taxas devidas nos tempos de snapshot para relatórios e análises. * **Indexadores de métricas:** computam métricas de pool e de ativos para páginas de lista rápidas (TVL, volume, APR, market cap, FDV).
```mermaid theme={null} --- config: theme: neutral --- flowchart TB RPC[RPC / Logs da cadeia]:::box IDX[Indexadores]:::box EVT[(Armazenamento de eventos)]:::db SNAP[(Tabelas de snapshot)]:::db MET[(Tabelas de métricas)]:::db API[Levery API]:::box UI[UI]:::box RPC --> IDX IDX --> EVT IDX --> SNAP IDX --> MET API -->|consultas| SNAP API -->|consultas| MET UI --> API ```
```mermaid theme={null} --- config: theme: dark --- flowchart TB RPC[RPC / Logs da cadeia]:::box IDX[Indexadores]:::box EVT[(Armazenamento de eventos)]:::db SNAP[(Tabelas de snapshot)]:::db MET[(Tabelas de métricas)]:::db API[Levery API]:::box UI[UI]:::box RPC --> IDX IDX --> EVT IDX --> SNAP IDX --> MET API -->|consultas| SNAP API -->|consultas| MET UI --> API ```
### Segurança contra reorgs e idempotência (por que isso importa) Para evitar “atividade fantasma” em relatórios regulados: * Os indexadores **aguardam confirmações** antes de finalizar blocos. * Cursors armazenam o **último bloco processado** e o **hash do bloco**; divergências acionam um rollback limitado. * Linhas são gravadas com valores de `uid` determinísticos (por exemplo, `chain:txHash:logIndex`) para que tentativas sejam seguras. * Em caminhos de erro (por exemplo, recibos ausentes), indexadores **não avançam os cursores**, evitando lacunas silenciosas de dados. ### Modelo de dados orientado a snapshots Em vez de consultar eventos brutos em tempo de execução, a plataforma materializa objetos de “estado mais recente” (por exemplo, `Pool`, `Position`, `Permission`) além de um histórico `Event` somente de acréscimos. Essa estrutura sustenta: * **Leituras rápidas de UI** (listas e painéis rodam em snapshots pré-computados). * **Reconstrução em nível de auditoria** (o histórico é preservado e pode ser reproduzido ou rederivado). ### Correção da avaliação A avaliação de portfólio alinha **preços**, **saldos** e **estado de mercado** à mesma janela de tempo do snapshot. Isso evita divergências como “saldo no tempo T avaliado usando preço no tempo T+Δ”. ## Extensibilidade e Topologia de Implantação Levery foi projetada para implantações multi-rede e multi-instituição: * **Configuração por rede:** implantações são descritas via configuração de ambiente (por exemplo, endereços de contratos, registro de tokens). * **Configuração por mercado:** taxas, vínculos de oráculo, requisitos de função e estado de pausa podem ser definidos por mercado. * **Integrações componíveis:** provedores de identidade/risco e sistemas de relatório se conectam via API da plataforma e são refletidos on-chain por habilitações. Para implantações reguladas, trate o registro de permissões como sua **fonte de verdade de política para execução** e trate a API/indexadores como sua **fonte de verdade para relatórios**.