Design and implement upgradable smart contracts

[crtahlin]

Summary

Design and implement an upgrade strategy for the provenance smart contracts so they can be updated at production time without disrupting operations.

Problem

Current contracts are not upgradable. Any changes require redeployment, which breaks existing references and disrupts live operations.

Requirements

• Contracts must be upgradable in-place (no migration, no downtime)
• Existing data and state must be preserved across upgrades
• Upgrade process must be secure (access-controlled)

Investigation

• Look into OpenZeppelin upgradable contracts (proxy pattern, UUPS, transparent proxy)
• Evaluate which pattern fits the provenance use case best
• Consider storage layout compatibility and upgrade safety tooling

Deliverables

• Upgrade strategy document (which pattern, why)
• Refactored contracts with upgrade support
• Upgrade scripts and tests
• Documentation for performing upgrades safely

[tfius]

Analysis: UUPS Proxy Pattern Recommended

Pattern comparison

Pattern	Verdict	Reason
UUPS	Best fit	Gas-efficient, OZ-recommended, upgrade logic in implementation, Hardhat Ignition has native support
Transparent Proxy	Viable but heavier	Extra gas on every call (admin slot check), separate ProxyAdmin per contract
Beacon Proxy	Wrong use case	Designed for many instances of the same contract — we have singletons
Diamond (EIP-2535)	Overkill	Complex facet system for large composable contracts — not needed here

Why UUPS specifically suits this project

1. Existing RBAC — DataProvenance already has ADMIN_ROLE. The UUPS _authorizeUpgrade() hook can delegate to it directly rather than introducing a separate ProxyAdmin contract.

2. Hardhat Ignition support — @openzeppelin/hardhat-upgrades integrates with Ignition for proxy deployments, so the existing deployment infrastructure needs minimal changes.

3. Gas efficiency — UUPS proxies are cheaper to deploy and cheaper per call than transparent proxies. The proxy contract is minimal (~200 bytes); all logic including upgrade authorization lives in the implementation.

4. 9 contracts, 3 tiers — Each gets its own UUPS proxy. The dependency addresses (e.g., IntegratedSystem pointing to ConsentReceipt + DataProvenance) point to the proxy addresses, which stay stable across upgrades.

What changes per contract

All contracts:

• Constructor → initialize() function with initializer modifier
• Inherit Initializable, UUPSUpgradeable from @openzeppelin/contracts-upgradeable
• Implement _authorizeUpgrade(address) with access control
• Add uint256[50] private __gap at the end of storage for future-proofing

Specific concerns:

Contract	Constructor today	Notes
ConsentReceipt	Computes DOMAIN_SEPARATOR using address(this)	With a proxy, address(this) is the proxy address — computing in initialize() is correct and the separator stays stable across upgrades
DataProvenance	Sets contractAdmin, grants ADMIN_ROLE	Moves to initialize(). _authorizeUpgrade checks hasRole(ADMIN_ROLE, msg.sender)
IntegratedConsentProvenanceSystem	Takes two contract addresses	Becomes initialize(address _consent, address _provenance). Proxy addresses are stable, so cross-contract references survive upgrades
DataAccessControl / DataDeletion	Takes provenance address	Same pattern: initialize(address _provenanceProxy)
KantaraConsentReceipt	Parameterless	Simplest case — initialize() with no params
ConsentProxy / PurposeRegistry / ConsentAuditLog	Parameterless or simple	Same straightforward pattern

Storage layout safety

The struct change from #6 (string[] transformations → TransformationLink[] transformationLinks) is a storage-breaking change that can only be done via redeployment, not proxy upgrade. This is fine since the contracts aren't upgradeable yet. But once UUPS is in place, struct layout changes like this would require careful storage migration or a new storage slot.

OpenZeppelin's @openzeppelin/upgrades-core package includes a storage layout checker that runs at upgrade time and rejects incompatible changes automatically.

New dependencies needed

@openzeppelin/contracts-upgradeable
@openzeppelin/hardhat-upgrades

