Spark ALM Controller

Source code: sparkdotfi/spark-alm-controller

Overview

The Spark ALM Controller is the onchain execution layer of the Spark Liquidity Layer. It is a small set of contracts that:

• Hold custody of all SLL capital in a single proxy (ALMProxy).
• Route every action through a controller (MainnetController on Ethereum, ForeignController on each supported L2).
• Enforce per-integration whitelists and exposure caps via a stateful RateLimits contract keyed by keccak256 identifiers.
• Provide an emergency revocation path via the FREEZER role that does not require a governance vote.

The same controller pattern is also used in two narrower contexts:

• ALMProxyFreezable, a variant of the proxy used where the relayers themselves are granted the proxy's CONTROLLER role directly. This is intended for lower-criticality state where governance accepts a wider attack surface in exchange for operational simplicity, and where the FREEZER quick-revoke path is still preserved.
• OTCBuffer and WEETHModule, two purpose-built helper contracts described in their own sections below.

Architecture

Every transaction originates from an offchain RELAYER, lands on the controller, is rate-limited and parameter-checked, and is then executed by the proxy that actually holds the funds. The controller calls triggerRateLimitDecrease / triggerRateLimitIncrease on RateLimits, and doCall / doCallWithValue / doDelegateCall on the ALMProxy, which performs the approved interaction with the external venue (Sky / PSM / AAVE / Morpho / Curve / Uniswap V4 / OTC / …).

When minting USDS via the Sky allocation system, funds are never held by the controller — they are pulled into the proxy and stay there until a subsequent relayer action moves them. The controller decrements LIMIT_USDS_MINT, instructs the proxy to draw from the Sky allocator vault (minting USDS to the allocator buffer), and then transfers that USDS from the buffer into the proxy.

Core contracts

ALMProxy

src/ALMProxy.sol. Holds custody of all SLL capital. Stateless except for OpenZeppelin AccessControl. Only addresses with the CONTROLLER role can invoke doCall, doCallWithValue, or doDelegateCall. New controllers can be onboarded by governance without migrating funds.

MainnetController and ForeignController

Stateful entry points for the RELAYER role. Each controller:

• Checks the relayer's role, decrements (or increments) the relevant rate limit, validates parameters, and asks the proxy to execute the underlying call.
• Holds per-integration configuration: maxSlippages per pool/exchange, ERC-4626 maxExchangeRate thresholds, Uniswap V4 tick limits, CCTP mintRecipients per destination domain, LayerZero layerZeroRecipients per destination endpoint, OTC buffer registrations, and Ethena delegatedSigner state.

RateLimits

src/RateLimits.sol. Stores all rate-limit data, keyed by bytes32. Each key resolves to a struct:

The current limit is:

currentRateLimit = min(slope * (block.timestamp - lastUpdated) + lastAmount, maxAmount)

A maxAmount of type(uint256).max flags an unlimited key (used for actions where the rate limit acts only as a whitelist gate, e.g., approval-only operations). A maxAmount of 0 means the key is not configured — any call that would consume it reverts. Only the CONTROLLER role on RateLimits (held by the active controller contract) may call triggerRateLimitDecrease or triggerRateLimitIncrease; only DEFAULT_ADMIN_ROLE may set new values directly.

ALMProxyFreezable

src/ALMProxyFreezable.sol. A 23-line subclass of ALMProxy used in narrower contexts. Two architectural differences from the canonical proxy:

• In this deployment pattern, the CONTROLLER role is intended to be granted directly to relayers rather than to a MainnetController / ForeignController contract (design intent documented in docs/ARCHITECTURE.md — the contract itself does not restrict who receives the role; the standard deploy path grants it to the controller contract). The relayer's calldata is the call.
• A FREEZER role is introduced. removeController(address) revokes the CONTROLLER role from a compromised relayer without a governance proposal.

This variant trades the parameter-validation layer of a full controller for operational simplicity, and is appropriate where the funds at risk or the action surface are constrained.

OTCBuffer

src/OTCBuffer.sol. UUPS-upgradeable buffer contract used to bound exposure to a single OTC counterparty. One OTCBuffer is deployed per whitelisted exchange. Its only state-changing method is the admin-callable approve(asset, allowance), which governance uses after deployment to grant the ALMProxy an infinite allowance over each whitelisted asset.

The OTC swap lifecycle (driven from MainnetController):

1. otcSend(exchange, asset, amount) — moves amount of asset from the proxy to the exchange's offchain address, after checking LIMIT_OTC_SWAP (keyed by exchange) and confirming any prior swap is isOtcSwapReady.
2. The counterparty deposits the returned asset into the corresponding OTCBuffer.
3. otcClaim(exchange, asset) — pulls the entire OTCBuffer balance of asset back into the proxy.
4. isOtcSwapReady(exchange) returns true once claimed + rechargeRate · elapsed ≥ sent · maxSlippage, allowing the next send.

The infinite allowance is intentional: otcClaim always transfers the full balance, and a finite allowance would let an attacker donate a small amount to push the balance past the allowance and brick claims.

WEETHModule

src/WEETHModule.sol. UUPS-upgradeable helper that exists because EtherFi's withdrawal flow mints an NFT rather than returning ETH synchronously, and the proxy cannot safely hold or process NFTs.

