Stellar AMM - Normal Finance

1. Introduction

Halborn was engaged by the Normal AMM team to perform a targeted security assessment of their Soroban-based automated market maker (AMM) protocol on Stellar. The scope included analyzing the core on-chain components responsible for liquidity management, routing, oracle integration, incentives, and access control. The assessment aimed to verify correctness, safety, and economic robustness.

2. Assessment Summary

A senior blockchain security engineer from Halborn conducted the review full-time. The engineer has extensive experience in Rust, Soroban/Stellar, AMM design, and protocol security, including upgradeability, authorization, and oracle systems.

The codebase components reviewed included:

• Contracts: pool, pool_router, oracle_registry, pool_plane, pool_swap_fee, insurance_fund, liquidity_calculator, token

• Shared modules: access_control, incentives, utils, upgrade

The review focused on verifying economic invariants (such as pricing, fees, and shares), oracle validation and safeguards, privilege boundaries, emergency controls, and upgrade procedures.

Engagement objectives included:

• Ensuring that new and modified functions behave as intended and are resistant to misuse and edge cases.

• Identifying vulnerabilities that could lead to fund loss, invariant violations, incorrect state transitions, oracle manipulation, privilege escalation, or denial of service.

• Highlighting areas where stronger invariants, defensive checks, or clearer authorization controls can reduce operational and economic risks.

3. Test Approach and Methodology

To ensure comprehensive and cross-cutting coverage, the assessment employed a consistent methodology across all first-party contracts and shared modules within the workspace:

• Contracts: buffer, insurance_fund, liquidity_calculator, oracle_registry, pool, pool_plane, pool_router, pool_swap_fee, token

• Shared modules: access_control, incentives, pool_tokens, upgrade, utils

• Integration tests located in: contracts/integration_tests

The approach combined architecture mapping, manual expert review, static and dynamic analysis, property-based testing, and adversarial scenario simulations:

1) Repository-wide inventory and architecture mapping

• Mapped all public entry points declared in interface.rs and within #[contractimpl] blocks; analyzed data and control flows among pool, pool_router, oracle_registry, pool_plane, liquidity_calculator, insurance_fund, and token contracts.

• Identified trust boundaries, administrative roles, kill switches, upgrade paths, and oracle dependencies; documented invariants for each component.

2) Manual line-by-line review (across all crates)

• Examined each contract’s contract.rs, storage.rs, errors.rs, and events.rs files:

• Verified authorization and role checks via modules/access_control.

• Assessed storage keys, data lifetimes, bumping strategies, and differentiated between persistent and temporary data usage.

• Analyzed mathematical invariants within pool.rs, liquidity_calculator, pool_swap_fee, utils::math, and incentives mechanisms.

• Reviewed cross-contract calls (router, oracle, plane, token) for error propagation, potential DoS vulnerabilities, and reentrancy issues.

• Verified upgrade flows via modules/upgrade across upgradable contracts.

• Assessed emergency/kill toggles, expiry, and settlement transition mechanisms.

• Ensured event schemas are consistent and correctly implemented.

3) Static analysis and linting (workspace-wide)

• Applied linting tools and targeted grep scans to identify anti-patterns, including:

• Unchecked type conversions, saturation underflows, panics affecting user flows.

• Misuse of U256 and fixed-point math, including rounding errors.

• Incomplete authorization checks and role management inconsistencies.

4) Property-based testing and fuzzing for critical math routines

Focused on:

• Swap route correctness, fee adjustments, and invariant violations (such as fee residues).

• Precision in receive computations and boundary condition handling.

• Price functions (peg_price, get_delta_a) and rolling metrics.

• Incentives accumulation and distribution, including per-user and per-pool calculations, with correct handling of pagination constants.

• Tested edge cases involving zero or near-zero values, maximum fees, large reserves, and rounding boundaries.

5) Stateful adversarial testing and PoC development

• Designed multi-step scenarios across contracts to detect emergent behaviors:

• Upgrade commit, apply, and revert; emergency mode activation and deactivation within deadlines.

• Kill/un-kill toggles; roles for pausing versus emergency pauses.

• Handling of oracle data volatility and staleness, cached versus fresh data paths, with safeguards.

• Insurance fund claims constrained by tiers and thresholds.

• Router orchestration and liquidity calculator during failures.

• Prototype calculations for NAV/share underpricing during rebalancing, supported by mathematical proof independent from harness dependencies.

6) Integration testing and cross-contract orchestration

• Utilized existing integration tests and created custom scenarios:

• Deployment of contracts using contractimport! for pool_plane, liquidity_calculator, pool_router, and oracle_registry.

• End-to-end testing covering initialization, deposits, swaps, withdrawals, incentives, claims, rebalancing, upgrades, and emergency procedures.

• Used functions like utils::test_utils::jump to manipulate time for testing staleness, delays, and expiry conditions.

7) Permission boundary testing (positive and negative cases)

• Systematically verified role-based permissions for Admin, EmergencyAdmin, RewardsAdmin, OperationsAdmin, PauseAdmin, and EmergencyPauseAdmin. Patterns followed those in each crate’s test_permissions.rs.

• Reviewed ownership transfer workflows and deadline enforcement for correctness.

8) Oracle validation and economic safety assessment

• Validated oracle safeguards, including volatility thresholds, staleness limits, clamping, TWAP updates, and cached versus live data handling.

• Assessed core economic invariants such as:

• Enforcement of AMM invariant, accurate fee accounting, and residue handling.

• Share valuation consistency aligned with pool NAV during rebalancing.

• Limits on insurance coverage per tier, as well as revenue withdrawals and settlement procedures.

9) Token interactions and assumptions testing

• Verified token helper functions (utils::token), pool token management (pool_tokens), and behaviors regarding allowances and transfers.

• Analyzed dependencies on standard token implementations and error handling pathways for non-standard tokens in strict-receive and refund scenarios.

10) Performance, resource consumption, and reliability evaluations

• Considered ledger instruction limits, storage growth, and pagination (e.g., PAGE_SIZE).

• Examined pool_plane updates for potential liveness issues and recommended implementing soft-fail patterns where appropriate to improve reliability.

11) Test execution and validation strategy

• Developed targeted tests and proofs of concept to validate identified risks and invariants, including snapshot captures of critical error pathways.

This methodology achieved full coverage of the codebase with focused depth on high-risk areas such as oracle integration, upgradeability, access control, AMM mathematics, and incentives, enabling the detection of both correctness and economic vulnerabilities.