Spark ALM Controller

Overview

This repository contains the onchain components of the Spark Liquidity Layer. The system enables controlled interaction with various DeFi protocols while enforcing rate limits and maintaining custody of funds through the ALMProxy.

Core Contracts

Contract	Description
ALMProxy	Proxy contract that holds custody of all funds and routes calls to external contracts
MainnetController	Controller for Ethereum mainnet operations (Sky allocation, PSM, CCTP bridging)
ForeignController	Controller for L2 operations (PSM, external protocols, CCTP bridging)
RateLimits	Enforces and manages rate limits on controller operations
OTCBuffer	Buffer contract for offchain OTC swap operations

Documentation

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-<domain>-<env>-<type>

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

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

See Security Documentation for complete trust assumptions and mitigations.

Audits

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

• Cantina
• ChainSecurity
• Certora

---