Added documention for core invariants and fixed example config #5046

anupsdf · 2025-12-04T00:52:04Z

what

Added documention for core invariants and fixed example config

why

Improve documentation

Copilot

Pull request overview

This PR adds comprehensive documentation for core invariants in stellar-core and updates the example configuration file to reflect currently available invariants.

Adds a new docs/invariants.md file documenting all invariant types, their purposes, implementation details, and configuration options
Updates docs/stellar-core_example.cfg to remove outdated CacheIsConsistentWithDatabase invariant and reorder existing invariants with improved descriptions
Documents three invariants with updated descriptions: ConservationOfLumens, ConstantProductInvariant, and adds new SponsorshipCountIsValid

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/stellar-core_example.cfg	Removes obsolete `CacheIsConsistentWithDatabase` entry, reorders invariants alphabetically, and adds documentation for `ConstantProductInvariant` and `SponsorshipCountIsValid` with improved descriptions
docs/invariants.md	Adds comprehensive documentation covering all 10 invariants with architectural overview, check methods, configuration instructions, and best practices for adding new invariants

SirTyson

Overall LGTM. I would add a big warning at the top of this though that invariants are very expensive, may reduce performance, and will crash your node if a fault is detected. Basically just a section to dissuade tier 1 from actually turning these on for production validators.

SirTyson · 2025-12-08T21:23:24Z

docs/invariants.md

+|--------|-------------|
+| `checkOnOperationApply` | After each operation is applied |
+| `checkOnBucketApply` | After bucket apply during catchup |
+| `checkAfterAssumeState` | After assuming state from history |


assume state runs on every restarts, not just when catching up from history

SirTyson · 2025-12-08T21:28:48Z

docs/invariants.md

+- Only applies to Soroban entry types (CONTRACT_CODE, CONTRACT_DATA) 
+- Verifies that no entry exists in both the live state and the archived (Hot Archive) state simultaneously
+- Checks eviction invariants: entries evicted from live state should not already exist in the hot archive
+- Checks restoration invariants: entries restored from hot archive should match expected states


Nit: restoration invariant checks that restored entries were not already in live state.

SirTyson · 2025-12-08T21:29:33Z

docs/invariants.md

+
+**File:** `BucketListIsConsistentWithDatabase.cpp`
+
+**Purpose:** Validates that the BucketList and Database are in a consistent state after bucket operations.


We should add a note that this only applies to OFFER types, as all non-offer LIVEENTRY are not reflected in the database.

SirTyson · 2025-12-08T21:31:34Z

docs/invariants.md

+**Details:**
+- Iterates over bucket entries and compares them to the database
+- Fails if:
+  - A LIVEENTRY in the bucket doesn't match the database (not present or different)


I would remove the references to LIVEENTRY and DEADENTRY. It doesn't make sense to talk about individual Bucket types here, since an entry can be shadowed, so the existence or nonexistence of a LIVEENTRY/DEADENTRY isn't particularly relevant. I would just say "check that there is a one-to-one mapping of OFFER entry types between SQL DB and BucketList state".

SirTyson · 2025-12-08T21:32:57Z

docs/invariants.md

+- For AMM (Automated Market Maker) pools using constant product formula
+- Validates: `currentReserveA * currentReserveB >= previousReserveA * previousReserveB`
+- Excludes `LIQUIDITY_POOL_WITHDRAW`, `SET_TRUST_LINE_FLAGS`, and `ALLOW_TRUST` operations (which intentionally may decrease the product)
+- Prevents manipulation that would drain liquidity unfairly


Instead of "prevent" I would say "detects"

SirTyson · 2025-12-08T21:35:31Z

docs/invariants.md

+
+## Configuration
+
+Invariants can be enabled through stellar-core configuration. The `InvariantManager` supports:


This section talks about what the interface of the InvariantManager class does and doesn't really have anything to do with configuration. I would just remove it and have the section below become "configuration"

SirTyson · 2025-12-08T21:36:32Z

docs/invariants.md

+
+### State Snapshot Invariants
+
+Some expensive invariants (like `ArchivedStateConsistency.checkSnapshot`) run periodically on a background thread against ledger state snapshots, as they require scanning the entire BucketList and can't run in a blocking fashion during normal operation.


We should note that enabling snapshot invariants is very expensive and requires lot's of memory. For this reason, it is not allowed on validator nodes.

Added a note.

SirTyson · 2025-12-08T21:38:14Z

docs/invariants.md

+
+## Best Practices for Adding New Invariants
+
+1. **Choose the right check method**: Select based on when the validation should occur


Item 1 and 3 aren't particularly helpful and are to niche.

Cleaned up.

Copilot AI review requested due to automatic review settings December 4, 2025 00:52

Copilot started reviewing on behalf of anupsdf December 4, 2025 00:52 View session

Copilot finished reviewing on behalf of anupsdf December 4, 2025 00:54

Copilot AI reviewed Dec 4, 2025

View reviewed changes

SirTyson requested changes Dec 8, 2025

View reviewed changes

Added document for core invariants and fixed example config

1fa10b0

anupsdf force-pushed the invariant-doc branch from 046ecfb to 1fa10b0 Compare December 16, 2025 07:58


		File: `BucketListIsConsistentWithDatabase.cpp`

		Purpose: Validates that the BucketList and Database are in a consistent state after bucket operations.


		## Configuration

		Invariants can be enabled through stellar-core configuration. The `InvariantManager` supports:


		### State Snapshot Invariants

		Some expensive invariants (like `ArchivedStateConsistency.checkSnapshot`) run periodically on a background thread against ledger state snapshots, as they require scanning the entire BucketList and can't run in a blocking fashion during normal operation.


		## Best Practices for Adding New Invariants

		1. Choose the right check method: Select based on when the validation should occur

Added documention for core invariants and fixed example config #5046

Are you sure you want to change the base?

Added documention for core invariants and fixed example config #5046

Conversation

anupsdf commented Dec 4, 2025

what

why

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

SirTyson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants