Core X3 Pallets
Relevant source files
The following files were used as context for generating this wiki page:
Core X3 Pallets constitute the foundational runtime logic of the X3 Chain, responsible for maintaining system invariants, managing cross-VM state transitions, and ensuring supply consistency. These modules are integrated directly into the Substrate-based runtime to provide high-risk capabilities such as atomic kernel execution and universal asset registration.
The pallet architecture is designed to handle "Flash Finality" and parallel execution while enforcing strict safety invariants. Key responsibilities include the management of the supply ledger, the coordination of cross-VM routing (EVM, SVM, and Native), and the execution of atomic bundles.
Sources: reports/prompt-runs/latest-full.md, X3_END_TO_END_GAPS_MASTER_PLAN.md:20-35
Pallet Matrix and Functional Scope
The X3 ecosystem relies on a specific set of pallets to achieve full-stack functionality. Each pallet manages a distinct domain of the blockchain state.
| Pallet Name | Core Responsibility | Key Invariants |
|---|---|---|
pallet-x3-cross-vm-router | Dispatches packets between VM domains (EVM, SVM, Native). | Replay protection, domain separation. |
pallet-x3-supply-ledger | Tracks and preserves canonical supply across all domains. | represented_total <= canonical_supply. |
pallet-x3-atomic-kernel | Orchestrates multi-step atomic settlement and finality. | Atomic commit/rollback integrity. |
pallet-x3-asset-registry | Manages cross-domain asset IDs and registration gating. | Unique asset mapping, registration authority. |
pallet-x3-account-registry | Enforces account type validation and spoofing guards. | Account type integrity. |
Sources: MAINNET_LAUNCH_CHECKLIST.md:120-135, reports/prompt-runs/latest-full.md:70-85
X3 Cross-VM Router
The Cross-VM Router is the primary gateway for interoperability within the X3 runtime. it facilitates the transfer of data and value between Native, EVM, and SVM environments through a standardized packet format.
Call Flow and Routing
The router handles internal atomic routes and external gateway connections. Before any transfer is finalized, the pallet verifies that the route is not closed and the asset is not paused.
The diagram above illustrates the validation sequence required for a cross-VM transfer.
Sources: MAINNET_LAUNCH_CHECKLIST.md:52-65, reports/prompt-runs/latest-full.md:70-75
X3 Supply Ledger and Invariants
The pallet-x3-supply-ledger is critical for ensuring that assets are not inadvertently minted or burned during cross-chain or cross-VM operations.
Canonical Supply Formula
The pallet enforces a strict invariant where the total represented supply must match the native and locked external balances:
canonical_supply == native + evm + svm + external_locked + pending
Safety Requirements
- Checked Arithmetic: All operations must use
checked_addorchecked_subto prevent overflows. - Invariant Validation: The
check_invariant()function is called in every supply-changing operation. - Refund Logic: Failed destination credits must return the
pending_supplyto zero and refund the source.
Sources: MAINNET_LAUNCH_CHECKLIST.md:70-85, reports/prompt-runs/latest-full.md:80-85
Atomic Kernel Execution
The pallet-x3-atomic-kernel manages complex settlements. It utilizes a finalize_atomic_bundle function which is protected by an authority model to prevent griefing and spam.
Authority and Economics
Submitting atomic bundles requires:
- Authorized Submitter Set: Only permitted actors can trigger bundle finalization.
- Economic Bonds: Submitters must provide deposits per bundle to discourage spam.
- Slashing Rules: Invalid proofs or malicious behavior results in bond slashing.
This sequence shows the interaction between submitters and the kernel, emphasizing the economic safety checks.
Sources: X3_END_TO_END_GAPS_MASTER_PLAN.md:105-115, MAINNET_LAUNCH_CHECKLIST.md:125-130
Integration and Wiring Audit
Every major pallet is wired into the runtime through construct_runtime!. The wiring audit ensures that entry points, storage, and events are properly exposed via RPC and Extrinsics.
Wiring Verification Checklist
- Entrypoints: Every extrinsic must be reachable and have a defined call signature.
- Storage: Read/Write access to storage items (e.g.,
ExternalBridgesEnabled) must be gated by origin. - Events: Events like
BridgeRootRegisteredmust only emit under valid conditions. - Feature Flags: Critical components (e.g.,
external-gateway) may be behind compile-time guards to prevent premature activation on mainnet.
Sources: launch-gates/prompts/01-wiring-audit.md:15-35, MAINNET_LAUNCH_CHECKLIST.md:95-105
Enforcement and Audit Controls
To prevent "agent-cheat" or unauthorized modification of consensus logic, X3 uses an enforcement script (x3_enforce.py) that monitors changes to sensitive paths.
Consensus Path Protection
Changes to pallets/consensus code require:
- Invariant Registry Update: Impacted safety and liveness invariants must be documented.
- Fuzzing/Property Plan: Proof of property preservation through tests.
- Audit Mode Pass: Manual reasoning pass under
codex --profile x3-audit.
Sources: scripts_infrastructure/install_x3_enforcement.sh:35-70, scripts_infrastructure/install_x3_enforcement.sh:160-185
Summary
Core X3 Pallets provide the essential state transition logic for the X3 Chain. By separating concerns into specialized modules for supply, routing, and atomic execution, the system maintains a high bar for security and determinism. These pallets are governed by strict invariants and automated enforcement scripts to ensure mainnet readiness and prevent consensus-critical regressions.