88 lines
5.4 KiB
Markdown
88 lines
5.4 KiB
Markdown
# Presenter Runbook: Prepared V1 and Live UUPS Upgrade
|
|
|
|
## Preflight and rehearsal
|
|
|
|
Rehearse once from a clean disposable branch created at the `demo-start` tag. Allow 25 minutes: 3 minutes for preflight, 5 for Act 1, 10 for the Codex change and verification, 4 for Act 3, and 3 for questions. Keep two terminals visible and open the browser only after Vite reports ready.
|
|
|
|
Before the audience arrives:
|
|
|
|
```bash
|
|
make setup
|
|
make reset-local
|
|
make doctor
|
|
make verify
|
|
git diff --check
|
|
git status --short
|
|
```
|
|
|
|
The doctor must show Foundry `1.7.1`, Node `24.18.0`, npm `11.17.0`, initialized dependencies, writable runtime paths, and free ports `8545`/`5173`. Verification must exit `0`. No upgrade or transfer command runs until `make verify` passes.
|
|
|
|
## The three-act story
|
|
|
|
### Act 1 — Prepared V1 establishes trust
|
|
|
|
First terminal:
|
|
|
|
```bash
|
|
make demo-local
|
|
```
|
|
|
|
Second terminal:
|
|
|
|
```bash
|
|
DEMO_EXPECTED_STAGE=v1 make check-state
|
|
curl --fail http://127.0.0.1:5173/
|
|
```
|
|
|
|
Open `http://127.0.0.1:5173/`; Anvil is at `http://127.0.0.1:8545`. Call out that every browser read targets the proxy, while the distinct implementation address is shown only to teach delegation. The exact expected state is Alice `900 mUSDC`, Bob `500 mUSDC`, liabilities `1,400 mUSDC`, reserves `1,400 mUSDC`, surplus `0`, and version `1`. Point to deposit, withdrawal, and upgrade/ownership events, then state that the browser is read-only.
|
|
|
|
Explain the initial flow: scripts minted 2,000 mUSDC to Alice and 1,000 to Bob; Alice deposited 1,000 and withdrew 100; Bob deposited 500. The stable proxy holds reserves and storage. Implementation code runs against that storage with `delegatecall`.
|
|
|
|
### Act 2 — Codex changes the system live
|
|
|
|
Give Codex this approved prompt verbatim:
|
|
|
|
> Add `BankV2` with customer-to-customer internal transfers. Preserve the UUPS storage layout and all V1 behavior. Add unit, fuzz, invariant, and upgrade-regression tests; an owner upgrade script; a scripted Alice-to-Bob transfer; exported ABI support; and the read-only console updates needed to show V2 and its transfer event. Explain each security decision. Do not perform an upgrade until all verification passes.
|
|
|
|
Ask Codex to show the diff and explain storage compatibility, authorization, conservation, error paths, and why the browser remains read-only. The expected prepared change adds transfer-aware source, tests, scripts, ABI output, and console rendering without changing V1 storage. Run:
|
|
|
|
```bash
|
|
make verify
|
|
```
|
|
|
|
If any gate fails, stop and let Codex diagnose it. Do not run an upgrade merely because a partial test command passed.
|
|
|
|
### Act 3 — V2 proves continuity
|
|
|
|
After Codex has implemented these targets and the full gate has passed:
|
|
|
|
```bash
|
|
make upgrade-v2
|
|
make demo-transfer
|
|
make check-state
|
|
```
|
|
|
|
The expected result is the same proxy and a new implementation, version `2`, Alice `650 mUSDC`, Bob `750 mUSDC`, liabilities `1,400 mUSDC`, reserves `1,400 mUSDC`, and a decoded 250 mUSDC internal transfer event. No ERC-20 transfer should accompany the ledger transfer. Refresh only if the console has not observed the next block; otherwise let its live status prove the change.
|
|
|
|
## Recovery without broad cleanup
|
|
|
|
- **Occupied port:** `make demo-local` refuses to claim either port. Use `curl http://127.0.0.1:8545` and `curl http://127.0.0.1:5173/` plus your operating system's process inspection to identify the external owner. Stop it yourself only after proving ownership; the project never uses broad process matching.
|
|
- **Recorded stale process:** run `make reset-local`. It validates numeric PID, process group, command signature, and Linux start tick before signaling. A mismatched live process is preserved and reset exits nonzero.
|
|
- **Stale console:** confirm `DEMO_EXPECTED_STAGE=v1 make check-state`, inspect `.demo/vite.log`, and use `curl --fail http://127.0.0.1:5173/`. The console labels stale/disconnected state and preserves the last good snapshot rather than inventing zeros.
|
|
- **Failed test or live edit:** do not upgrade. Save the diff for review, continue diagnosis on the disposable live branch, or start a new disposable branch from `demo-start`; never overwrite unrelated work. The prepared V1 remains the successful ending if time expires.
|
|
- **Unexpected child exit:** the attached launcher stops its other validated group. Inspect `.demo/anvil.log` and `.demo/vite.log`, then run `make reset-local` and restart.
|
|
|
|
End the local session with Ctrl-C in the attached terminal, then `make reset-local`. The optional public encore is outside this prepared V1 run: local success does not depend on Base Sepolia, a faucet, an explorer, a wallet, or any external RPC.
|
|
|
|
## Closing trust disclosure checklist
|
|
|
|
Read these points while the matching console panel is visible:
|
|
|
|
- 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.
|
|
|
|
Codex supplies the cross-stack implementation, tests, orchestration, and explanation. OpenZeppelin supplies reviewed contract primitives and upgrade validation; Foundry supplies compilation, tests, scripts, and the local chain. None of those tools turns this teaching artifact into an audited or regulated custody product.
|