Invariant Subsystem — Technical Summary

Overview

The invariant subsystem provides a runtime correctness-checking framework for stellar-core. It defines a registry of invariant checks that are executed at key lifecycle events (operation apply, ledger commit, bucket apply, assume-state, and periodic background snapshots). When an invariant is violated, it either throws InvariantDoesNotHold (for strict invariants) or logs an error (for non-strict ones). Invariants are registered at application startup and enabled via configuration patterns (regex matching on invariant names).

Key Files

• Invariant.h — Abstract base class Invariant with virtual checkOn* hooks.
• InvariantManager.h — Abstract interface for the invariant registry and dispatch system.
• InvariantManagerImpl.h / .cpp — Concrete implementation of InvariantManager; owns invariant registration, enablement, dispatch loops, failure handling, and background snapshot scheduling.
• InvariantDoesNotHold.h — Exception type thrown when a strict invariant fails.
• ConservationOfLumens.h / .cpp — Validates total lumen supply is conserved across operations and via full BucketList snapshot scans.
• AccountSubEntriesCountIsValid.h / .cpp — Validates numSubEntries on accounts matches actual sub-entry counts.
• BucketListIsConsistentWithDatabase.h / .cpp — Cross-checks BucketList entries against SQL database (offers) during catchup.
• LedgerEntryIsValid.h / .cpp — Validates structural correctness and field bounds of all LedgerEntry types.
• LiabilitiesMatchOffers.h / .cpp — Ensures buying/selling liabilities on accounts/trustlines match aggregated offer liabilities.
• SponsorshipCountIsValid.h / .cpp — Validates numSponsoring/numSponsored counters on accounts match sponsorship extensions.
• ConstantProductInvariant.h / .cpp — Ensures the constant-product AMM invariant (reserveA * reserveB) never decreases.