smom-dbis-138/docs/ccip-integration/operations/ADMIN_KEY_MANAGEMENT.md

Admin Key Management for CCIP Contracts

Date: 2025-01-27
Network: ChainID 138 (DeFi Oracle Meta Mainnet)

---

Overview

This document outlines best practices for managing admin keys for CCIP contracts on ChainID 138.

---

Admin Functions

CCIP Router Admin Functions

• addSupportedChain(uint64 chainSelector)
• removeSupportedChain(uint64 chainSelector)
• addSupportedToken(uint64 chainSelector, address token)
• updateFees(uint256 baseFee, uint256 dataFeePerByte)
• changeAdmin(address newAdmin)
• withdrawFees(uint256 amount)
• withdrawNativeFees()

Bridge Admin Functions

• addDestination(uint64 chainSelector, address receiverBridge)
• removeDestination(uint64 chainSelector)
• updateDestination(uint64 chainSelector, address receiverBridge)
• updateFeeToken(address newFeeToken)
• changeAdmin(address newAdmin)

---

Key Management Best Practices

1. Key Storage

DO:

• Use hardware wallets (Ledger, Trezor)
• Use secure key management systems (HSM, AWS KMS, Azure Key Vault)
• Store keys in encrypted format
• Use separate keys for different environments (testnet/mainnet)
• Implement key rotation procedures

DON'T:

• Store keys in plain text files
• Commit keys to version control
• Share keys via insecure channels
• Use same key for multiple purposes
• Store keys on shared systems

2. Access Control

DO:

• Implement multi-sig for admin functions
• Use role-based access control
• Require multiple approvals for critical changes
• Log all admin actions
• Monitor for unauthorized access

DON'T:

• Grant admin access to untrusted parties
• Skip approval processes
• Ignore access logs
• Allow unmonitored admin access

3. Key Rotation

Procedure:

1. Generate New Key

   • Create new key pair
   • Store securely
   • Verify key works

2. Transfer Admin

   cast send $CONTRACT \
     "changeAdmin(address)" \
     $NEW_ADMIN \
     --rpc-url $RPC_URL \
     --private-key $OLD_ADMIN_KEY
   

3. Verify Transfer

   cast call $CONTRACT "admin()" --rpc-url $RPC_URL
   

4. Revoke Old Key

   • Securely delete old key
   • Update documentation
   • Notify team

4. Emergency Procedures

If Key is Compromised:

1. Immediate Actions:

   • Transfer admin to new secure key
   • Review recent transactions
   • Check for unauthorized changes
   • Notify team and stakeholders

2. Investigation:

   • Analyze access logs
   • Identify compromise source
   • Document incident

3. Recovery:

   • Restore from backup if needed
   • Revert unauthorized changes
   • Implement additional security

---

Multi-Sig Setup

Recommended: Use Multi-Sig Wallet

For production deployments, use a multi-sig wallet:

1. Deploy Multi-Sig

   • Use OpenZeppelin's MultiSigWallet
   • Set required confirmations (e.g., 2 of 3)
   • Add trusted signers

2. Set Multi-Sig as Admin

   cast send $CONTRACT \
     "changeAdmin(address)" \
     $MULTISIG_ADDRESS \
     --rpc-url $RPC_URL \
     --private-key $DEPLOYER_KEY
   

3. Use Multi-Sig for Admin Functions

   • Submit transactions through multi-sig
   • Require multiple approvals
   • Track all proposals

---

Key Rotation Schedule

Recommended Schedule

• Quarterly: Review key security
• Annually: Rotate keys (if no issues)
• Immediately: Rotate if compromised
• After Incidents: Rotate as part of recovery

---

Monitoring

Monitor Admin Actions

Track all admin function calls:

# Monitor admin changes
cast logs --address $CONTRACT \
  "AdminChanged(address,address)" \
  --rpc-url $RPC_URL

# Monitor configuration changes
cast logs --address $CONTRACT \
  "DestinationAdded(uint64,address)" \
  --rpc-url $RPC_URL

Alerts

Set up alerts for:

• Admin changes
• Configuration changes
• Unusual admin activity
• Failed admin operations

---

Documentation

Required Documentation

1. Key Inventory: List all admin keys and their purposes
2. Access Logs: Maintain logs of all admin actions
3. Rotation Records: Document all key rotations
4. Incident Reports: Document security incidents

Key Information to Document

• Key purpose (router admin, bridge admin, etc.)
• Key location (hardware wallet, HSM, etc.)
• Key holders (who has access)
• Last rotation date
• Next rotation date

---

Compliance

Audit Requirements

• Regular security audits
• Key management reviews
• Access control audits
• Incident response reviews

Regulatory Considerations

• Follow industry best practices
• Maintain audit trails
• Implement proper controls
• Document procedures

---

Related Documentation

• CCIP Security Guide
• CCIP Runbooks
• CCIP Monitoring

---

Last Updated: 2025-01-27