feat(deployments): generate the subgraph manifest from the deployment record

.prettierignore

@@ -12,3 +12,5 @@ stellar
 **/subgraph/build
 **/subgraph/tests/.bin
 **/subgraph/tests/.latest.json
+# Generated from subgraph.template.yaml by `npm run manifest`.
+**/subgraph/subgraph.yaml

deployments/README.md

@@ -79,7 +79,7 @@ must carry a source commit.
 
 | File                                                             | Checked                                                                       | Generated by `build` |
 | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------- |
-| `evm/subgraph/subgraph.yaml`                                     | address and `startBlock` per data source; undeployed contracts stay `0x…dead` | no                   |
+| `evm/subgraph/subgraph.template.yaml`                            | each `source.abi` is an EVM contract; no `network`, `address` or `startBlock` | no                   |
 | `evm/subgraph/<network>/instant-config.json`                     | address, chain, `startBlock`                                                  | yes                  |
 | `evm/subgraph/abis/*.json`, `evm/subgraph/<network>/abis/*.json` | canonical ABI hash                                                            | no                   |
 | `evm/hardhat.config.ts`                                          | `chainId` of the matching network                                             | no                   |
@@ -98,7 +98,8 @@ npm ci
 ```
 
 - **EVM**: `evm/scripts/deploy.ts` records automatically on any non-local network, using
-  each contract's deployment receipt. Then update `evm/subgraph/subgraph.yaml` to match.
+  each contract's deployment receipt. Then regenerate the subgraph manifest from the
+  record (see [Subgraph manifest](#subgraph-manifest)).
 - **Stellar**: `stellar/deploy.sh` records automatically, before `init`.
 - **Solana, CKB**, or anything deployed by hand: record from the chain.
 
@@ -121,11 +122,29 @@ record for that network, and runs `build`. `--rpc` is only used for queries, so
 may contain an API key; only `--public-rpc` is written to the record. Commit the
 record, `manifest.json` and every file `build` regenerated.
 
+## Subgraph manifest
+
+`evm/subgraph/subgraph.yaml` is not checked in. It is generated for one network from
+`evm/subgraph/subgraph.template.yaml` and `deployments/evm/<network>.json`:
+
+```bash
+npm run subgraph -- --network horizen-testnet
+```
+
+Each data source gets `network`, `source.address` and `source.startBlock` from the
+contract its `source.abi` names. If any contract is not recorded, has no start block
+(or start block 0), or has the placeholder address `0x…dead`, nothing is written and
+every such contract is listed. `npm run subgraph -- --check` fails unless the
+existing `subgraph.yaml` is exactly what `--network` would write now for the network
+it names; `npm run deploy` and `npm run deploy-local` in `evm/subgraph` run it before
+`graph deploy`.
+
 ## Commands
 
-| Command          | What it does                                                                                    |
-| ---------------- | ----------------------------------------------------------------------------------------------- |
-| `npm run build`  | Validate records, write `manifest.json`, regenerate the generated consumers.                    |
-| `npm run check`  | Offline validation of records, manifest and consumers. Runs in CI.                              |
-| `npm run verify` | Re-read every deployment from its chain and compare IDs, heights and hashes. Runs weekly in CI. |
-| `npm test`       | Unit and end-to-end tests for the tool.                                                         |
+| Command            | What it does                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `npm run build`    | Validate records, write `manifest.json`, regenerate the generated consumers.                    |
+| `npm run check`    | Offline validation of records, manifest and consumers. Runs in CI.                              |
+| `npm run verify`   | Re-read every deployment from its chain and compare IDs, heights and hashes. Runs weekly in CI. |
+| `npm run subgraph` | Write `evm/subgraph/subgraph.yaml` for `--network <slug>`; `--check` verifies it.               |
+| `npm test`         | Unit and end-to-end tests for the tool.                                                         |

evm/README.md

@@ -78,20 +78,22 @@ slither . --config-file slither.config.json --fail-medium
 ## Subgraph
 
 `subgraph/` indexes all five contracts: event handlers for Announcer, Registry,
-and Names, plus call handlers for Sender and Withdrawer. The manifest targets
-Horizen Testnet; fill in the three `0x…dead` placeholder addresses (Names,
-Sender, Withdrawer) from `scripts/deploy.ts` output before deploying.
+and Names, plus call handlers for Sender and Withdrawer. The checked-in
+`subgraph.template.yaml` has no network, addresses or start blocks;
+`npm run manifest` generates `subgraph.yaml` from `deployments/evm/<network>.json`
+and refuses if a contract or start block is not recorded (see `subgraph/README.md`).
 
 ```bash
 cd subgraph
 npm ci
