Update and improvements to the config-schema reference

[JasoonS]

Summary by CodeRabbit

• New Features

  • Added address_format option (checksum or lowercase).
  • Added preload_handlers configuration.
  • Added per-contract start_block to control indexing start height.

• Documentation

  • Updated config schema docs with clearer types, renamed anchors, and inline "Available values" for transaction/block fields.
  • Added Chainweb Testnet 21 to supported networks documentation.

• Chores

  • Expanded supported networks list; ordering and duplication cleaned up.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
envio-docs	Ready	Preview	Comment	Oct 2, 2025 2:41pm

[coderabbitai]

Walkthrough

Refactors schema anchors to def-* names, adds top-level properties preload_handlers and address_format, introduces start_block in contracts, updates network listings (adds Chainweb Testnet 21), and makes the schema-doc generator rootSchema-aware with inline enum value rendering.

Changes

Cohort / File(s)	Summary
Config schema & docs docs/HyperIndex/Advanced/config-schema-reference.md, static/schemas/config.evm.json	Adds top-level preload_handlers and address_format (enum); adds start_block to per-contract definition; renames many anchors to def-*; replaces ambiguous unknown types with explicit object<...> refs and updates nested refs to def-* variants.
Schema-doc generator scripts/generate-config-schema-doc.js	Threads rootSchema into describeType and rendering calls to resolve $ref contextually; adds slugify(text, preserveUnderscores = false); switches anchor naming to def-*; inlines TransactionField/BlockField enum values in generated docs.
Supported networks (docs) docs/HyperRPC/hyperrpc-supported-networks.md, docs/HyperSync/hypersync-supported-networks.md	Adds a row for Chainweb Testnet 21 (Network ID 5921) and corresponding URLs; table structure unchanged.
Supported networks (data) supported-networks.json	Replaces/expands the supportedNetworks block, adds chainweb-testnet-21, and adjusts ordering/entries per diff.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as docs generator CLI
  participant Gen as generate-config-schema-doc.js
  participant Root as root schema ($defs)
  participant MD as Markdown output

  CLI->>Gen: request doc generation
  Gen->>Root: load rootSchema
  loop traverse schema nodes
    Gen->>Root: resolve $ref (with rootSchema context)
    alt $ref -> TransactionField/BlockField
      Root-->>Gen: enum values
      Gen->>Gen: inline "Available values" list & emit `def-*` anchor
    else other $ref/object/array
      Root-->>Gen: resolved schema node
      Gen->>Gen: render type with `def-*` anchor
    end
  end
  Gen-->>MD: write updated Markdown with def-* anchors and inline enums

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Config schema #687 — Overlaps changes to config schema docs, generator, and def-* anchor handling.
• chore: updated supported networks #697 — Similar edits to supported-networks.json (replacement/reordering of entries).
• Document Preload Optimization #685 — Related to adding/documenting preload_handlers referenced by schema and docs.

Suggested reviewers

• DenhamPreen
• moose-code
• DZakh

Poem

I nibble at defs and hop through refs,
RootSchema guides my careful steps.
New nets bloom, start blocks in view,
Address formats — checksum or lowercase too.
A tiny rabbit stamps and cheers, "Docs polished for brave engineers!" 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title specifically mentions updates and improvements to the config-schema reference, which accurately describes a substantial portion of the changeset; while the PR also includes script modifications, JSON schema updates, and supported-networks additions, the title remains a valid partial summary of a core aspect of this work.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch config-schema-update

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d3cd848 and 55557f1.

📒 Files selected for processing (2)

• docs/HyperIndex/Advanced/config-schema-reference.md (19 hunks)
• scripts/generate-config-schema-doc.js (10 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[JasoonS]

These 'unknown' fields were annoying, since we did actually have the type.

[JasoonS]

New features

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e47e8fb and d3cd848.

📒 Files selected for processing (6)

• docs/HyperIndex/Advanced/config-schema-reference.md (19 hunks)
• docs/HyperRPC/hyperrpc-supported-networks.md (1 hunks)
• docs/HyperSync/hypersync-supported-networks.md (1 hunks)
• scripts/generate-config-schema-doc.js (10 hunks)
• static/schemas/config.evm.json (3 hunks)
• supported-networks.json (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-07-29T14:30:03.677Z

Learnt from: DenhamPreen
PR: enviodev/docs#673
File: docs/HyperIndex/supported-networks/chainweb-testnet-21.md:14-16
Timestamp: 2025-07-29T14:30:03.677Z
Learning: Chainweb Testnet 20 (ID: 5920) and Chainweb Testnet 21 (ID: 5921) have non-functional HyperSync endpoints that return HTTP 404, indicating these networks are not properly supported and should be removed from documentation.

Applied to files:

• docs/HyperSync/hypersync-supported-networks.md
• docs/HyperRPC/hyperrpc-supported-networks.md

🪛 markdownlint-cli2 (0.18.1)

docs/HyperSync/hypersync-supported-networks.md

51-51: Bare URL used

(MD034, no-bare-urls)

---

51-51: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (1)

docs/HyperRPC/hyperrpc-supported-networks.md (1)

43-44: Chainweb Testnet 21 RPC is live (405 expected)
The 405 responses confirm the service is running (GET is disallowed on JSON-RPC endpoints). Keep the Chainweb Testnet 21 row as-is.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify Chainweb Testnet 21 before advertising support

We previously removed this row after confirming the HyperSync endpoint returned HTTP 404; unless the service is now live, re-adding it gives users a broken URL. Please confirm the endpoint is operational (e.g. simple curl -I https://chainweb-testnet-21.hypersync.xyz) before keeping it here.
Based on learnings

---

🏁 Script executed:

#!/bin/bash
curl -s -o /dev/null -w "%{http_code}\n" https://chainweb-testnet-21.hypersync.xyz
curl -s -o /dev/null -w "%{http_code}\n" https://5921.hypersync.xyz

Length of output: 7

---

Remove Chainweb Testnet 21 Both endpoints return HTTP 404; remove this row until support is restored.

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

51-51: Bare URL used

(MD034, no-bare-urls)

---

51-51: Bare URL used

(MD034, no-bare-urls)

---

52-52: Bare URL used

(MD034, no-bare-urls)

---

52-52: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents

docs/HyperSync/hypersync-supported-networks.md around lines 51 to 52: remove the
entire table row for "Chainweb Testnet 21" (the row containing port 5921 and the
two endpoints) so the table no longer lists that network; ensure the table
remains syntactically valid (remove the line only, do not alter other rows or
table headers) and save the file.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Pass root schema when listing nested property types

Inside the object “Properties” list we still call describeType(prop) without the new rootSchema context, so $ref-backed children now render as unknown (e.g. FieldSelection fields) instead of object<...>. Please thread the rootSchema argument through this call as well.

-          `- ${toInlineCode(propName)}: ${toInlineCode(describeType(prop))}${prop.description ? ` – ${prop.description}` : ""}` + "\n";
+          `- ${toInlineCode(propName)}: ${toInlineCode(describeType(prop, rootSchema))}${prop.description ? ` – ${prop.description}` : ""}` + "\n";

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const prop = props[propName];
	out +=
	`- ${toInlineCode(propName)}: ${toInlineCode(describeType(prop))}${
	prop.description ? ` – ${prop.description}` : ""
	`- ${toInlineCode(propName)}: ${toInlineCode(describeType(prop))}${prop.description ? ` – ${prop.description}` : ""
	}` + "\n";
	});
	}
	const prop = props[propName];
	out +=
	`- ${toInlineCode(propName)}: ${toInlineCode(describeType(prop, rootSchema))}${prop.description ? ` – ${prop.description}` : ""
	}` + "\n";

🤖 Prompt for AI Agents

In scripts/generate-config-schema-doc.js around lines 237 to 242, the call
describeType(prop) inside the Properties list needs the rootSchema context so
$ref-backed children render correctly; update the call to pass the same
rootSchema used elsewhere (e.g. describeType(prop, rootSchema)), ensuring
rootSchema is in scope or passed into the enclosing function/closure if
necessary, so nested property types resolve correctly.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Hold off on listing chainweb-testnet-21 until the endpoint works

This JSON powers the docs, so adding supported-networks/chainweb-testnet-21 will surface the same non-functional HyperSync endpoint noted earlier. Please keep it out (and avoid publishing duplicates like this) until the network is actually live.
Based on learnings

---

🏁 Script executed:

#!/bin/bash
curl -s -o /dev/null -w "%{http_code}\n" https://chainweb-testnet-21.hypersync.xyz
curl -s -o /dev/null -w "%{http_code}\n" https://5921.hypersync.xyz

Length of output: 7

---

Remove chainweb-testnet-21 from supported-networks.json

Its HyperSync endpoint returns HTTP 404; re-add the entry only once the network is live.

🤖 Prompt for AI Agents

In supported-networks.json around line 5, remove the
"supported-networks/chainweb-testnet-21" entry from the array (delete the exact
string and adjust surrounding commas so the JSON remains valid), save the file
and run a JSON lint/formatter to ensure no trailing commas or syntax errors;
re-add the entry later only when the network is live.

[JasoonS]

There were clashes, eg on the old site there was no way to link to this part of the page (since they both had the same link: https://docs.envio.dev/docs/HyperIndex/config-schema-reference#fieldselection)

unavailable via link since overshadowed:

[JasoonS]

This was just wrong, Timestamp is always included on the block and if you add this here the codegen will not allow it (and fail with error)

[JasoonS]

This was just a bug, it was overwriting it for some reason.

[JasoonS]

Not necessary - keeping the < / > is better.

[JasoonS]

This removes the "unknown" fields...

[JasoonS]

Unnecessary duplicate example

[JasoonS]

Taken back, added - it shows that it works under contracts as per event also!