feat(settlement): add checkpoint entrypoint for bounded storage growth

contracts/helpers/src/snapshot_diff.rs

@@ -35,17 +35,14 @@ impl<K, V> Change<K, V> {
 ///
 /// # Ordering Guarantees
 /// The resulting change list is guaranteed to be sorted in a stable, deterministic order based
-/// on the `Ord` implementation of the key. This ensures consistent diff reports regardless of 
+/// on the `Ord` implementation of the key. This ensures consistent diff reports regardless of
 /// the input ordering of elements.
 ///
 /// # Efficiency
 /// The snapshots are loaded into `BTreeMap` structures in $O(N \log N + M \log M)$ time,
 /// and then compared in a single linear $O(N + M)$ pass. The final list of changes is
 /// sorted in $O(C \log C)$ where $C$ is the number of changes.
-pub fn diff_snapshots<K, V>(
-    before: &[(K, V)],
-    after: &[(K, V)],
-) -> Vec<Change<K, V>>
+pub fn diff_snapshots<K, V>(before: &[(K, V)], after: &[(K, V)]) -> Vec<Change<K, V>>
 where
     K: Ord + Clone,
     V: PartialEq + Clone,
@@ -117,9 +114,9 @@ where
 #[cfg(test)]
 mod tests {
     use super::*;
-    use alloc::vec;
     use alloc::string::String;
     use alloc::string::ToString;
+    use alloc::vec;
 
     #[test]
     fn test_identical_snapshots() {

contracts/revenue_pool/src/events.rs

@@ -245,6 +245,9 @@ mod tests {
     #[test]
     fn test_event_admin_broadcast_bytes() {
         let env = Env::default();
-        assert_eq!(event_admin_broadcast(&env), Symbol::new(&env, "admin_broadcast"));
+        assert_eq!(
+            event_admin_broadcast(&env),
+            Symbol::new(&env, "admin_broadcast")
+        );
     }
 }

contracts/revenue_pool/src/lib.rs

@@ -1,7 +1,8 @@
 #![no_std]
 
 use soroban_sdk::{
-    contract, contracterror, contractimpl, contracttype, token, Address, BytesN, Env, Map, String, Symbol, Vec,
+    contract, contracterror, contractimpl, contracttype, token, Address, BytesN, Env, Map, String,
+    Symbol, Vec,
 };
 
 /// Revenue settlement contract: receives USDC from vault deducts and distributes to developers.
@@ -85,7 +86,6 @@ pub struct StorageEntryTtl {
     pub bump_amount: u32,
 }
 
-
 /// TTL bump constants for instance storage archival risk mitigation.
 /// Soroban archives ledger entries after ~7 days (631 ledgers) of inactivity.
 /// Bumping TTL ensures state remains accessible for critical operations.
@@ -152,6 +152,15 @@ impl RevenuePool {
             .expect("revenue pool not initialized")
     }
 
+    /// Return the contract semver string.
+    ///
+    /// Read-only view returning the Cargo package version embedded at
+    /// compile time, enabling off-chain tooling to detect capability
+    /// deltas after upgrades.
+    pub fn version(_env: Env) -> soroban_sdk::String {
+        soroban_sdk::String::from_str(&_env, env!("CARGO_PKG_VERSION"))
+    }
+
     /// Initiate replacement of the current admin. Only the existing admin may call this.
     /// The new admin must call `claim_admin` to complete the transfer.
     ///
@@ -898,6 +907,7 @@ impl RevenuePool {
         let instance_ttl = {
             #[cfg(any(test, feature = "testutils"))]
             {
+                use soroban_sdk::testutils::storage::Instance;
                 env.storage().instance().get_ttl()
             }
             #[cfg(not(any(test, feature = "testutils")))]
@@ -918,7 +928,6 @@ impl RevenuePool {
     }
 }
 
-
 mod events;
 /// Split `payments` into consecutive chunks of at most `chunk_size` legs each,
 /// preserving order.

contracts/revenue_pool/src/test_error_codes.rs

@@ -31,6 +31,9 @@ fn error_code_docs_list_every_revenue_pool_code() {
     ];
 
     for line in expected_lines {
-        assert!(docs.contains(line), "missing revenue-pool docs line: {line}");
+        assert!(
+            docs.contains(line),
+            "missing revenue-pool docs line: {line}"
+        );
     }
 }

contracts/revenue_pool/src/test_proptest.rs

@@ -1,13 +1,12 @@
-
 extern crate std;
 
 use crate::{RevenuePool, RevenuePoolClient, Severity};
 use proptest::prelude::*;
 use proptest::strategy::ValueTree;
 use soroban_sdk::testutils::Address as _;
 use soroban_sdk::token::{self, StellarAssetClient};
-use soroban_sdk::{Address, Env};
 use soroban_sdk::Vec as SorobanVec;
+use soroban_sdk::{Address, Env};
 use std::panic::{catch_unwind, AssertUnwindSafe};
 
 fn create_usdc<'a>(

contracts/settlement/src/admin.rs

@@ -2,9 +2,8 @@
 
 use soroban_sdk::{Address, Env, Vec};
 
-use crate::{
-    events, timelock, AdminMigrationEvent, CalloraSettlement, SettlementError, StorageKey,
-};
+use crate::types::AdminMigrationEvent;
+use crate::{events, timelock, CalloraSettlement, SettlementError, StorageKey};
 
 fn require_admin(env: &Env, caller: &Address) {
     caller.require_auth();
@@ -38,7 +37,10 @@ pub(crate) fn propose_balance_migration(env: &Env, caller: &Address, from: &Addr
     let amount: i128 = env
         .storage()
         .persistent()
-        .get(&StorageKey::DeveloperBalance(from.clone(), usdc_token.clone()))
+        .get(&StorageKey::DeveloperBalance(
+            from.clone(),
+            usdc_token.clone(),
+        ))
         .unwrap_or(0);
     if amount <= 0 {
         env.panic_with_error(SettlementError::NoDeveloperBalance);
@@ -76,11 +78,7 @@ pub(crate) fn execute_balance_migration(env: &Env, caller: &Address, from: &Addr
     let source_key = StorageKey::DeveloperBalance(from.clone(), usdc_token.clone());
     let destination_key = StorageKey::DeveloperBalance(migration.to.clone(), usdc_token.clone());
 
-    let source_balance: i128 = env
-        .storage()
-        .persistent()
-        .get(&source_key)
-        .unwrap_or(0);
+    let source_balance: i128 = env.storage().persistent().get(&source_key).unwrap_or(0);
     let new_source_balance = source_balance
         .checked_sub(migration.amount)
         .filter(|b| *b >= 0)

contracts/settlement/src/errors.rs

@@ -57,5 +57,7 @@ pub enum SettlementError {
     MigrationNotFound = 20,
     TimelockNotExpired = 21,
     MigrationBalanceChanged = 22,
-    MinimumBalanceRequired = 23,
+    OverDraft = 23,
+    InvalidClaimWindow = 24,
+    ClaimWindowClosed = 25,
 }

contracts/settlement/src/events.rs

@@ -100,6 +100,11 @@ pub fn event_admin_migration(env: &Env) -> Symbol {
     Symbol::new(env, "admin_migration")
 }
 
+/// Returns the Symbol for a checkpoint snapshot.
+pub fn event_checkpoint_created(env: &Env) -> Symbol {
+    Symbol::new(env, "checkpoint_created")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -209,7 +214,10 @@ mod tests {
     #[test]
     fn test_event_admin_broadcast_bytes() {
         let env = Env::default();
-        assert_eq!(event_admin_broadcast(&env), Symbol::new(&env, "admin_broadcast"));
+        assert_eq!(
+            event_admin_broadcast(&env),
+            Symbol::new(&env, "admin_broadcast")
+        );
     }
 
     #[test]