-npm run codegen   # graph codegen
-npm run build     # graph build
+npm run codegen   # graph codegen, from the template
+npm run build     # graph build, from the template
 ```
 
 Deploy to a local graph-node:
 
 ```bash
+npm run manifest -- --network <network>
 npm run create-local
 npm run deploy-local
 ```
@@ -103,8 +105,10 @@ npx hardhat run scripts/deploy.ts --network <network>
 ```
 
 The script deploys Announcer, Registry, Sender (pointing at the Announcer),
-Names, and Withdrawer, logging each address. Point the subgraph at the deployed
-addresses and redeploy.
+Names, and Withdrawer, logging each address. On any non-local network it records
+them in `deployments/evm/<network>.json`. Regenerate the subgraph manifest from
+that record (`npm run manifest -- --network <network>` in `subgraph/`) and
+redeploy.
 
 ## CI
 

evm/scripts/deploy.ts

@@ -37,6 +37,7 @@ async function main() {
   // runtime bytecode, then rebuilds deployments/manifest.json and the subgraph
   // instant config. See deployments/README.md.
   const network = hre.network.name;
+  const slug = network.replace(/_/g, '-');
   if (network === 'hardhat' || network === 'localhost') {
     console.log('\nLocal network: not recording to deployments/.');
   } else {
@@ -51,7 +52,7 @@ async function main() {
         'record',
         'evm',
         '--network',
-        network.replace(/_/g, '-'),
+        slug,
         '--rpc',
         hre.network.config.url,
         '--recorded-by',
@@ -64,7 +65,9 @@ async function main() {
       ],
       { cwd: path.join(__dirname, '../../scripts/deployment-manifest'), stdio: 'inherit' },
     );
-    console.log('\nUpdate evm/subgraph/subgraph.yaml to match, then run the manifest check.');
+    console.log(
+      `\nGenerate the subgraph manifest from the record (from evm/): cd subgraph && npm run manifest -- --network ${slug}`,
+    );
   }
 
   console.log('\nDeployment summary:');

evm/subgraph/.gitignore

@@ -3,3 +3,5 @@ generated/
 build/
 tests/.bin/
 tests/.latest.json
+# Generated per network from subgraph.template.yaml (npm run manifest).
+/subgraph.yaml

evm/subgraph/README.md

@@ -1,11 +1,15 @@
 # Subgraph Deployments
 
 Each subdirectory contains the Goldsky instant subgraph config for one EVM network.
+The `graph-cli` manifest is generated per network from `subgraph.template.yaml`; see
+[graph-cli manifest](#graph-cli-manifest).
 
 ## Structure
 
 ```
 subgraph/
+  subgraph.template.yaml ← graph-cli manifest without network, addresses or start blocks
+  subgraph.yaml          ← generated from the template for one network (git-ignored)
   horizen-testnet/       ← Horizen Testnet
     instant-config.json
     abis/
@@ -66,6 +70,9 @@ cd evm/subgraph/<network>
 goldsky subgraph deploy wraith-protocol-<network>/1.0.0 --from-abi instant-config.json
 ```
 
+To deploy with `graph deploy` instead, generate the manifest first (see
+[graph-cli manifest](#graph-cli-manifest)).
+
 ### 4. Adding a New Network
 
 To add support for a new EVM network:
@@ -100,6 +107,32 @@ To add support for a new EVM network:
 6. Deploy contracts using the new script
 7. Validate and deploy the subgraph
 
+## graph-cli manifest
+
+`subgraph.template.yaml` is the checked-in `graph-cli` manifest. It has no network,
+contract addresses or start blocks. `npm run manifest` fills them in from
+`deployments/evm/<network>.json` and writes `subgraph.yaml`, which is git-ignored:
+
+```bash
+(cd scripts/deployment-manifest && npm ci)   # once, from the repository root; the generator lives here
+cd evm/subgraph
+npm ci
+npm run manifest -- --network <network>
+npm run codegen
+npm run deploy -- <subgraph-name> --node <graph-node-url>   # any graph deploy arguments
+```
+
+`npm run manifest` fails and writes nothing if a contract the template indexes is
+not in the record, has no start block (or start block 0), or has the placeholder
+address `0x…dead`. It lists every such contract. `npm run deploy` and
+`npm run deploy-local` first run `npm run manifest -- --check`, which fails unless
+`subgraph.yaml` exists and is exactly what the generator writes now for the network
+it names, so these scripts do not deploy a stale or hand-edited manifest. A bare
+`graph deploy` skips that check; use the npm scripts.
+
+`codegen`, `build` and `test` read the template directly (`matchstick.yaml` points
+`graph test` at it), so they work without a deployment.
+
 ## Deployed Subgraphs
 
 | Network         | Subgraph URL                                                                                                              |
@@ -114,3 +147,6 @@ To add support for a new EVM network:
 - **Not yet deployed**: WraithNames, WraithSender, WraithWithdrawer
 
 The subgraph currently only indexes the deployed contracts. To add support for WraithNames, WraithSender, and WraithWithdrawer, deploy these contracts to Horizen Testnet and update the subgraph configuration following the redeployment process above.
+
+Until they are recorded in `deployments/evm/horizen-testnet.json`,
+`npm run manifest -- --network horizen-testnet` fails and names the three of them.

evm/subgraph/matchstick.yaml

@@ -0,0 +1,2 @@
+# graph test reads the template; the tests do not depend on a network.
+manifestPath: ./subgraph.template.yaml

evm/subgraph/package.json

@@ -3,13 +3,14 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "codegen": "graph codegen",
-    "build": "graph build",
+    "manifest": "npm --prefix ../../scripts/deployment-manifest run --silent subgraph --",
+    "codegen": "graph codegen subgraph.template.yaml",
+    "build": "graph build subgraph.template.yaml",
     "test": "graph test --version 0.6.0",
     "test:coverage": "graph test --coverage --version 0.6.0",
-    "deploy": "graph deploy",
+    "deploy": "npm run manifest -- --check && graph deploy",
     "create-local": "graph create --node http://localhost:8020 wraith-protocol/wraith",
-    "deploy-local": "graph deploy --node http://localhost:8020 --ipfs http://localhost:5001 wraith-protocol/wraith"
+    "deploy-local": "npm run manifest -- --check && graph deploy --node http://localhost:8020 --ipfs http://localhost:5001 wraith-protocol/wraith"
   },
   "devDependencies": {
     "@graphprotocol/graph-cli": "^0.96.0",

evm/subgraph/subgraph.yaml → evm/subgraph/subgraph.template.yaml

@@ -1,3 +1,12 @@
+# Template for subgraph.yaml. It has no network, contract addresses or start
+# blocks, so it cannot be deployed as is. scripts/deployment-manifest fills them
+# in from deployments/evm/<network>.json:
+#
+#   npm run manifest -- --network <network>
+#
+# and refuses if a contract or start block is not recorded. codegen, build and
+# test read this file directly. See README.md.
+
 specVersion: 1.0.0
 description: Wraith Protocol stealth address indexer
 repository: https://github.com/wraith-protocol/contracts
@@ -7,11 +16,8 @@ schema:
 dataSources:
   - kind: ethereum
     name: ERC5564Announcer
-    network: horizen-testnet
     source:
-      address: '0x8AE65c05E7eb48B9bA652781Bc0a3DBA09A484F3'
       abi: ERC5564Announcer
-      startBlock: 14202900
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
@@ -28,11 +34,8 @@ dataSources:
 
   - kind: ethereum
     name: ERC6538Registry
-    network: horizen-testnet
     source:
-      address: '0x953E6cEdcdfAe321796e7637d33653F6Ce05c527'
       abi: ERC6538Registry
-      startBlock: 14202905
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
@@ -51,12 +54,8 @@ dataSources:
 
   - kind: ethereum
     name: WraithNames
-    network: horizen-testnet
     source:
-      # TODO: fill in after deployment — matches scripts/deploy.ts output.
-      address: '0x000000000000000000000000000000000000dead'
       abi: WraithNames
-      startBlock: 14202900
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
@@ -75,12 +74,8 @@ dataSources:
 
   - kind: ethereum
     name: WraithSender
-    network: horizen-testnet
     source:
-      # TODO: fill in after deployment — matches scripts/deploy.ts output.
-      address: '0x000000000000000000000000000000000000dead'
       abi: WraithSender
-      startBlock: 14202900
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7
@@ -103,12 +98,8 @@ dataSources:
 
   - kind: ethereum
     name: WraithWithdrawer
-    network: horizen-testnet
     source:
-      # TODO: fill in after deployment — matches scripts/deploy.ts output.
-      address: '0x000000000000000000000000000000000000dead'
       abi: WraithWithdrawer
-      startBlock: 14202900
     mapping:
       kind: ethereum/events
       apiVersion: 0.0.7

scripts/deployment-manifest/package.json

@@ -12,6 +12,7 @@
     "check": "tsx src/cli.ts check",
     "verify": "tsx src/cli.ts verify",
     "record": "tsx src/cli.ts record",
+    "subgraph": "tsx src/cli.ts subgraph",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },