Architecture

Levery is a permissioned on-chain market infrastructure designed for regulated institutions. Instead of relying on front-ends or off-chain middleware to enforce policy, Levery embeds compliance and operational controls directly into smart-contract execution. Every transaction path, from wallet admission to liquidity lifecycle actions and swap execution, runs deterministic checks before any state change. Non-compliant calls revert with explicit reasons; compliant actions execute normally. This gives institutions uniform enforcement, auditable outcomes, and tamper-resistant governance across all user interactions. Levery’s on-chain architecture is organized into modular domains that work together to provide: permissioning, identity validation, pricing integrity, economic controls, governance, lifecycle enforcement, and transparent treasury operations. Institutions can tailor venue behavior through governed parameters (per pool or global) without weakening core security guarantees.

---

​

Core Domains

​

Permissioning and Admission Control

Levery enforces “who can do what” at the execution layer. Before swaps or liquidity actions, contracts validate that the initiating account is authorized and meets the pool’s policy requirements (e.g., role-based access, institution rules, and KYC/KYB-derived permissions). This ensures only verified actors can access pools, add/remove liquidity, or trade, while keeping the system non-custodial.

​

Controlled Entry Points for Swaps and Liquidity

Levery separates transaction entry points by intent:

​

Swap

Swap entry is routed through a compliant execution path that ties the user identity to the call and prevents accidental or unauthorized token reception.

​

Liquidity

Liquidity entry is mediated through a position manager that performs lifecycle checks on mint, increase, decrease, and burn, so permissioning remains enforced across the entire LP journey, not just at creation time. This structure makes policy enforcement consistent while keeping the user experience predictable and institution-friendly.

​

Oracle-Guided Pricing Integrity and Dynamic Fees

Levery integrates decentralized price-feed oracles to anchor execution to external market references and to compute dynamic fees. Pools can be configured with an oracle reference and comparison rules, and the protocol adjusts fees in response to oracle-to-pool divergence to reduce toxic flow and protect liquidity providers, while maintaining competitive pricing for traders. To preserve pricing integrity, the oracle layer includes safeguards such as:

• On‑demand Queries: Price feeds only invoked in swap hooks, minimizing gas overhead for liquidity ops.
• Decimal Normalization: Safe adjustments to align feed decimals with token decimals, preventing mispricing.
• Zero‑price Guard: Immediate revert on zero or stale oracle values to prevent erroneous fee calcs.

​

Price‑Feed Oracle Integration

Levery supports per‑pool oracle configuration via setPoolOracle().

• Adapters & decimals – Each pool stores {oracle, compareWithPrice0}. The returned feed value is scaled to match the token decimals before comparison.
• Deviation logic – beforeSwap calculates price0 / price1 on‑chain, fetches market price M and applies the formula:

$$F_{swap}=F_{base}+\bigl|\tfrac{P_{onchain}-M}{M}\bigr|\times \texttt{deviationFeeFactor}$$

• Capped multiplier – deviationFeeFactor (ppm) is clamped to $0,1$, guaranteeing the fee never overshoots the absolute price delta.

Let:

• $P_0$ and $P_1$ be the current prices for asset 0 and asset 1, respectively.
• $M$ be the real-time market price from the Oracle.
• $\alpha$ deviationFeeFactor be the liquidity provider fee multiplier.
• $F_{\text{base}}$ be the base fee for the swap.
• $F_{\text{pool}}$ be the pool-specific fee for the swap, which takes precedence over $F_{\text{base}}$ if defined.

​

Initial Swap Fee Definition

The initial swap fee $F_{\text{swap}}$ is defined as: $$F_{\text{swap}} = \begin{cases} F_{\text{pool}} & \text{if } F_{\text{pool}} \neq 0 \\ F_{\text{base}} & \text{otherwise} \end{cases}$$

​

Price Comparison and Fee Adjustment

If a market price oracle is defined, we adjust $F_{\text{swap}}$ based on the price comparison: If compareWithPrice0 is true: $$F_{\text{swap}} = \begin{cases} F_{\text{swap}} + \left( \frac{P_0 - M}{M} \times \alpha \right) & \text{if } P_0 > M \text{ and } \text{params.zeroForOne} \\ F_{\text{swap}} + \left( \frac{M - P_0}{M} \times \alpha \right) & \text{if } P_0 < M \text{ and not } \text{params.zeroForOne} \\ F_{\text{swap}} & \text{otherwise} \end{cases}$$ Else: $$F_{\text{swap}} = \begin{cases} F_{\text{swap}} + \left( \frac{M - P_1}{M} \times \alpha \right) & \text{if } P_1 < M \text{ and } \text{params.zeroForOne} \\ F_{\text{swap}} + \left( \frac{P_1 - M}{M} \times \alpha \right) & \text{if } P_1 > M \text{ and not } \text{params.zeroForOne} \\ F_{\text{swap}} & \text{otherwise} \end{cases}$$

​

Final Fee Update

The updated swap fee is used to update the dynamic LP fee: $$\text{poolManager.updateDynamicLPFee}(key, F_{\text{swap}})$$

​

Non-Transferable Liquidity Positions

Liquidity positions are represented as non-transferable ERC-721 tokens bound to their verified owner. This design prevents unauthorized transfers, preserves compliance status across the entire lifecycle, and simplifies compliance reporting by ensuring LP ownership remains traceable and immutable at the protocol level. Position metadata can be generated in a standardized, auditor-friendly format, enabling transparent reviews of position state (ownership, ranges, and other relevant properties) without relying on off-chain interpretation.

​

Configurable Service Fee and Transparent Treasury

Levery supports a programmable service fee that routes to an on-chain vault. The service fee can be applied predictably across swap flows and accrues transparently for accounting. Vault distribution logic is executed by contract and recorded on-chain, enabling clear treasury visibility and optional revenue-sharing models between stakeholders (e.g., provider/institution).

​

Governance, Administration, and Operational Safety

On-chain administration allows institutions to:

• update administrators and privileged roles,
• adjust fee parameters globally or per pool,
• update oracle references and pool settings,
• replace the permission manager under controlled procedures.

Levery also includes robust operational controls such as global and per-pool pausing. These controls let institutions isolate incidents, respond to risk events, and comply with procedural requests, without compromising non-custodial guarantees (the protocol restricts actions, but does not seize user funds).

​

Auditability by Design

Every decision and execution step emits structured on-chain events that tie policy enforcement to the transaction lifecycle. This makes audits straightforward: institutions can reconstruct “who attempted what, under which policy, and what happened” directly from chain data. The result is a deterministic, evidence-first audit trail aligned with institutional compliance expectations.

---

​

Permissioning & governance model

Permissions are represented as explicit, queryable entitlements. This keeps enforcement deterministic and makes audits easier.

​

Permission lifecycle

​

Emergency controls

---

​

Why This Design

Levery is built around a simple principle: regulatory assurance should be embedded into protocol logic, not bolted on afterward. By relocating compliance controls, risk checks, pricing integrity rules, and governance into smart contracts, Levery achieves consistent enforcement, strong auditability, and operational flexibility, while keeping markets non-custodial and institution-ready.

---

​

Off-chain architecture: indexing, snapshots, and reporting

Levery uses an event-sourced indexing pipeline that is designed for correctness under reorgs, idempotency, and fast UI queries.

​

Indexers

The worker layer runs multiple indexers in parallel. Key responsibilities include:

• Protocol configuration indexer: captures global config and per-market policy updates into a System and Pool snapshot model.
• Permission indexer: materializes the latest permissions per account into a Permission snapshot model.
• Market activity indexer: canonicalizes swaps and liquidity changes, attributes service fees, and writes normalized facts.
• Price indexer: ingests oracle feed updates and produces both latest and time-slot prices for historical valuation.
• Balance indexers: create daily and “current” token balance snapshots for every account.
• Portfolio indexer: values balances + positions + owed fees at snapshot times for reporting and analytics.
• Metrics indexers: compute pool and asset metrics for fast list pages (TVL, volume, APR, market cap, FDV).

​

Reorg safety & idempotency (why it matters)

To prevent “phantom activity” in regulated reporting:

• Indexers wait for confirmations before finalizing blocks.
• Cursors store the last processed block and block hash; mismatches trigger a bounded rollback.
• Rows are written with deterministic uid values (e.g., chain:txHash:logIndex) so retries are safe.
• In error paths (e.g., missing receipts), indexers do not advance cursors, avoiding silent data gaps.

​

Snapshot-first data model

Rather than querying raw events at runtime, the platform materializes “latest state” objects (e.g., Pool, Position, Permission) plus an append-only Event history. This structure supports both:

• Fast UI reads (lists and dashboards run on precomputed snapshots).
• Audit-grade reconstruction (history is preserved and can be replayed or re-derived).

​

Valuation correctness

Portfolio valuation aligns prices, balances, and market state to the same snapshot time window. This avoids mismatches such as “balance at time T valued using price at time T+Δ”.

​

Extensibility and deployment topology

Levery is designed for multi-network and multi-institution deployments:

• Per-network configuration: deployments are described via environment configuration (e.g., contract addresses, token registry).
• Per-market configuration: fees, oracle bindings, role requirements, and pause state can be scoped to a market.
• Composable integrations: identity/risk providers and reporting systems connect through the platform API and are reflected on-chain via entitlements.