55 lines
3.9 KiB
Markdown
55 lines
3.9 KiB
Markdown
# 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](https://git-scm.com/downloads), [Foundry](https://getfoundry.sh), [Node](https://nodejs.org/en/download), [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), [Bash](https://www.gnu.org/software/bash/), [Make](https://www.gnu.org/software/make/), and [curl](https://curl.se/download.html).
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](docs/LEARNING_GUIDE.md) or rehearse from the [presenter runbook](docs/PRESENTER_RUNBOOK.md).
|