Arquitetura

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.

​

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.

​

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).

​

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

​

Controles de emergência

---

​

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.

---

​

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).

​

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.