feat: Document the full escrow state machine (open → funded → settled/withdrawn) in docs/escrow-lifecycle.md#294
Open
Oluwatomilola wants to merge 2 commits into
Open
Conversation
…t#271 - Authoritative state-transition table in docs/escrow-lifecycle.md - Comprehensive rustdoc comments on all public entrypoints - 95%+ test coverage on state machine, auth, overflow, double-spend - Legal hold interaction validated across all risky operations - Security assumptions (auth, overflow, storage TTL) fully tested - Ready for review and mainline merge
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of fix:
Fixes: #271
Liquifact Escrow State Machine — Complete Implementation
Authoritative Documentation
✅ docs/escrow-lifecycle.md — Complete state-transition table with all entrypoints, allowed source states, target states, auth requirements, and legal-hold interaction
Status values documented: 0 (open), 1 (funded), 2 (settled), 3 (withdrawn), 4 (cancelled)
Valid transitions: init→0, fund 0→1, settle 1→2, withdraw 1→3, cancel_funding 0→4, refund 4→principal returned
Rustdoc/NatSpec Comments
✅ All public functions in include comprehensive doc comments with:
Purpose & behavior
Authorization requirements
Status guards & legal-hold checks
Typed error codes
Invariants & security properties
Security Validation Tests (95%+ coverage)
✅ Authorization boundaries — admin/SME/investor roles enforced
✅ Overflow prevention — funded_amount, contribution, claim-time all checked with checked_add/checked_mul
✅ Double-spend prevention — contribution zeroed before token transfer; second panics
✅ Legal hold interaction — blocks fund, settle, withdraw, claim, dust-sweep, cancel_funding
✅ Status transitions — forbidden regressions panic; mutual exclusivity (settle vs withdraw)
✅ Storage safety — immutable snapshots, TTL extension, no orphaned state
Build Artifacts
Branch Status