Deployment flow after UUPS

# Initial deploy (creates proxy + implementation for each contract)
npx hardhat ignition deploy ignition/modules/ConsentSystem.ts --network baseSepolia

# Upgrade (deploys new implementation, points existing proxy to it)
npx hardhat ignition deploy ignition/modules/ConsentSystemUpgrade.ts --network baseSepolia

Risk mitigation

Risk	Mitigation
Forgot _authorizeUpgrade?	OZ's UUPSUpgradeable won't compile without it
Storage collision?	__gap reservations + OZ storage layout checker catch this at deploy time
Unauthorized upgrade?	_authorizeUpgrade checks ADMIN_ROLE
Bricked proxy?	UUPS's only real risk — mitigated by always inheriting UUPSUpgradeable and testing the upgrade path before mainnet

Implementation order

1. Add OZ upgradeable dependencies
2. Refactor contracts (constructors → initializers, add UUPS inheritance, add __gap)
3. Update Ignition modules for proxy deployment
4. Add upgrade tests (deploy v1, upgrade to v2, verify state preserved)
5. Add upgrade scripts for each target network

[crtahlin]

Review notes

@tfius — reviewed the plan against the current codebase. The UUPS recommendation is solid, but a few things need addressing before implementation:

1. immutable DOMAIN_SEPARATOR in ConsentReceipt (blocker)

ConsentReceipt.sol uses bytes32 immutable DOMAIN_SEPARATOR set in the constructor. Immutable variables are baked into implementation bytecode, not proxy storage — so behind a UUPS proxy, the separator would be computed with the wrong address(this) (implementation address instead of proxy address).

Fix: Change from immutable to a regular state variable set in initialize(). The proxy address is stable across upgrades, so EIP-712 signatures remain valid.

2. PurposeRegistry constructor registers 10 core purposes

The plan doesn't mention this. PurposeRegistry constructor calls _registerPurpose() 10 times to seed core purposes. This logic needs to move into initialize() — straightforward but shouldn't be overlooked.

3. Hardhat Ignition v0.15 does NOT have native UUPS proxy support

The plan states "Hardhat Ignition has native support" — but that's Ignition v1.0+ which requires Hardhat v3. We're on Hardhat v2 with Ignition v0.15. Options:

Option	Effort	Risk
Upgrade to Hardhat v3 + Ignition v1.0	High — breaking changes across config, plugins, tests	Scope creep
Use @openzeppelin/hardhat-upgrades with custom deploy scripts (not Ignition)	Medium	Lose Ignition's state tracking
Manual proxy deployment in Ignition module (deploy impl, deploy ERC1967Proxy, call initialize)	Medium	More code but stays on current stack

Need a decision on which path to take.

4. No OpenZeppelin dependency exists yet

The project currently has zero OZ imports. Need to add @openzeppelin/contracts-upgradeable and @openzeppelin/hardhat-upgrades.

5. Interface mismatch in IKantaraConsentReceipt

IKantaraConsentReceipt.sol uses uint8[] for purposes but the implementation uses Purpose[] enums. Not UUPS-related, but should be cleaned up before locking in a proxy storage layout — any interface-driven tooling would hit type mismatches.

6. Positive: no inheritance in any contract

All 9 contracts are standalone with no inheritance chains. This simplifies the migration — no diamond inheritance storage ordering issues. Each contract just adds Initializable, UUPSUpgradeable as parents.

7. Upgrade testing strategy

The plan mentions upgrade tests briefly but this deserves explicit scope:

• Deploy v1 via proxy → populate state → deploy v2 implementation → verify all state survives
• Test that _authorizeUpgrade blocks unauthorized callers
• Test the "bricked proxy" scenario (implementation deployed without UUPSUpgradeable inheritance)
• Run OZ storage layout checker on every upgrade

Summary

Plan is directionally correct. Main open question is item 3 (Ignition/Hardhat version strategy) — that decision affects the implementation approach for everything else.