> For the complete documentation index, see [llms.txt](https://docs.ipor.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipor.io/build-on-fusion/developer-guide/cross-chain-vault-integration-technical-overview.md).

# Cross-Chain Vault Integration - Technical Overview

Technical detail behind cross-chain vault integration: NAV attestation and emergency recovery roles.

## 1. Architecture Overview

The IPOR Fusion Cross-Chain Vault system extends the core `PlasmaVault` architecture to enable asynchronous, secure, and transport-agnostic capital allocation across multiple blockchain networks. By leveraging the existing modular Fuse system, source-chain vaults can permissionlessly deploy liquidity to destination-chain strategies while maintaining a unified ERC4626 interface for end-users.

### 1.1. Core Design Principles

The cross-chain architecture is built upon three foundational pillars:

1. **Hub and Spoke Execution:** User interactions (deposits, withdrawals, and share minting) are strictly isolated to the Source Vault (the Hub). Destination networks host Remote Vaults (the Spokes) which are dedicated exclusively to local yield generation and cannot accept direct user deposits.
2. **Asynchronous Accounting (Fail-Closed):** Cross-chain messaging is inherently asynchronous and subject to transport delays or execution failures. The system implements a "fail-closed" state machine utilizing Epochs and State Versions to track pending transactions. If a message fails, the vault protects user funds by temporarily locking state transitions until the failure is repaired or rescued by a Guardian.
3. **Transport Agnosticism:** The bridging layer is structurally abstracted. The core cross-chain logic does not depend on a specific bridge, allowing the protocol to securely route liquidity using the optimal transport layer (e.g., Stargate or Chainlink CCIP) based on the asset type and destination network.

### 1.2. Component Roles & Relationships

The cross-chain flow involves a precise choreography between source and destination components. This separation of concerns ensures that the core `PlasmaVault` logic remains pristine, offloading cross-chain complexity to dedicated adapters.

* **Source Vault (`PlasmaVault`):** The primary ERC4626 vault where liquidity providers deposit assets. It holds the canonical state of total assets (NAV), issues shares, and acts as the central command center for the `ALPHA_ROLE` strategist.
* **Crosschain Fuses:** Operation and balance fuses natively attached to the Source Vault. For example, a `CrosschainBalanceFuse` tracks the value of assets deployed on remote chains, while a `CrosschainClaimFuse` initiates the harvesting of remote yields.
* **Dispatcher:** The remote operator contract deployed on the destination chain. It holds the tracked remote assets and executes authenticated commands.
* **Executor:** The vault-specific gateway deployed on the source chain. It acts as the origin point for all cross-chain commands and maintains the source-side accounting ledger.
* **Remote Vault (`PlasmaVault`):** A streamlined vault deployed on the destination chain. It receives liquidity from the Dispatcher and utilizes its own local Fuse system to deploy capital into destination-native DeFi protocols.

### 1.3. Transport Layers: Stargate vs. CCIP

To maximize security and routing efficiency, the IPOR Fusion Cross-Chain architecture supports multiple arbitrary messaging bridges (AMBs). The initial implementation provides native integration for **Stargate** (built on LayerZero V2) and **Chainlink CCIP**.

* **Stargate Transport:** Optimized for highly liquid stablecoin transfers and native asset routing. It utilizes LayerZero's messaging primitives to provide fast, cost-efficient execution. The `StargateCrosschainFactory` handles the deployment.
* **Chainlink CCIP Transport:** Utilized for scenarios requiring Programmable Token Transfers combined with maximum security guarantees. CCIP benefits from Chainlink's Risk Management Network, making it the preferred transport for large-scale operations. Configured via the `CcipCrosschainFactory`.

## 2. Smart Contract Components

The cross-chain architecture relies on a suite of specialized smart contracts designed to strictly segregate bridging logic from core vault accounting. This modularity ensures that the `PlasmaVault` remains secure and unaware of transport-specific complexities.

#### 2.1. Factories (`StargateCrosschainFactory`, `CcipCrosschainFactory`)

Factories serve as the shared platform infrastructure responsible for the deterministic deployment and configuration of cross-chain components. There is a distinct factory implementation for each supported transport layer.

* **Deterministic Deployment (`CREATE3`):** Factories utilize `CREATE3` to ensure that an Executor deployed on the source chain and its corresponding Dispatcher deployed on the destination chain share the exact same contract address. This same-address pairing is a foundational security guarantee for cross-chain authentication.
* **Route and Asset Governance:** Factories maintain the canonical configuration of supported source-to-destination routes, cross-chain gas policies, fee ceilings, and allowed bridge tokens.
* **Access Control:** Factory configurations are governed by the platform team (often behind a timelock) and can enforce creator restrictions, allowing only approved addresses to deploy new Executor instances.

### 2.2. Executors

The **Executor** is the vault-specific gateway deployed on the source chain. It acts as the origin point for all cross-chain commands and maintains the source-side accounting ledger.

* **Immutable Binding:** An Executor is not a shared omnibus account. Upon deployment, it is permanently bound to a single `MANAGER` (the source `PlasmaVault`), a specific asset, and a specific transport layer.
* **Source Accounting:** The Executor tracks the business state of capital through different phases:
  * `idle`: Assets returned to the source chain but not yet claimed by the vault.
  * `inFlight`: Outbound assets awaiting authenticated settlement on the destination chain.
  * `settled`: The approved, canonical value of assets deployed remotely.
* **Recovery Boundary:** Each Executor maintains its own isolated incident state, ensuring that a failure in one cross-chain lane does not halt operations in another vault's Executor.

### 2.3. Dispatchers

The **Dispatcher** is the remote operator contract deployed on the destination chain. It receives instructions exclusively from its same-address Executor counterpart on the source chain.

* **Remote Custody:** The Dispatcher holds the "tracked idle" assets on the destination chain as well as the shares issued by remote ERC-4626 vaults.
* **Execution Engine:** It decodes authenticated commands (e.g., `DEPOSIT`, `REDEEM`, `REQUEST_SHARES`) and executes them against the allowlisted remote vaults.
* **Canonical State Publication:** The Dispatcher exposes a public, monotonic state version and accounting epoch. Off-chain observers read this state to attest to the remote NAV back on the source chain.

### 2.4. Fuses

Fuses act as the connective tissue between the source `PlasmaVault` and the Executor, translating standard portfolio manager intents into cross-chain operations.

* **Transport Supply Fuses:** Validates vault liquidity and transfers fresh assets to the Executor, initiating an outbound bridging message to the destination Dispatcher. It is also used to trigger asynchronous `RECALL` requests.
* **Transport Command Fuses:** Dispatches authenticated business actions (e.g., allocating tracked idle assets into a specific remote vault) to the destination chain.
* **`CrosschainClaimFuse`:** A shared, transport-agnostic fuse that pulls returning `idle` assets from the Executor back into the source `PlasmaVault`'s active balance.
* **`CrosschainBalanceFuse`:** Calculates the tracked market value of one or more Executors. It aggregates `idle`, `inFlight`, and `settled` ledgers, prices the Executor's asset using the vault's `PriceOracleMiddleware`, and returns the USD-WAD market value for the vault's NAV calculation.

### 2.5. Hooks (`CrosschainNavValidationPreHook`)

To protect the integrity of the source vault's share price during cross-chain operations, the system introduces the `CrosschainNavValidationPreHook`.

* **Fail-Closed Protection:** If cross-chain messaging stalls, observations expire, or a state-version gap is detected, the `CrosschainBalanceFuse` will revert to protect against pricing inaccuracies.
* **Share-Price Gating:** The `CrosschainNavValidationPreHook` catches this "fail-closed" state and blocks all share-price-sensitive operations on the `PlasmaVault` (e.g., `deposit`, `mint`, `withdraw`, `redeem`).
* This ensures users cannot enter or exit the vault at a distorted valuation when the remote state is unverified or compromised.

### 2.6. Attestation & Rescue Modules

Because cross-chain bridges are asynchronous and cannot directly return synchronous return values, the architecture relies on robust attestation and recovery modules.

* **Attestation Library:** Implements a two-role approval process (`PROPOSER` and `APPROVER`) to recognize remote yield. An off-chain observer reads the Dispatcher's state and proposes it on the source chain. The approver validates the state version and freshness before the Executor's `settled` ledger is updated.
* **Rescue Module:** A generic, delayed break-glass mechanism built into both Executors and Dispatchers. It allows a `RESCUE_ADMIN` to schedule arbitrary recovery transactions (e.g., recovering stuck tokens). To prevent abuse, all rescue actions are subject to a mandatory 24-hour timelock and can be unilaterally canceled by an independent `RESCUE_GUARDIAN`.

## 3. Substrates & Configuration

The IPOR Fusion architecture uses "substrates" as granular permission identifiers. The cross-chain integration extends this system by introducing specific typed substrates that authorize remote execution pathways. This ensures that the portfolio manager (the `ALPHA_ROLE`) cannot arbitrarily bridge funds or interact with unvetted remote contracts.

### 3.1. EXECUTOR Substrates

Before a source `PlasmaVault` can interact with an Executor, the vault's governance (`ATOMIST_ROLE`) must explicitly grant it permission using an `EXECUTOR` substrate.

* **Structure:** An `EXECUTOR` substrate is a `bytes32` identifier generated by encoding the specific Executor contract address.
* **Validation:** Both the `CrosschainSupplyFuse` and the `CrosschainCommandFuse` validate that the target Executor is granted as a substrate on the source vault.
* **Purpose:** This prevents the portfolio manager from routing funds to unauthorized bridging contracts or rogue Executors, effectively locking the outbound capital flow to verified pathways.

### 3.2. REMOTE\_VAULT Substrates

To control where capital is deployed on the destination chain, the source vault uses `REMOTE_VAULT` substrates.

* **Structure:** A `REMOTE_VAULT` substrate binds a specific destination `chainId` to a specific `remoteVaultAddress`. This prevents the ambiguity of using the same vault address on the wrong network.
* **Source-Side Enforcement:** When the portfolio manager submits a command (e.g., `DEPOSIT`) via the `CrosschainCommandFuse`, the fuse verifies that the target `(chainId, remoteVaultAddress)` is an approved `REMOTE_VAULT` substrate on the source `PlasmaVault`.
* **Destination-Side Enforcement:** The remote Dispatcher only executes authenticated commands. Because the command originated from the source vault (which already validated the substrate), the Dispatcher implicitly trusts the target. However, as a secondary defense, the Dispatcher also maintains its own local allowlist of approved remote vaults.

### 3.3. Market ID Assignments

In the IPOR Fusion architecture, every integration is associated with a specific `MARKET_ID`. The cross-chain integration utilizes dedicated market IDs to group related Executors and define their dependencies.

* **Cross-Chain Market ID:** A unique market ID (e.g., `CROSSCHAIN_MARKET`) is assigned to group all Executors belonging to a specific cross-chain strategy.
* **Balance Fuse Association:** The `CrosschainBalanceFuse` is registered against this specific cross-chain market ID. When `PlasmaVault.updateMarketsBalances()` is called, it triggers the balance fuse for this market, updating the aggregate tracked value of all granted Executors.
* **Dependency Graph:** The cross-chain market depends on the `ERC20_VAULT_BALANCE` market. This dependency ensures that the vault's local token balances are updated before calculating the cross-chain NAV, preventing double-counting during the `claim` process when assets move from the Executor's `idle` ledger back into the vault's local token balance.

## 4. Execution Flows

This section details the lifecycle of capital and operational commands as they move between the source `PlasmaVault` and destination remote vaults. The operations rely on the `ALPHA_ROLE` passing specific `FuseAction` payloads to `PlasmaVault.execute()`.

### 4.1. Deployment & Initialization

Before any capital is moved, the lane must be initialized:

1. **Factory Setup**: Shared transport infrastructure is deployed and routes are configured by the platform team.
2. **Executor & Dispatcher Creation**: The factory deploys a vault-specific Executor on the source chain, followed by a deterministically paired Dispatcher on the destination chain.
3. **Source Configuration**: Vault governance (`ATOMIST_ROLE`) registers the transport fuses, balance fuse, claim fuse, and the NAV pre-hook. It also grants the necessary `EXECUTOR` and `REMOTE_VAULT` substrates.
4. **Bounded Canary**: A small, bounded test transaction is executed to verify end-to-end accounting and attestation before full exposure limits are approved.

### 4.2. Cross-Chain Supply (Source to Destination)

To move fresh liquidity to a remote network, the portfolio manager initiates a supply action.

* **Execution**: The `ALPHA_ROLE` calls `execute()` with a `FuseAction` targeting the transport-specific supply fuse. The fuse verifies live NAV and transfers assets from the `PlasmaVault` to the Executor.
* **Bridging**: The Executor dispatches the underlying assets via the configured transport layer (e.g., CCIP or Stargate) to the remote Dispatcher.
* **Accounting State**: The assets transition from the vault's local physical balance to the Executor's `inFlight` ledger. They are not considered `settled` until an authenticated destination response completes the accounting transition.

### 4.3. Remote Vault Deposit/Redeem

Once assets arrive safely at the Dispatcher, they are classified as tracked `idle` remote assets. The `ALPHA_ROLE` can now allocate them to remote yield strategies.

* **Deposit**: The manager sends a `DEPOSIT` command via the `CrosschainCommandFuse`. The source validates the `REMOTE_VAULT` substrate. Once received by the Dispatcher, it deposits the `idle` assets into the allowlisted remote ERC-4626 vault and begins tracking the issued shares.
* **Redeem**: The manager sends a `REDEEM` command. The Dispatcher redeems the specified shares, converting them back into tracked `idle` assets.
* **Asynchronous Withdrawals**: If the remote PlasmaVault utilizes an asynchronous withdrawal queue, the redemption requires two sequential commands: `REQUEST_SHARES` (entering the queue) followed by `REDEEM_FROM_REQUEST` (claiming the assets once the lockup expires).

### 4.4. Recall and Claim (Destination to Source)

Returning capital to the source vault is a managed, two-step asynchronous process to protect against liquidity shocks.

1. **Recall**: The `ALPHA_ROLE` triggers a `RECALL` request through the source supply fuse. The Dispatcher on the destination chain packages the requested `idle` assets and sends them back across the bridge.
2. **Claim**: When the assets arrive at the source Executor, they are added to the source `idle` ledger. Finally, the `ALPHA_ROLE` executes the shared `CrosschainClaimFuse`, which pulls the assets from the Executor back into the source `PlasmaVault`'s active balance, restoring local liquidity.

### 4.5. NAV Attestation Flow

Because physical token balances on remote chains cannot be synchronously read, the system relies on an off-chain attestation pipeline to recognize remote yield.

1. **Observation**: The remote Dispatcher exposes a canonical observation containing its `idle` balances and remote vault shares, tied to a monotonic state version.
2. **Proposal**: An off-chain observer prepares this state, and an independent `PROPOSER` submits it to the source Executor.
3. **Approval**: An independent `APPROVER` verifies the state's freshness and version sequencing. Once approved, the Executor's `settled` ledger is updated with the new valuation.
4. **Market Refresh**: Immediately following approval, the source vault's `updateMarketsBalances()` function must be called. This triggers the `CrosschainBalanceFuse` to read the new `settled` value and persist the updated cross-chain market NAV within the `PlasmaVault` cache. Share-price-sensitive operations are then permitted against the fresh valuation.

## 5. NAV and Accounting Internals

Accurate Net Asset Value (NAV) reporting is essential for maintaining the integrity of the ERC4626 share price. Cross-chain operations introduce the challenge of asynchronous state. To address this safely, the IPOR Fusion Cross-Chain architecture decouples physical token balances from accounted value and implements strict fail-closed state machines.

### 5.1. Tracked Value vs. Physical Balances

The architecture relies strictly on "tracked value" ledgers rather than raw `IERC20.balanceOf()` readings. This design prevents direct, unauthenticated token transfers (e.g., unexpected airdrops or "donations" to the Dispatcher) from instantly distorting the vault's NAV.

Value is divided into strict accounting ledgers across the two chain environments:

* **Source Executor Ledgers:**
  * `idle`: Assets successfully returned to the source chain via a recall, but not yet swept into the primary `PlasmaVault` by the Claim Fuse.
  * `inFlight`: Outbound assets that have left the source chain but are awaiting authenticated delivery confirmation on the destination chain.
  * `settled`: The last approved, canonical valuation of assets deployed remotely on the destination chain.
* **Remote Dispatcher Ledgers:**
  * `idle`: Unallocated assets physically held by the Dispatcher.
  * `remote shares`: Tracked share positions in approved ERC4626 remote vaults.
  * `pending requests`: Tracked shares locked in remote asynchronous withdrawal queues.
  * `queued response`: Token value queued for an outbound recall response (specifically applicable for CCIP transports).

When the `CrosschainBalanceFuse` calculates the market value, it sums the Executor's `idle`, `inFlight`, and `settled` ledgers. It then prices the aggregated underlying asset using the source vault's `PriceOracleMiddleware` to return the precise USD-WAD market value. Remote yield only affects the `settled` ledger after passing through the off-chain attestation pipeline.

### 5.2. The Fail-Closed Mechanism

Because cross-chain bridging is asynchronous, transport layers can experience congestion, outages, or delivery failures. To protect liquidity providers from minting or redeeming shares against stale or inaccurate valuations during these periods, the system adopts a "fail-closed" security posture.

The `CrosschainBalanceFuse` actively monitors the health of the cross-chain lane. A call to `getBalance()` will intentionally revert if any of the following safety tripwires are hit:

1. Stale NAV: The last approved remote observation exceeds the configured maximum staleness threshold.
2. Stale In-Flight Transfers: An outbound transfer has remained in the `inFlight` ledger longer than the configured maximum settlement time.
3. Blocked Lanes: A state-version gap is detected, indicating that a sequential bridging message was lost or skipped, rendering the current state unreliable.

When the balance fuse reverts, it triggers the `CrosschainNavValidationPreHook`. This hook acts as a circuit breaker attached to the source `PlasmaVault`. By catching the fail-closed state, it blocks share-price-sensitive vault entry points:

* `deposit` and `depositWithPermit`
* `mint`
* `withdraw`
* `redeem` and `redeemFromRequest`
* `updateMarketsBalances`

Special Handling for `execute`: Unlike deposits and withdrawals which are strictly blocked, the pre-hook delegates the blocking decision for `execute` to fuse-level controls. This crucial distinction ensures that while new cross-chain exposure is blocked during a fail-closed state, approved recovery and rescue actions can still continue within a narrowly scoped recovery context.

### 5.3. State Versions & Epochs

To guarantee that remote observations are processed sequentially and accurately, the accounting system utilizes monotonic identifiers.

* **State Versions:** The remote Dispatcher maintains a monotonic `stateVersion`. Every time a value-mutating remote action occurs (e.g., executing a remote `DEPOSIT` or generating yield), this version increments. When proposing a new remote observation back to the source Executor, the off-chain observer must include this state version. The source strictly validates that version numbers are sequential. If a state-version gap is detected (e.g., bridging message #4 arrives but message #3 never settled), the Executor enters a blocked state.
* **Epochs:** The `epoch` counter tracks major structural configuration changes (like redefining rescue roles or changing allowed vault parameters). If an observer attempts to attest to a remote balance using an outdated epoch, the `APPROVER` pipeline will reject it, ensuring that old state cannot overwrite new architectural rules.

## 6. Transports and Cross-Chain Messaging

The IPOR Fusion cross-chain architecture abstracts the underlying messaging protocols while strictly isolating their execution contexts. To prevent complex failure dependencies, the system does not automatically route between different bridge providers. Instead, a dedicated `Executor` and `Dispatcher` pair is deployed for each specific transport and asset combination.

The current implementation natively supports two isolated transport stacks: Chainlink CCIP and Stargate with LayerZero V2.

### 6.1 Transport Layer Comparison

While both transports expose a unified interface to the PlasmaVault's supply and command fuses, their underlying mechanics, routing identities, and failure-handling models differ significantly.

| **Capability**    | **Chainlink CCIP**                                                   | **Stargate / LayerZero V2**                                      |
| ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Asset Movement    | Programmable Token Transfers (via CCIP Router).                      | Stargate `taxi` transfers with a mandatory `compose` payload.    |
| Message Transport | CCIP Router messages.                                                | LayerZero V2 OApp messages.                                      |
| Route Identity    | Immutable CCIP chain selector and registered peer.                   | Append-only chain ID/EID mapping and same-address peer.          |
| Remote Responses  | Ordered, bounded FIFO response queue with permissionless head flush. | LayerZero delivery/retry execution model.                        |
| Recall Behavior   | Token-bearing return response via CCIP.                              | Request via OApp, Stargate token/compose return.                 |
| Fee Model         | Native or configured fee token, bounded by per-call ceilings.        | Native token budgets for LayerZero/Stargate sends and responses. |

*Note on USDC Operations: Both transports utilize their respective protocol-configured USDC liquidity pools. The current implementation does not integrate native Circle CCTP directly.*

### 6.2 Chainlink CCIP Implementation

The CCIP implementation (`CcipCrosschainFactory`, `CcipRouteLib`) uses Chainlink's arbitrary messaging combined with Programmable Token Transfers.

FIFO Response Queue & Flushing:

Because CCIP strictly orders messages, a failed remote execution on the source chain (e.g., due to an out-of-gas error or logic revert upon receiving an ACK/NACK) can block subsequent messages in the lane. To prevent channel blocking, the CCIP `Dispatcher` implements a bounded FIFO response queue.

* If a response fails to process automatically upon delivery, it is queued.
* Keepers or users can invoke a permissionless flush of the FIFO head once the underlying issue (e.g., insufficient fee budget) is resolved.
* A guardian-vetoable delayed skip is available as an emergency break-glass mechanism if a queued response is permanently unprocessable.

Delivery Policy and Fees:

Route policies—including fee tokens, gas limits, and fee ceilings—are governed by the factory. Route policy updates utilize a 24-hour configuration delay to protect inflight messages, followed by permissionless synchronization across the lane.

### 6.3 LayerZero V2 & Stargate Implementation

The Stargate implementation leverages LayerZero V2's Omnichain Application (OApp) standard for passing arbitrary logic, coupled with Stargate V2 `taxi` transfers for capital movement.

Execution and Retries:

Unlike the CCIP implementation, LayerZero V2 handles message execution and retries natively at the protocol layer via the `EndpointV2`.

* Outbound messages are paid for using native gas budgets.
* If a `compose` payload or OApp message fails on the destination, it is caught by the LayerZero endpoint's internal retry mechanism rather than a custom vault-level FIFO queue.
* The route mapping relies on EID (Endpoint ID) mappings, which are append-only to prevent historical message corruption.

### 6.4 Message Lifecycle and Delivery Guarantees

Both implementations guarantee strict ordering for business commands to prevent race conditions during remote strategy execution. The lifecycle enforces the following rules:

1. One Active Command Limit: The `Executor` allows only one active business or configuration command per destination chain. Subsequent commands revert until the active command receives a terminal response.
2. Sequenced ACK / NACK:
   * ACK (Acknowledgement): The destination `Dispatcher` successfully executed the command (e.g., deposited into the remote ERC-4626 vault). The sequence is finalized.
   * NACK (Negative Acknowledgement): The remote execution reverted (e.g., due to slippage bounds or paused remote vaults). The command is returned as failed.
3. Retry and Cancellation: A command that results in a NACK is not automatically discarded. The `ALPHA_ROLE` can explicitly trigger a retry of the failed command or formally cancel it to clear the lane.
4. Command Abandonment: If a command is sent but an ACK/NACK response is permanently lost (due to bridge failure or irrecoverable state), a delayed, vetoable rescue action must be utilized to abandon the command and reconcile accounting.

## 7. Security, Governance, and Access Control

The cross-chain architecture extends IPOR Fusion's robust `IporFusionAccessManager` with domain-specific access controls. Because cross-chain operations introduce asynchronous state and bridge-dependency risks, the system strictly separates day-to-day portfolio management from NAV attestation and emergency recovery.

### 7.1 Immutable Vault Binding

To prevent omnibus-style commingling of funds, the `Executor` is not a shared router. Upon deployment, the `Executor` is permanently bound to a single source `PlasmaVault` (assigned as the immutable `MANAGER`).

* The supply and command fuses actively verify this relationship before forwarding any `FuseAction`.
* The destination `Dispatcher` deterministically inherits this isolation, accepting authenticated messages only from its paired `Executor`.

### 7.2 Attestation Roles: Proposer and Approver

To prevent a single compromised key from artificially inflating the source vault's Net Asset Value (NAV), remote yield recognition requires a two-role attestation process on the `Executor`:

* `PROPOSER_ROLE`: Responsible for querying the remote `Dispatcher`, structuring the canonical observation, and proposing it to the `Executor`.
* `APPROVER_ROLE`: Independently verifies the proposed state (including state versions, aggregate vault shares, and tracked idle assets) and approves it.

*Note: The smart contract enforces that the `PROPOSER_ROLE` and `APPROVER_ROLE` must be distinct addresses. Approvals are subject to configurable freshness thresholds and large-change rate limits.*

### 7.3 Recovery Roles: Admin and Guardian

The generic rescue mechanism provides a powerful break-glass authority to execute arbitrary calls from the `Executor` or `Dispatcher` during critical bridge failures. To secure this, control is bifurcated:

* `RESCUE_ADMIN`: Schedules and executes delayed recovery actions. This role operates as a full delayed administrator and should be assigned to a multisig or timelocked governance contract.
* `RESCUE_GUARDIAN`: Possesses the authority to veto and cancel one or all pending rescue actions.

*Note: The `RESCUE_ADMIN` and `RESCUE_GUARDIAN` must be independent addresses. The system natively enforces a strict minimum 24-hour execution delay on all scheduled rescues.*

### 7.4 PlasmaVault Configuration and Substrates

On the source `PlasmaVault`, cross-chain interactions are authorized by the `ATOMIST_ROLE` using the standard `PlasmaVaultGovernance` interface. Integration requires granting typed substrates via `CrosschainSubstrateLib`:

1. Executor Substrates: Granted as `EXECUTOR(executorAddress)` to authorize the vault to supply capital to the bridge.
2. Remote Vault Substrates: Granted as `REMOTE_VAULT(chainId, vaultAddress)` to explicitly allowlist destination ERC-4626 vaults. The `Dispatcher` will reject any `DEPOSIT` command targeting a vault not explicitly granted by the source.

## 8. Failure Handling and the Rescue Module

Cross-chain messaging protocols are subject to latency, message loss, and destination-chain reversions. The IPOR Fusion cross-chain architecture is built to gracefully handle `NACK` (Negative Acknowledgement) responses, state desynchronization, and permanent channel blocks.

### 8.1 Structural Safety Bounds

To prevent out-of-gas errors and limit theoretical exposure during incident response, the contracts enforce strict structural bounds:

* Max Remote Vaults: Maximum 32 approved/tracked remote-vault positions per `Dispatcher`.
* Max In-Flight Transfers: Maximum 16 concurrent in-flight transfer records per chain where the transfer-slot model applies.
* Active Commands: Only 1 active business or configuration command, and 1 active recall permitted per destination chain at any time.
* FIFO Bounds: Maximum 64 queued responses in the CCIP `Dispatcher`.
* Stargate Chain Limits: Maximum 32 registered Dispatcher chains in the Stargate Executor.
* Rescue Queue: Maximum 64 pending rescue records.

### 8.2 Command Failures and Retries

If a remote execution fails (e.g., due to slippage bounds in the remote ERC-4626 vault or a paused protocol), the destination returns a `NACK`. The active command sequence remains open on the source `Executor`.

* Retry: The `ALPHA_ROLE` can adjust parameters (if applicable) and trigger a retry of the failed command.
* Cancellation: The `ALPHA_ROLE` can formally cancel the failed command, resetting the lane and moving the allocated capital back to the tracked remote idle ledger.

### 8.3 State-Version Gaps and Frontier Repair

The `Dispatcher` increments a monotonic state version on material accounting transitions. If the source `Executor` receives an observation where $$ $v\_{remote} > v\_{source} + 1$ $$, it indicates a lost or permanently stalled message.

* This immediately triggers the fail-closed NAV protection, halting share-price-sensitive operations.
* Operators must utilize the Frontier Repair mechanism. This allows the system to advance the source state version (up to 32 versions per action) after a 6-hour cooldown, forcefully reconciling the accounting ledgers and allowing fresh attestations to resume.

### 8.4 The Rescue Module

When standard retry or cancellation paths are insufficient (e.g., unexpected token surpluses, permanent bridge blacklisting, or lost outbound settlement evidence), the `RescueModule` is invoked.

Tracked-Ledger Protection:

While the `RescueModule` can execute broad calls, it is constrained by a strict accounting invariant. The `RescueModule` cannot transfer or rescue tokens that are actively accounted for in the `Executor` or `Dispatcher` tracked ledgers (Settled Value, In-Flight, or Tracked Idle). It can only be used to extract untracked fee dust or unexpected airdrops/donations.

If tracked backing must be manually manipulated due to a catastrophic bridge failure, it requires a fully governed, delayed force-resolution path that explicitly declares the final accounting outcome, subject to the `RESCUE_GUARDIAN` veto.