docs/UPGRADE_PROCEDURE.md

Upgrade Procedure for eMoneyToken

Overview

eMoneyToken uses the UUPS (Universal Upgradeable Proxy Standard) upgradeable proxy pattern. This document outlines the procedure for safely upgrading token implementations.

Prerequisites

1. OpenZeppelin Upgrades Core tools installed: npm install --save-dev @openzeppelin/upgrades-core 2. Storage layout validation script (see tools/validate-storage-layout.sh)

Pre-Upgrade Checklist

• Review all changes to storage variables
• Ensure no storage variables are removed or reordered
• Verify new storage variables are appended only
• Run storage layout validation
• Test upgrade on testnet
• Get multisig approval for upgrade

Storage Layout Validation

Using OpenZeppelin Upgrades Core

1. Extract storage layout from current implementation: forge build npx @openzeppelin/upgrades-core validate-storage-layout
   --contract-name eMoneyToken
   --reference artifacts/build-info/.json
   --new artifacts/build-info/.json 2. Compare layouts:

   tools/validate-storage-layout.sh

   Manual Validation

Storage variables in eMoneyToken (in order):

1. _decimals (uint8)
2. _inForceTransfer (bool)
3. _inClawback (bool)
4. Inherited from ERC20Upgradeable
5. Inherited from AccessControlUpgradeable
6. Inherited from UUPSUpgradeable
7. Inherited from ReentrancyGuardUpgradeable

CRITICAL: Never remove or reorder existing storage variables. Only append new ones.

Upgrade Steps

1. Deploy New Implementation: forge script script/Upgrade.s.sol:UpgradeScript --rpc-url $RPC_URL --broadcast 2. Verify Implementation: forge verify-contract <NEW_IMPL_ADDRESS> eMoneyToken --chain-id 138 3. Authorize Upgrade (via multisig): eMoneyToken(tokenAddress).upgradeTo(newImplementationAddress); 4. Verify Upgrade: forge script script/VerifyUpgrade.s.sol:VerifyUpgrade --rpc-url $RPC_URL

   Post-Upgrade Verification

• Token balances unchanged
• Transfer functionality works
• Policy checks still enforced
• Lien enforcement still works
• Compliance checks still work
• Events emit correctly
• All roles still functional

Emergency Rollback

If issues are discovered post-upgrade:

1. Deploy previous implementation
2. Authorize upgrade back to previous version
3. Investigate and fix issues
4. Re-attempt upgrade with fixes

Storage Layout Validation Script

See tools/validate-storage-layout.sh for automated validation.

References

• OpenZeppelin UUPS Documentation
• Storage Layout Safety