Labels / Complexity: area:contracts, documentation, feature · Medium — 5
Context
Both contracts implement administrative pause controls (pause, unpause, is_paused in onchain/contracts/stellar_hunts/src/lib.rs and onchain/contracts/stellar_hunts_nft/src/lib.rs), and the game contract consults the flag in submit_answer and claim_level_completion_nft. The backend has a complementary maintenance-mode module. Nothing documents when to use which control, in what order, or how to recover state afterward.
Several of the relevant behaviours are currently broken or unclear - the game contract's pause path references an undefined error variant, and the two contracts have independent pause flags - so an operator responding to an incident has neither correct tooling nor a procedure.
Goal
Document a single, reviewable incident-response procedure for halting and resuming gameplay and minting, including the preconditions and the verification steps, and identify the state that must be checked before resuming.
Scope
1. Decision guide
State which control halts what: the game contract's pause (answer submission and badge claiming), the NFT contract's pause (minting), and the backend maintenance mode (API-wide). Include the combinations and why one is insufficient.
2. Procedure
Provide the exact steps (contract invocations and API calls), the expected observable result of each, and how to confirm the halt took effect before investigating.
3. Recovery
Define the checks to perform before unpausing, including in-flight claims and the reconciliation path for a player whose submission was interrupted by a pause.
Acceptance criteria
Out of scope
Implementing new pause controls.
Getting started
- In scope: a new document under
onchain/docs/ or docs/.
- Verify: follow the steps against a locally deployed pair of contracts.
- Good first files to read:
pause/unpause/is_paused in both contracts, backend/src/maintenance-mode/maintenance-mode.service.ts.
Labels / Complexity: area:contracts, documentation, feature · Medium — 5
Context
Both contracts implement administrative pause controls (
pause,unpause,is_pausedinonchain/contracts/stellar_hunts/src/lib.rsandonchain/contracts/stellar_hunts_nft/src/lib.rs), and the game contract consults the flag insubmit_answerandclaim_level_completion_nft. The backend has a complementarymaintenance-modemodule. Nothing documents when to use which control, in what order, or how to recover state afterward.Several of the relevant behaviours are currently broken or unclear - the game contract's pause path references an undefined error variant, and the two contracts have independent pause flags - so an operator responding to an incident has neither correct tooling nor a procedure.
Goal
Document a single, reviewable incident-response procedure for halting and resuming gameplay and minting, including the preconditions and the verification steps, and identify the state that must be checked before resuming.
Scope
1. Decision guide
State which control halts what: the game contract's pause (answer submission and badge claiming), the NFT contract's pause (minting), and the backend maintenance mode (API-wide). Include the combinations and why one is insufficient.
2. Procedure
Provide the exact steps (contract invocations and API calls), the expected observable result of each, and how to confirm the halt took effect before investigating.
3. Recovery
Define the checks to perform before unpausing, including in-flight claims and the reconciliation path for a player whose submission was interrupted by a pause.
Acceptance criteria
Out of scope
Implementing new pause controls.
Getting started
onchain/docs/ordocs/.pause/unpause/is_pausedin both contracts,backend/src/maintenance-mode/maintenance-mode.service.ts.