smom-dbis-138/docs/bridge/trustless/MULTISIG_OPERATIONS.md

Multisig Operations Guide

Overview

The trustless bridge system uses multisig wallets (recommended: Gnosis Safe) for managing admin functions and critical operations. This document describes multisig setup, operations, and procedures.

Multisig Configuration

Recommended Setup

• Type: Gnosis Safe
• Threshold: 2-of-3 or 3-of-5 (recommended)
• Signers: Trusted team members or key stakeholders
• Network: Ethereum Mainnet

Setup Steps

1. Deploy Gnosis Safe

   • Use Gnosis Safe Factory or deploy directly
   • Configure signers and threshold
   • Test multisig operations on testnet first

2. Transfer Admin Rights

   • Transfer ownership of upgradeable contracts to multisig
   • Update access control roles to multisig address
   • Verify multisig has required permissions

3. Configure Timelocks (if applicable)

   • 48-72 hour timelock for contract upgrades
   • 24 hour timelock for emergency pause
   • Configure via timelock contract or Gnosis Safe modules

Contracts Requiring Multisig

Immutable Contracts (No Admin Functions)

These contracts have no admin functions and don't require multisig:

• Lockbox138 - Immutable, no admin functions
• BondManager - Immutable, no admin functions
• ChallengeManager - Immutable, no admin functions
• InboxETH - Immutable, no admin functions

Contracts with Admin Functions

Review these contracts for admin functions:

• LiquidityPoolETH - Review for any admin functions
• SwapRouter - Review for any admin functions
• BridgeSwapCoordinator - Review for any admin functions

Common Operations

1. Proposing Contract Upgrades

Script: scripts/bridge/trustless/multisig/propose-upgrade.sh

Usage:

./propose-upgrade.sh <multisig_address> <target_contract> <new_implementation> [description]

Example:

./propose-upgrade.sh \
  0x1234567890123456789012345678901234567890 \
  0x5678901234567890123456789012345678901234 \
  0x9ABCDEF0123456789012345678901234567890AB \
  "Upgrade LiquidityPoolETH to v2"

Process:

1. Prepare upgrade transaction data
2. Submit proposal to multisig
3. Wait for required signatures
4. Execute after timelock (if applicable)

2. Emergency Pause

Script: scripts/bridge/trustless/multisig/propose-pause.sh

Usage:

./propose-pause.sh <multisig_address> <target_contract> [reason]

Example:

./propose-pause.sh \
  0x1234567890123456789012345678901234567890 \
  0x5678901234567890123456789012345678901234 \
  "Security incident detected"

Process:

1. Prepare pause transaction data
2. Submit proposal to multisig
3. Wait for required signatures (may have shorter timelock)
4. Execute immediately if emergency

3. Executing Approved Proposals

Script: scripts/bridge/trustless/multisig/execute-proposal.sh

Usage:

./execute-proposal.sh <multisig_address> <transaction_id>

Example:

./execute-proposal.sh \
  0x1234567890123456789012345678901234567890 \
  42

Gnosis Safe Web Interface

Accessing Multisig

1. Go to https://app.safe.global/
2. Connect wallet (must be a signer)
3. Select your multisig wallet
4. View pending transactions

Creating Transactions

1. Click "New Transaction"
2. Select "Contract Interaction"
3. Enter contract address
4. Select function and enter parameters
5. Review and submit

Signing Transactions

1. View pending transactions
2. Review transaction details
3. Click "Sign" or "Reject"
4. Wait for required signatures

Executing Transactions

1. Once threshold is met, transaction becomes executable
2. Click "Execute"
3. Confirm gas fees
4. Submit execution transaction

Security Best Practices

1. Key Management

• Use hardware wallets for signers
• Store backup keys securely
• Use key management services if needed
• Never share private keys

2. Access Control

• Limit number of signers with admin access
• Use role-based access where possible
• Regularly review and audit permissions
• Rotate signers periodically

3. Transaction Review

• Always review transaction details before signing
• Verify contract addresses
• Check function parameters
• Confirm transaction purpose

4. Emergency Procedures

• Have emergency response plan
• Document emergency contacts
• Test emergency procedures regularly
• Maintain backup signers

Timelock Configuration

Standard Operations

• Contract Upgrades: 48-72 hours
• Parameter Changes: 24-48 hours
• Fee Adjustments: 24-48 hours

Emergency Operations

• Pause: 24 hours (or shorter for critical emergencies)
• Emergency Withdrawals: 24 hours
• Security Patches: As needed (may bypass timelock)

Monitoring Multisig

Transaction Monitoring

• Monitor all multisig transactions
• Alert on large value transfers
• Track pending proposals
• Log all executions

Access Monitoring

• Monitor signer activity
• Alert on new signer additions
• Track threshold changes
• Audit access logs

Troubleshooting

Transaction Stuck

1. Check if threshold is met
2. Verify all required signatures
3. Check for timelock delays
4. Contact other signers if needed

Missing Signatures

1. Identify missing signers
2. Contact signers to sign
3. Consider backup signers if needed
4. Document missing signatures

Emergency Access

1. Use emergency procedures if available
2. Contact all signers immediately
3. Document emergency actions
4. Post-incident review

Testing

Testnet Testing

1. Deploy test multisig on testnet
2. Test all operations
3. Verify timelocks work correctly
4. Test emergency procedures

Mainnet Verification

1. Deploy multisig on mainnet
2. Test with small transactions first
3. Verify all signers can sign
4. Confirm threshold works correctly

References

• Gnosis Safe Documentation: https://docs.safe.global/
• Scripts: scripts/bridge/trustless/multisig/
• Emergency Procedures: docs/operations/EMERGENCY_RESPONSE.md