Emergency Circuit Breaker with Scoped Function Guards & Time-Bound Auto-Expiry #42

Activity

1. meshackyaro

   added

   enhancementNew feature or requestNew feature or request

   help wantedExtra attention is neededExtra attention is needed

   contractsSmart contract (Soroban) workSmart contract (Soroban) work

   priority: high🔴 High priority — core / blocking🔴 High priority — core / blocking

   Maybe RewardedIssue may be eligible for a GrantFox rewardIssue may be eligible for a GrantFox reward

   GrantFox OSSIssue tracked in GrantFox OSSIssue tracked in GrantFox OSS

   Official Campaign | FWC26Campaign: Official Campaign | FWC26Campaign: Official Campaign | FWC26

   difficulty: hard🔴 Hard🔴 Hard

   on Aug 19, 2026
2. grantfox-oss

   added

   Third CampaignCampaign: Third CampaignCampaign: Third Campaign

   on Aug 19, 2026
3. bbjiggy commented on Aug 19, 2026

   

   bbjiggy

   on Aug 19, 2026 – with GrantFox OSS

   Contributor

   More actions

   Hi, I would like to take up this issue. Below is the proposed design, architectural plan, and testing strategy for implementing the Emergency Circuit Breaker with Scoped Function Guards & Time-Bound Auto-Expiry across the Soroban workspace.

   ---

   Architectural Design

   1. Shared Circuit Breaker Primitive

   To ensure uniform logic across escrow, reputation, and loyalty, I will introduce a shared pausable module inside the workspace's shared utilities/crates.

   Storage Data Structure:

   #[contracttype]
   pub enum PauseScope {
       CreateAppointment = 1 << 0,
       MintReputation    = 1 << 1,
       MintLoyalty       = 1 << 2,
       AllInbound        = 0xFFFFFFFF,
   }
   
   #[contracttype]
   pub struct PauseState {
       pub flags: u32,         // Bitmask for active pause scopes
       pub expires_at: u64,    // Ledger timestamp (env.ledger().timestamp())
   }
   
   #[contracttype]
   pub enum DataKey {
       PauseState,
       // ... existing keys
   }

   2. Time-Bound Auto-Expiry Logic

   Instead of relying solely on an administrative transaction to clear a pause state, every guard check evaluates the current ledger time:

   pub fn require_not_paused(env: &Env, scope: PauseScope) -> Result<(), ContractError> {
       if let Some(state) = env.storage().instance().get::<_, PauseState>(&DataKey::PauseState) {
           let current_time = env.ledger().timestamp();
           
           // Auto-expiry check: pause self-clears once deadline passes
           if current_time < state.expires_at && (state.flags & (scope as u32)) != 0 {
               return Err(ContractError::OperationPaused);
           }
       }
       Ok(())
   }

   3. Scoped Guards & Fund-Recovery Immunity

   • Halted Operations: create_appointment, mint_reputation, and new reward minting paths will invoke require_not_paused(env, Scope).
   • Fund-Recovery Exemption: Critical exit routes—such as cancel_appointment, dispute resolution distributions, and emergency token withdrawals—will explicitly omit the pause guard. This guarantees funds are never trapped, even during an active pause.
   • Max Pause Duration Cap: Admin execution of pause() will enforce a strict MAX_PAUSE_DURATION constant (e.g., 7 days) to prevent setting indefinite freeze states.

   4. Authorization & Event Integration

   • Governance Alignment: pause and unpause methods will require admin.require_auth(), remaining compatible with the signer rotation and guard patterns established in #16 and #27.
   • Structured Events:
   • PauseEvent { scopes: u32, expires_at: u64, caller: Address }
   • UnpauseEvent { scopes: u32, caller: Address }

   ---

   Work Plan & Tasks

   • Core Module: Implement Pausable state management and scope bitmask logic in the common smart contract crate.
   • Contract Integration: Integrate scoped guards into escrow, reputation, and loyalty entrypoints.
   • Error Handling: Declare ContractError::OperationPaused across contracts to distinguish pause halts from InvalidStatus.
   • CI Optimizations: Update GitHub Actions workflows to include actions/cache or Swatinem/rust-cache for Cargo target directories and dependencies.
   • Documentation: Document storage layouts, scope mappings, and auto-expiry logic in inline docs and repository architecture notes.

   ---

   Testing Strategy

   1. Scope Isolation Tests: Verify that halting CreateAppointment blocks new deposits while cancel_appointment executes without failure.
   2. Auto-Expiry Boundary Tests: Advance env.ledger().set_timestamp() past expires_at to confirm operations resume automatically without an unpause transaction.
   3. Adversarial / Auth Tests: Confirm non-admin calls to pause/unpause fail with authorization errors.
   4. CI Verification: Run local validations for cargo fmt --check, cargo clippy -- -D warnings, cargo test, and soroban contract build.
4. Sparexonzy95 commented on Aug 19, 2026

   

   Sparexonzy95

   on Aug 19, 2026 – with GrantFox OSS

   More actions

   I’m interested in taking this issue. I have experience working with Stellar/Soroban smart contracts and understand the security requirements around scoped pause guards, admin authorization, fund-recovery paths, and ledger-based auto-expiry. I’m confident I can implement this safely across the existing contracts, cover the critical success, failure, and adversarial cases with tests, and submit a solid PR within 2-3 days.
5. grantfox-oss

   assigned

   bbjiggy

   on Aug 19, 2026
6. grantfox-oss commented on Aug 19, 2026

   

   grantfox-ossBot

   on Aug 19, 2026 – with GrantFox OSS

   More actions

   🦊 GrantFox — @bbjiggy has been assigned to this issue as part of the Third Campaign campaign!

   Next steps:

   1. Open a Pull Request referencing this issue (e.g., Closes #42)
   2. Your PR will be reviewed by the workman-labs maintainers

   Good luck! Track your progress on GrantFox.
7. bbjiggy

   added a commit that references this issue on Aug 20, 2026

   docs(contracts): cross-link the changelog entry to issue workman-labs#42

   ...

   caa1145
8. meshackyaro

   added a commit that references this issue on Aug 20, 2026

   feat(contracts): emergency circuit breaker with scoped function guard…

   ...

   28a20c1
9. meshackyaro

   closed this as completedin #46on Aug 20, 2026
10. grantfox-oss commented on Aug 20, 2026

    

    grantfox-ossBot

    on Aug 20, 2026 – with GrantFox OSS

    More actions

    🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

    @bbjiggy's PR #46 was approved and merged by @meshackyaro.

    🏆 @bbjiggy: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (780 total points). Track your full progress on GrantFox.

    👏 Great work, @bbjiggy! Keep contributing to workman-labs.