Skip to content

Base to network - #1129

Open
brandonleekramer wants to merge 4 commits into
mainfrom
base-to-network
Open

brandonleekramer wants to merge 4 commits into
mainfrom
base-to-network

Conversation

@brandonleekramer

Copy link
Copy Markdown
Member

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)

  • New: Elysium page (/supported-networks/elysium/), Kinetiq's Arbitrum Orbit L2 on HyperEVM. Substreams via The Graph Market.
  • zkSync Era: Pinax added Substreams, so the page now covers both Subgraphs and Substreams.
  • Removed: Blast, Starknet, Starknet Testnet, and Robinhood Chain Testnet have no providers left in the registry, so the table no longer lists them. Their custom pages are deleted and their routes redirect to /supported-networks/.
  • Substreams overview and quick start: removed Starknet, Vara, and MANTRA, none of which has a live endpoint.

Base

  • The Base page now uses the same template as BSC and Polygon: longer intro, a "Find Existing Subgraphs on Base" card grid (Uniswap V4, Uniswap V3, Aerodrome, Morpho Blue, Aave V3, Moonwell), and the Graph Network publishing flow.
  • Follow-up needed in the registry: v0.8.14 still lists a Studio entry for Base. The "no Studio indexing" warning will show only after that entry is removed, the same change networks-registry#263 made for BSC and Polygon.

Guides & Best Practices

  • Merged How-to Guides into /subgraphs/best-practices/ under the nav title Guides & Best Practices.
  • New default page: Subgraph Guides & Best Practices, with a performance checklist and a map of the section.
  • Reordered the pages to follow the overview: contract design → schema → storage and queries → debugging and grafting → composition → migration.
  • Rewrote the pages in one voice: removed the "Subgraph Best Practice N" titles and the 1-6 lists, replaced TLDR and Conclusion sections with a short opening paragraph, switched to second person, and ended every page with a shared "Learn More" block.
  • Merged the two grafting pages into one Grafting page that covers both hotfixes and contract replacement. Its compatible-schema list now matches the official reference.
  • Renamed Tooling to Testing & Tooling (URL unchanged).
  • Fixed content bugs: a mangled * operator in the timeseries docs, graph-example/graft-example typos, 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.
  • Fixed redirects that led to removed pages: Arweave → Supported Networks, multisig → Studio FAQ, substreams/sps/* → Substreams overview.

Checks

  • Prettier, tsc, and an MDX compile of every changed page pass.
  • Every internal link and anchor in the section resolves.
  • route-lockfile.txt was updated by hand. Confirm it matches the CI-generated version.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HpT75uYTePhuL7KFioUPqS

brandonleekramer and others added 2 commits November 16, 2026 19:01
…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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be:
event: TransferWithPool(indexed address,indexed address,uint256,indexed bytes32)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

@juanmardefago juanmardefago Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Has the same issue as previously stated, though it is not part of the PR:
event: TransferWithPool(indexed address,indexed address,uint256,indexed bytes32)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is not true, though using nested fields for sorting isn't ideal

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graph Node supports mutable-to-immutable copying when the copied history contains no updates or deletions.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

brandonleekramer and others added 2 commits November 17, 2026 03:24
- 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants