docs: add consolidated trust-model page (admin authority, key custody) - #751
Conversation
Closes drydocs#726 Admin-authority and immutability facts were scattered across docs/contracts.md, the drydocs#557 bug thread, and SECURITY.md (a vulnerability-disclosure policy, not a trust/permissions explainer). Nothing stated in one place what the ADMIN key can and cannot do, or what happens if it's lost or compromised. Adds apps/docs/overview/trust-model.md, covering exactly the four things the issue asked for: what ADMIN can do (set_paused, set_adapter, begin_migration/migrate_adapter, transfer_admin/accept_admin), what it structurally cannot do (no upgrade path exists at all, cross-referenced from docs/contracts.md rather than duplicated), key-loss/compromise consequences, and a pointer to the incident-response runbook tracked as drydocs#721 (confirmed not yet written -- referenced as forthcoming, not linked as if it exists). States plainly, since it's true and directly relevant to the page's own purpose: Meridian is already live on mainnet with real depositor funds, and per mainnet-deployment.md's own go-live checklist, neither the security audit nor ADMIN key custody finalization is done yet. This page describes what the contract enforces regardless of who holds ADMIN; it does not claim either open item is resolved. Grounded directly in packages/contracts/vault/src/lib.rs, not just existing docs: read every admin-gated function's real implementation and doc comments (which already name drydocs#557's threat model explicitly) to confirm claims like 'set_paused never blocks withdraw' and 'transfer_admin requires the current admin's signature' against actual require_auth() calls and storage keys, not assumptions. Verified: vitepress build (apps/docs) failed on first attempt with 11 dead-link errors from linking directly to files outside apps/docs's source root (docs/contracts.md, SECURITY.md, two .rs source files); fixed by matching the existing convention in this docs site (plain backtick-code references for out-of-tree files, e.g. in architecture/vault-contract.md), not by disabling the check. Clean build after the fix, confirmed the new page's real content renders in the built HTML output (not just that the build succeeded), and added the page to .vitepress/config.ts's sidebar nav.
|
@Iker2522 is attempting to deploy a commit to the Collins' projects Team on Vercel. A member of the Team first needs to authorize it. |
collinsezedike
left a comment
collinsezedike
left a comment
There was a problem hiding this comment.
@Iker2522 apps/docs/overview/trust-model.md fails pnpm format:check: it uses single-asterisk italics (*word*) throughout, and Prettier normalizes markdown italics to underscores (_word_). Run pnpm prettier --write apps/docs/overview/trust-model.md and push the result; that's the only thing blocking CI.
Content itself checked out well against packages/contracts/vault/src/lib.rs and storage.rs (the pause/withdraw independence, the two-step admin handoff, the migration timelock and slippage bound, and the absence of any upgrade entry point all match the actual code and existing tests), and the cross-referenced anchors in mainnet-deployment.md all resolve correctly.
|
@Iker2522 The quoted sentence "the ~1-day timelock ... is the only thing standing between a leaked key and the vault's entire position moving to an address the attacker controls" is cited to |
collinsezedike caught two things: 1. pnpm format:check failed: the page used single-asterisk markdown italics (*word*) throughout; Prettier normalizes these to underscores (_word_). Fixed with prettier --write. 2. The quoted sentence 'the ~1-day timelock ... is the only thing standing between a leaked key and the vault's entire position moving to an address the attacker controls' was attributed to migrate_adapter's doc comment, but it's actually verbatim from begin_migration's doc comment (lib.rs lines 781-783). migrate_adapter's own doc comment makes a related but differently-worded point (citing the same MIN_LEDGER_GAP mechanism, and additionally naming the two concrete reaction options: transfer_admin/accept_admin rotation, or pausing deposits). Fixed by citing each doc comment separately and accurately, rather than merging them under one attribution. Verified: prettier --check passes, vitepress build succeeds, and confirmed the corrected content (not a stray encoding artifact from my own edit, which I introduced and caught before pushing) renders correctly in the built HTML output.
bf14572 to
08eb641
Compare
|
@Iker2522 thank you for the contribution! If you have a moment, a star on the repo goes a long way. |
2 participants
Summary
Admin-authority and immutability facts were scattered across docs/contracts.md, the #557 bug thread, and SECURITY.md (a vulnerability-disclosure policy, not a trust/permissions explainer). Nothing stated in one place what the ADMIN key can and cannot do, or what happens if it's lost or compromised.
Adds apps/docs/overview/trust-model.md, covering exactly what the issue asked for: what ADMIN can do (set_paused, set_adapter, begin_migration/migrate_adapter, transfer_admin/accept_admin), what it structurally cannot do (no upgrade path exists at all, cross-referenced from docs/contracts.md rather than duplicated), key-loss/compromise consequences, and a pointer to the incident-response runbook tracked as #721 (confirmed not yet written — referenced as forthcoming, not linked as if it exists).
States plainly, since it's true and directly relevant to the page's own purpose: Meridian is already live on mainnet with real depositor funds, and per mainnet-deployment.md's own go-live checklist, neither the security audit nor ADMIN key custody finalization is done yet. This page describes what the contract enforces regardless of who holds ADMIN; it does not claim either open item is resolved.
What changed
New apps/docs/overview/trust-model.md, grounded directly in packages/contracts/vault/src/lib.rs — read every admin-gated function's real implementation and doc comments (which already name #557's threat model explicitly) to confirm claims like "set_paused never blocks withdraw" and "transfer_admin requires the current admin's signature" against actual require_auth() calls, not assumptions.
Added the page to .vitepress/config.ts's sidebar nav.
Test plan
vitepress build (apps/docs) — failed on first attempt with 11 dead-link errors from linking directly to files outside apps/docs's source root (docs/contracts.md, SECURITY.md, two .rs files); fixed by matching the existing convention in this docs site (plain backtick-code references for out-of-tree files), not by disabling the check
Clean build after the fix; confirmed the new page's real content renders in the built HTML output, not just that the build succeeded
No contract or test changes — docs only
Closes #726