Initial commit: add .gitignore and README

UPGRADE_PROCEDURE.md

@@ -0,0 +1,84 @@
+# 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)