# 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](https://docs.openzeppelin.com/upgrades-plugins/1.x/uups-upgradeable)
- [Storage Layout Safety](https://docs.openzeppelin.com/upgrades-plugins/1.x/storage-layout)