Cross-VM Router
Relevant source files
The following files were used as context for generating this wiki page:
The Cross-VM Router is a core architectural component of the X3 Chain designed to facilitate atomic message and asset transfers across three primary execution domains: X3Native, X3Evm, and X3Svm. It operates as a 6-route matrix that ensures state consistency and enforces supply invariants during internal chain movements. By providing a unified settlement layer, the router allows tokens to exist across multiple virtual machine environments without fragmented supply or the security risks associated with asynchronous external bridging.
Sources: README.md:46-56, crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:460-470
Architecture and Components
The Cross-VM Router resides within the pallets/x3-cross-vm-router module and integrates directly with the X3 Kernel and Supply Ledger. Its primary responsibility is managing the lifecycle of cross-domain packets and instructions (IXL).
Routing Matrix
The router supports six internal routes connecting the three main domains:
- X3Native ↔ X3Evm
- X3Native ↔ X3Svm
- X3Evm ↔ X3Svm
Sources: MAINNET_LAUNCH_CHECKLIST.md:54-55, crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:417-422
Domain and Account Mapping
The system uses a domain separation strategy to prevent replay attacks and ensure correct routing. Domains are identified by unique IDs, and accounts are mapped using a canonical AccountBytes enum.
| Domain Name | Domain ID | Target Account Type |
|---|---|---|
| X3Native | 1 | AccountBytes::X3Native([u8; 32]) |
| X3Evm | 2 | AccountBytes::Evm([u8; 20]) |
| X3Svm | 3 | AccountBytes::Svm([u8; 32]) |
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:144-160
Technical Integration Flow
The following diagram illustrates how the Cross-VM Router interacts with the different virtual machine environments and the underlying settlement engine.
The router acts as the central coordinator, ensuring that any movement between VMs is validated by the Supply Ledger before execution.
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:118-132, reports/prompt-runs/prompt-full-20260427T225413Z.md:75-85
Core Logic and Invariants
The Cross-VM Router is governed by a "King Invariant" which dictates that no sequence of calls can create more token representation than the canonical supply locked in the system.
The King Invariant
The total represented supply across all domains must always be less than or equal to the canonical supply:
native_supply + evm_vm_supply + svm_vm_supply + pending_supply <= canonical_supply
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:14-20
State Transitions
The router handles transfers through a defined lifecycle to prevent "stuck" funds and double-spending:
- Source Debited: The sender's balance is locked or burned in the source domain.
- Pending State: The amount is added to the
pending_supplybucket. - Destination Credited: The amount is minted or unlocked in the destination domain.
- Finalized: The transfer is complete;
pending_supplyreturns to zero. - Refund Path: If destination credit fails or the transfer expires (default 100 blocks), the funds are returned to the source.
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:195-215, MAINNET_LAUNCH_CHECKLIST.md:57-61
Replay Protection
Replay protection is enforced using domain-separated message IDs. A StorageMap tracks processed message IDs to ensure an instruction is never executed twice.
let message_id = blake2_256(&[
b"X3_CROSS_DOMAIN_TRANSFER_V1",
&source_domain.encode(),
&destination_domain.encode(),
&asset_id.encode(),
&sender.encode(),
&recipient.encode(),
&amount.to_be_bytes(),
&nonce.to_be_bytes(),
].concat());
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:300-315
Operational Controls and Security
The router includes surgical pause controls to manage risks without halting the entire chain. These are categorized by scope:
- Asset Pause: Rejects transfers for a specific
AssetId. - Route Pause: Rejects transfers between specific
DomainIdsfor an asset. - Global Pause: Last resort for security incidents.
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:231-240, MAINNET_LAUNCH_CHECKLIST.md:63-64
Route Limits
To mitigate potential exploit impacts during early launch phases, the router enforces daily and per-transaction limits on specific routes.
| Route | Max Transaction | Daily Limit |
|---|---|---|
| Internal (Native ↔ EVM ↔ SVM) | 1,000,000 X3 | Unlimited |
| Ethereum USDC ↔ X3 | 10,000 USDC | 100,000 USDC |
| Solana SPL ↔ X3 | 10,000 USDC-eq | 100,000 |
Sources: crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:255-265
Cross-VM Settlement Sequence
The following sequence diagram represents a typical atomic transfer initiated from the EVM domain targeting an SVM recipient.
This sequence ensures that tokens are only credited to the destination VM if they have been successfully debited from the source and the total supply remains constant.
Sources: MAINNET_LAUNCH_CHECKLIST.md:57-60, crates/x3-relayer/TOKEN_SYSTEM_IMPLEMENTATION_ROADMAP.md:200-210
Conclusion
The Cross-VM Router is the critical infrastructure that enables X3 Chain's multi-VM capabilities while maintaining strict economic security. By enforcing the King Invariant and providing a standardized routing matrix, it allows for high-throughput, atomic interactions between Native, EVM, and SVM environments, laying the foundation for a unified decentralized finance ecosystem.