Skip to content

docs: document two-step governance admin rotation flow and timelock#510

Merged
Chucks1093 merged 1 commit into
accesslayerorg:devfrom
iwayemi5:dev
Jun 28, 2026
Merged

docs: document two-step governance admin rotation flow and timelock#510
Chucks1093 merged 1 commit into
accesslayerorg:devfrom
iwayemi5:dev

Conversation

@iwayemi5

Copy link
Copy Markdown
Contributor

Summary

This PR adds a comprehensive runbook documenting the governance admin rotation process for the escrow contract. It explains the complete two-step flow, authorization requirements, timelock behavior, pending state inspection, emitted events, and includes a CLI-style walkthrough to help contributors and operators safely perform admin rotations.

Closes #361

Changes

  • Added "docs/escrow/admin-rotation.md" documenting the end-to-end governance admin rotation process.
  • Documented the complete rotation lifecycle:
    • Current governance admin calls "propose_governance_admin".
    • Proposal enters a pending state.
    • Wait for "ADMIN_ROTATION_MIN_DELAY_LEDGERS" (approximately two days).
    • Proposed governance admin completes the rotation via "accept_governance_admin".
  • Documented authorization requirements for both operations:
    • "propose_governance_admin" requires current governance admin authorization.
    • "accept_governance_admin" requires proposed governance admin authorization.
  • Explained the "TimelockNotElapsed" error, including when it is returned and how to resolve it.
  • Documented how to inspect pending proposals with "get_pending_governance_admin", including interpretation of the anchor ledger and remaining timelock.
  • Included documentation for the emitted:
    • "admin/proposed"
    • "admin/accepted"
      event payloads.
  • Added a CLI-style example demonstrating the complete proposal → wait → acceptance workflow.
  • Added NatSpec-style ("///") documentation comments in "contracts/escrow/src/governance.rs" linking to the runbook.
  • Cross-referenced the timelock tests in "contracts/escrow/src/test/admin_auth_helper.rs".

Security Considerations

  • Documents the two-step transfer model to prevent accidental or unauthorized governance changes.
  • Clarifies that governance ownership is not transferred immediately after proposal.
  • Emphasizes that each stage requires authorization from a different actor.
  • Explains the mandatory timelock before ownership can be accepted.

Validation

Verified that the documentation reflects the implementation in "contracts/escrow/src/governance.rs".

Executed:

  • ✅ "cargo fmt --all -- --check"
  • ✅ "cargo build"
  • ✅ "cargo test"

@Chucks1093 Chucks1093 merged commit 00f9656 into accesslayerorg:dev Jun 28, 2026
1 check 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 loading state for wallet balance after network switch

2 participants