Spark ALM Controller

!Foundry CI [![Foundry][foundry-badge]][foundry]

| Document | Description | |----------|-------------| | Architecture | System architecture, contract interactions, and permissions | | Rate Limits | Rate limit design, calculations, and configuration | | Liquidity Operations | Curve, Uniswap V4, OTC, and PSM integrations | | weETH Integration | EtherFi weETH module architecture and withdrawal flow | | Threat Model | Attack vectors, trust assumptions, and security invariants | | Security | Protocol-specific considerations and audit information | | Operational Requirements | Seeding, configuration, and onboarding checklists | | Development | Testing, deployment, and upgrade procedures | | Code Notes | Implementation details and design decisions |

Quick Start

Testing

forge test

Deployments

Deploy commands follow the pattern: make deploy---

# Deploy full ALM system to Base production
make deploy-base-production-full
Deploy controller to Mainnet production
make deploy-mainnet-production-controller
Deploy full staging environment
make deploy-staging-full

See Development Guide for detailed instructions.

Architecture Overview

The controller contract is the entry point for all calls. It checks rate limits and executes logic, performing multiple calls to the ALMProxy atomically.

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│     Relayer     │────▶│  MainnetController   │────▶│    ALMProxy     │
│   (External)    │     │  or ForeignController│     │ (Funds Custody) │
└─────────────────┘     └──────────────────────┘     └─────────────────┘
                                   │                          │
                                   │                          │
                                   ▼                          ▼
                        ┌──────────────────┐       ┌────────────────────┐
                        │   RateLimits     │       │ External Protocols │
                        │   (State Store)  │       │  (Sky, PSM, etc.)  │
                        └──────────────────┘       └────────────────────┘

See Architecture Documentation for detailed diagrams and explanations.

Max Slippages

Max slippage values throughout ALM controller integrations are defined as how close the resulting value should be to the expected or minimum value, not as how much deviation is allowed. This is an inverse way of denoting max slippages compared to common DeFi nomenclature.

How It Works

In common DeFi terminology, a 0.1% max slippage typically means the resulting value can be 0.1% away from the expected or spot rate/value. However, throughout this codebase, such an expectation would be denoted as a max slippage of 99.9% (or 0.999e18 when scaled).

Historical Context

The reason for this inverse notation is to allow a max slippage of 0 (the unset default value for any storage slot) to imply that the integration is disabled, instead of 0 implying "no slippage allowed". This design choice means that:

• A value of 0 indicates the integration is disabled
• Non-zero values represent the minimum acceptable ratio of actual result to expected result

Value Scaling

All max slippage values are scaled to 1e18, meaning:

• 0.999e18 represents a "max slippage" of 99.9%, which means the resulting price, rate, or value must be at least 99.9% of the expected price, rate, or value
• 0.995e18 represents 99.5%, meaning the result must be at least 99.5% of the expected value
• 1e18 represents 100%, meaning no slippage is allowed (result must equal expected value)

UniswapV4 Integration

Particularly for the UniswapV4 integration, since the pools being interacted with are assumed to pair 1:1 stablecoins (i.e., USDT and USDC), the max slippage defines how close to a 1.0 price the swap is allowed to be. For example:

• A max slippage of 0.999e18 means the swap out value must be at least $0.999 for each $1.00 of input value.
• A max slippage of 0.995e18 means the swap out value must be at least $0.995 for each $1.00 of input value.

Security

Key Trust Assumptions

• DEFAULT_ADMIN_ROLE: Fully trusted, run by governance
• RELAYER: Assumed compromisable - logic prevents unauthorized value movement
• FREEZER: Can stop compromised relayers via removeRelayer

Audits

Audit reports are available in the audits/ directory. The system has been audited by:

• Cantina
• ChainSecurity
• Certora