Strengthen multisig guidance: timelocks, separation, address discipline, and key takeaways#448
Strengthen multisig guidance: timelocks, separation, address discipline, and key takeaways#448ipatka wants to merge 1 commit intosecurity-alliance:developfrom
Conversation
…page for quick reference and linking
Sidebar Configuration ReminderThis PR includes added, renamed, or removed documentation files:
Please ensure that:
See Contributing Guide – Sidebar & Navigation for more details. This is an automated reminder. If this PR doesn't need sidebar changes, you can ignore this message. |
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
DicksonWu654
left a comment
DicksonWu654
left a comment
There was a problem hiding this comment.
lgtm! I sent a few suggestions in DMs
| eliminates confusion about which multisig a signing request belongs to and reduces the risk of signing the wrong | ||
| transaction. | ||
| - **Key isolation**: If your key for one multisig is compromised, it cannot be used to attack any other multisig you | ||
| participate in. Each multisig has an independent security boundary. |
There was a problem hiding this comment.
if the addresses are from the same hd path on a hardware wallet, and the seed is compromised, you don't have true firewalling
| <AttributionList contributors={frontmatter.contributors} /> | ||
|
|
||
| If you read one page from the Multisig Security Framework, make it this one. These are the principles that matter most. | ||
|
|
There was a problem hiding this comment.
if this advice is ethereum/safe specific I would add something here to add guards and other safeguards to force changes through the timelock.
| Hash verification confirms you are signing the intended transaction, but it does not tell you what the transaction does. | ||
| Always [decode the calldata](/wallet-security/signing-and-verification/secure-multisig-safe-verification#5-calldata-review) | ||
| and verify the function, target, and parameters match what was described. Watch for red flags like unexpected | ||
| `DELEGATECALL`, `approve` calls, or hidden batch operations. |
There was a problem hiding this comment.
I would add: calculate hashes across multiple devices and OS to make sure computer isn't compromised, then make sure to verify the entire hash on the hardware wallet when signing
| ## Separating Multisigs by Function | ||
|
|
||
| Protocols should not consolidate all admin privileges into a single multisig. If one multisig controls everything | ||
| (treasury, protocol upgrades, operational parameters, emergency pause), then compromising that multisig means total | ||
| protocol compromise. |
There was a problem hiding this comment.
this is solid advice. if these are all behind timelocks, do they need to deploy 1 msig and 1 timelock for each role?
There was a problem hiding this comment.
yup would require multiple to be deployed
| [External Transaction Monitoring](#external-transaction-monitoring) for treasury-specific requirements. | ||
| - **Redundant channels**: Use multiple independent alert channels (e.g., email, Slack, Telegram) so that a single | ||
| channel failure does not cause a missed alert | ||
|
|
There was a problem hiding this comment.
recommend adding bullet point on integration testing. there should be extensive internal tooling that will catch mistakes like misconfigurations of a protocol via governance, even after the change is deployed onchain.
if a threat actor wanted to exploit a larger protocol, one vector would be supply chain attack that slips in malicious governance payload. the payload looks one way locally, once broadcast, it morphs into something else.
without extensive tests and harnesses to simulate that what you have in your local repo is actually what ended up on chain, you run the risk of a mismatch.
from experience, once stuff goes onchain, almost no one reviews, which is why automated testing with protocol invariants is extremely important.
| Consider making timelock queues publicly visible through a dashboard or notification feed. This allows the broader | ||
| community to observe pending changes, which adds an additional layer of scrutiny beyond the core team. |
There was a problem hiding this comment.
imo this transparency is non-negotiable. without it, it's hard for the community to understand the changes being made.
| - **`MultiSend` when a single action was expected**: Extra calls could be hidden in a batch. | ||
| - **Unfamiliar function selectors**: If you cannot identify the function being called, do not sign until you verify it. | ||
| - **Parameters that do not match the briefing**: Wrong recipient, wrong amount, wrong contract address. | ||
| - **Mismatched target contract**: The function call is going to a different contract than described. |
There was a problem hiding this comment.
- unverified smart contracts on etherscan being called
- calldata mismatch with simulation output. e.g. the selector is "transfer(address,uint256)" but no tokens are transferred. (this is similar to how bybit attack worked at the smart contract level. unverified smart contract on etherscan, and calldata that was decoded to "transfer")
frameworks-volunteer
left a comment
frameworks-volunteer
left a comment
There was a problem hiding this comment.
Model: z-ai/glm-5.1 Reasoning: high Provider: openrouter
Review: Strengthen multisig guidance
Security Review
No issues found. This is pure MDX documentation content with no code execution, no secrets, no injection vectors, and no dependency changes.
QA Review
- All internal links and anchor fragments resolve to existing headings (verified: dedicated-keys-per-multisig, address-book-discipline, address-poisoning-and-permissionless-safe-additions, constrain-emergency-powers, separating-multisigs-by-function, tiered-timelock-durations, timelock-configuration, timelock-monitoring, delegated-proposer, maintain-an-access-control-inventory, 5-calldata-review)
- Frontmatter on new key-takeaways.mdx matches existing conventions (title, description, tags, contributors, imports)
- Tags in fetched-tags.json match key-takeaways.mdx frontmatter exactly
- vocs.config.tsx sidebar entry added correctly
- CI passes: Build Preview, lint, sidebar-reminder all green
- No leftover debug content, TODOs, or placeholder text
- fetched-tags.json sectionMappings diff is alphabetical reorder only, no functional change
Minor Observation
The PR checklist marks "modify the general outline, update vocs.config.ts adding the dev: true parameter" as done, but the new Key Takeaways sidebar entry does not include dev: true. This appears intentional since the content is production-ready, not a WIP section. No action needed.
Verdict
Solid contribution. The new design principles (slowness by design, constrained emergency powers, separation), expanded timelock guidance with tiered durations, address discipline sections, and the key takeaways summary page are all well-written and internally consistent. Approving.
4 participants
Strengthen multisig guidance: timelocks, separation, address discipline, and key takeaways
Revises the multisig security framework based on lessons from real-world multisig operations and emerging risks. Adds a one-page key takeaways summary for quick reference.
Key changes
Files changed
docs/pages/multisig-for-protocols/key-takeaways.mdx(new)docs/pages/wallet-security/secure-multisig-best-practices.mdxdocs/pages/multisig-for-protocols/use-case-specific-requirements.mdxdocs/pages/multisig-for-protocols/setup-and-configuration.mdxdocs/pages/multisig-for-protocols/planning-and-classification.mdxdocs/pages/multisig-for-protocols/registration-and-documentation.mdxdocs/pages/wallet-security/signing-and-verification/secure-multisig-safe-verification.mdxdocs/pages/wallet-security/signing-and-verification/secure-multisig-squads-verification.mdxdocs/pages/multisig-for-protocols/joining-a-multisig.mdxdocs/pages/multisig-for-protocols/overview.mdxvocs.config.tsxDescribe your changes
If you are touching an existing piece of content, tag current contributors from the attribution list
If there is a steward for that framework, ask the steward to review it
If you're modifying the general outline, make sure to update it in the
vocs.config.tsadding thedev: trueparameterIf you need feedback for your content from the wider community, share the PR in our Discord
Review changes to ensure there are no typos; see instructions below.