Skip to content

feat(escrow): guard release/refund paths with a circuit breaker - #28

Merged
Meshmulla merged 1 commit into
stellar-kracken:mainfrom
Favouromale:feature/6-escrow-circuit-breaker
Aug 19, 2026
Merged

feat(escrow): guard release/refund paths with a circuit breaker#28
Meshmulla merged 1 commit into
stellar-kracken:mainfrom
Favouromale:feature/6-escrow-circuit-breaker

Conversation

@Favouromale

Copy link
Copy Markdown
Contributor

Summary

Adds a circuit breaker to the escrow contract's highest-value flows so an authorized guardian can halt fund movement instantly if an anomaly or exploit is detected, without blocking read-only queries.

closes #6

  • TimeLockedEscrowContract::release_escrow, batch_release, and refund_escrow now check the breaker first and revert with the new EscrowError::CircuitBreakerTripped when tripped.
  • trip_circuit_breaker(caller, reason) / reset_circuit_breaker(caller) are gated to the contract admin or an optional dedicated breaker guardian address (set via the new admin-only set_breaker_guardian), mirroring the trip/reset access-control pattern used by the existing circuit_breaker.rs / submission_pause.rs modules elsewhere in this repo.
  • Read-only queries (get_escrow, get_challenge, get_dispute, get_accrued_fees, plus the new is_circuit_breaker_tripped / get_circuit_breaker_state) remain available regardless of breaker state.
  • New CircuitBreakerTripped / CircuitBreakerReset events for auditability, and a CircuitBreakerState record (reason, actor, timestamp) exposed via get_circuit_breaker_state.
  • No changes to unrelated existing behavior (e.g. set_emergency_pause / emergency_recover are untouched).

Testing / validation performed

All run locally against the workspace at HEAD of this branch:

  • cargo fmt --all -- --check — clean
  • cargo clippy --all-targets --all-features -- -D warnings — clean (whole workspace)
  • cargo build --release --target wasm32-unknown-unknown — succeeds
  • cargo test — all 18 test binaries pass (including the 3 new circuit-breaker tests), 0 failures
  • cargo test --test escrow_contract_fuzz -p escrow-contract (FUZZ_ITERATIONS=200, as CI runs it) — passes

New tests added in escrow_contract/tests/escrow_contract.test.rs:

  • circuit_breaker_blocks_release_and_refund_when_tripped — tripped breaker rejects release_escrow/refund_escrow with CircuitBreakerTripped, while get_escrow/get_circuit_breaker_state keep working.
  • circuit_breaker_reset_restores_release_and_refund — reset clears the trip and release proceeds normally.
  • circuit_breaker_only_authorized_role_can_trip_or_reset — an unauthorized caller is rejected; a delegated guardian (set via set_breaker_guardian) can trip/reset, a stranger cannot.

Issue

#6

What changed:
- Added a circuit breaker to TimeLockedEscrowContract (escrow_contract/src/lib.rs),
  mirroring the pause/breaker style already used elsewhere in this repo
  (soroban's circuit_breaker.rs / submission_pause.rs).
- release_escrow, batch_release, and refund_escrow now revert with the new
  EscrowError::CircuitBreakerTripped when the breaker is tripped, while
  read-only queries (get_escrow, get_challenge, get_dispute,
  get_accrued_fees, is_circuit_breaker_tripped, get_circuit_breaker_state)
  keep working.
- trip_circuit_breaker/reset_circuit_breaker are restricted to the admin or
  an optional dedicated breaker guardian address, set via the new
  set_breaker_guardian admin-only entrypoint.
- Added CircuitBreakerTripped/CircuitBreakerReset events and a
  CircuitBreakerState query type for auditability.
- Added tests covering: release/refund blocked while tripped with read
  paths unaffected, reset restoring normal operation, and unauthorized
  callers being rejected for both trip and reset.
@Meshmulla
Meshmulla merged commit e95d7bd into stellar-kracken:main Aug 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a circuit-breaker guard to the escrow contract's release paths

2 participants