• requestWithdrawFromWeETH on the controller routes the unwrap → LiquidityPool.requestWithdraw call so that the resulting WithdrawRequestNFT is minted to the WEETHModule.
• claimWithdrawal(requestId) on the module — only callable by its configured almProxy — verifies the request is valid and finalized, claims it, wraps received ETH into WETH, and transfers WETH back to the proxy.
• The module never holds ETH or WETH outside the single claim transaction, and never holds NFTs except between request and claim.

Permissions

All contracts inherit OpenZeppelin AccessControl. The roles are:

Controller action surface

All functions below run with nonReentrant and require the RELAYER role. Each action consumes (or restores) the rate-limit key shown. Keys with an "→ address" suffix are combined with an asset, pool, vault, exchange, or destination via RateLimitHelpers before lookup; the underlying base key must also exist for the call to succeed.

MainnetController (src/MainnetController.sol)

ForeignController (src/ForeignController.sol)

Rate limit keys: full reference

The keccak256-derived constants currently declared on each controller. Keys flagged "→ ..." are combined with their suffix via RateLimitHelpers (makeAddressKey, makeAddressAddressKey, makeBytes32Key, makeUint32Key) before storage lookup.

Common to both controllers

LIMIT_4626_DEPOSIT          → token
LIMIT_4626_WITHDRAW         → token
LIMIT_AAVE_DEPOSIT          → aToken
LIMIT_AAVE_WITHDRAW         → aToken
LIMIT_ASSET_TRANSFER        → (asset, destination)
LIMIT_LAYERZERO_TRANSFER    → (oftAddress, destinationEndpointId)
LIMIT_SPARK_VAULT_TAKE      → sparkVault
LIMIT_USDC_TO_CCTP
LIMIT_USDC_TO_DOMAIN        → destinationDomain

MainnetController-only

LIMIT_CURVE_DEPOSIT           → pool
LIMIT_CURVE_SWAP              → pool
LIMIT_CURVE_WITHDRAW          → pool
LIMIT_FARM_DEPOSIT            → farm
LIMIT_FARM_WITHDRAW           → farm
LIMIT_MAPLE_REDEEM            → mapleToken
LIMIT_OTC_SWAP                → exchange
LIMIT_SUPERSTATE_SUBSCRIBE
LIMIT_SUSDE_COOLDOWN
LIMIT_UNISWAP_V4_DEPOSIT      → poolId
LIMIT_UNISWAP_V4_SWAP         → poolId
LIMIT_UNISWAP_V4_WITHDRAW     → poolId
LIMIT_USDE_BURN
LIMIT_USDE_MINT
LIMIT_USDS_MINT
LIMIT_USDS_TO_USDC
LIMIT_WEETH_DEPOSIT
LIMIT_WEETH_REQUEST_WITHDRAW  → weETHModule
LIMIT_WSTETH_DEPOSIT
LIMIT_WSTETH_REQUEST_WITHDRAW

ForeignController-only

LIMIT_PSM_DEPOSIT   → asset
LIMIT_PSM_WITHDRAW  → asset

Trust assumptions

A compromised relayer can DOS Ethena unstaking; recovery is documented in test/mainnet-fork/Attacks.t.sol.

Operational requirements

These are conditions that must hold for each integration. They are not enforced by governance proposal review alone — most are also enforced in the contract.

• Token requirements. ERC-20 tokens must be non-rebasing, have at least 6 decimals, and behave as standard ERC-20s.
• Rate-limit keys are the whitelist. A venue with no governance-set maxAmount for its rate-limit key reverts on first interaction. Withdrawals require the matching deposit key to also exist (ERC-4626 and AAVE families).
• ERC-4626 seeding. Vaults must have initial shares burned to an unrecoverable address before onboarding, to prevent first-deposit rounding attacks. The maxExchangeRate mechanism is the second line of defense against donation attacks.
• Curve and Uniswap V4 seeding. Pools must be seeded with initial liquidity to an unrecoverable address (e.g., address(1)) before onboarding.
• Uniswap V4 restrictions. Only 1:1 stablecoin pools may be onboarded. Pools must be hookless (the rate-limit decrease is computed from pre/post balances and empty hookData is passed; a hook could otherwise manipulate balances mid-call). Tick limits and maxSlippage must be configured before any action succeeds.
• OTC buffer deployment. After deploying a new OTCBuffer, the admin must call approve to grant an infinite allowance (type(uint256).max) to the ALMProxy for each whitelisted asset. Without this, otcClaim can be bricked by a donation attack.
• Slippage required. Curve, Uniswap V4, AAVE, and OTC operations require a non-zero maxSlippage for the target pool / aToken / exchange.

Verifying the live configuration

Live values change as governance onboards venues, raises ceilings, and rotates roles. The repository ships a Wake printer that enumerates which controller function consumes which rate-limit key and verifies the live configuration matches:

wake --config printers/wake.toml print rate-limits

A zero exit code indicates the spec is satisfied.

For live contract addresses (proxy, controllers, rate-limits, OTC buffers, weETH module, per-network deployments) refer to the Spark Address Registry. For role assignees and current per-key maxAmount / slope values, the RateLimits.getRateLimitData(key) and getCurrentRateLimit(key) view functions are authoritative.

Audits

Every released controller version has been audited. Cantina audited all versions from v1.0.0 through v1.10.0 (v1.2.0 never shipped as a final release); ChainSecurity audited v1.0.0–v1.7.0 and v1.10.0; Certora audited v1.8.0 and v1.9.0. Reports are linked from the security and audits page and live in audits/.