Summary
Right now, "the contract holds exactly as much as it should" is something anyone has to trust rather than verify. Build a way to prove this on-chain, verifiably, without depending on the backend's own accounting.
Background
escrow's storage holds individual TradeState entries but has no aggregate accounting — nothing tracks "total currently locked" as a queryable, provable on-chain fact. A malicious or buggy off-chain component could show a user a "you're covered" message with no actual on-chain backing.
Scope
Contract
Add a running, on-chain-maintained total_locked accumulator, incremented on every lock() and decremented on every release()/refund() — updated atomically as part of each state transition
Add a public view function verify_reserve() -> bool comparing total_locked against the actual token contract balance held by this contract's address
Reason explicitly about edge cases: what if someone sends tokens directly to the contract address outside of lock()
Backend Integration
Surface verify_reserve()'s result on the public status page as an independently-checkable transparency signal
Tests
Lock several trades, confirm total_locked matches the sum
Release/refund some, confirm the accumulator decrements correctly
Confirm verify_reserve() correctly reflects true/false state in each scenario
Relevant Files
contracts/escrow/src/lib.rs
apps/api/src/routes/status.ts
Acceptance Criteria
total_locked accumulator correctly maintained atomically across every state-changing function
verify_reserve() implemented, tested, and exposed on the public status page
Written reasoning for the "extra tokens sent directly" edge case
Out of Scope
Historical/point-in-time proof-of-reserve — this issue only covers real-time, current-state verification
Note for Contributors
"Trust the backend's dashboard" and "verify it yourself against the chain" are very different promises. This issue is what turns the first into the second.
Summary
Right now, "the contract holds exactly as much as it should" is something anyone has to trust rather than verify. Build a way to prove this on-chain, verifiably, without depending on the backend's own accounting.
Background
escrow's storage holds individual TradeState entries but has no aggregate accounting — nothing tracks "total currently locked" as a queryable, provable on-chain fact. A malicious or buggy off-chain component could show a user a "you're covered" message with no actual on-chain backing.
Scope
Contract
Add a running, on-chain-maintained total_locked accumulator, incremented on every lock() and decremented on every release()/refund() — updated atomically as part of each state transition
Add a public view function verify_reserve() -> bool comparing total_locked against the actual token contract balance held by this contract's address
Reason explicitly about edge cases: what if someone sends tokens directly to the contract address outside of lock()
Backend Integration
Surface verify_reserve()'s result on the public status page as an independently-checkable transparency signal
Tests
Lock several trades, confirm total_locked matches the sum
Release/refund some, confirm the accumulator decrements correctly
Confirm verify_reserve() correctly reflects true/false state in each scenario
Relevant Files
contracts/escrow/src/lib.rs
apps/api/src/routes/status.ts
Acceptance Criteria
total_locked accumulator correctly maintained atomically across every state-changing function
verify_reserve() implemented, tested, and exposed on the public status page
Written reasoning for the "extra tokens sent directly" edge case
Out of Scope
Historical/point-in-time proof-of-reserve — this issue only covers real-time, current-state verification
Note for Contributors
"Trust the backend's dashboard" and "verify it yourself against the chain" are very different promises. This issue is what turns the first into the second.