External State Fuse

The ExternalState fuse family is a generic integration framework designed to connect IPOR Fusion PlasmaVaults with blockchain exogenous actions such as Real World Asset (RWA) strategies or other positions like CEX positions or derivatives where the actual state and asset valuation are tracked and attested off-chain (e.g., by custodians), rather than being fully derivable on-chain.

Unlike standard DeFi protocols where balances are queried directly from smart contracts (like Aave or Morpho), External State markets rely on a trust-minimized, dual-custodian reporting system to synchronize off-chain states with the onchain vault accounting.

What is an External State Fuse?

The ExternalState setup is a bundle of contracts rather than a single fuse. They fundamentally change how a market's balance is determined.

Instead of reading a balance from a yield-bearing token (like an aToken or cToken), the ExternalStateBalanceFuse reads a cached value from a persistent, per-market ExternalStateExecutor contract. This cached value is updated periodically via transactions submitted by authorized custodians.

Because this involves off-chain actors asserting the value of the vault's assets, this is a special type of balance fuse that involves trust. To mitigate risks, the architecture enforces a dual-approval mechanism (propose and confirm) by distinct custodians, rate limiting, and strict substrate whitelisting.

Technical Architecture

The ExternalState integration bundles several components that work together to securely bridge off-chain state and onchain accounting.

1. Core Components

Component

Role

ExternalStateOperationFuse

The entry point fuse executed via delegatecall from the PlasmaVault. It transfers assets to/from the executor, validates substrates, and forwards batched actions to external protocols.

ExternalStateExecutor

A persistent contract deployed once per (vault, marketId). It holds the actual asset tokens, tracks the off-chain balances reported by custodians, and executes authorized calls to target protocols.

ExternalStateBalanceFuse

The balance fuse used by the vault. It computes the NAV/USD value of the position based on the balances reported to the executor. It can also trigger a pause flag if it detects a "big change" in value.

ExternalStatePausePreHook

A pre-hook registered on the vault's user-facing operations (deposit, withdraw, etc.). It blocks operations if the market is paused, if custodian reports are stale, or if the executor is missing.

2. Execution and Accounting Flow

Enter/Exit Operations: When an ALPHA executes a strategy via ExternalStateOperationFuse.enter() or .exit(), the operation runs via delegatecall. The fuse lazily deploys the ExternalStateExecutor if it doesn't exist, transfers assets, and forwards execution actions (e.g., approve, deposit to a target protocol router) to the executor.
Asset Custody: The ExternalStateExecutor is the entity that actually holds the ERC20 tokens or interacts with the off-chain protocol's on-chain router.
Balance Synchronization (The Trust Assumption): As the off-chain yield accrues (e.g., T-Bill yield), authorized custodians must report the new balance. This requires a two-step process on the ExternalStateExecutor:
- Custodian A calls proposeBalance().
- Custodian B calls confirmBalance().
Balance Reading: When the PlasmaVault calls updateMarketsBalances(), the ExternalStateBalanceFuse reads the confirmed balance from the ExternalStateExecutor and converts it to a USD value using the vault's oracle.

3. Security Model & Validations

Because the balance relies on external actors, strict security boundaries are enforced:

Substrate Whitelisting: The primary authorization boundary. Every asset, balance account, custodian, and allowable action target/selector must be explicitly granted by the ATOMIST via grantMarketSubstrates.
Dual-Custodian Verification: Balance updates require two distinct custodian addresses.
Rate Limiting & Staleness: Updates are rate-limited per account (MIN_UPDATE_INTERVAL), and user operations are paused if the last update is older than STALENESS_MAX.
Big Change Detection: If a confirmed balance update moves the total balance by a percentage exceeding BIG_CHANGE_BPS, the market is automatically paused to protect users from erroneous reporting.
Live Substrate Checks: Custodian balance proposals are validated against the live vault substrate set, preventing compromised custodians from injecting balances into revoked accounts.

Setting up an External State Market

Setting up an External State market involves deploying the suite of fuses, registering them with the vault, and carefully configuring the substrates.

Note: The External State market uses a dedicated market ID: IporFusionMarkets.EXTERNAL_STATE = 50. A single PlasmaVault can only host one External State market.

Step 1: Deploy Fuses

Deploy one instance of each fuse, bound to the EXTERNAL_STATE market ID. The ExternalStateExecutor is not deployed here; it is lazy-deployed later.

uint256 marketId = IporFusionMarkets.EXTERNAL_STATE;
ExternalStateOperationFuse opFuse    = new ExternalStateOperationFuse(marketId);
ExternalStateBalanceFuse   balanceFuse = new ExternalStateBalanceFuse(marketId);
ExternalStateUnpauseFuse   unpauseFuse = new ExternalStateUnpauseFuse(marketId);
ExternalStateRescueFuse    rescueFuse  = new ExternalStateRescueFuse(marketId);
ExternalStatePausePreHook  preHook     = new ExternalStatePausePreHook(marketId);

Step 2: Register Fuses

address[] memory fuses = new address[](4);
fuses[0] = address(opFuse);
fuses[1] = address(balanceFuse);
fuses[2] = address(unpauseFuse);
fuses[3] = address(rescueFuse);
PlasmaVaultGovernance(vault).addFuses(fuses);

PlasmaVaultGovernance(vault).setBalanceFuse(marketId, address(balanceFuse));

Step 3: Register Pre-Hook

The ExternalStatePausePreHook must be registered against user-facing functions to enforce staleness and pause checks.

bytes4[] memory selectors = new bytes4[](5);
selectors[0] = 0x6e553f65; // deposit
selectors[1] = 0x94bf804d; // mint
selectors[2] = 0x00f714ce; // depositWithPermit
selectors[3] = 0xba087652; // redeem
selectors[4] = 0xb460af94; // withdraw

address[] memory impls = new address[](5);
for (uint256 i; i < selectors.length; ++i) impls[i] = address(preHook);

bytes32[] memory emptySubstrates = new bytes32[](5); 
PlasmaVaultGovernance(vault).setPreHookImplementations(selectors, impls, emptySubstrates);

Step 4: Grant Substrates (Security Configuration)

This is the most critical step. You must configure the allowed assets, off-chain tracking accounts, custodians, allowable actions, and safety parameters.

Substrate types include:

ASSET: ERC20 tokens allowed for deposit/withdrawal.
BALANCE_ACCOUNT: Logical off-chain tracking buckets.
CUSTODIAN: Authorized EOA/Multisigs for reporting.
TARGET: Allowed (contractAddress, functionSelector) pairs the executor can call.
STALENESS_MAX (Singleton): Max age of an update before operations pause.
BIG_CHANGE_BPS (Singleton): Max change in NAV before triggering a pause.
MIN_UPDATE_INTERVAL (Singleton): Rate limit between updates.

// Build the substrate array
bytes32[] memory subs = new bytes32[](N);
uint256 i = 0;

// Example Configuration
subs[i++] = ExternalStateSubstrateLib.encodeAssetSubstrate(USDC);
subs[i++] = ExternalStateSubstrateLib.encodeBalanceAccountSubstrate(brokerAccountA);
subs[i++] = ExternalStateSubstrateLib.encodeCustodianSubstrate(custodianOne);
subs[i++] = ExternalStateSubstrateLib.encodeCustodianSubstrate(custodianTwo);
subs[i++] = ExternalStateSubstrateLib.encodeTargetSubstrate(rwaRouter, IRWARouter.deposit.selector);
subs[i++] = ExternalStateSubstrateLib.encodeStalenessMaxSubstrate(24 hours);
subs[i++] = ExternalStateSubstrateLib.encodeBigChangeBpsSubstrate(500); // 5%

PlasmaVaultGovernance(vault).grantMarketSubstrates(marketId, subs);

Important: Verify that TARGET addresses do not overlap with ASSET addresses.

Step 5: Deploy Executor

Explicitly create the executor via the ALPHA execution path before opening the vault. This ensures substrate configurations are validated early.

FuseAction[] memory calls = new FuseAction[](1);
calls[0] = FuseAction({
    fuse: address(opFuse),
    data: abi.encodeCall(ExternalStateOperationFuse.createExecutor, ())
});
PlasmaVault(vault).execute(calls);

Step 6: Ongoing Operations

Once live, the ALPHA executes strategies using ExternalStateOperationFuseEnterData / ExitData.

Custodians must regularly call proposeBalance and confirmBalance on the ExternalStateExecutor to ensure the ExternalStatePausePreHook does not block user withdrawals due to staleness.

Risk Analysis and Trust Assumptions

The External State fuse family introduces a fundamentally different risk profile compared to standard on-chain DeFi integrations. While standard fuses rely on trustless, mathematically verifiable smart contract logic, the External State framework inherently relies on trust in off-chain actors and infrastructure.

This section outlines the specific risks associated with using External State fuses. It is essential reading for Atomists configuring these markets, and for depositors understanding the security model of their investments.

Custodial and Valuation Risk

The primary distinction of the External State fuse is that the vault's assets are no longer fully verifiable via on-chain logic. Their valuation depends entirely on reports from off-chain attestors.

Reliance on Off-Chain Truth: If the attestors report an incorrect value, the vault will use that incorrect value to price its shares.
Malfeasance: If a sufficient number of attestors (the required 2-of-N threshold) collude or are compromised, they can maliciously inflate or deflate the reported balance. Inflating the balance artificially raises the vault's NAV, allowing early withdrawers to extract more value than their fair share. Deflating the balance unfairly penalizes users attempting to withdraw during that period.
The Circuit Breaker Mitigation: The primary defense against custodial compromise—aside from careful selection of reputable attestors—is the BIG_CHANGE_BPS parameter. If a confirmed balance update alters the total NAV by a percentage exceeding this threshold, the vault automatically pauses.
- Tradeoff: While this circuit breaker protects users from erroneous or malicious reporting, it can trigger "false positives" during legitimate, sudden market volatility. If tripped, it requires manual intervention from an Atomist (via off-chain signatures and the ExternalStateUnpauseFuse) to resume operations, leading to temporary illiquidity for users.

Operational and Liveness Risks

The reliance on off-chain reporting pipelines introduces risks related to the timeliness of data feeds.

Stale Balances: The ExternalStatePausePreHook actively monitors the timestamp of the last confirmed balance update. If attestors fail to provide updates within the configured STALENESS_MAX period, the vault will automatically pause all user-facing operations (deposit, withdraw, etc.). A failure in the off-chain reporting pipeline (e.g., server downtime) directly leads to a denial-of-service condition for depositors until fresh data is provided.
Rate Limiting Constraints: The MIN_UPDATE_INTERVAL prevents reporters from spamming updates. While this protects against certain network attacks, it means the vault's NAV may temporarily lag behind the true off-chain value during periods of high volatility.

Target Configuration Risk (The Generic Proxy Problem)

While a malicious Atomist could compromise any vault by explicitly deploying a malicious custom fuse, the External State framework expands the surface area for accidental configuration errors.

Hardcoded vs. Dynamic Targets: In a standard DeFi integration (e.g., AaveV3SupplyFuse), the target protocol address is hardcoded into the immutable smart contract logic. The fuse only knows how to interact with Aave. The ExternalStateOperationFuse, however, acts as a generic proxy executor. It relies entirely on TARGET substrates to know which external contracts and functions it is allowed to call.
Misconfiguration Impact: The Atomist must explicitly allowlist every (targetAddress, functionSelector) pair. If an Atomist accidentally allowlists a sensitive function (such as an unverified contract, or a generic transfer function to an arbitrary address), the Alpha role suddenly gains the ability to execute those calls and drain the funds held in the ExternalStateExecutor. The security boundary here relies strictly on diligent, error-free substrate configuration by the Atomist, making it uniquely vulnerable to human error compared to standard, purpose-built fuses.

Last updated 1 month ago

Was this helpful?