@perspectivefi/addresses 0.1.3 → 0.2.4

package/README.md

@@ -8,6 +8,8 @@ The registry decides whether something _may_ go to prod, not whether it _is_ lis
 
 Token addresses stay in `token-list`. Pools, PTs and vaults are not listed one by one (see [Pools inherit from factories](#pools-inherit-from-factories)).
 
+What `safe` means and who may approve it: [POLICY.md](./POLICY.md). What this package does and does not guarantee: [Guarantees](#guarantees).
+
 ## The four statuses
 
 | Status        | What it means                                     | Allowed on QA | Allowed in prod |
@@ -39,8 +41,15 @@ One file per chain in `registry/`: `registry/<chainId>.json` (e.g. `1.json`, `84
             "audit": "https://...",
             "deployer": "0x...",
             "inherit": true,
+            "approval": { "basis": "audit", "pr": 12, "note": "..." },
             "notes": "..."
         }
+    ],
+    "denylist": [
+        {
+            "address": "0x...",
+            "reason": "test vault removed from the registry; must never be listed in prod"
+        }
     ]
 }
 ```
@@ -55,24 +64,41 @@ One file per chain in `registry/`: `registry/<chainId>.json` (e.g. `1.json`, `84
 | `audit`      | Link to the audit report. Optional for `unsafe` and `external`.                                  |
 | `deployer`   | Optional deployer EOA. The nightly and PR role check make sure it holds no admin role on `safe`. |
 | `inherit`    | Only on `factory` / `beacon`: instances created by it inherit its status.                        |
+| `approval`   | `{ basis, pr, note? }`. **Required on every `safe` entry**, see [POLICY.md](./POLICY.md).        |
+| `denylist`   | Per chain file, optional: `{ address, reason }` items. These addresses are never acceptable.     |
+
+`approval.basis` is one of `audit`, `prod-baseline`, `external-integration`, `governance`; `approval.pr` is the registry PR that approved the entry. `approval` is not part of the runtime data, only of `dist/registry.json`.
+
+### Denylist
+
+A `blocked` entry must never simply be deleted: once it is gone the address is just "unknown" (or, behind a `safe` factory, looks inherited-safe). Move it to the chain's `denylist` instead. A denylisted address:
+
+- is `blocked` for `statusOf(chain, address)` even without an entry, and `isDenied(chain, address)` is `true`;
+- is shipped in both the full and the `/prod` datasets, so consumers can still refuse it;
+- fails the build check wherever it appears, on that chain;
+- cannot also be an entry (validation error); addresses must be valid, unique and have a non-empty `reason`.
+
+CI enforces this: `npm run validate -- --base origin/main` fails when a `blocked` entry of the base branch has disappeared and is not in the denylist.
 
 ## How to add an address
 
-1. Add an entry to `registry/<chain>.json` with status `unsafe`. Use the checksummed address. If the chain has no file yet, create it (name = chain id) and fill `governance`.
+1. Add an entry to `registry/<chain>.json` with status `unsafe` (never straight to `safe`: approval is a separate PR, see [POLICY.md](./POLICY.md)). Use the checksummed address. If the chain has no file yet, create it (name = chain id) and fill `governance`.
 2. Run `npm run validate`, and `npm run onchain` if you want to see the chain check locally.
 3. Open a PR. CI runs the checks below; you need 2 approvals.
 
-Run `npm run generate` after editing a registry file and commit `src/generated/registry.ts` as well. CI fails if it is stale.
+Run `npm run generate` after editing a registry file and commit the files in `src/generated/` as well. CI fails if it is stale.
 
 ## How to promote a status
 
 Each step is a PR that changes one `status` line (plus the fields it needs).
 
-| Change                    | What you add                                        | What CI checks                                                                                                                                     |
-| ------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `unsafe` -> `role-unsafe` | `source.repo` + 40-hex `source.commit`, `audit` URL | The fields exist and are well-formed. The contract has bytecode on-chain.                                                                          |
-| `role-unsafe` -> `safe`   | Hand admin roles to the DAO, then change status     | Everything above, plus the **on-chain role check**: every owner / admin found is in `governance`, and the `deployer` (if set) holds no admin role. |
-| anything -> `blocked`     | A reason in `notes`                                 | The contract has bytecode.                                                                                                                         |
+| Change                    | What you add                                                    | What CI checks                                                                                                                                                                                   |
+| ------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `unsafe` -> `role-unsafe` | `source.repo` + 40-hex `source.commit`, `audit` URL             | The fields exist and are well-formed. The contract has bytecode on-chain.                                                                                                                        |
+| `role-unsafe` -> `safe`   | Hand admin roles to the DAO, then change status, add `approval` | Everything above, plus `approval.pr` equal to this PR's number, plus the **on-chain role check**: every owner / admin found is in `governance`, and the `deployer` (if set) holds no admin role. |
+| anything -> `blocked`     | A reason in `notes`                                             | The contract has bytecode.                                                                                                                                                                       |
+
+`source` and `audit` are required for `role-unsafe`, and for `safe` unless the entry's `approval.basis` is something other than `audit` (`prod-baseline`, `external-integration`, `governance`; the evidence is then in the PR, see [POLICY.md](./POLICY.md)).
 
 The on-chain role check reads `owner()`, the EIP-1967 admin slot (and the owner of that admin contract if it is one), and `authority()` for OpenZeppelin AccessManager (`hasRole(0, governance[i])` must be true for at least one governance address, and `hasRole(0, deployer)` must be false). RPC failures on a `safe` entry fail the run.
 
@@ -81,6 +107,8 @@ Every other check, on every PR:
 - JSON shape and types, `chain` matches the file name, keys are well-formed and unique per chain.
 - EVM addresses are EIP-55 checksummed, Stellar ids are valid, `governance` addresses are valid.
 - `inherit` only on factories / beacons.
+- `approval` is well-formed and present on every `safe` entry; in a PR, an entry that is newly `safe` must carry this PR's number in `approval.pr`.
+- `denylist` is valid (see above) and no blocked entry was deleted compared with the base branch.
 - The same address under two keys gives a warning, not a failure.
 - Every address has bytecode on-chain (Stellar is not checked yet).
 
@@ -90,7 +118,7 @@ Every other check, on every PR:
 
 There are hundreds of pools, PTs and vaults and new ones appear all the time, so they are not listed. They inherit the status of the factory that created them: a pool made by a `safe` factory is `safe`. Mark a factory or beacon with `"inherit": true` to make that explicit.
 
-If someone creates a test pool through a prod factory, add that single pool to the registry as `blocked` (`kind: "instance"`). A `blocked` entry always wins over the factory's status.
+If someone creates a test pool through a prod factory, add that single pool to the registry as `blocked` (`kind: "instance"`). A `blocked` entry, and a denylisted address, always win over the factory's status. Runtime data carries `inherit: true` on the factories / beacons that opted in; the package only exposes the data, consumers decide how to verify provenance.
 
 ## Using it in an app
 
@@ -107,23 +135,39 @@ requireAddress(1, 'otc.engine') // throws "no address for key ... on chain 1" in
 
 Pick the entry point at build time (alias `@perspectivefi/addresses` to `.../prod` in production builds). Both have the same API:
 
-| Function                      | Returns                                                |
-| ----------------------------- | ------------------------------------------------------ |
-| `address(chain, key)`         | the address or `undefined`                             |
-| `requireAddress(chain, key)`  | the address or throws an error naming chain and key    |
-| `entry(chain, key)`           | the full `Entry` or `undefined`                        |
-| `findByAddress(chain, addr)`  | the `Entry` (EVM compare is case-insensitive)          |
-| `statusOf(chain, addr)`       | `Status` or `undefined`                                |
-| `isProdSafe(chain, addr)`     | `true` only for `safe`                                 |
-| `entries(chain?)`, `chains()` | all entries (optionally one chain), the chains present |
+| Function                      | Returns                                                        |
+| ----------------------------- | -------------------------------------------------------------- |
+| `address(chain, key)`         | the address or `undefined`                                     |
+| `requireAddress(chain, key)`  | the address or throws an error naming chain and key            |
+| `entry(chain, key)`           | the full `Entry` or `undefined`                                |
+| `findByAddress(chain, addr)`  | the `Entry` (EVM compare is case-insensitive)                  |
+| `statusOf(chain, addr)`       | `Status`, `blocked` for a denylisted address, else `undefined` |
+| `isDenied(chain, addr)`       | `true` when the address is on that chain's denylist            |
+| `isProdSafe(chain, addr)`     | `true` only for `safe`                                         |
+| `entries(chain?)`, `chains()` | all entries (optionally one chain), the chains present         |
 
 Types: `Entry`, `Status`, `Kind`, `ChainRef` (chain ids + `'stellar'`), `AddressKey` (every key in the registry). `chain` also accepts a plain `number`, e.g. a runtime chain id.
 
-The package has zero runtime dependencies. The `/prod` bundle contains no non-safe address at all (a test checks `dist/prod.*`).
+The package has zero runtime dependencies. The `/prod` bundle contains no non-safe entry at all (a test checks `dist/prod.*`); the only non-safe addresses in it are the denylisted ones, which are there so they can be refused.
+
+### Per-key exports (tree-shakeable)
+
+For front-ends, import only the keys you need. Unused keys are dropped by the bundler, so only those addresses end up in the bundle:
+
+```ts
+import { coreRouter } from '@perspectivefi/addresses/prod/keys' // safe addresses only (production)
+import { coreRouter } from '@perspectivefi/addresses/keys' // every status (QA, previews)
+
+coreRouter[1] // string | undefined, a frozen { chain -> address } record
+```
+
+One export per registry key, named in camelCase: `core.router` -> `coreRouter`, `external.zodiac.roles-mastercopy-v2.1.0` -> `externalZodiacRolesMastercopyV2_1_0` (a segment that starts with a digit is joined with `_`). Generation fails if two keys would get the same name. In `/prod/keys` a key with no safe chain is an empty frozen object, so imports never break; check the chain you need and hide the feature when it is missing.
+
+Each value is emitted as `JSON.parse("{\"$spectraAddresses\":1,\"key\":\"core.router\",\"chains\":{...}}")`. Minifiers never rewrite string literals, so the release check finds these blocks verbatim in the built bundle and checks every `(chain, address)` pair. The package declares `sideEffects: false`.
 
 ### Release check (CLI)
 
-`spectra-addresses check` scans a finished build for contract addresses and fails the release if one is not `safe` in the registry, or not in the registry at all.
+`spectra-addresses check` scans a finished build and fails the release when it finds an address that is not approved for the chain it is used on.
 
 ```jsonc
 // package.json of the app
@@ -131,16 +175,19 @@ The package has zero runtime dependencies. The `/prod` bundle contains no non-sa
 ```
 
 ```
-spectra-addresses check <paths...> [--mode warn|enforce] [--allow <json file>]... [--registry <url|file>] [--offline]
+spectra-addresses check <paths...> [--mode off|enforce] [--allow <json file>]... [--registry <url|file>] [--offline]
 ```
 
-- **Mode**: `--mode`, else env `ADDRESS_GATE`, else `warn`. In `warn` it only prints. In `enforce` it exits 1 on violations, but only when `VERCEL_ENV` is unset or `production`; in a Vercel preview build `enforce` is downgraded to `warn`. The effective mode is printed.
-- **Latest registry**: the check does not use the registry version your lockfile pins. It fetches `https://cdn.jsdelivr.net/npm/@perspectivefi/addresses@latest/dist/registry.json` (10 second timeout), so an address marked `blocked` today stops today's release even when the app still pins an older package. Override the source with `--registry <url-or-file>` or env `ADDRESS_REGISTRY_URL` (the flag wins). The output says which dataset was used.
-- **Fallback**: if the fetch or the JSON shape check fails, the check falls back to the dataset bundled in the installed package and prints a `WARNING` that names the bundled version. This also applies in `enforce` mode: a jsDelivr outage does not fail your build, but the run is only as fresh as the installed version. `--offline` skips the fetch and uses the bundled dataset on purpose.
-- Scans files recursively for EVM addresses and Stellar contract ids (skips `*.map`, `cache` and `node_modules` dirs, and binary files over 5 MB).
-- Each unique address is checked against every chain: `safe` anywhere is ok; listed but not safe is a violation (shows key, chain, status); not listed is a violation (`unknown`).
-- Always allowed: the zero address and `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. `--allow` takes JSON files with an array of address strings (or objects with an `address` field). Use it for token-list addresses.
-- Exit codes: `0` ok / warn, `1` violations in effective `enforce`, `2` bad usage.
+- **Mode**: `--mode`, else env `ADDRESS_GATE`. There are two modes. `off` prints the full report and always exits 0. `enforce` exits 1 on any violation. If `VERCEL_ENV=production` and the mode is unset or invalid, the check exits 1 ("ADDRESS_GATE must be set to off or enforce in production"), so a missing setting can never silently disable protection. Outside production an unset or invalid mode means `off`. `enforce` is not downgraded on preview builds.
+- **Tagged blocks first**: every `$spectraAddresses` block (from `/keys`, `/prod/keys`, the runtime datasets and the runtime denylist) is found, also when its JSON is escaped inside a JS string. For each `(chain, address)` in a block, the exact entry for **that chain** must be `safe` in the latest registry and not denylisted. The report names key and chain. A block that cannot be parsed, or carries anything besides the fields we emit, is a violation. The runtime denylist block is accepted only for addresses the registry itself denylists.
+- **Then bare addresses**: the blocks are cut out and the rest of the file is scanned for EVM addresses and Stellar contract ids. A bare address passes only if it is on an `--allow` list, **or** every registry entry with that address (on any chain) is `safe` and it is denylisted on no chain. Otherwise it is a violation, and the report says which chain made it fail (`blocked`, `unsafe`, `denylisted`, or `not in registry`). A denylisted address fails even if it is on an `--allow` list.
+- **Latest registry**: the check does not use the version your lockfile pins. It fetches the latest `dist/registry.json` from jsDelivr (`https://cdn.jsdelivr.net/npm/@perspectivefi/addresses@latest/dist/registry.json`), then from unpkg (`https://unpkg.com/@perspectivefi/addresses@latest/dist/registry.json`), 10 second timeout each. `--registry <url-or-file>` or env `ADDRESS_REGISTRY_URL` replaces both (the flag wins). The output says which dataset was used.
+- **If no source loads**: in `off` the check prints a `WARNING` and uses the dataset bundled in the installed package. In `enforce` it exits 1 ("cannot verify against the latest registry"). `--offline` skips the fetch and uses the bundled dataset on purpose; in `enforce` it prints a loud warning that the run is only as fresh as the installed version.
+- Scans files recursively (skips `*.map`, `cache` and `node_modules` dirs, and binary files over 5 MB).
+- Always allowed: the zero address and `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. `--allow` takes JSON files with an array of address strings (or objects with an `address` field). Use it for token-list addresses. It applies to bare addresses only.
+- Exit codes: `0` ok / off, `1` violations in `enforce`, an unset mode in production, or an unverifiable registry in `enforce`, `2` bad usage.
+
+`dist/registry.json` is `{ "entries": [...], "denylist": [...] }` (every field, every status). Versions before 0.2.0 published a bare array; their CLI cannot read the new shape and falls back to its bundled data, so upgrade the CLI together with the first release that uses this one.
 
 ### ESLint preset (no hardcoded addresses)
 
@@ -173,6 +220,26 @@ rules: {
 
 (`restrictedSyntax`, `hardcodedAddressRules` and `literalKeyRules` are available as properties of the default export.)
 
+## Guarantees
+
+What this package guarantees, and what it does not.
+
+**Covered**
+
+- **Lookups are per chain.** `address`, `statusOf`, `findByAddress`, `isDenied` and the per-key records never mix chains. An address approved on one chain says nothing about the same address on another.
+- **Production build scan.** `spectra-addresses check` runs against the latest published registry (not the pinned one) and fails the release when a built bundle contains an address that is not `safe` on its chain: tagged per-key blocks are checked per chain, and any other address-looking literal (the "bare-address rule") must be `safe` on every chain it is listed on, denylisted nowhere, or be on an `--allow` list. Unknown addresses fail. With the mode set to `enforce` this blocks the release; in production the mode must be set explicitly.
+- **Removed means refused, not forgotten.** Deleting a blocked entry requires moving it to the denylist, and the denylist is in the prod dataset too.
+- **Every `safe` entry has an approval record** (basis and registry PR), and in CI a newly safe entry must be approved by the PR that introduces it.
+- **Nightly on-chain check** that `safe` entries still have their roles with the DAO. It opens an issue; nothing is downgraded automatically.
+
+**Not covered here**
+
+- **The API runtime gate lives in the consumers.** This package supplies data (`statusOf`, `isDenied`, `inherit`, entries); the API decides what to serve, and how to verify that a pool or vault really comes from an approved factory.
+- **No RPC in consumers.** The package never calls a chain. On-chain checks (bytecode, roles) run only in this repo's CI and nightly job.
+- **App addresses change only with a release.** A frontend bundle contains the addresses it was built with. A status change in the registry reaches an app through its next release, where the build scan checks it against the latest registry; it does not change a bundle that is already deployed. Likewise the API only sees registry changes when it is rebuilt with a newer package.
+- **Addresses assembled at runtime** (concatenated strings, fetched from elsewhere) cannot be found by the scan. Tokens come from `token-list`.
+- **The runtime datasets are chain-aware too.** `/prod` (and the full dataset) is emitted as a tagged block of `(chain, key, address)` entries, so a prod build that uses `address(1, 'core.access-manager')` is judged on chain 1 only, even if the same address is a different, unapproved contract on another chain.
+
 ## Slack announcements
 
 After each successful publish, the workflow posts the registry changes to Slack (#nt-deployment-addresses-announcements), most important first:
@@ -196,11 +263,12 @@ npx tsx scripts/announce.ts --from HEAD~1 --to HEAD --dry-run
 
 ```
 npm ci
-npm run generate    # registry/*.json -> src/generated/registry.ts (commit the result)
+npm run generate    # registry/*.json -> src/generated/{registry,keys,keys-prod}.ts (commit the result)
 npm run validate    # static checks on registry/*.json
+npm run validate -- --base origin/main   # also compare with the base branch (CI does this on PRs)
 npm run typecheck
 npm test            # generates, builds, then runs vitest
-npm run build       # dist/index, dist/prod, dist/cli.js, dist/registry.json
+npm run build       # dist/index, dist/prod, dist/keys, dist/prod-keys, dist/cli.js, dist/registry.json
 npm run onchain [-- --report out.json]
 ```