Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
cb961c7
Add multisig operational runbooks and documentation guidance
DicksonWu654 Mar 9, 2026
a9d9acf
Apply Sara suggestion 2939860587
DicksonWu654 Mar 17, 2026
a23ae95
Apply Sara suggestion 2939862252
DicksonWu654 Mar 17, 2026
f7848a5
Apply Sara suggestion 2939862857
DicksonWu654 Mar 17, 2026
c9e84dc
Apply Sara suggestion 2939863443
DicksonWu654 Mar 17, 2026
2580f88
Apply Sara suggestion 2939864078
DicksonWu654 Mar 17, 2026
4ff71dd
Apply Sara suggestion 2939865123
DicksonWu654 Mar 17, 2026
7c4af56
Apply Sara suggestion 2939865976
DicksonWu654 Mar 17, 2026
bfd7830
Apply Sara suggestion 2939866383
DicksonWu654 Mar 17, 2026
21081f0
Apply Sara suggestion 2939866879
DicksonWu654 Mar 17, 2026
3318354
Apply Sara suggestion 2939867530
DicksonWu654 Mar 17, 2026
691e746
Apply Sara suggestion 2939868060
DicksonWu654 Mar 17, 2026
3f44ce0
Apply Sara suggestion 2939868577
DicksonWu654 Mar 17, 2026
3daf0a3
Apply Sara suggestion 2939869042
DicksonWu654 Mar 17, 2026
7d2e803
Apply Sara suggestion 2939869584
DicksonWu654 Mar 17, 2026
1232f89
Apply Sara suggestion 2939870091
DicksonWu654 Mar 17, 2026
5ae5012
Apply Sara suggestion 2939870587
DicksonWu654 Mar 17, 2026
817e263
Apply Sara suggestion 2939872250
DicksonWu654 Mar 17, 2026
4b916c5
Apply Sara suggestion 2939889864
DicksonWu654 Mar 17, 2026
b76e043
Apply Sara suggestion 2939890542
DicksonWu654 Mar 17, 2026
c8ca0eb
Apply Sara suggestion 2939891050
DicksonWu654 Mar 17, 2026
0722cbe
Apply Sara suggestion 2939892263
DicksonWu654 Mar 17, 2026
4e98c72
Apply Sara suggestion 2939893596
DicksonWu654 Mar 17, 2026
cddbe67
Apply Sara suggestion 2939896797
DicksonWu654 Mar 17, 2026
1447a81
Apply Sara suggestion 2939897584
DicksonWu654 Mar 17, 2026
7bf4fcc
Apply Sara suggestion 2939898225
DicksonWu654 Mar 17, 2026
e4543e1
Apply Sara suggestion 2939899242
DicksonWu654 Mar 17, 2026
ba13e02
Apply Sara suggestion 2939899923
DicksonWu654 Mar 17, 2026
b4582fc
Apply Sara suggestion 2939900381
DicksonWu654 Mar 17, 2026
6ea35fd
Apply Sara suggestion 2939900962
DicksonWu654 Mar 17, 2026
719c6cc
Apply Sara suggestion 2939901549
DicksonWu654 Mar 17, 2026
66272b2
Apply Sara suggestion 2939902429
DicksonWu654 Mar 17, 2026
8bdc5f1
Apply Sara suggestion 2939903042
DicksonWu654 Mar 17, 2026
8033473
Apply Sara suggestion 2939905276
DicksonWu654 Mar 17, 2026
1839ad3
Apply Sara suggestion 2939905940
DicksonWu654 Mar 17, 2026
ea5c1e6
Apply Sara suggestion 2939906462
DicksonWu654 Mar 17, 2026
078fc87
Apply Sara suggestion 2939907379
DicksonWu654 Mar 17, 2026
79d8a9a
Apply Sara suggestion 2939908300
DicksonWu654 Mar 17, 2026
a8b8996
Apply Sara suggestion 2939909096
DicksonWu654 Mar 17, 2026
f1f5de8
Apply Sara suggestion 2939909964
DicksonWu654 Mar 17, 2026
54dda6e
Apply Sara suggestion 2939910868
DicksonWu654 Mar 17, 2026
2e8fa6b
Apply Sara suggestion 2939911520
DicksonWu654 Mar 17, 2026
886e96e
Apply Sara suggestion 2939912288
DicksonWu654 Mar 17, 2026
d19c024
Update offboarding guidelines and reviewers
mattaereal Mar 23, 2026
5b4709f
Revise multisig responsibilities and documentation
mattaereal Mar 23, 2026
46a2cdf
Update emergency pause response time and threshold
mattaereal Mar 23, 2026
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
11 changes: 9 additions & 2 deletions docs/pages/multisig-for-protocols/emergency-procedures.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ lost access, and communication breaches.
1. **Isolate** - Quarantine potentially compromised devices
2. **New hardware setup** - Set up fresh wallet with new seed following [Hardware Wallet Setup](/wallet-security/intermediates-and-medium-funds)
3. **Coordinate replacement** - Plan signer replacement transaction with team
4. **Execute replacement** - Replace compromised signer on multisig, following steps for signer rotation in [Secure
Multisig Best Practices](/wallet-security/secure-multisig-best-practices)
4. **Execute replacement** - Replace compromised signer on multisig, following the
[Signer Rotation Runbook](/multisig-for-protocols/runbooks/signer-rotation)
5. **Verify security** - Confirm new setup before resuming operations

## Lost Key Access
Expand Down Expand Up @@ -173,6 +173,12 @@ Current multisig status:
- **Backup signers** - Have additional signers available for activation
- **Communication redundancy** - Multiple ways to reach each signer

## Emergency Pause Runbook

Use the full [Emergency Pause Runbook](/multisig-for-protocols/runbooks/emergency-pause) as the canonical execution
playbook for emergency pause transactions. Keep this page focused on incident coordination, communication, and recovery,
and use the runbook page for the transaction-specific signing and execution steps.

### Emergency Drill Procedures

#### Regular Testing Schedule
Expand Down Expand Up @@ -230,6 +236,7 @@ Current multisig status:
- [Hardware Wallet Setup](/wallet-security/intermediates-and-medium-funds) - Device replacement procedures
- [Seed Phrase Management](/wallet-security/seed-phrase-management) - Key recovery procedures
- [Personal Security (OpSec)](/multisig-for-protocols/personal-security-opsec) - Account security measures
- [Operational Runbooks](/multisig-for-protocols/runbooks/overview) - Example runbooks for common operations

</TagProvider>
<ContributeFooter />
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 @@ -24,3 +24,4 @@ title: "Multisig For Protocols"
- [Multisig Incident Reporting](/multisig-for-protocols/incident-reporting)
- [Multisig Offboarding](/multisig-for-protocols/offboarding)
- [Multisig Implementation Checklist](/multisig-for-protocols/implementation-checklist)
- [Runbooks](/multisig-for-protocols/runbooks)
16 changes: 14 additions & 2 deletions docs/pages/multisig-for-protocols/offboarding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ contributors:
- role: wrote
users: [isaac, geoffrey, louis, pablo, dickson]
- role: reviewed
users: [pinalikefruit, engn33r]
users: [pinalikefruit, engn33r, mattaereal]
---

import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
Expand All @@ -27,10 +27,22 @@ When leaving a multisig, follow these steps:
## Signer removal

1. **Coordinate with team** - Notify other signers and schedule the removal transaction
2. **Execute removal** - Follow standard signer rotation procedures ([Signer Rotation](/wallet-security/secure-multisig-best-practices#signer-rotation))
2. **Execute removal** - Follow the [Signer Rotation Runbook](/multisig-for-protocols/runbooks/signer-rotation)
3. **Verify removal** - Confirm your address has been removed from the multisig
4. **Update documentation** - Ensure documentation reflects the change

## Timing requirements

Teams should define offboarding timelines in advance based on the multisig's role, risk, and governance process.

For higher-risk or emergency-sensitive multisigs, signer removal may need to happen on a much shorter timeline. For
lower-risk setups, the appropriate timeline may be longer. Document the expected response window in your internal
policy and make sure it is understood by all signers. For example:

- **Emergency-class multisigs**: Complete signer removal within 48-72 hours
- **Critical-class multisigs**: Complete signer removal within 7 days
- **Other multisigs**: Complete signer removal within 14 days

## Clean up access

- Leave all multisig communication channels (Signal, Telegram, etc.)
Expand Down
4 changes: 3 additions & 1 deletion docs/pages/multisig-for-protocols/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
- Joining as a signer? → [Joining a Multisig](/multisig-for-protocols/joining-a-multisig) and [Hardware Wallet Setup](/wallet-security/intermediates-and-medium-funds)
- Need to sign a transaction? → Signing & Verification:
[Safe Multisig](/wallet-security/signing-and-verification/secure-multisig-safe-verification) and
[Squads](/wallet-security/signing-and-verification/secure-multisig-squads-verification)
[Squads](/wallet-security/signing-and-verification/secure-multisig-squads-verification), plus
[Operational Runbooks](/multisig-for-protocols/runbooks/overview)
- Emergency situation? → [Emergency Procedures](/multisig-for-protocols/emergency-procedures)

## Core principles
Expand All @@ -55,6 +56,7 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
- [Registration & Documentation](/multisig-for-protocols/registration-and-documentation) - Document and verify setup
- [Communication Setup](/multisig-for-protocols/communication-setup) - Establish secure communication channels
- [Use Case Specific Requirements](/multisig-for-protocols/use-case-specific-requirements) - Special requirements by type
- [Operational Runbooks](/multisig-for-protocols/runbooks/overview) - Example procedures for common operations

### 3. For Signers

Expand Down
213 changes: 212 additions & 1 deletion docs/pages/multisig-for-protocols/registration-and-documentation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,87 @@ Detailed steps for collecting this information are provided in [Joining a Multis

**Note**: Entity affiliations are acceptable - the goal is accountability, not doxing.

## Roles & Accountability

### Accountability Structure

| Role | Responsibilities |
|------|------------------|
| **Multisig Operations Lead** | Policy maintenance, signer coordination, documentation, periodic reviews, incident escalation |
| **Security Contact** | Security incident response, signer verification, emergency coordination |

### Multisig-Specific Roles

For each multisig, assign:

| Role | Responsibility |
|------|----------------|
| **Admin** | Setup, configuration, signer management, documentation |
| **Transaction Proposer** | Prepares and proposes transactions (may be delegated non-signer) |
| **Signers** | Review, verify, and sign transactions |

### Signer Responsibilities

Every signer must:

- Use a hardware wallet for multisig operations
- Maintain a documented recovery and continuity plan
- Store seed material and recovery credentials securely
- Verify every transaction before signing
- Understand multisig response time expectations
- Report incidents promptly
- Complete required onboarding, training, and drills

Recovery procedures vary by team. Some teams use backup devices or replicated seed material, while others avoid
that model because it changes the threat surface. Document the tradeoffs and controls for whichever recovery approach
you use.

#### Response Time SLAs

Define expected response windows based on the multisig's classification, the assets or permissions it controls, and
the team's operational model. See [Planning & Classification](/multisig-for-protocols/planning-and-classification#operational-classification).

For example, teams often set much shorter expectations for emergency actions than for routine operational
transactions. Record those expectations in your internal policy and make sure all signers understand them.

Example:

- **Emergency**: \<2 hours
- **Time-Sensitive**: 2-12 hours
- **Routine**: 24-48 hours

### Admin Responsibilities

Multisig admins typically:

- Ensure the multisig is properly documented
- Maintain an up-to-date signer list with verified addresses
- Set up primary and backup communication channels
- Coordinate signer onboarding and offboarding
- Schedule and conduct periodic reviews at a cadence appropriate to the multisig's risk and activity level (e.g. quarterly minimum)
- Ensure backup infrastructure is configured and tested

### Operational Lead Responsibilities

- Maintain the playbook and keep documentation current
- Coordinate across all multisigs
- Periodically review multisig configurations and supporting documentation
- Escalate security concerns to the security contact
- Report on operational status

### Review Schedule

The right review cadence depends on the multisig's scope, activity level, and risk profile.

Example review areas to assign and track:

| Review Type | Frequency | Owner |
|------------|-----------|-------|
| Signer access review | Quarterly | Multisig Admin |
| Classification review | Quarterly or after major changes | Ops Lead |
| Emergency contact verification | Every 6 months | Ops Lead |
| Full policy review | Annually | Ops Lead + Security |

## Update Template

Use this template when making changes to signer composition:
Expand Down Expand Up @@ -124,6 +205,135 @@ Transaction: [Link to executed transaction]
- Update classification if operational patterns change
- Maintain current contact information

### Transaction Review Records

Maintain transaction records appropriate to your team's operational, legal, and compliance needs.

At a minimum, teams often record:

- What the transaction was for
- Who proposed it
- Who reviewed or approved it
- Whether it was executed successfully
- Any issues or anomalies encountered

Retention periods and evidence requirements should be defined by your organization's own policy.

**Retention**: 3 years minimum

Transaction records should capture:

#### Header

- Transaction: [Brief Description]
- Date: [YYYY-MM-DD]
- Multisig: [Name]
- Status: Proposed / Signing / Executed / Rejected

#### Transaction Details

- Network
- Safe or Squad address
- Nonce
- Transaction type

#### What This Transaction Does

- Plain language description of what the transaction accomplishes

#### Initiation

- Proposed by
- Proposed date
- Reason or justification
- Runbook followed

#### Verification & Signing

- Signer
- Verified
- Signed
- Date
- Notes

#### Verification Checklist

- Correct multisig address
- Correct network
- Expected nonce
- Target address verified
- Calldata or amount verified
- Simulation performed
- Hash matched hardware wallet

#### Simulation Results

- Tool used
- Result
- Expected behavior confirmed
- Link

#### Execution

- Executed by
- Execution date
- Transaction hash
- Block explorer link
- Gas used

#### Post-Execution Verification

- Transaction confirmed on-chain
- Expected state change verified
- Registration updated if applicable
- Team notified

#### Issues Encountered

- Document any issues, delays, or anomalies

#### Attachments

- Screenshot of simulation
- Screenshot of hardware wallet confirmation
- Communication thread link

### Alternative simple transaction record

A simple transaction record might capture:

#### Core Record

- Transaction: [Brief Description]
- Date: [YYYY-MM-DD]
- Multisig: [Name]
- Status: Proposed / Signing / Executed / Rejected
- Proposed by
- Reason or justification
- Network
- Multisig address
- Transaction type
- Transaction hash or proposal link
- Who reviewed or signed
- Outcome
- Notes on any issues encountered

#### Optional Additional Evidence

Higher-maturity teams may also choose to retain:

- Expected nonce
- Simulation results
- Verification notes
- Links to communication threads
- Post-execution verification notes
- Screenshots or supporting artifacts where appropriate

#### Sign-Off

- Proposer
- Final executor

## Ongoing Management

### Regular reviews
Expand All @@ -146,7 +356,7 @@ Follow these procedures for adding, removing, or replacing signers:

#### Replacing signers

Follow steps in [Signer Rotation](/wallet-security/secure-multisig-best-practices#signer-rotation)
Follow steps in the [Signer Rotation Runbook](/multisig-for-protocols/runbooks/signer-rotation)

### Documentation updates

Expand All @@ -164,6 +374,7 @@ Use the template in [Registration & Documentation → Update Template](/multisig

- [Planning & Classification](/multisig-for-protocols/planning-and-classification) - How to classify your multisig
- [Joining a Multisig](/multisig-for-protocols/joining-a-multisig) - Signer verification process
- [Operational Runbooks](/multisig-for-protocols/runbooks/overview) - Example procedures for common operations

</TagProvider>
<ContributeFooter />
Loading
Loading