Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/pages/multisig-for-protocols/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ title: "Multisig For Protocols"
## Pages

- [Multisig Security Framework](/multisig-for-protocols/overview)
- [Multisig Key Takeaways](/multisig-for-protocols/key-takeaways)
- [Multisig Planning & Classification](/multisig-for-protocols/planning-and-classification)
- [Multisig Setup & Configuration](/multisig-for-protocols/setup-and-configuration)
- [Multisig Registration & Documentation](/multisig-for-protocols/registration-and-documentation)
Expand Down
13 changes: 12 additions & 1 deletion docs/pages/multisig-for-protocols/joining-a-multisig.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,18 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
<TagList tags={frontmatter.tags} />
<AttributionList contributors={frontmatter.contributors} />

It is recommended to always create a fresh address on a hardware wallet for each new multisig.
## Use a Dedicated Key for Each Multisig

Always create a fresh address on a hardware wallet for each new multisig you join. Use a different address index on
your hardware wallet (same derivation path, just switch between addresses) and label each clearly.

This matters for two reasons:

- **Signing clarity**: With a dedicated key, your wallet interface only shows transactions from one multisig. This
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.

## Verifying address ownership

Expand Down
115 changes: 115 additions & 0 deletions docs/pages/multisig-for-protocols/key-takeaways.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
title: "Multisig Key Takeaways | SEAL"
description: "The most important multisig security principles on one page. Timelocks, multisig separation, address discipline, monitoring, and calldata verification."
tags:
- Engineer/Developer
- Security Specialist
- Operations & Strategy
- Multisig Security
contributors:
- role: wrote
users: [isaac]
- role: reviewed
users: []
---

import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'

<TagProvider>
<TagFilter />

# Key Takeaways

<TagList tags={frontmatter.tags} />
<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.

## 1. Use Timelocks on All Admin Changes

