uupl-smart-contract/README.md

UUPS Bank V1 Demo

This repository is the prepared starting point for a live upgradeability lesson. It deploys a local V1 bank that custodies a six-decimal mock ERC-20, records customer balances behind an ERC-1967 proxy, and presents the result in a read-only operations console.

Trust boundary: MockUSDC has no value. These contracts are educational and unaudited; real deposits must never be sent here. The owner can pause customer actions and install arbitrary future logic. UUPS mistakes can corrupt state or permanently brick upgradeability. A real custody product requires professional audits, operational key controls, multisig or timelocked governance, incident procedures, legal advice, and jurisdiction-specific compliance work.

Prerequisites

Use a Linux-like Bash environment with Git, GNU Make, curl, Foundry 1.7.1 (forge, anvil, and cast), Node 24.18.0, and npm 11.17.0. The exact package graph is committed in the lockfiles. Installation documentation: Git, Foundry, Node, npm, Bash, Make, and curl.

make setup
make doctor

make setup initializes recursive Git submodules and installs both pinned npm dependency trees. make doctor is read-only: it verifies versions, dependencies, writable runtime locations, and that local ports 8545 and 5173 are available.

Ten-minute local quick start

In the first terminal:

make demo-local

The command performs a scoped reset, starts a deterministic Anvil chain at http://127.0.0.1:8545, deploys and seeds V1, checks its exact state, exports public artifacts, and starts the console at http://127.0.0.1:5173/. It remains attached so Ctrl-C safely stops only the recorded project process groups.

In a second terminal:

DEMO_EXPECTED_STAGE=v1 make check-state
curl --fail http://127.0.0.1:5173/

The state check proves Alice has 900 mUSDC, Bob has 500 mUSDC, liabilities and reserves are both 1,400 mUSDC, and the contract version is 1. After Ctrl-C in the first terminal, run make reset-local to remove reproducible local state.

Architecture

Foundry scripts are the state-changing control plane; the browser never signs. MockUSDC holds no value. An ERC-1967 proxy keeps the bank address and storage stable while delegating calls to BankV1. The proxy itself holds token reserves and the internal ledger records liabilities. A confirmed public deployment manifest and generated ABI connect that on-chain system to a React/Vite console using viem and wagmi for read-only, block-consistent state and event display.

Command reference

• make doctor — read-only prerequisite, dependency, directory, and port checks.
• make setup — initialize pinned submodules and npm dependencies.
• make demo-local — run the complete attached V1 experience.
• make verify — run formatting, clean build, artifact checks, upgrade CLI check, Solidity tests, script tests, process tests, project scan, web lint/typecheck/tests, and production build.
• make check-state — validate and print the active local V1 state at http://127.0.0.1:8545.
• make reset-local — validate recorded process identity, stop only owned groups, and remove only known local artifacts.
• make deploy-v1 — lower-level guarded V1 deployment and manifest finalization.
• make seed-v1 — lower-level deterministic Act 1 deposits and withdrawal.
• make sync-artifacts — regenerate the ABI module and publish the confirmed active manifest.
• make sync-artifacts-check — test generation and prove generated ABIs are current.

Continue with the learning guide or rehearse from the presenter runbook.