Arquitetura

A 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, a Levery embute controles de compliance e operações diretamente na execução de contratos inteligentes. Cada caminho de transação, da admissão da carteira a ações de ciclo de vida da liquidez e execução de swaps, executa checagens 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 da Levery é organizada em domínios modulares que trabalham juntos para fornecer: permissões, validação de identidade, integridade de preços, controles econômicos, governança, aplicação de ciclo de vida e operações de tesouraria transparentes. Instituições podem ajustar o comportamento do venue por parâmetros governados (por pool ou globais) sem enfraquecer garantias centrais de segurança.

---

​

Domínios principais

​

Permissões e controle de admissão

A Levery aplica “quem pode fazer o quê” na camada de execução. Antes de swaps ou ações de liquidez, os contratos validam que 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 atores verificados possam acessar pools, adicionar/remover liquidez ou negociar, enquanto mantém o sistema não custodial.

​

Pontos de entrada controlados para swaps e liquidez

A Levery separa pontos de entrada de transação por intenção:

​

Swap

A entrada de swap é roteada por um caminho de execução conforme que vincula a identidade do usuário à chamada e evita recepção acidental ou não autorizada de tokens.

​

Liquidez

A entrada de liquidez é mediada por um gerenciador de posições que executa checagens de ciclo de vida em mint, increase, decrease e burn, para que a aplicação de permissões se mantenha ao longo de toda a jornada do LP, não apenas no momento da criação. Essa estrutura mantém a aplicação de políticas consistente enquanto preserva uma experiência de usuário previsível e amigável para instituições.

​

Integridade de preços guiada por oráculos e taxas dinâmicas

A Levery integra oráculos de price-feed descentralizados para ancorar a execução a referências externas de mercado e computar taxas dinâmicas. Pools podem ser configurados com uma referência de oráculo e regras de comparação, e o protocolo ajusta 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 chamados apenas em hooks de swap, minimizando overhead de gas para operações de liquidez.
• Normalização de decimais: ajustes seguros para alinhar decimais do feed com decimais do token, evitando precificação incorreta.
• Proteção contra preço zero: revert imediato em valores zero ou obsoletos para evitar cálculos de taxa errôneos.

​

Integração do oráculo de price-feed

A Levery suporta configuração de oráculo por pool via setPoolOracle().

• Adaptadores e decimais – Cada pool armazena {oracle, compareWithPrice0}. O valor retornado pelo 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 com limite – 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 dos ativos 0 e 1, respectivamente.
• $M$ como o preço de mercado em tempo real do oráculo.
• $\alpha$ deviationFeeFactor como o multiplicador de taxa de LP.
• $F_{\text{base}}$ como a taxa base do 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 do 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 da taxa

Se um oráculo de preço de mercado estiver definido, ajustamos $F_{\text{swap}}$ com base na comparação de preço: Se compareWithPrice0 for true: $$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

Posições de liquidez são representadas como tokens ERC-721 intransferíveis vinculados ao seu proprietário verificado. Esse design impede transferências não autorizadas, preserva o status de compliance ao longo de todo o ciclo de vida e simplifica relatórios de conformidade ao garantir que a propriedade de LP permaneça rastreável e imutável no nível do protocolo. Metadados de posição podem ser gerados em um formato padronizado e amigável a auditoria, 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

A Levery suporta uma taxa de serviço programável que é roteada para um cofre on-chain. A taxa de serviço pode ser aplicada de forma previsível nos fluxos de swap e acumula de forma transparente para contabilidade. A lógica de distribuição do cofre é executada por contrato e registrada on-chain, permitindo visibilidade clara de 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 papéis privilegiados,
• 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.

A Levery também inclui controles operacionais robustos, como pausa global 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 custodiais (o protocolo restringe ações, mas não confisca fundos de 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 auditorias simples: instituições podem reconstruir “quem tentou o quê, sob qual política, e o que aconteceu” diretamente dos dados da chain. O resultado é uma trilha de auditoria determinística e orientada a evidências, alinhada às expectativas de compliance institucional.

---

​

Modelo de permissões e governança

Permissões são representadas como direitos explícitos e consultáveis. Isso mantém a aplicação determinística e torna auditorias mais fáceis.

​

Ciclo de vida de permissões

​

Controles de emergência

---

​

Por que este design

A Levery é construída em torno de um princípio simples: a garantia regulatória deve estar embutida na lógica do protocolo, e não adicionada depois. Ao mover controles de compliance, checagens de risco, regras de integridade de preço e governança para contratos inteligentes, a Levery alcança aplicação consistente, forte auditabilidade e flexibilidade operacional, mantendo os mercados não custodiais e prontos para instituições.

---

​

Arquitetura off-chain: indexação, snapshots e reporting

A 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. 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: canonicaliza swaps e mudanças de liquidez, atribui taxas de serviço e escreve fatos normalizados.
• Indexador de preços: ingere atualizações de feeds de oráculo e produz preços latest e 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: valoriza saldos + posições + taxas devidas nos horários de snapshot para reporting e analytics.
• Indexadores de métricas: computam métricas de pool e ativos para páginas de lista rápidas (TVL, volume, APR, market cap, FDV).

​

Segurança contra reorgs e idempotência (por que importa)

Para prevenir “atividade fantasma” em relatórios regulados:

• Indexadores aguardam confirmações antes de finalizar blocos.
• Cursores armazenam o último bloco processado e o hash do bloco; divergências disparam um rollback limitado.
• Linhas são escritas com valores uid determinísticos (por exemplo, chain:txHash:logIndex) para que retries sejam seguros.
• Em caminhos de erro (por exemplo, receipts ausentes), indexadores não avançam cursores, evitando lacunas silenciosas de dados.

​

Modelo de dados snapshot-first

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 append-only. Essa estrutura suporta:

• Leituras rápidas de UI (listas e dashboards rodam sobre snapshots pré-computados).
• Reconstrução de nível de auditoria (o histórico é preservado e pode ser reproduzido ou rederivado).

​

Correção de valuation

A valorização do portfólio alinha preços, saldos e estado de mercado à mesma janela de snapshot. Isso evita divergências como “saldo no tempo T valorizado com preço no tempo T+Δ”.

​

Extensibilidade e topologia de implantação

A Levery é 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 papéis e estado de pausa podem ser definidos por mercado.
• Integrações componíveis: provedores de identidade/risco e sistemas de reporting se conectam pela API da plataforma e são refletidos on-chain por direitos.