Skip to content

docs: add multisig authority rotation guide for Stellar - #137

Merged
truthixify merged 1 commit into
wraith-protocol:developfrom
Mathew2k-hash:feat/stellar-multisig-authority-rotation
Aug 26, 2026
Merged

docs: add multisig authority rotation guide for Stellar#137
truthixify merged 1 commit into
wraith-protocol:developfrom
Mathew2k-hash:feat/stellar-multisig-authority-rotation

Conversation

@Mathew2k-hash

Copy link
Copy Markdown
Contributor

Multisig authority rotation guide for Stellar

Adds an operational runbook for custodians rotating signer keys on Stellar multisig accounts —
picking up where the existing Recovery Scenarios section in stellar-multisig-withdrawal.mdx
leaves off.

What's new

  • Zero-downtime staged rotation — add the replacement signer before removing the retiring one,
    keeping the account continuously authorized. Includes addSigner, verifySignerWeight, and
    removeSigner helpers with the overlap-window tradeoffs explained.
  • Emergency rotation — two paths: fast single-tx revocation when remaining good signers cover
    the high threshold, and an atomic break-glass add+remove for when they don't. Includes a
    follow-up note on moving funds after any compromise.
  • Auditor trail — block-by-block table showing what a rotation looks like in the ledger and
    Wraith announcement stream, a getSignerSetAtLedger Horizon query pattern, and
    getAnnouncementsAroundRotation for correlating withdrawals to a signer epoch.
  • End-to-end futurenet script — full 2-of-3 → fresh 2-of-3 rotation: account setup, three
    staged add/verify/remove cycles, final signer-set assertion, and annotated expected output.
  • Operational checklist — pre-rotation steps (HSM storage, anti-clipboard-hijack review,
    testnet dry-run, monitoring setup).

Changes

┌──────┬────────┐
│ File │ Change │
├────────────────────────────────────────────────┼───────────────────────┤
│ guides/stellar/multisig-authority-rot │ New guide (709 lines) │
│ ation.mdx │ │
├───────────────────────────────────────┼──────────────────────────────────────────────────┤
│ guides/stellar-multisig-withdrawal.md │ cross-link added at top of Recovery │
│ .mdx │ Scenarios section │
├────────────────────────────────────┼─────────────────────────────────────────────────────┤
│ docs.json │ Nav entry added to Operations group after │
│ │ stellar-multisig-withdrawal │
└────────────────────────────────────┴─────────────────────────────────────────────────────┘

Tested

pnpm run check:snippets — 586 snippets checked, 0 failures.
closes #129

- New guides/stellar/multisig-authority-rotation.mdx covering:
  - Zero-downtime staged add-then-remove rotation
  - Emergency rotation on suspected key compromise (fast-revoke and break-glass paths)
  - Auditor trail: block-by-block annotation of rotation in announcement stream
  - End-to-end scripted 2-of-3 to fresh 2-of-3 rotation on futurenet
- Cross-link added to Recovery Scenarios section in stellar-multisig-withdrawal.mdx
- Nav entry added to docs.json Operations group
@drips-wave

drips-wave Bot commented Aug 25, 2026

Copy link
Copy Markdown

@Mathew2k-hash Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@truthixify
truthixify merged commit a82723e into wraith-protocol:develop Aug 26, 2026
2 checks passed
@truthixify

Copy link
Copy Markdown
Contributor

Merged. The staged add-then-remove rotation is exactly the gap the existing recovery scenarios left open. Nice work @Mathew2k-hash.

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.

Multi-sig authority rotation tutorial

2 participants