e8ae376e90
- Integrated Zod validation schemas across various API routes to ensure input integrity and improve error handling. - Updated `mapping-service`, `orchestrator`, `packet-service`, and `webhook-service` to utilize validation middleware for request parameters and bodies. - Improved error handling in webhook management, packet generation, and compliance routes to provide clearer feedback on request failures. - Added new validation schemas for various endpoints, enhancing overall API robustness and maintainability. - Updated dependencies in `package.json` to include the new validation library.
106 lines
2.8 KiB
Markdown
106 lines
2.8 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
forge script script/Upgrade.s.sol:UpgradeScript --rpc-url $RPC_URL --broadcast
|
|
```
|
|
|
|
2. **Verify Implementation**:
|
|
```bash
|
|
forge verify-contract <NEW_IMPL_ADDRESS> eMoneyToken --chain-id 138
|
|
```
|
|
|
|
3. **Authorize Upgrade** (via multisig):
|
|
```solidity
|
|
eMoneyToken(tokenAddress).upgradeToAndCall(newImplementationAddress, "");
|
|
```
|
|
|
|
4. **Verify Upgrade**:
|
|
```bash
|
|
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)
|
|
|