Skip to content

docs: clarify decommission and missed-deposit behavior in NatSpec#152

Open
Tranquil-Flow wants to merge 1 commit into
devfrom
docs/decommission-behavior
Open

docs: clarify decommission and missed-deposit behavior in NatSpec#152
Tranquil-Flow wants to merge 1 commit into
devfrom
docs/decommission-behavior

Conversation

@Tranquil-Flow
Copy link
Copy Markdown

Summary

Closes #96

Adds comprehensive NatSpec documentation to clarify the existing decommission and missed-deposit behavior. As discussed in #96, the current behavior is correct for v1 — this PR documents it so the contract's rules are unambiguous to developers, auditors, and frontend integrators.

What's documented

ISavingCircles.sol:

  • CircleState enum: detailed description of each state (NotStarted, Active, DepositInProgress, DepositComplete, Expired, Decommissioned, MissedDeposit) and when transitions occur
  • CircleDecommissioned event: clarifies it fires after all recoverable funds have been returned
  • CircleTimedOut error: explains the exact condition (round window elapsed + incomplete deposits)
  • deposit(), depositFor(): documents partial deposit support, CircleTimedOut revert conditions, and that decommission must be called first to recover from missed-deposit state
  • withdraw(), withdrawFor(): documents the 5 conditions for withdrawal eligibility, payout amount formula, auto-deactivation on last claim
  • decommission(): full flow documentation including preconditions, refund mechanics, storage deletion, and post-decommission state

SavingCircles.sol:

  • decommission(): inline documentation of the decommissionable conditions and refund flow
  • isWithdrawable(): documents O(N) iteration and return semantics
  • _isDecommissionable(): documents the time + state conditions and fund recovery purpose

No behavioral changes. Documentation only.

Test plan

  • forge test passes (140 tests)
  • No code changes — NatSpec only

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.

Clarify decommission + missed deposit behavior (is it ideal?)

1 participant