Supply Ledger & Invariants
Relevant source files
The following files were used as context for generating this wiki page:
The Supply Ledger & Invariants system is a critical security and accounting framework within the X3 Atomic Star project. Its primary purpose is to ensure the integrity of the token supply across multiple execution environments (Native, EVM, and SVM) by enforcing mathematical rules that must remain true at all times. By maintaining a canonical ledger of total supply and validating it against the sum of all balances, the system prevents unauthorized minting, double-spending, and state inconsistencies during cross-VM operations.
This system acts as a "hard gate" for mainnet readiness, requiring 100% verification of supply conservation before the network can be considered production-ready. It integrates closely with the Asset Kernel and Cross-VM Router to monitor state transitions and trigger emergency halts if an invariant is violated.
Sources: MAINNET_LAUNCH_CHECKLIST.md:59-64, plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:31-36
Canonical Supply Invariants
The core of the system is the Canonical Supply Formula, which defines the relationship between different balance buckets across the network. The system ensures that the represented total supply is always less than or equal to the canonical supply.
The Invariant Formula
The total supply is calculated as the sum of assets across all supported virtual machines and transitional states:
canonical_supply == native + evm + svm + external_locked + pending
Note: Some planning documents suggest the inclusion of x3vm as a separate bucket, though it is omitted in current core definitions.
Sources: knowledge-audit-report.md:209-216, launch-gates/prompts/04-invariant-hunter.md:15-20
Invariant Categories
The project classifies invariants into four distinct levels of enforcement:
| Category | Description | Requirement |
|---|---|---|
| Safety | Prevents invalid states or unauthorized assets. | Nothing invalid is accepted; no unintended mint/burn. |
| Liveness | Ensures valid transactions are eventually processed. | Valid transactions are eventually included in blocks. |
| Determinism | Guarantees identical inputs result in identical states. | Identical input → identical state root. |
| Economic | Protects fee accounting and slashing integrity. | Gas metering and fee distribution remain correct. |
Sources: scripts_infrastructure/install_x3_enforcement.sh:84-98, X3_END_TO_END_GAPS_MASTER_PLAN.md:144-149
Supply Ledger Architecture
The Supply Ledger is implemented as a Substrate pallet (pallet-x3-supply-ledger) that maintains the authoritative record of the token supply. It interfaces with the pallet-x3-invariants to perform checks during every supply-changing operation.
The diagram shows the relationship between cross-VM routing, the supply ledger storage, and the invariant validation gate.
Sources: MAINNET_LAUNCH_CHECKLIST.md:59-64, plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:73-82
Invariant Enforcement & Verification
Enforcement is mandatory and occurs at multiple levels of the stack. A "failure to verify" an invariant is treated as a P0 blocker for any release.
Runtime Enforcement
- Checked Arithmetic: Every operation involving supply values MUST use
checked_add,checked_sub, orsaturating_*variants. Bare arithmetic operators (+,-) are strictly prohibited in production paths to prevent overflow/underflow vulnerabilities. - Operation Hooks: The
check_invariant()function is called in every operation that alters the supply, such as minting, burning, or cross-VM bridging. - Terminal States: For atomic transactions, the system ensures that the state either moves to a fully executed terminal state or a fully rolled-back state, preserving the supply balance in either case.
Sources: MAINNET_LAUNCH_CHECKLIST.md:65-68, plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:61-66
Verification Procedures
To maintain the "Invariant Hunter" status, the following testing matrix is employed:
The verification flow requires moving from simple unit tests to complex property-based and fuzz testing before a feature can be considered verified.
Sources: launch-gates/prompts/04-invariant-hunter.md:22-38, reports/prompt-runs/latest-full.md:142-152
Mainnet Readiness Checklist: Phase 5
The following items must be verified specifically for the Supply Ledger and Invariants before Mainnet launch:
| Item | Status Requirement | Verification Source |
|---|---|---|
pallet-x3-supply-ledger | ALL PASS | cargo test -p pallet-x3-supply-ledger |
check_invariant() | Mandatory Call | Grep confirmation in all supply-changing ops |
| Negative Test Path | PASS | Verify represented_total > canonical_supply fails |
| Roundtrip Stress | PASS | 10-round stress test across all 6 internal routes |
| Zero-Amount Rejection | PASS | Ensure zero-value transfers are rejected |
Sources: MAINNET_LAUNCH_CHECKLIST.md:46-68, reports/prompt-runs/latest-full.md:120-130
Emergency Response
If an invariant is violated in a live environment, the system is designed to "fail-closed." This involves:
- Immediate Revert: Transactional state changes are rolled back.
- Circuit Breaking: If the
canonical_supplyis exceeded, the affected bridge or VM route is automatically paused. - Audit Trail: The system generates an evidence bundle including the conflicting block, proof of violation, and current state root for forensic analysis.
Sources: X3_END_TO_END_GAPS_MASTER_PLAN.md:151-158, scripts_infrastructure/install_x3_enforcement.sh:40-55
Conclusion
The Supply Ledger & Invariants system provides the mathematical foundation of trust for the X3 Atomic Star. By strictly enforcing supply conservation across Native, EVM, and SVM environments through checked arithmetic and mandatory runtime hooks, the project ensures that its cross-VM capabilities do not compromise the fundamental integrity of the token economy. Completion of the verification matrix for this system is the primary prerequisite for mainnet transition.