Any multisig controlling protocol parameters or upgrades should route through a
[timelock contract](/multisig-for-protocols/use-case-specific-requirements#timelock-configuration). Without a timelock,
once threshold signatures are collected, changes take effect immediately with no chance to detect or stop a malicious
proposal. Use
[tiered durations](/multisig-for-protocols/use-case-specific-requirements#tiered-timelock-durations): longer delays for
major changes (upgrades, token changes), shorter delays for routine parameter tuning.

## 2. Separate Multisigs by Function

Do not put all admin privileges in one multisig. If that single multisig is compromised, everything is lost. Use
[separate multisigs](/multisig-for-protocols/use-case-specific-requirements#separating-multisigs-by-function) for
different functional areas (protocol upgrades, operational parameters, emergency pause, treasury) with tailored
thresholds and signer sets for each.

## 3. Use Dedicated Keys Per Multisig

Each signer should use a
[different address](/wallet-security/secure-multisig-best-practices#dedicated-keys-per-multisig) for each multisig.
This makes it easy to distinguish which multisig a transaction belongs to in your wallet, and prevents a compromised key
from being usable across multiple multisigs. Same derivation path on your hardware wallet, just different address
indexes.

## 4. Maintain an Access Control Inventory

Keep a living document of every privileged role in your protocol: what it can do, which multisig holds it, what
constraints exist, and what the blast radius is if compromised. You cannot design proper multisig separation or classify
risk without this foundation. See
[Access Control Inventory](/multisig-for-protocols/planning-and-classification#maintain-an-access-control-inventory).

## 5. Constrain Emergency Powers

If emergency bypass mechanisms exist (e.g., bypassing a timelock), they should be limited to the minimum necessary
action like pausing. An emergency path should never be able to upgrade contracts or move funds. This way, even
maliciously obtained emergency signatures cause minimal damage. See
[Design Principles](/wallet-security/secure-multisig-best-practices#constrain-emergency-powers).

## 6. Monitor Timelock Queues Actively

A timelock without monitoring provides no protection. Implement
[automated alerting](/multisig-for-protocols/use-case-specific-requirements#timelock-monitoring) that watches for queued
transactions and immediately notifies the team with decoded transaction details. At least one monitoring channel should
be operated by an external party so internal compromise cannot suppress alerts.

## 7. Never Copy Addresses from Explorer History

Always use a verified
[address book](/wallet-security/secure-multisig-best-practices#address-book-discipline). Never copy addresses from block
explorer transaction history, Etherscan, or chat messages. For first-time recipients, perform a bidirectional test
transaction. For high-value transfers, verify addresses character-by-character on a video call.

## 8. Watch for Permissionless Safe Additions

Anyone can create a Safe and add you as an owner without your consent, making it appear in your Safe app. Attackers
create Safes with addresses matching the first 4 and last 4 characters of your real Safes. Always verify the full
address and navigate from bookmarks, not the dashboard. See
[Address Poisoning](/wallet-security/secure-multisig-best-practices#address-poisoning-and-permissionless-safe-additions).

## 9. Verify Calldata, Not Just Hashes

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.

## 10. Use Delegated Proposers and Non-Signer Execution

Set up a [delegated proposer](/multisig-for-protocols/setup-and-configuration#delegated-proposer) for Safe multisigs.
Hash verification tools rely on the Safe API, which only has data after a transaction is proposed. Without a delegated
proposer, the first signer faces additional challenges to verify what they are signing. For a related reason, avoid "sign and execute" for the final signature, as verification tools do not provide the

Check failure on line 98 in docs/pages/multisig-for-protocols/key-takeaways.mdx

View workflow job for this annotation

GitHub Actions / lint

Line length

docs/pages/multisig-for-protocols/key-takeaways.mdx:98:121 MD013/line-length Line length [Expected: 120; Actual: 200] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md
expected hashes for this combined action. Instead, have all signers sign only, then have a non-signer execute the
fully-signed transaction.

## 11. Hardware Wallets, Backup Infrastructure, and Drills

All signers must use hardware wallets. Maintain
[backup signing infrastructure](/multisig-for-protocols/backup-signing-and-infrastructure) (Eternal Safe, Squads Public
Client) in case primary UIs go down. Run regular emergency drills to verify that signers can respond under pressure and
that communication channels work. See the
[Implementation Checklist](/multisig-for-protocols/implementation-checklist).

---

For the full framework, see the [Multisig Security Framework Overview](/multisig-for-protocols/overview).

</TagProvider>
<ContributeFooter />
5 changes: 5 additions & 0 deletions docs/pages/multisig-for-protocols/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr

## How to use this guide

**Short on time?** Start with [Key Takeaways](/multisig-for-protocols/key-takeaways) for the most important points
on one page.

**Quick start**: New to multisigs? Start with the Foundation for the essentials, then jump to your role:

- Setting up a new multisig? → Multisig Administration: [Setup &
Expand All @@ -39,6 +42,8 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
## Core principles

- **Security first**: Every multisig must meet [minimum security standards](/wallet-security/secure-multisig-best-practices)
- **Built-in slowness**: Timelocks and review windows are intentional security mechanisms, not obstacles to work around
- **Constrained emergency powers**: Emergency bypass mechanisms should do the minimum necessary and nothing more
- **Operational readiness**: Procedures that work under pressure
- **Clear accountability**: Everyone knows their role and responsibilities
- **Emergency preparedness**: Plans for when things go wrong
Expand Down
21 changes: 21 additions & 0 deletions docs/pages/multisig-for-protocols/planning-and-classification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,27 @@ Document the multisig's intended use:
- **Decision timeline** - How quickly must it respond?
- **Integration points** - What systems will it interact with?

### Maintain an Access Control Inventory

Before classifying multisigs, protocols should first build a comprehensive inventory of all privileged roles in their
system. You cannot classify risk or design multisig separation if you do not know what powers exist and where they live.

For each privileged role, document:

- **Role name**: The on-chain role or permission (e.g., `UPGRADER_ROLE`, `owner`, `pauser`, `fee-setter`)
- **Held by**: Which address or multisig currently holds this role
- **Contract**: Which contract(s) this role controls
- **Capabilities**: What this role can do (specific functions and their effects)
- **Constraints**: What limits exist on this role (timelocks, parameter bounds, governance controls)
- **Blast radius**: The maximum potential impact if this role is compromised

This inventory is the foundation for all multisig planning — it directly informs how many multisigs you need, how to
separate responsibilities, and what threshold and timelock configurations to use. Maintain it as a living document,
updated whenever new contracts are deployed or roles change.

See the [Registration Template](/multisig-for-protocols/registration-and-documentation#registration-template) for how
to document this per multisig.

### Assess Constraints and Recovery

Consider limiting factors that affect risk:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,17 @@ Signers:
Controlled contracts: [List contract addresses and purposes]
On-chain roles: [Describe roles like ownable, Access Control roles (PAUSER_ROLE)]

Access Control Inventory:
- Role: [Role name, e.g., UPGRADER_ROLE]
Held by: [This multisig address]
Contract: [Contract address and name]
Capabilities: [What this role can do]
Constraints: [Timelock duration, parameter bounds, etc.]
Blast radius: [Maximum potential impact if compromised]

Timelock configuration: [Timelock contract address, delay duration, who can cancel]
Related multisigs: [Other multisigs that interact with the same contracts or share signers]

Impact assessment:
- Financial exposure: $[amount] ([reasoning])
- Protocol impact: [description]
Expand Down
27 changes: 21 additions & 6 deletions docs/pages/multisig-for-protocols/setup-and-configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,17 @@ For emergency situations when the primary UI is unavailable, see

## Delegated Proposer

It is recommended, but not required to authorize a separate transaction proposer for a Safe. This address can prepare
transactions for signers to sign but is not an authorized signer on the Safe. Therefore **there is no risk of malicious
signatures which can affect the Safe assets**. This wallet can hold no funds and simply act as a proposer. The primary
reason to have a delegated proposer is that the hash verification utilities depend on the Safe API (unless details are
entered manually). Until a transaction is **proposed** it does not show up in the API so the hash verification tools
cannot detect it.
It is recommended to authorize a separate transaction proposer for a Safe. This address can prepare transactions for
signers to sign but is not an authorized signer on the Safe. This wallet can hold no funds and simply acts as a
proposer.

Hash verification tools rely on the Safe API, which only has transaction data after the transaction is proposed.
Without a delegated proposer, the first signer faces additional challenges to verify what they are signing. A
delegated proposer submits the transaction to the API before any signer approves, so every signer can verify.

For a related reason, the final signer should avoid "sign and execute." Verification tools do not provide the expected
hashes for this combined action. Instead, have all signers sign only, then have a non-signer execute the fully-signed
transaction.

![Delegated proposer configuration interface](https://frameworks-static.s3.us-east-2.amazonaws.com/images/multisig-for-protocols/delegated-proposer-configuration-interface.png)

Expand Down Expand Up @@ -160,6 +165,16 @@ Implement monitoring and alerting systems to be immediately notified of any on-c
including proposed transactions, new signatures, and owner changes (e.g., using tools like [Safe
Watcher](https://github.com/Gearbox-protocol/safe-watcher)).

Monitoring should also cover activity on individual signer addresses to detect unauthorized use of signer keys outside
the multisig context.

### Timelock Transaction Monitoring

For any multisig that uses a timelock, configure automated monitoring for all timelock events (queue, execute, cancel).
Alerts should fire immediately when a new transaction is queued, providing decoded calldata and a countdown to the
execution window. See
[Timelock Monitoring](/multisig-for-protocols/use-case-specific-requirements#timelock-monitoring) for full requirements.

### Immutable Monitoring Channels

Monitoring channels (e.g. email, Slack or Telegram chats) must be immutable (or trigger alerts when their configuration
Expand Down
Loading
Loading