self/contracts/UPGRADE_GUIDE.md

Contract Upgrade Guide

Quick Start

1. Update Your Contract

// Update version in NatSpec
* @custom:version 2.13.0

// Update reinitializer modifier (increment by 1)
function initialize(...) external reinitializer(13) {
    // Add any new initialization logic
}

2. Run the Upgrade Script

cd contracts
npx hardhat upgrade --contract IdentityVerificationHub --network celo --changelog "Added feature X"

3. Approve in Safe

The script outputs instructions to submit to the Safe multisig. Once 3/5 signers approve, execute the transaction.

---

Governance Roles

Role	Threshold	Purpose
SECURITY_ROLE	3/5	Contract upgrades, role management
OPERATIONS_ROLE	2/5	CSCA root updates, OFAC list updates

---

Detailed Workflow

Step 1: Modify the Contract

1. Make your code changes
2. Update @custom:version in the contract's NatSpec comment
3. Increment the reinitializer(N) modifier (e.g., reinitializer(12) → reinitializer(13))
4. Add any new storage fields at the end of the storage struct

Example:

/**
 * @title IdentityVerificationHubImplV2
 * @custom:version 2.13.0
 */
contract IdentityVerificationHubImplV2 is ImplRoot {

    struct HubStorage {
        // Existing fields...
        uint256 newField;  // Add new fields at the end only
    }

    function initialize(...) external reinitializer(13) {
        // Initialize new fields if needed
        HubStorage storage $ = _getHubStorage();
        $.newField = defaultValue;
    }
}

Step 2: Run the Upgrade Script

npx hardhat upgrade --contract <ContractName> --network <network> --changelog "Description"

Options:

• --contract - Contract name (e.g., IdentityVerificationHub)
• --network - Target network (celo, sepolia, localhost)
• --changelog - Brief description of changes
• --prepare-only - Deploy implementation without creating Safe proposal

Step 3: Script Execution

The script automatically:

1. Validates version - Ensures @custom:version is incremented correctly
2. Checks reinitializer - Verifies reinitializer(N) matches expected version
3. Validates storage - Ensures no breaking storage layout changes
4. Compiles fresh - Clears cache to prevent stale bytecode
5. Compares bytecode - Warns if implementation hasn't changed
6. Deploys implementation - Deploys new implementation contract
7. Updates registry - Records deployment in deployments/registry.json
8. Creates git commit & tag - Auto-commits changes with version tag
9. Creates Safe proposal - If you're a signer, auto-proposes to Safe

Step 4: Multisig Approval

If you're a Safe signer:

• Script auto-proposes the transaction
• Other signers approve in Safe UI
• Execute once threshold (3/5) is met

If you're not a signer:

• Script outputs transaction data for manual submission
• Copy data to Safe Transaction Builder
• Signers approve and execute

---

Safety Checks

The upgrade script performs these automatic checks:

Check	What it Does	Failure Behavior
Version validation	Ensures semantic version increment	Blocks upgrade
Reinitializer check	Verifies modifier matches version	Blocks upgrade
Storage layout	Detects breaking storage changes	Blocks upgrade
Bytecode comparison	Warns if code unchanged	Prompts confirmation
Safe role verification	Confirms Safe has SECURITY_ROLE	Blocks upgrade
Constructor check	Flags _disableInitializers()	Prompts confirmation

---

Registry Structure

All deployments are tracked in deployments/registry.json:

{
  "contracts": {
    "ContractName": {
      "source": "ContractSourceFile",
      "type": "uups-proxy"
    }
  },
  "networks": {
    "celo": {
      "deployments": {
        "ContractName": {
          "proxy": "0x...",
          "currentVersion": "2.12.0",
          "currentImpl": "0x..."
        }
      }
    }
  },
  "versions": {
    "ContractName": {
      "2.12.0": {
        "initializerVersion": 12,
        "changelog": "...",
        "gitTag": "contractname-v2.12.0",
        "deployments": { ... }
      }
    }
  }
}

---

Utility Commands

# Check current deployment status
npx hardhat upgrade:status --contract IdentityVerificationHub --network celo

# View version history
npx hardhat upgrade:history --contract IdentityVerificationHub

---

Rollback

If issues occur after upgrade:

1. Deploy the previous implementation version
2. Create Safe transaction calling upgradeToAndCall(previousImpl, "0x")
3. Execute with 3/5 multisig approval

---

Environment Setup

Required in .env:

CELO_RPC_URL=https://forno.celo.org
PRIVATE_KEY=0x...  # Deployer wallet (needs ETH for gas)

Optional for contract verification:

CELOSCAN_API_KEY=...
ETHERSCAN_API_KEY=...

---

Troubleshooting

Issue	Solution
"Version matches current"	Update @custom:version in contract
"Reinitializer mismatch"	Update reinitializer(N) to next version
"Storage layout incompatible"	Don't remove/reorder storage variables
"Safe not indexed"	Submit manually via Safe UI
"Bytecode unchanged"	Ensure you saved contract changes