feat: add admin-controlled pause for assert, dispute, and resolve

Author: collinsezedike

CONTRACT.md

@@ -59,6 +59,7 @@ State of an assertion: `Pending`, `Disputed`, or `Resolved`.
 | `ChallengeWindowOpen` | Tried to finalize before the challenge window elapsed |
 | `NotAResolver` | Caller isn't in the current resolver committee |
 | `AlreadyVoted` | Resolver already voted on this assertion |
+| `Paused` | Called `assert_outcome`, `dispute`, or `resolve` while paused |
 
 ## Functions
 
@@ -76,17 +77,26 @@ odd-length requirement as `initialize`. Emits `ResolversUpdated`. Does not affec
 longer cast further votes; a resolver added mid-dispute can vote on assertions that
 were already disputed before they joined.
 
+### `set_paused(paused)`
+
+Pauses or unpauses `assert_outcome`, `dispute`, and `resolve`. Requires the stored
+admin's signature. `finalize` is deliberately exempt: assertions already `Pending`
+before a pause can still be finalized while paused, so an uncontested claim isn't
+stuck waiting on an unpause. `update_resolvers` is also exempt, so a compromised
+committee can be replaced without unpausing first. Emits `PauseUpdated`.
+
 ### `assert_outcome(asserter, outcome) -> u64`
 
 Posts a bonded claim. Transfers `bond_amount` from `asserter` to the contract.
-Requires `asserter`'s signature. Returns the new assertion id. Emits `Asserted`.
+Requires `asserter`'s signature. Fails with `Paused` if paused. Returns the new
+assertion id. Emits `Asserted`.
 
 ### `dispute(disputer, id)`
 
 Disputes a `Pending` assertion within the challenge window, matching its bond.
-Requires `disputer`'s signature. Fails with `NotPending` if the assertion isn't
-pending (including if it's already disputed), or `ChallengeWindowClosed` if the
-window has elapsed. Emits `Disputed`.
+Requires `disputer`'s signature. Fails with `Paused` if paused, `NotPending` if the
+assertion isn't pending (including if it's already disputed), or
+`ChallengeWindowClosed` if the window has elapsed. Emits `Disputed`.
 
 ### `finalize(id) -> bool`
 
@@ -97,8 +107,8 @@ dispute. Returns the asserter's bond and returns the asserted outcome. Fails wit
 ### `resolve(resolver, id, agrees_with_asserter) -> Option<bool>`
 
 Casts one resolver's vote on a `Disputed` assertion. Requires `resolver`'s signature
-and that they're in the current committee. Fails with `NotAResolver`,
-`NotDisputed`, or `AlreadyVoted` as appropriate.
+and that they're in the current committee. Fails with `Paused` if paused,
+`NotAResolver`, `NotDisputed`, or `AlreadyVoted` as appropriate.
 
 Returns `None` if no side has reached a strict majority yet. Once a majority agrees,
 the winning side (asserter if the majority agreed with them, disputer otherwise)
@@ -134,6 +144,7 @@ history without polling `get_assertion_state`:
 | `Finalized` | `finalize` | `id`, `outcome` |
 | `Resolved` | `resolve`, once a majority is reached | `id`, `outcome` |
 | `ResolversUpdated` | `update_resolvers` | `resolvers` (the new committee) |
+| `PauseUpdated` | `set_paused` | `paused` |
 
 ## Example: calling it with the Stellar CLI
 
@@ -164,7 +175,6 @@ resolve.
 - No fee/reward mechanism for uncontested finalizes: the original design called for
   a small reward funded by market fees, but no fee-generating market layer exists
   yet, so `finalize` just returns the bond as-is.
-- No pause or emergency-stop.
-- `update_resolvers` is a single-admin-key operation, which is a bigger centralization
+- `set_paused` and `update_resolvers` are both single-admin-key operations, which is a bigger centralization
   point than the resolver committee itself. A resolver self-rotation scheme (the
   committee votes to replace one of its own) was considered but not built for v1.

INTEGRATION.md

@@ -138,5 +138,9 @@ event carries, not `get_assertion_state(id).outcome`.
   mechanism, so integrators who want to incentivize keepers to call `finalize`
   promptly need to handle that themselves (e.g. your own contract pays a small
   bounty to whoever triggers your callback).
-- No pause: if something goes wrong, there's no way to freeze in-flight assertions
-  short of `update_resolvers` locking out the compromised committee.
+- The admin can pause `assert_outcome`, `dispute`, and `resolve` at any time via
+  `set_paused`. Your integration should treat a `Paused` error as a distinct,
+  expected failure mode (surface it to the user as "resolution temporarily
+  unavailable") rather than an unexpected error. `finalize` and
+  `update_resolvers` stay callable while paused, so assertions already `Pending`
+  before a pause can still resolve uncontested.

README.md

@@ -8,9 +8,10 @@ The assertion and dispute contract (`contracts/tholos`) is implemented, tested,
 
 - Core propose/dispute/resolve flow: done
 - Admin-controlled resolver committee updates: done
+- Pause / emergency-stop: done
+- Reentrancy hardening (state written before external token transfers): done
 - CI (fmt, clippy, tests, wasm build): done
 - Fee-funded reward for uncontested finalizes: not yet (no fee-generating market layer exists to fund it)
-- Pause / emergency-stop: not yet
 
 See [CONTRACT.md](CONTRACT.md) for the full interface and known gaps, or
 [INTEGRATION.md](INTEGRATION.md) if you're building a contract that wants to call

contracts/demo-consumer/test_snapshots/test/test_demo_consumer_can_assert_and_read_status_through_tholos.1.json

@@ -38,6 +38,11 @@ pub struct ResolversUpdated {
     pub resolvers: Vec<Address>,
 }
 
+#[contractevent]
+pub struct PauseUpdated {
+    pub paused: bool,
+}
+
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum Status {
@@ -69,6 +74,7 @@ pub enum DataKey {
     Resolvers,
     Assertion(u64),
     NextId,
+    Paused,
 }
 
 #[contracterror]
@@ -84,6 +90,7 @@ pub enum Error {
     ChallengeWindowOpen = 8,
     NotAResolver = 9,
     AlreadyVoted = 10,
+    Paused = 11,
 }
 
 const DAY_IN_LEDGERS: u32 = 17280;
@@ -126,6 +133,7 @@ impl Tholos {
             .instance()
             .set(&DataKey::Resolvers, &resolvers);
         env.storage().instance().set(&DataKey::NextId, &0u64);
+        env.storage().instance().set(&DataKey::Paused, &false);
         env.storage()
             .instance()
             .extend_ttl(INSTANCE_LIFETIME_THRESHOLD, INSTANCE_BUMP_AMOUNT);
@@ -135,7 +143,8 @@ impl Tholos {
 
     /// Replaces the resolver committee. Only callable by the admin set at
     /// initialization. `new_resolvers` must have an odd length so a simple
-    /// majority vote can never tie.
+    /// majority vote can never tie. Callable even while paused, so a
+    /// compromised committee can be replaced without waiting to unpause.
     pub fn update_resolvers(env: Env, new_resolvers: Vec<Address>) -> Result<(), Error> {
         let admin: Address = env
             .storage()
@@ -159,8 +168,39 @@ impl Tholos {
         Ok(())
     }
 
+    /// Pauses or unpauses new assertions, disputes, and resolver votes.
+    /// Assertions already `Pending` can still be `finalize`d while paused,
+    /// so existing uncontested claims aren't stuck waiting on an unpause.
+    /// Only callable by the admin set at initialization.
+    pub fn set_paused(env: Env, paused: bool) -> Result<(), Error> {
+        let admin: Address = env
+            .storage()
+            .instance()
+            .get(&DataKey::Admin)
+            .ok_or(Error::NotInitialized)?;
+        admin.require_auth();
+
+        env.storage().instance().set(&DataKey::Paused, &paused);
+        PauseUpdated { paused }.publish(&env);
+
+        Ok(())
+    }
+
+    fn require_not_paused(env: &Env) -> Result<(), Error> {
+        let paused: bool = env
+            .storage()
+            .instance()
+            .get(&DataKey::Paused)
+            .ok_or(Error::NotInitialized)?;
+        if paused {
+            return Err(Error::Paused);
+        }
+        Ok(())
+    }
+
     /// Posts a bonded claim about an outcome. Returns the new assertion id.
     pub fn assert_outcome(env: Env, asserter: Address, outcome: bool) -> Result<u64, Error> {
+        Self::require_not_paused(&env)?;
         asserter.require_auth();
 
         let bond_amount: i128 = Self::get(&env, &DataKey::BondAmount);
@@ -204,6 +244,7 @@ impl Tholos {
 
     /// Disputes a pending assertion within the challenge window by matching its bond.
     pub fn dispute(env: Env, disputer: Address, id: u64) -> Result<(), Error> {
+        Self::require_not_paused(&env)?;
         disputer.require_auth();
 
         let mut assertion = Self::get_assertion(&env, id)?;
@@ -284,6 +325,7 @@ impl Tholos {
         id: u64,
         agrees_with_asserter: bool,
     ) -> Result<Option<bool>, Error> {
+        Self::require_not_paused(&env)?;
         resolver.require_auth();
 
         let resolvers: Vec<Address> = Self::get(&env, &DataKey::Resolvers);

contracts/tholos/src/lib.rs

@@ -323,6 +323,62 @@ fn test_admin_can_update_resolvers() {
     assert_eq!(token.balance(&disputer), 1_100);
 }
 
+#[test]
+fn test_paused_blocks_assert_dispute_and_resolve_but_not_finalize() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let (_token_admin, token_id, token, resolvers) = setup(&env);
+    let token_asset_client = token::StellarAssetClient::new(&env, &token_id);
+    let contract_id = env.register(Tholos, ());
+    let client = TholosClient::new(&env, &contract_id);
+
+    let admin = Address::generate(&env);
+    let asserter = Address::generate(&env);
+    let disputer = Address::generate(&env);
+    token_asset_client.mint(&asserter, &1_000);
+    token_asset_client.mint(&disputer, &1_000);
+    client.initialize(&admin, &token_id, &100, &3600, &resolvers);
+
+    // An assertion posted before the pause can still finalize normally.
+    let pending_id = client.assert_outcome(&asserter, &true);
+
+    client.set_paused(&true);
+
+    assert_eq!(
+        client.try_assert_outcome(&asserter, &true),
+        Err(Ok(Error::Paused))
+    );
+    assert_eq!(
+        client.try_dispute(&disputer, &pending_id),
+        Err(Ok(Error::Paused))
+    );
+
+    env.ledger().with_mut(|l| l.timestamp += 3601);
+    let outcome = client.finalize(&pending_id);
+    assert!(outcome);
+    assert_eq!(token.balance(&asserter), 1_000);
+
+    client.set_paused(&false);
+    let id = client.assert_outcome(&asserter, &true);
+    client.dispute(&disputer, &id);
+    assert_eq!(
+        client.try_resolve(&resolvers.get(0).unwrap(), &id, &true),
+        Ok(Ok(None))
+    );
+}
+
+#[test]
+fn test_cannot_pause_before_initialization() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let contract_id = env.register(Tholos, ());
+    let client = TholosClient::new(&env, &contract_id);
+
+    assert_eq!(client.try_set_paused(&true), Err(Ok(Error::NotInitialized)));
+}
+
 #[test]
 fn test_cannot_update_resolvers_to_even_count() {
     let env = Env::default();

contracts/tholos/src/test.rs

@@ -544,6 +544,18 @@
                         "u64": "1"
                       }
                     },
+                    {
+                      "key": {
+                        "vec": [
+                          {
+                            "symbol": "Paused"
+                          }
+                        ]
+                      },
+                      "val": {
+                        "bool": false
+                      }
+                    },
                     {
                       "key": {
                         "vec": [

contracts/tholos/test_snapshots/test/test_admin_can_update_resolvers.1.json

@@ -412,6 +412,18 @@
                         "u64": "1"
                       }
                     },
+                    {
+                      "key": {
+                        "vec": [
+                          {
+                            "symbol": "Paused"
+                          }
+                        ]
+                      },
+                      "val": {
+                        "bool": false
+                      }
+                    },
                     {
                       "key": {
                         "vec": [

contracts/tholos/test_snapshots/test/test_cannot_dispute_after_window_closes.1.json

@@ -499,6 +499,18 @@
                         "u64": "1"
                       }
                     },
+                    {
+                      "key": {
+                        "vec": [
+                          {
+                            "symbol": "Paused"
+                          }
+                        ]
+                      },
+                      "val": {
+                        "bool": false
+                      }
+                    },
                     {
                       "key": {
                         "vec": [

contracts/tholos/test_snapshots/test/test_cannot_dispute_an_already_disputed_assertion.1.json

@@ -370,6 +370,18 @@
                         "u64": "1"
                       }
                     },
+                    {
+                      "key": {
+                        "vec": [
+                          {
+                            "symbol": "Paused"
+                          }
+                        ]
+                      },
+                      "val": {
+                        "bool": false
+                      }
+                    },
                     {
                       "key": {
                         "vec": [