@sm-lab/receipts 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @sm-lab/receipts
+
+Versioned, typed snapshots of Lido SM contract ABIs and deploy addresses. Replaces ad-hoc `deploy.json`
+files copied between repos and the `DEPLOY_JSON_PATH` env-var dance.
+
+```ts
+import { addresses, csModuleAbi, manifest } from '@sm-lab/receipts';
+
+addresses.hoodi.csm; // typed address string, autocompleted, compile-checked
+addresses.mainnet.csm;
+```
+
+## What's inside
+
+| Path                         | Contents                                                                      |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `src/abi/*.ts`               | One `as const` TypeScript module per contract (`csModuleAbi`, `vEBOAbi`, …)   |
+| `src/index.ts`               | Re-exports `addresses`, all ABI consts, and `manifest`                        |
+| `data/<chain>/<module>.json` | Per-(chain, module) address book                                              |
+| `data/manifest.json`         | Contracts `git-ref`(s) + per-ABI sha256 hashes + optional protocol provenance |
+| `scripts/refresh.ts`         | CLI that populates the above from a local contracts checkout                  |
+
+Public surface:
+
+```ts
+import { addresses, csModuleAbi, vEBOAbi, manifest } from '@sm-lab/receipts';
+//       ^^^^^^^^^ { hoodi: { csm, cm }, mainnet: { csm } }
+```
+
+Available chains/modules: `hoodi.csm`, `hoodi.cm`, `mainnet.csm`.
+`mainnet/cm` is intentionally absent — no curated mainnet deployment exists yet.
+
+## Address book shape
+
+Each `data/<chain>/<module>.json` is an **allowlist-curated, strictly-typed** set of addresses.
+Only proxy and gate contracts that SM recipes actually use are included. `DeployParams`, `*Impl`
+addresses, and linked library entries present in the upstream deploy config are intentionally
+dropped — committing them here would add noise without value and they change on every upgrade.
+
+> **Warning:** if you copy addresses from the raw upstream deploy config and notice extra keys
+> (`*Impl`, `DeployParams`, `libraries`, …), those are not in `@sm-lab/receipts` by design.
+
+Each book may also contain an optional `protocol` block with 6 addresses sourced directly
+from the on-chain `LidoLocator` contract (see [Protocol block](#protocol-block) below).
+
+## Protocol block
+
+The `protocol` field in each address book holds addresses resolved by calling the canonical
+getter methods on the deployed `LidoLocator` contract:
+
+| Key                       | LidoLocator getter          |
+| ------------------------- | --------------------------- |
+| `lido`                    | `lido()`                    |
+| `withdrawalVault`         | `withdrawalVault()`         |
+| `validatorsExitBusOracle` | `validatorsExitBusOracle()` |
+| `stakingRouter`           | `stakingRouter()`           |
+| `burner`                  | `burner()`                  |
+| `withdrawalQueue`         | `withdrawalQueue()`         |
+
+These are the addresses that `@sm-lab/recipes`'s `connect()` and the `@sm-lab/keys` tool
+need at runtime. When a `protocol` block is present in the committed data, both consumers
+prefer it over resolving the addresses at runtime; they fall back to their previous runtime
+resolution when it is absent.
+
+`manifest.protocolResolvedAt` records provenance for the last enrichment:
+
+```json
+{
+  "protocolResolvedAt": {
+    "hoodi/csm": { "chainId": 560048, "block": 1234567 },
+    "mainnet/csm": { "chainId": 1, "block": 654321 }
+  }
+}
+```
+
+**The `protocol` blocks are not populated in the initial committed data** — they require a live
+RPC. Run enrichment once an RPC is available (see [Enriching protocol addresses](#enriching-protocol-addresses)).
+
+## How ABIs and addresses are sourced
+
+No Solidity toolchain runs here. The `refresh` script only reads Forge's existing build output
+from a local checkout of `community-staking-module`:
+
+- **ABIs** — read from `out/<Contract>.sol/<Contract>.json` (`.abi` field). Several contracts are
+  interface-mapped so the ABI matches the actual public surface:
+
+  | Upstream contract | Artifact read    |
+  | ----------------- | ---------------- |
+  | `VEBO`            | `IVEBO`          |
+  | `StakingRouter`   | `IStakingRouter` |
+  | `Lido`            | `ILido`          |
+  | `LidoLocator`     | `ILidoLocator`   |
+  | all others        | same name        |
+
+- **Addresses** — read from `artifacts/<chain>[/curated]/deploy-<chain>.json`.
+
+The extracted snapshots are committed here. Consumers get reproducible, offline reads with no
+Forge dependency.
+
+## Enriching protocol addresses
+
+To populate (or refresh) the `protocol` block in the committed address data, pass `--rpc` (or
+set the matching env var) when running `refresh`:
+
+```bash
+# hoodi csm — explicit flag
+pnpm --filter @sm-lab/receipts refresh --chain hoodi --module csm --rpc <url>
+
+# hoodi csm — via env var
+HOODI_RPC_URL=<url> pnpm --filter @sm-lab/receipts refresh --chain hoodi --module csm
+
+# mainnet csm — via generic fallback
+ETH_RPC_URL=<url> pnpm --filter @sm-lab/receipts refresh --chain mainnet --module csm
+```
+
+RPC URL resolution order: `--rpc` flag → `<CHAIN>_RPC_URL` (uppercased chain name) → `ETH_RPC_URL`.
+
+**Without an RPC** the enrichment step is skipped entirely and any existing `protocol` block
+already in `data/<chain>/<module>.json` is carried forward unchanged (no data loss). This
+means you can run a plain ABI/address refresh without a live node and the protocol provenance
+remains intact.
+
+After enriching, commit the updated `data/` files together with the updated `manifest.json`
+(`protocolResolvedAt` is written there).
+
+## Refreshing snapshots
+
+Run per-target when a deployment or contract changes:
+
+```bash
+pnpm --filter @sm-lab/receipts refresh -- \
+  --chain <hoodi|mainnet> \
+  --module <csm|cm> \
+  [--contracts <path-to-community-staking-module>] \
+  [--config <relative-path-inside-contracts-repo>] \
+  [--force]
+```
+
+`--contracts` defaults to `../../../community-staking-module` — a sibling of the sm-lab repo root
+(relative paths resolve from the package root, `fixtures/receipts/`). `--force` bypasses
+the git-ref guard (see below).
+
+`--config` overrides which JSON file inside the contracts repo to read addresses from. Use it to
+point at the **latest** upgrade config per the contracts repo's `.env` `DEPLOY_CONFIG` value —
+CSM has been upgraded twice (v2, v3); proxy addresses are stable across upgrades but `*Impl`
+addresses change and new contracts are added. Current per-(chain, module) configs:
+
+| chain   | module | config path                                 | version |
+| ------- | ------ | ------------------------------------------- | ------- |
+| hoodi   | csm    | `artifacts/hoodi/upgrade-v3-hoodi.json`     | v3      |
+| hoodi   | cm     | `artifacts/hoodi/curated/deploy-hoodi.json` | —       |
+| mainnet | csm    | `artifacts/mainnet/deploy-mainnet.json`     | v2      |
+
+If `--config` is omitted, the default is `artifacts/<chain>/deploy-<chain>.json` (or
+`artifacts/<chain>/curated/deploy-<chain>.json` for cm). Only override when the authoritative
+config for that chain has moved to an upgrade file.
+
+After refreshing, commit the updated `data/` and `src/abi/` files together.
+
+## Drift guard
+
+The manifest records the `git-ref` from the contracts checkout at refresh time. On subsequent
+runs, the guard refuses to write addresses from a _different_ deployment's `git-ref` against the
+already-committed ABIs unless `--force` is passed. This prevents silently pairing addresses with
+ABIs from a mismatched contracts version.
+
+## Sibling SDK note
+
+`lido-csm-sdk` maintains its own ABI copy via its `/update-abis` script. After refreshing here,
+check whether the SDK needs a matching update — it applies an `Accounting.deposit*` overload
+filter that may need adjustment if the ABI changes.
+
+## Build
+
+```ts
+// tsdown.config.ts
+import { libConfig } from '@sm-lab/config/tsdown';
+export default libConfig();
+```

package/data/hoodi/cm.json

@@ -0,0 +1,34 @@
+{
+  "CuratedModule": "0x87EB69Ae51317405FD285efD2326a4a11f6173b9",
+  "Accounting": "0x7f7356D29aCd915F1934220956c3305808ceB235",
+  "FeeDistributor": "0x0ced6de191E2A15f7BBAf9E32307626C9f6BD0Cd",
+  "FeeOracle": "0x5D2F27000C80f6f7A03015Fd49dB7FEba3fBfa83",
+  "HashConsensus": "0x920883908A78c1554f682006a8aB32E62Be09F33",
+  "ParametersRegistry": "0xefb8e4091A75C4828826bf64595F392f87A07b37",
+  "ValidatorStrikes": "0x4c427Ec826F403339719C0FABfb3209e80939eA6",
+  "Verifier": "0x209190Ebc2Be80367a15d05e626784Eb94d6A880",
+  "Ejector": "0xfDbde2B3554B69C84e0f8d7daB68D390Ff0f4394",
+  "ExitPenalties": "0xad79e1d3B380cEb1a0e188fBAB91f85A446E9E54",
+  "MetaRegistry": "0x857289cCBFBc4C134Cc312022a104CD9b38d8AAE",
+  "CuratedGateFactory": "0x0e26d2cC3f0c2A17D2D784068cAAD34206B6804D",
+  "LidoLocator": "0xe2EF9536DAAAEBFf5b1c130957AB3E80056b06D8",
+  "CuratedGates": [
+    "0xF1862d120831eBE31f7202378Ff3Ae63A5658ae3",
+    "0x410A309dF81B782190188CDB3d215729cc6bC1f3",
+    "0xa5A604b172787e017b1b118F02fE54fC1D696519",
+    "0xE966874cDB6A4282ED75Cd10439e3799e5531a2D",
+    "0x5c063da03e3f21443716D75a2205EE16706e1153",
+    "0x1cD655Ac53CfE8269DE0DBfc0140B074623C4A6B",
+    "0x28518be9894C20135F280a9539617783b08a04c7"
+  ],
+  "ChainId": 560048,
+  "git-ref": "a6be775483e17d76718f8852428b5251a75c6429",
+  "protocol": {
+    "stakingRouter": "0xCc820558B39ee15C7C45B59390B503b83fb499A8",
+    "validatorsExitBusOracle": "0x8664d394C2B3278F26A1B44B967aEf99707eeAB2",
+    "lido": "0x3508A952176b3c15387C97BE809eaffB1982176a",
+    "withdrawalQueue": "0xfe56573178f1bcdf53F01A6E9977670dcBBD9186",
+    "burner": "0xb2c99cd38a2636a6281a849C8de938B3eF4A7C3D",
+    "withdrawalVault": "0x4473dCDDbf77679A643BdB654dbd86D67F8d32f2"
+  }
+}

package/data/hoodi/csm.json

@@ -0,0 +1,27 @@
+{
+  "CSModule": "0x79CEf36D84743222f37765204Bec41E92a93E59d",
+  "Accounting": "0xA54b90BA34C5f326BC1485054080994e38FB4C60",
+  "FeeDistributor": "0xaCd9820b0A2229a82dc1A0770307ce5522FF3582",
+  "FeeOracle": "0xe7314f561B2e72f9543F1004e741bab6Fc51028B",
+  "HashConsensus": "0x54f74a10e4397dDeF85C4854d9dfcA129D72C637",
+  "ParametersRegistry": "0xA4aD5236963f9Fe4229864712269D8d79B65C5Ad",
+  "ValidatorStrikes": "0x8fBA385C3c334D251eE413e79d4D3890db98693c",
+  "Verifier": "0x1773b2Ff99A030F6000554Cb8A5Ec93145650cbA",
+  "Ejector": "0xCAe028378d69D54dc8bF809e6C44CF751F997b80",
+  "ExitPenalties": "0xD259b31083Be841E5C85b2D481Cfc17C14276800",
+  "GateSeal": "0x725166f143DdcD9EC1b96dfb70f16E3f44968A65",
+  "LidoLocator": "0xe2EF9536DAAAEBFf5b1c130957AB3E80056b06D8",
+  "VettedGate": "0x10a254E724fe2b7f305F76f3F116a3969c53845f",
+  "PermissionlessGate": "0xd7bD8D2A9888D1414c770B35ACF55890B15de26a",
+  "IdentifiedDVTClusterGate": "0x887F8512F9998045f4b5993e6eaa6BCfE5F02A94",
+  "ChainId": 560048,
+  "git-ref": "a6be775483e17d76718f8852428b5251a75c6429",
+  "protocol": {
+    "stakingRouter": "0xCc820558B39ee15C7C45B59390B503b83fb499A8",
+    "validatorsExitBusOracle": "0x8664d394C2B3278F26A1B44B967aEf99707eeAB2",
+    "lido": "0x3508A952176b3c15387C97BE809eaffB1982176a",
+    "withdrawalQueue": "0xfe56573178f1bcdf53F01A6E9977670dcBBD9186",
+    "burner": "0xb2c99cd38a2636a6281a849C8de938B3eF4A7C3D",
+    "withdrawalVault": "0x4473dCDDbf77679A643BdB654dbd86D67F8d32f2"
+  }
+}

package/data/mainnet/csm.json

@@ -0,0 +1,26 @@
+{
+  "CSModule": "0xdA7dE2ECdDfccC6c3AF10108Db212ACBBf9EA83F",
+  "Accounting": "0x4d72BFF1BeaC69925F8Bd12526a39BAAb069e5Da",
+  "FeeDistributor": "0xD99CC66fEC647E68294C6477B40fC7E0F6F618D0",
+  "FeeOracle": "0x4D4074628678Bd302921c20573EEa1ed38DdF7FB",
+  "HashConsensus": "0x71093efF8D8599b5fA340D665Ad60fA7C80688e4",
+  "ParametersRegistry": "0x9D28ad303C90DF524BA960d7a2DAC56DcC31e428",
+  "ValidatorStrikes": "0xaa328816027F2D32B9F56d190BC9Fa4A5C07637f",
+  "Verifier": "0xdC5FE1782B6943f318E05230d688713a560063DC",
+  "Ejector": "0xc72b58aa02E0e98cF8A4a0E9Dce75e763800802C",
+  "ExitPenalties": "0x06cd61045f958A209a0f8D746e103eCc625f4193",
+  "GateSeal": "0xE1686C2E90eb41a48356c1cC7FaA17629af3ADB3",
+  "LidoLocator": "0xC1d0b3DE6792Bf6b4b37EccdcC24e45978Cfd2Eb",
+  "VettedGate": "0xB314D4A76C457c93150d308787939063F4Cc67E0",
+  "PermissionlessGate": "0xcF33a38111d0B1246A3F38a838fb41D626B454f0",
+  "ChainId": 1,
+  "git-ref": "cc8409a8ac21d7816d572658077dd6cf5f61507f",
+  "protocol": {
+    "stakingRouter": "0xFdDf38947aFB03C621C71b06C9C70bce73f12999",
+    "validatorsExitBusOracle": "0x0De4Ea0184c2ad0BacA7183356Aea5B8d5Bf5c6e",
+    "lido": "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84",
+    "withdrawalQueue": "0x889edC2eDab5f40e902b864aD4d7AdE8E412F9B1",
+    "burner": "0xE76c52750019b80B43E36DF30bf4060EB73F573a",
+    "withdrawalVault": "0xB9D7934878B5FB9610B3fE8A5e441e8fad7E293f"
+  }
+}

package/data/manifest.json

@@ -0,0 +1,53 @@
+{
+  "abiGitRef": "b8efc5695322f3b5064dec961888806633ad2419",
+  "abiHashes": {
+    "CSModule": "9cad8e9a5e8330e9ec0e4b045713a6bfa8b63eeebfe15cea5b5745a2c6c661a5",
+    "CuratedModule": "f5460a39f02e1221b515deb642ba36783758dfb5e59e703f407b034a735846b5",
+    "Accounting": "26039df3e117838bb86c035b106038cb746514e440007fc10683bada8b2117ce",
+    "FeeDistributor": "3631179853889acf2b35ecc727daa0289631442cbb1979f8a9e7eec3bd25eee1",
+    "FeeOracle": "bea2188e38e62f4f32efec379b2b4886b3a810dd2da726f629c8910dc157a401",
+    "HashConsensus": "c56bd6734d1de5c843d8af3eef132f2baf65157937d3fa640471407317403731",
+    "VettedGate": "fbd27dfaf50549ad081740998f54b199d694e642d97db285eaf9f3e6ac67ac5c",
+    "CuratedGate": "64cbffb05557fc80711fd310760f121c01f4a4920a49361c5c8c13f9cbcfc02f",
+    "PermissionlessGate": "3d2f6e54999af1bb8a14b284f10e7a89f67e4e0b41ed8a85c8991a71078eaff9",
+    "ParametersRegistry": "8c8e9ec98221320f46c4593bbbcf07fda252d8291894c43e5ee9f1bbc490000c",
+    "MetaRegistry": "8aa946bab44d8dfccf38a381c541628d8ab59d3831e5168d3f3534b0b2dbb6f1",
+    "Verifier": "b86b0ba3eda936e51026043652c33197d73a77b708dfc67b41e605e964bcdcee",
+    "VEBO": "7999bdb1db0520c141efdcc3be6e5e185ffefc74b928948feae9f209bec1b6df",
+    "StakingRouter": "5c167acfa7b7afbd18323bef94936c1e41b96d2a71a1562b08a8da6f6b2639d4",
+    "Lido": "5d0b9f1b8017e723505fdc8ade1516b2556891527c05bda13cccb4369b46e700",
+    "LidoLocator": "352bf71565e2f635d6a86e59ea1f5921c1f6bc7a04d76caadcbd475a51e3b9e3"
+  },
+  "snapshots": [
+    {
+      "chain": "hoodi",
+      "module": "cm",
+      "gitRef": "a6be775483e17d76718f8852428b5251a75c6429"
+    },
+    {
+      "chain": "hoodi",
+      "module": "csm",
+      "gitRef": "a6be775483e17d76718f8852428b5251a75c6429"
+    },
+    {
+      "chain": "mainnet",
+      "module": "csm",
+      "gitRef": "cc8409a8ac21d7816d572658077dd6cf5f61507f"
+    }
+  ],
+  "protocolResolvedAt": {
+    "hoodi/csm": {
+      "chainId": 560048,
+      "block": 3113497
+    },
+    "hoodi/cm": {
+      "chainId": 560048,
+      "block": 3113499
+    },
+    "mainnet/csm": {
+      "chainId": 1,
+      "block": 25423656
+    }
+  },
+  "generatedAt": "2026-06-29T13:35:19.356Z"
+}