Technical Reference

This page documents the Box smart contract and its funding modules for readers who want the onchain mechanics and operational guardrails.

What Box does

• Holds a single base asset (e.g., USDC) and issues ERC-4626 shares.

• Allocates between the base asset and whitelisted ERC-20 tokens.

• Borrows and lends through whitelisted funding modules.

• Tracks NAV using token oracles and funding module NAV.

Architecture

Adapters are the intended feeders for Box. Box shares are held by adapters and reported back to Vault V2 using previewRedeem (cached in BoxAdapterCached).

Roles & permissions

Owner

• Sets the curator.

• Transfers ownership.

• Sets skimRecipient.

Curator

• Manages allocators and funding modules.

• Adds/removes whitelisted tokens and oracles.

• Configures slippage limits.

• Submits timelocked changes.

• Can initiate shutdown.

Guardian

• Vetoes timelocked actions (revoke).

• Triggers shutdown.

• Can recover from shutdown before winddown.

• May update oracles only in final winddown.

• Commonly controlled by an Aragon DAO representing Vault V2 share holders.

Allocator

• Executes swaps (allocate, deallocate, reallocate).

• Pledges collateral, borrows, repays via funding modules.

• Can use flash for atomic multi-step operations.

Feeder

• The only role allowed to deposit/mint shares.

• In practice, adapters act as feeders.

Timelock governance

Critical functions require a timelock delay and must be queued with submit() before execution. Governance is intentionally structured so Vault V2 share holders can intervene via the Aragon DAO-controlled guardian, allowing them to veto queued actions or trigger shutdowns if needed.

Typical timelocked actions include:

• Adding/removing feeders

• Setting maxSlippage

• Adding tokens, oracles, funding modules, or facilities

• Setting guardian

Timelock delays default to 0; deployments should initialize non-zero delays to prevent immediate execution.

Allocation & swap safety

Box enforces two layers of slippage control:

1. Per-swap slippage check Based on oracle prices, each swap must satisfy received ≥ expected * (1 - maxSlippage).

2. Epoch slippage budget Realized slippage is tracked relative to NAV over slippageEpochDuration. If accumulated slippage exceeds maxSlippage, further swaps are blocked until the epoch resets.

During winddown, the per-epoch limit is ignored and the per-swap tolerance linearly ramps up to 1%.

Lifecycle states

Funding modules

Box integrates lending protocols through IFunding modules. Each module is owned by the Box and supports:

• Facilities (protocol-specific configuration)

• Whitelisted collateral tokens

• Whitelisted debt tokens

Box will only add empty funding modules (no facilities, no tokens, no debt).

FundingAave (Aave v3)

• facilityData must be empty ("").

• Uses Aave Pool and optional eMode.

• pledge supplies collateral and enables collateral usage.

• borrow returns debt tokens to Box.

• NAV is collateral value - debt value, floored at zero.

FundingMorpho (Morpho Blue)

• facilityData encodes Morpho market parameters.

• Supports multiple facilities per module.

• Enforces LTV caps via lltvCap against each market’s LLTV.

• pledge / borrow validated per facility.

• NAV computed per facility and aggregated, floored at zero.

Flash operations

Allocators (or anyone during winddown) can call flash() to temporarily source liquidity for complex sequences. NAV is cached during the flash to prevent manipulation, and the flash token must be returned in the same transaction.

Audit and source

• ChainSecurity audit (Dec 2025): 2025-12-16-chainsecurity.pdf

• Cantina audit (Jan 2026): 2026-01-06-cantina.pdf