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 SLL capital in an ALMProxy on each network. Segregated PAUs (see Diamond PAUs) hold their own funds in a separate 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 three narrower contexts:

• ALMProxyFreezable, a variant of the proxy where relayers are granted an ALLOCATOR_ROLE and call the proxy directly. This is intended for lower-criticality state where governance accepts a wider attack surface in exchange for operational simplicity, and where a FREEZER_ROLE quick-revoke path is still preserved.
• Diamond PAUs, a newer modular controller stack that runs next to the controllers on some networks. See Diamond PAUs.
• 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 SLL capital on its network. 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

A variant of ALMProxy used in narrower contexts, for example as the allocator on Spark-curated Morpho vaults. The live deployments on Ethereum, Base, Arbitrum, Avalanche, Robinhood and X Layer use the diamond-pau ALMProxyFreezable v1.12.0, which replaced the earlier spark-alm-controller version in the June 4, 2026 spell. Two architectural differences from the canonical proxy:

• Relayers are granted the ALLOCATOR_ROLE and call doCall / doCallWithValue on the proxy directly, rather than going through a MainnetController / ForeignController contract. The relayer's calldata is the call.
• A FREEZER_ROLE is introduced. removeAllocator(address) revokes the ALLOCATOR_ROLE from a compromised relayer without a governance proposal.

The earlier src/ALMProxyFreezable.sol in spark-alm-controller used the CONTROLLER role and removeController(address) for the same purpose.

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.

Diamond PAUs

Spark has also deployed a modular controller stack from the diamond-pau repository (v1.14.0). Each PAU consists of a Controller with pluggable facets (for example CCTP, Aave, ERC-4626, LayerZero, Spark Vault, transfer and Uniswap V4 facets), its own RateLimits and AccessControls contracts, and an AdministeredAgent that acts as the relayer. Per-network Beacon and PAUFactory contracts deploy new PAUs. The AdministeredAgent has actors (hot wallets that submit transactions), grantors that can add actors, and revokers (freezers) that can remove them.

Live deployments:

• Arbitrum (parallel PAU). Since the October 8, 2026 spell, a PAU Controller holds the CONTROLLER role on the Arbitrum ALMProxy next to the v1.8.0 ForeignController. It bridges USDC to Ethereum over CCTP V2, limited to 5M USDC with 50M USDC per day of regeneration. The Soter freezer multisig is a revoker and the Soter grantor multisig is a grantor on its AdministeredAgent.
• Ethereum and X Layer (segregated spUSDC PAUs). Each has its own ALMProxy, Controller, RateLimits, AccessControls and AdministeredAgent, used for the spUSDC vault on that network. Funds in these proxies are separate from the main SLL ALMProxy.

Addresses are listed in the Spark Address Registry.

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)

The controller still supports every family below, but governance can deactivate a venue by setting its rate limits to zero. The September 10, 2026 spell did this for Ethena (USDe mint/burn, sUSDe cooldown and deposits), Maple syrupUSDC and syrupUSDT, Superstate USTB and USCC, and several Curve pools, among others.

ForeignController (src/ForeignController.sol)

The table follows the v1.10.0 source, which is deployed on Robinhood and X Layer. Arbitrum, Base, Avalanche, Optimism and Unichain still run ForeignController v1.8.0, which also exposes setSupplyQueueMorpho, updateWithdrawQueueMorpho and reallocateMorpho for Morpho vault allocation. Ethereum runs MainnetController v1.10.0. Controller v1.11.0 has been tagged but is not yet deployed.

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