@perspectivefi/addresses 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# @perspectivefi/addresses
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract address registry for Spectra. One shared list of every contract address, where each address has a **status**. Production only accepts addresses marked `safe`.
+
+It exists so that test contracts stop reaching prod. Addresses used to be copied by hand into every repo, and the copies drifted apart. Now there is one list, changes go through reviewed PRs, and CI checks them against the chain.
+
+The registry decides whether something _may_ go to prod, not whether it _is_ listed. Existing curation (whitelists, API catalog filters) still decides what users see.
+
+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)).
+
+## The four statuses
+
+| Status        | What it means                                     | Allowed on QA | Allowed in prod |
+| ------------- | ------------------------------------------------- | ------------- | --------------- |
+| `unsafe`      | Deployed, code not audited                        | yes           | no              |
+| `role-unsafe` | Audited, but the deployer still holds admin roles | yes           | no              |
+| `safe`        | Audited, and admin roles handed to the DAO        | yes           | yes             |
+| `blocked`     | Explicitly banned, e.g. a test pool               | yes           | no              |
+
+A contract moves up as it matures: `unsafe` -> `role-unsafe` -> `safe`. Each step is a small PR. For third-party contracts (Kyber, Pendle, Multicall3...) `safe` means "approved integration"; we don't audit them.
+
+## Data format
+
+One file per chain in `registry/`: `registry/<chainId>.json` (e.g. `1.json`, `8453.json`) or `registry/stellar.json`.
+
+```json
+{
+    "chain": 1,
+    "name": "Ethereum",
+    "governance": ["0x..."],
+    "entries": [
+        {
+            "key": "core.router",
+            "address": "0x...",
+            "kind": "contract",
+            "status": "unsafe",
+            "tags": ["core"],
+            "source": { "repo": "perspectivefi/...", "commit": "<40-hex sha>" },
+            "audit": "https://...",
+            "deployer": "0x...",
+            "inherit": true,
+            "notes": "..."
+        }
+    ]
+}
+```
+
+| Field        | Notes                                                                                            |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `governance` | DAO Safe / timelock addresses allowed to hold admin roles on this chain.                         |
+| `key`        | `<domain>.<name>`, lowercase, dots and dashes, unique per chain. This is what code asks for.     |
+| `address`    | EVM: EIP-55 checksummed. Stellar: `C...` 56-character contract id.                               |
+| `kind`       | `contract`, `factory`, `beacon`, `instance` or `external` (third party).                         |
+| `source`     | Repo and commit the deployed code came from. Optional for `unsafe` and `external`.               |
+| `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.                        |
+
+## 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`.
+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.
+
+## 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.                                                                                                                         |
+
+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.
+
+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.
+- The same address under two keys gives a warning, not a failure.
+- Every address has bytecode on-chain (Stellar is not checked yet).
+
+**Nightly**: the on-chain run repeats daily. If a `safe` entry no longer passes (roles changed after approval), it opens an issue labelled `registry-drift` (or comments on the open one). Nothing is downgraded automatically; a human decides.
+
+## Pools inherit from factories
+
+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.
+
+## Using it in an app
+
+```ts
+// QA, previews, API server: every address, whatever its status
+import { address, requireAddress, isProdSafe } from '@perspectivefi/addresses'
+
+// Production front-ends: only `safe` addresses exist in this bundle
+import { address, requireAddress } from '@perspectivefi/addresses/prod'
+
+address(1, 'otc.engine') // string | undefined  (undefined in prod unless safe: hide the feature)
+requireAddress(1, 'otc.engine') // throws "no address for key ... on chain 1" instead
+```
+
+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 |
+
+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.*`).
+
+### 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.
+
+```jsonc
+// package.json of the app
+"build": "next build && spectra-addresses check .next --allow token-list-addresses.json"
+```
+
+```
+spectra-addresses check <paths...> [--mode warn|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.
+
+### ESLint preset (no hardcoded addresses)
+
+`@perspectivefi/addresses/eslint` is a flat-config object (plain JS, no ESLint dependency). It errors on any string or template literal that is an EVM address (zero address allowed) or a Stellar contract id, and on `address()` / `requireAddress()` calls whose 2nd argument is not a string literal.
+
+```js
+// eslint.config.mjs
+import addresses from '@perspectivefi/addresses/eslint'
+
+export default [
+    // ...your other configs
+    addresses,
+    {
+        // tests and fixtures may contain raw addresses
+        files: ['**/*.test.{ts,tsx}', '**/__tests__/**', '**/fixtures/**', '**/mocks/**'],
+        rules: { 'no-restricted-syntax': 'off' },
+    },
+]
+```
+
+ESLint keeps one `no-restricted-syntax` setting per file, so the preset replaces yours. If you already use that rule, merge the selectors instead:
+
+```js
+import addresses from '@perspectivefi/addresses/eslint'
+
+rules: {
+    'no-restricted-syntax': ['error', ...addresses.restrictedSyntax, /* your own */],
+}
+```
+
+(`restrictedSyntax`, `hardcodedAddressRules` and `literalKeyRules` are available as properties of the default export.)
+
+## Slack announcements
+
+After each successful publish, the workflow posts the registry changes to Slack (#nt-deployment-addresses-announcements): new addresses grouped by chain and domain (with the chain's DAO Safe as admin), address changes, status changes and removals. Changes to tags, notes, source or audit only are not announced, and nothing is posted when nothing relevant changed. If more than 50 addresses are added at once, only a per-chain count is posted. Messages stay under about 3500 characters and are split between chains when needed.
+
+Setup: a Slack admin creates an incoming webhook for the channel, and it is stored as the repository secret `SLACK_ADDRESSES_WEBHOOK_URL`. If the secret is missing or Slack is down, the step prints a `::warning::` and the publish still succeeds.
+
+Preview locally, without posting anything:
+
+```
+npx tsx scripts/announce.ts --from HEAD~1 --to HEAD --dry-run
+```
+
+## Development
+
+```
+npm ci
+npm run generate    # registry/*.json -> src/generated/registry.ts (commit the result)
+npm run validate    # static checks on registry/*.json
+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 onchain [-- --report out.json]
+```
+
+`npm run onchain` uses `RPC_URL_<chainId>` when set, otherwise viem's default public RPC for the chain. Stellar entries are skipped for now ("not supported yet"). `ONCHAIN_CONCURRENCY` (default 4) limits parallel RPC work.
+
+Merging to `main` publishes a new version to npm (trusted publishing). The version is `<major>.<minor>` from `package.json` plus the workflow run number, and is never committed back (main is protected); bump major or minor in a PR.
+
+## Branch protection to apply on `main`
+
+Apply this in GitHub (Settings -> Rules / Branches) on `perspectivefi/spectra-addresses`:
+
+- Require a pull request before merging.
+- Required approvals: **2**.
+- **Dismiss stale approvals** when new commits are pushed.
+- Require status checks to pass: **`validate`** (the job in `.github/workflows/validate.yml`); require branches to be up to date.
+- **No bypass for anyone, including admins**: enable "Do not allow bypassing the above settings" / leave the bypass list empty, and turn on "Include administrators" if using classic branch protection.
+- Block force pushes and branch deletion.