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**:
```bash
./propose-upgrade.sh <multisig_address> <target_contract> <new_implementation> [description]
```

**Example**:
```bash
./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**:
```bash
./propose-pause.sh <multisig_address> <target_contract> [reason]
```

**Example**:
```bash
./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**:
```bash
./execute-proposal.sh <multisig_address> <transaction_id>
```

**Example**:
```bash
./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`