From 8bb234fbc37ef18460a63497724cab7dcf3d57ca Mon Sep 17 00:00:00 2001 From: Dennis Trautwein Date: Fri, 15 May 2026 17:23:44 +0200 Subject: [PATCH 1/4] test: assert contract addresses are up-to-date As of comment: https://github.com/FilOzone/dealbot/pull/469/changes#r3245740521 --- apps/subgraph/package.json | 2 +- apps/subgraph/scripts/check-networks.test.mjs | 36 +++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 apps/subgraph/scripts/check-networks.test.mjs diff --git a/apps/subgraph/package.json b/apps/subgraph/package.json index c56cce5b..8c421738 100644 --- a/apps/subgraph/package.json +++ b/apps/subgraph/package.json @@ -10,7 +10,7 @@ "build:calibration": "pnpm run codegen && graph build --network filecoin-testnet", "deploy:mainnet": "goldsky subgraph deploy dealbot-mainnet/$VERSION --path ./build", "deploy:calibration": "goldsky subgraph deploy dealbot-calibration/$VERSION --path ./build", - "test": "graph test" + "test": "graph test && node --test scripts/check-networks.test.mjs" }, "dependencies": { "@filoz/synapse-core": "0.3.3", diff --git a/apps/subgraph/scripts/check-networks.test.mjs b/apps/subgraph/scripts/check-networks.test.mjs new file mode 100644 index 00000000..59699e72 --- /dev/null +++ b/apps/subgraph/scripts/check-networks.test.mjs @@ -0,0 +1,36 @@ +// Asserts apps/subgraph/networks.json stays in sync with the contract +// addresses shipped by @filoz/synapse-core (which is generated from +// FilOzone/filecoin-services). Bumping synapse-core is the trigger for any +// address change; this test fails fast if networks.json drifts. + +import { readFile } from "node:fs/promises"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { generated } from "@filoz/synapse-core/abis"; + +const { filecoinWarmStorageServiceAddress, pdpVerifierAddress } = generated; + +const here = dirname(fileURLToPath(import.meta.url)); +const networksPath = join(here, "..", "networks.json"); +const networks = JSON.parse(await readFile(networksPath, "utf8")); + +const cases = { + "filecoin": 314, + "filecoin-testnet": 314159, +}; + +for (const [network, chainId] of Object.entries(cases)) { + test(`${network} PDPVerifier address matches synapse-core[${chainId}]`, () => { + const actual = networks[network]?.PDPVerifier?.address; + const expected = pdpVerifierAddress[chainId]; + assert.equal(actual, expected, `expected ${expected}, got ${actual} for ${network}.PDPVerifier.address`) + }); + + test(`${network} FilecoinWarmStorageService address matches synapse-core[${chainId}]`, () => { + const actual = networks[network]?.FilecoinWarmStorageService?.address; + const expected = filecoinWarmStorageServiceAddress[chainId]; + assert.equal(actual, expected, `expected ${expected}, got ${actual} for ${network}.FilecoinWarmStorageService.address`); + }); +} \ No newline at end of file From 91a0252149ce3da49326ea71490fc5653a546c07 Mon Sep 17 00:00:00 2001 From: Dennis Trautwein Date: Fri, 15 May 2026 17:43:54 +0200 Subject: [PATCH 2/4] docs: add motivation for custom dealbot subgraph addresses comment: https://github.com/FilOzone/dealbot/pull/469/changes#r3245751024 --- apps/subgraph/README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/apps/subgraph/README.md b/apps/subgraph/README.md index 81a80b1d..94ef5a68 100644 --- a/apps/subgraph/README.md +++ b/apps/subgraph/README.md @@ -2,11 +2,20 @@ A dealbot-owned Graph Protocol subgraph. -## What it indexes +What it indexes - **PDPVerifier** — dataset lifecycle, piece add/remove, proving periods. - **FilecoinWarmStorageService (FWSS)** — payer/service-provider metadata, `withIPFSIndexing` flag, `ipfsRootCID` per piece, service/payment termination. +## Motivation + +The motivation comes from the anonymous retrieval check from [#427](https://github.com/FilOzone/dealbot/issues/427): probing SPs for pieces dealbot did not create, so an SP can't preferentially serve pieces when "the teacher is watching". To pick those pieces fairly we need to query any FWSS-managed piece on a given SP, including `withIPFSIndexing` and `ipfsRootCID`, uniformly at random across the SP's entire active piece set. Neither existing subgraph supports that shape: + +- [FilOzone/pdp-explorer](https://github.com/FilOzone/pdp-explorer): indexes the PDPVerifier contract only. No FWSS-level fields, so it can't tell us whether a piece is CAR-validatable (`withIPFSIndexing`) or what its `ipfsRootCID` is. +- [FIL-Builders/fwss-subgraph](https://github.com/FIL-Builders/fwss-subgraph): FWSS-centric, but doesn't expose the joined PDP+FWSS view we need (active piece set per SP, with IPFS metadata attached) and isn't on a release cadence we control. + +`@dealbot/subgraph` is intentionally a strict functional superset of `pdp-explorer`: same PDPVerifier coverage, plus the FWSS fields we need. Once we're confident in its correct operation it can become a drop-in replacement for `PDP_SUBGRAPH_ENDPOINT`, but for now the basic retrieval and data-retention checks continue to use `pdp-explorer`. + ## Contract ABIs `abis/*.json` is generated by `scripts/sync-abis.mjs` from the canonical From 7bc1f08d489df9970905647db3eebe8a0440a85a Mon Sep 17 00:00:00 2001 From: Dennis Trautwein Date: Fri, 15 May 2026 18:08:34 +0200 Subject: [PATCH 3/4] docs: describe subgraph release & deploy process --- apps/subgraph/README.md | 17 +----- docs/release-process.md | 2 +- docs/release-subgraph.md | 114 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+), 16 deletions(-) create mode 100644 docs/release-subgraph.md diff --git a/apps/subgraph/README.md b/apps/subgraph/README.md index 94ef5a68..4107c604 100644 --- a/apps/subgraph/README.md +++ b/apps/subgraph/README.md @@ -40,20 +40,7 @@ pnpm build:calibration pnpm test ``` -## Deploy +## Release and Deployment -Requires `goldsky` CLI authenticated via `GOLDSKY_API_KEY`. +The subgraph is versioned and released independently of `apps/backend` and `apps/web`. The end-to-end checklist lives in [`docs/release-subgraph.md`](../../docs/release-subgraph.md). -```bash -export VERSION=0.1.0 -pnpm build:calibration -pnpm deploy:calibration - -pnpm build:mainnet -pnpm deploy:mainnet -``` - -Goldsky slots (slugs TBD): - -- `dealbot-mainnet/` — mainnet -- `dealbot-calibration/` — calibration diff --git a/docs/release-process.md b/docs/release-process.md index 1df82c12..72a93387 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -1,6 +1,6 @@ # Release Process -Dealbot uses [release-please](https://github.com/googleapis/release-please) to drive semver releases from [Conventional Commits](https://www.conventionalcommits.org/), and ArgoCD Image Updater to promote those releases into Kubernetes. For release-please mechanics (commit parsing, version bumps, troubleshooting) see [release-please-flow.md](release-please-flow.md). For container images, manifests, and runtime topology see [deployment.md](deployment.md). For ingress, egress, persistence, secrets, and observability expectations see [infra.md](infra.md). +Dealbot uses [release-please](https://github.com/googleapis/release-please) to drive semver releases from [Conventional Commits](https://www.conventionalcommits.org/), and ArgoCD Image Updater to promote those releases into Kubernetes. For release-please mechanics (commit parsing, version bumps, troubleshooting) see [release-please-flow.md](release-please-flow.md). For container images, manifests, and runtime topology see [deployment.md](deployment.md). For ingress, egress, persistence, secrets, and observability expectations see [infra.md](infra.md). For the subgraph release checklist see [release-subgraph.md](release-subgraph.md). ## Flow diff --git a/docs/release-subgraph.md b/docs/release-subgraph.md new file mode 100644 index 00000000..6e3bf97b --- /dev/null +++ b/docs/release-subgraph.md @@ -0,0 +1,114 @@ +# Subgraph Release Checklist + +Source of truth for releasing and deploying [`apps/subgraph/`](../apps/subgraph/). + +The dealbot subgraph is versioned independently from `apps/backend` and `apps/web`. Those two go through a release process as described in [release-process.md](release-process.md). The subgraph is published to [Goldsky](https://goldsky.com/) on its own cadence following the steps below. + +When cutting a release, you may copy the checklist into a new GitHub issue titled `Release subgraph vX.Y.Z` and tick the boxes as you go. The structure mirrors [filecoin-pay-explorer's release template](https://github.com/FilOzone/filecoin-pay-explorer/blob/main/.github/ISSUE_TEMPLATE/release.md). + +## Notes + +- Dealbot's backend consumes the subgraph at a `prod`-tagged URL (e.g. `.../dealbot-mainnet/prod/gn`). Re-tagging is what actually promotes a new version to production (no backend redeploy required). +- This checklist assumes a **backward-compatible** change. For a breaking change see [Breaking changes](#breaking-changes) at the bottom. + +## 1. Define the new version + +```bash +NEW_RELEASE_VERSION="X.Y.Z" # no v prefix — used as the Goldsky version segment +CURRENT_VERSION="X.Y.Z" # version currently tagged as `prod` (will be replaced) +``` + +- [ ] Version strings agreed and set +- [ ] Bump follows semver: additive → minor, fix → patch, breaking → major + +## 2. Create a GitHub release + +```bash +gh release create "subgraph-v$NEW_RELEASE_VERSION" \ + --title "subgraph v$NEW_RELEASE_VERSION" \ + --generate-notes +``` + +- [ ] GitHub release created with tag `subgraph-vX.Y.Z` + +The `subgraph-` prefix disambiguates from backend / web releases, which are tagged on the same repo by release-please. + +## 3. Build and publish the subgraph + +> **Note:** Tag-triggered CI for subgraph deploys is not wired up yet — for now every release uses the manual fallback. Tracked as follow-up; target is to match [filecoin-pay-explorer's `deploy.yml`](https://github.com/FilOzone/filecoin-pay-explorer/blob/main/.github/workflows/deploy.yml). + +The following commands need to be run in the `apps/subgraph` directory and require the `goldsky` CLI authenticated via a `GOLDSKY_API_KEY`. + +```bash +export VERSION=0.3.0 # no v prefix; used as the Goldsky version segment + +pnpm build:calibration +pnpm deploy:calibration + +pnpm build:mainnet +pnpm deploy:mainnet +``` + +- [ ] `dealbot-calibration/$NEW_RELEASE_VERSION` deployed +- [ ] `dealbot-mainnet/$NEW_RELEASE_VERSION` deployed + +## 4. Await subgraph indexing + +- [ ] Received confirmation email that `dealbot-calibration` finished indexing +- [ ] Received confirmation email that `dealbot-mainnet` finished indexing + +## 5. Smoke-test the candidate in staging + +Point dealbot staging at the new versioned URL. The cleanest way is via a `staging` tag so the staging backend's config can stay stable: + +```bash +for network in mainnet calibration; do + goldsky subgraph tag delete dealbot-$network/$CURRENT_VERSION --tag staging 2>/dev/null || true + goldsky subgraph tag create dealbot-$network/$NEW_RELEASE_VERSION --tag staging +done +``` + +- [ ] `dealbot-mainnet/$NEW_RELEASE_VERSION` tagged as `staging` +- [ ] `dealbot-calibration/$NEW_RELEASE_VERSION` tagged as `staging` +- [ ] Dealbot staging backend's subgraph-dependent checks succeed against the new subgraph +- [ ] No new errors in dealbot staging logs + +## 6. Promote subgraphs to `prod` + +> [!NOTE] +> Re-tagging as `prod` below switches the **production** dealbot backend over to the new subgraph version. Do this only when you're ready to take it live. + +```bash +for network in mainnet calibration; do + # `tag create` errors if `prod` already points at another version, so we + # delete first. The window between the two calls is sub-second; consumers + # querying the `prod` URL in that window will get an error. + goldsky subgraph tag delete dealbot-$network/$CURRENT_VERSION --tag prod 2>/dev/null || true + goldsky subgraph tag create dealbot-$network/$NEW_RELEASE_VERSION --tag prod +done +``` + +- [ ] `dealbot-mainnet` tagged as `prod` +- [ ] `dealbot-calibration` tagged as `prod` + +## 7. Verify production + +- [ ] Dealbot production backend's subgraph-dependent checks are healthy +- [ ] No regressions in production metrics or dashboards + +## 8. Wrap-up + +- [ ] Announce the release in `#fil-foc` +- [ ] Capture any improvements needed for next time +- [ ] Close this issue + +--- + +## Breaking changes + +When the schema or entity shape changes in a way the current backend can't read, the order changes — re-tagging `prod` first would take the backend down: + +1. Steps 1–4 as above (cut & deploy the new version, wait for indexing). +2. Land the backend changes that consume the new shape, configured to read from the new **versioned** URL (not `prod`). Deploy to dealbot staging and validate end-to-end against `vX.Y.Z`. +3. Once dealbot production is on a backend release that understands the new shape (either both shapes during a migration, or new-only), proceed to step 6 to re-tag `prod`. +4. Rollback: re-tag the previous subgraph version back to `prod`. The `prod` tag is the rollback lever — a single Goldsky API call, no backend redeploy required. From d657aadbf5103c80c2e7424ec11fd0b12ce993a7 Mon Sep 17 00:00:00 2001 From: Dennis Trautwein Date: Tue, 26 May 2026 11:38:16 +0200 Subject: [PATCH 4/4] docs(subgraph): link #573, generalize version, deploy calib first --- docs/release-subgraph.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/release-subgraph.md b/docs/release-subgraph.md index 6e3bf97b..8d799e16 100644 --- a/docs/release-subgraph.md +++ b/docs/release-subgraph.md @@ -35,12 +35,12 @@ The `subgraph-` prefix disambiguates from backend / web releases, which are tagg ## 3. Build and publish the subgraph -> **Note:** Tag-triggered CI for subgraph deploys is not wired up yet — for now every release uses the manual fallback. Tracked as follow-up; target is to match [filecoin-pay-explorer's `deploy.yml`](https://github.com/FilOzone/filecoin-pay-explorer/blob/main/.github/workflows/deploy.yml). +> **Note:** Tag-triggered CI for subgraph deploys is not wired up yet — for now every release uses the manual fallback. Tracked as follow-up in [#573](https://github.com/FilOzone/dealbot/issues/573); target is to match [filecoin-pay-explorer's `deploy.yml`](https://github.com/FilOzone/filecoin-pay-explorer/blob/main/.github/workflows/deploy.yml). The following commands need to be run in the `apps/subgraph` directory and require the `goldsky` CLI authenticated via a `GOLDSKY_API_KEY`. ```bash -export VERSION=0.3.0 # no v prefix; used as the Goldsky version segment +export VERSION=X.Y.Z # no v prefix; used as the Goldsky version segment pnpm build:calibration pnpm deploy:calibration @@ -62,7 +62,7 @@ pnpm deploy:mainnet Point dealbot staging at the new versioned URL. The cleanest way is via a `staging` tag so the staging backend's config can stay stable: ```bash -for network in mainnet calibration; do +for network in calibration mainnet; do goldsky subgraph tag delete dealbot-$network/$CURRENT_VERSION --tag staging 2>/dev/null || true goldsky subgraph tag create dealbot-$network/$NEW_RELEASE_VERSION --tag staging done @@ -79,7 +79,7 @@ done > Re-tagging as `prod` below switches the **production** dealbot backend over to the new subgraph version. Do this only when you're ready to take it live. ```bash -for network in mainnet calibration; do +for network in calibration mainnet; do # `tag create` errors if `prod` already points at another version, so we # delete first. The window between the two calls is sub-second; consumers # querying the `prod` URL in that window will get an error.