Repository navigation
Base to network - #1129
Base to network#1129brandonleekramer wants to merge 4 commits into
Conversation
…rk template, and add Guides & Best Practices Supported Networks (registry v0.8.8 -> v0.8.14) - Add an Elysium page (Substreams via The Graph Market) - Remove pages for networks dropped from the table (Blast, Starknet, Starknet Testnet, Robinhood Chain Testnet) and redirect their routes to /supported-networks/ - zkSync Era: add Pinax Substreams section and "two ways" intro - Substreams overview and quick start: drop Starknet, Vara, and MANTRA Base - Use the BSC/Polygon template: longer intro, "Find Existing Subgraphs on Base" cards, Graph Network publishing flow Subgraphs: Guides & Best Practices - Merge How-to Guides into best-practices/ under the nav title "Guides & Best Practices"; rename "Tooling" to "Testing & Tooling" - Add the Subgraph Guides & Best Practices overview as the first page - Reorder pages to follow the overview, rewrite pages in one voice, and merge the two grafting pages into one - Redirect guides/, cookbook/, and grafting-hotfix URLs to their final pages in nginx.conf, and fix redirects to removed pages Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS
Promote the intro headings to h2 so each page's first heading is rank 2 (remark-lint-first-heading-level). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS
|
|
||
| ## After Grafting | ||
|
|
||
| - **Republish without grafting:** Once the grafted version is stable, deploy a non-grafted version for long-term maintenance. Relying on a graft indefinitely complicates future updates. |
There was a problem hiding this comment.
It's worth noting that the new "not grafted" version would need to have 2 data sources, one for the old contract, and one for the new contract, otherwise it will only index the data from the new one (if you just replace the address).
Also worth noting that if the grafted version only has one data source, it will copy the old contract data so far, but not index new data from that contract.
There was a problem hiding this comment.
My guy and I updated both points. Scenario 2 now has a note that a single-data-source graft copies the old contract’s data up to the graft block but stops indexing it after that. “After Grafting” now says the non-grafted republish needs data sources for both contracts (old one with its original startBlock). Otherwise it only indexes the new contract. I hope that addresses your concern.
|
|
||
| ```yaml | ||
| eventHandlers: | ||
| - event: TransferWithPool(address indexed, address indexed, uint256, bytes32 indexed) |
There was a problem hiding this comment.
Should be:
event: TransferWithPool(indexed address,indexed address,uint256,indexed bytes32)
There was a problem hiding this comment.
Fixed to TransferWithPool(indexed address,indexed address,uint256,indexed bytes32).
| You can declare `eth_calls` only for event handlers, and only with `specVersion` 1.2.0 or later. In the manifest, add a `calls` section to the handler: | ||
|
|
||
| ```yaml | ||
| event: TransferWithPool(address indexed, address indexed, uint256, bytes32 indexed) |
There was a problem hiding this comment.
Has the same issue as previously stated, though it is not part of the PR:
event: TransferWithPool(indexed address,indexed address,uint256,indexed bytes32)
There was a problem hiding this comment.
Fixed to TransferWithPool(indexed address,indexed address,uint256,indexed bytes32).
| ### Types and Query-Friendly Modeling | ||
|
|
||
| - **Sort by numbers, not strings:** Store amounts as `Int` or `BigInt`. String order puts "10" before "2". | ||
| - **Put sort keys on the entity itself:** GraphQL queries cannot order by a nested field, so add a `createdAt` or similar field where you sort. |
There was a problem hiding this comment.
I think this is not true, though using nested fields for sorting isn't ideal
There was a problem hiding this comment.
Noted, the GraphQL API docs do say nested sorting works one level deep on String/ID fields (orderBy: owner__name). I reworded it to say: nested sorting works but is slower and limited, so store sort keys you use often (like createdAt) on the entity.
| ### Entity Reads and Writes | ||
|
|
||
| - **Save only what changed:** Do not load and save entities that the handler does not modify. | ||
| - **Use `loadInBlock()` for entities created earlier in the same block:** It skips the database round trip for a [lookup that would miss](/subgraphs/developing/creating/graph-ts/api/). It returns `null` if the entity was not created in the current block, even if it exists in the store. |
There was a problem hiding this comment.
An entity created earlier but updated and saved in this block is also returned. Graph Node’s existing test explicitly covers this. The text should describe current-block writes, and clarify that a non-null result doesn’t prove the entity was newly created.
There was a problem hiding this comment.
Updated. Now it says loadInBlock() returns an entity created, or updated and saved, in the current block. A non-null result doesn’t prove the entity is new, and it returns null if the entity wasn’t written in this block, even if it exists in the store. It also links the graph-ts section, which already says “created or updated”.
| ### Iterate Faster During Development | ||
|
|
||
| - **Use a recent `startBlock` locally:** Restore the real block before you publish ([Graph Node Dev Mode](/subgraphs/developing/creating/graph-node-dev/)). | ||
| - **Run Graph Node in watch mode:** `gnd dev --watch` rebuilds when files change. Always pass `--node` to `gnd deploy`; without it, `gnd deploy` targets Subgraph Studio. |
There was a problem hiding this comment.
Says gnd dev --watch rebuilds when files change. It watches compiled output and redeploys it. Editing mappings alone leaves the old code running.
If you already have graph build --watch or gnd build --watch running editing mappings triggers compilation, then gnd dev --watch picks up the output and redeploys, but gnd dev --watch alone doesn’t compile. Its watcher calls deploy_all_subgraphs. Compilation happens in the separate build watcher. The documentation should mention both processes.
There was a problem hiding this comment.
Updated. It now says gnd dev --watch only redeploys the build output and doesn’t compile. You'd have to run gnd build --watch (or graph build --watch) in a second terminal so mapping, schema, and manifest edits get recompiled, and gnd dev --watch picks up the new build.
My guy also caught that the Supported Networks Subgraph template _subgraph-community.mdx had the same issue and also needed to be updated, so we addressed that too.
| - It adds or removes interfaces | ||
| - It changes for which entity types an interface is implemented | ||
|
|
||
| Any other change, such as changing a field's type or making a nullable field non-nullable, is not graft-compatible. Schema optimizations such as switching to [immutable entities or `Bytes` IDs](/subgraphs/best-practices/immutable-entities-bytes-as-ids/) also break compatibility. |
There was a problem hiding this comment.
Graph Node supports mutable-to-immutable copying when the copied history contains no updates or deletions.
There was a problem hiding this comment.
Corrected. Switching id to Bytes is still listed as not graft-compatible. Marking a mutable entity immutable is now listed as supported only when the copied history has no updates or deletions of that entity. The overview’s grafting summary made the same claim, so my guy fixed it there too and linked it to this section.
- Declared eth_call examples: use the manifest event signature format `TransferWithPool(indexed address,indexed address,uint256,indexed bytes32)` - Overview: nested sorting works one level deep (String/ID fields), so recommend storing frequent sort keys on the entity rather than saying nested sorting is impossible - Overview: loadInBlock returns entities created or updated in the current block; a non-null result does not prove the entity is new - Overview: gnd dev --watch only redeploys the build output; run gnd build --watch (or graph build --watch) alongside it to recompile - Grafting: switching to Bytes IDs is not graft-compatible, but mutable to immutable is supported when the copied history has no updates or deletions - Grafting: a non-grafted republish after a contract replacement needs data sources for both contracts, and a single-data-source graft stops indexing the old contract after the graft block Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS
gnd --watch only redeploys the build output and does not compile, so the local verification step now starts graph build --watch (or gnd build --watch) in one terminal and gnd --watch in a second terminal. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS
Summary
Three updates: sync Supported Networks with networks registry v0.8.14, move the Base page to the Network-only template, and merge the Subgraph How-to Guides into a new Guides & Best Practices section with an overview page.
Supported Networks (registry v0.8.8 → v0.8.14)
/supported-networks/elysium/), Kinetiq's Arbitrum Orbit L2 on HyperEVM. Substreams via The Graph Market./supported-networks/.Base
Guides & Best Practices
/subgraphs/best-practices/under the nav title Guides & Best Practices.*operator in the timeseries docs,graph-example/graft-exampletypos, and stale/developing/and/cookbook/links.Redirects (
nginx.conf)/subgraphs/guides/*,/subgraphs/cookbook/*, and/cookbook/*→/subgraphs/best-practices/*, in one step with no redirect chains. Old tooling and public-Subgraph slugs still go to their own sections./subgraphs/best-practices/grafting-hotfix/→/subgraphs/best-practices/grafting//subgraphs/best-practices/,/subgraphs/guides/, and/subgraphs/cookbook/→ the overview page.substreams/sps/*→ Substreams overview.Checks
tsc, and an MDX compile of every changed page pass.route-lockfile.txtwas updated by hand. Confirm it matches the CI-generated version.🤖 Generated with Claude Code
https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS