> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperlane.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Details

## Overview

Metastable is built on top of [Hyperlane Warp Routes 2.0](https://docs.hyperlane.xyz/docs/applications/warp-routes/multi-collateral-warp-routes.md).

Each chain in a Metastable route has a [**`CrossCollateralRouter`**](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol) deployed for each collateral token (e.g. one for USDC, one for the branded stablecoin). `CrossCollateralRouter` extends `HypERC20Collateral`, so each instance holds collateral for exactly one ERC-20.

Every router has an **owner**, the admin address set at deployment. It's typically a wallet or multisig held by the issuing team. The owner manages a per-domain allowlist of trusted peer `CrossCollateralRouter`s, using [`enrollCrossCollateralRouters`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol#L85) and [`unenrollCrossCollateralRouters`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol#L98), which write to the `_crossCollateralRouters` mapping (domain → set of router addresses). A single primary remote router can also be enrolled per domain through the standard `Router` enrollment. Together these define which source/destination pairs are valid for a given route, and allow multiple target routers on the same destination chain (for example, several branded stablecoins).

> [!NOTE]
>
> **Token support:** standard ERC-20s only. Rebasing tokens, fee-on-transfer
> tokens, and ERC-777 are not supported. The contract relies on exact-amount
> accounting.

## Cross-chain swap flow

1. The stablecoin holder's wallet (`msg.sender`) calls [`transferRemoteTo`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol#L327) on the source chain router with the destination domain, recipient, amount, and target router.
2. The source router validates that the target router is enrolled, pulls `amount + protocol fee + external fee` from `msg.sender`, routes each fee to its configured fee address, and dispatches a single interchain message via Hyperlane.
3. The destination router receives the message, verifies it came from a trusted router, and releases the full `amount` of the target stablecoin to the recipient.

Routers expose a single function for both cross-chain and same-chain swaps:

```solidity theme={null}
transferRemoteTo(
    uint32 destination,    // destination domain ID
    bytes32 recipient,     // recipient address on destination
    uint256 amount,        // amount of source token
    bytes32 targetRouter   // enrolled CrossCollateralRouter on destination
) public payable returns (bytes32 messageId)
```

The returned `messageId` is the Hyperlane message ID used to track delivery (for example, in the Hyperlane Explorer).

## Same-chain swap flow

Same-chain swaps use the same `transferRemoteTo` function, but pass the local domain as the destination. The source router skips mailbox dispatch and calls the target router's [`handle`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol#L180) directly. No interchain relay, no gas payment. The function returns the zero hash since no message is dispatched.

To allow this, `CrossCollateralRouter` overrides `handle` to drop the standard `onlyMailbox` modifier. The override accepts two callers:

* **The mailbox**, for cross-chain messages (origin must be a different domain).
* **Another local `CrossCollateralRouter`**, for same-chain swaps (the caller must be enrolled in this router's local-domain allowlist).

## Fee quoting

Fees are configured per destination domain and per target router. Call [`quoteTransferRemoteTo`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRouter.sol#L394) on the source router before a swap to get the exact cost for a route:

```solidity theme={null}
quoteTransferRemoteTo(
    uint32 destination,
    bytes32 recipient,
    uint256 amount,
    bytes32 targetRouter
) public view returns (Quote[] memory quotes)
```

Each `Quote` is `{ address token, uint256 amount }`. The function returns an array of **three** entries, in this order:

1. **Interchain gas**: paid in `feeToken()`. Zero for same-chain swaps.
2. **Token amount + protocol fee**: the source token amount being transferred, plus the protocol fee.
3. **External fee**: additional fee in the source token. Zero when no external fee is configured for the route.

The stablecoin holder (`msg.sender`) pays entries 2 and 3 in the source token (sum them for total source-token cost) plus entry 1 in `feeToken()` for interchain gas. The recipient (usually the same holder on the destination chain) receives the full `amount` of the target token.

The fee comes from a fee contract set as the router's `feeRecipient`. By default, that's [`CrossCollateralRoutingFee`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/CrossCollateralRoutingFee.sol), which points each route at its own pricing contract, either a fixed schedule or an off-chain signed quote ([`OffchainQuotedLinearFee`](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/solidity/contracts/token/fees/OffchainQuotedLinearFee.sol)) for cases like a preferential 1:1 rate. Routes with no fee recipient charge no protocol fee.

## Liquidity and rebalancing

Liquidity for a Metastable route lives directly in the router contracts. The issuing team funds each `CrossCollateralRouter` with its collateral token, and swaps are settled from those reserves.

As swap volume flows in one direction, a router can run low on the collateral it holds. Metastable uses the same onchain rebalancing as [HWR 2.0](https://docs.hyperlane.xyz/docs/guides/warp-routes/evm/multi-collateral-warp-routes-rebalancing.md): the rebalancer monitors inventory levels and moves collateral between chains to restore target weights, keeping routes available without manual intervention.

> [!NOTE]
>
> **Why rebalancing is different in Metastable:** In a same-asset
> multi-collateral route, restoring balance is straightforward — the rebalancer
> moves the same token between chains. Metastable routes hold *different* assets
> on each side, so an imbalance often can't be fixed by moving the source token,
> since the scarce asset has to be sourced directly (e.g. acquiring more of the
> branded stablecoin on a chain where it's been drawn down). That extra step
> relies on external liquidity and carries real cost beyond the cross-chain
> transfer itself. The mechanics stay automatic; the operating economics are
> what change.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.