docs: add networks and environments guide by oduameh · Pull Request #1179 · midnightntwrk/midnight-docs

oduameh · 2026-08-05T09:46:23Z

What this adds

A new guide, Networks and environments (/guides/networks-and-environments), built as a modular-docs assembly (concept, procedure, and reference modules in one page, same structure as /guides/security-best-practices). It gives the four networks (undeployed, preview, preprod, mainnet) a single home:

The Midnight networks (concept): what each network is for, the three services every network exposes, and a note that the retired testnet-02 name no longer resolves.
Network selection at a glance (reference): which network to target for a given task, with the funding consequence of each choice.
Environment reference (reference): tabbed per-network tables with node RPC and WebSocket, indexer HTTP and WS, faucet, proof server, Bech32m address prefixes, and block explorers.
Connecting a DApp to a network (procedure): setNetworkId plus endpoint wiring, the create-mn-app network scripts, ending in a runnable Vitest verification.
Funding and transaction cost (concept): NIGHT and DUST per network, faucets, local pre-funding, and the mainnet cNIGHT registration path.
Preparing a DApp for mainnet (procedure): preprod validation, cNgD registration, mainnet configuration, with a filtered verification run.
Mainnet readiness checklist (reference).

Also included, to close the mainnet contradiction the guide would otherwise inherit: docs/nodes/node-endpoints.mdx no longer says only "two active test networks" exist; it now names Preview, Preprod, and Mainnet, gains a Mainnet RPC tab, and links to the new reference.

Update: local network guide merged into the assembly

Per review direction, docs/guides/midnight-local-network.mdx is now part of this guide rather than a separate page, completing the single user journey (understand > choose > set up locally > connect > fund > mainnet):

New procedure module Running a local network, verified against a live stack brought up during authoring (midnight-node:1.0.0, indexer-standalone:4.3.3, proof-server:8.1.0); its Verification block is a real executed Vitest run against localhost:9944/8088/6300.
New reference module Local network troubleshooting, which also adds a freshly observed failure mode: on a fresh chain the indexer can exit at first start with block number 1 not found (startup race) and latches on after docker start midnight-indexer.
The old page's pinned-version tables were dropped in favor of pointing at standalone.yml (they had drifted: the page said node 0.22.3 / indexer 4.0.1 / proof server 8.0.3; the tool pins 1.0.0 / 4.3.3 / 8.1.0), and its funding-menu text was corrected against the tool source ([3] Display wallets).
All six inbound pages repointed; vercel.json redirects /midnight-local-network and /guides/midnight-local-network directly to /guides/networks-and-environments (no chains).

Add a modular-docs assembly at /guides/networks-and-environments covering the four networks (undeployed, preview, preprod, mainnet): what each is for, a selection reference, a tabbed environment reference with endpoints and address prefixes, a connect procedure with an executed Vitest verification, funding and cost, and a mainnet preparation procedure with a readiness checklist. Reconcile docs/nodes/node-endpoints.mdx with the mainnet endpoints (it said only two test networks exist) and add the new route to pipelines-urls.json.

vercel · 2026-08-05T09:46:29Z

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

Project	Deployment	Actions	Updated (UTC)
midnight-wiki	Ready	Preview	Aug 7, 2026 11:00am

github-actions · 2026-08-05T09:46:42Z

Summary

Status	Count
🔍 Total	167
🔗 Unique	90
✅ Successful	78
⏳ Timeouts	0
🔀 Redirected	10
👻 Excluded	0
❓ Unknown	0
🚫 Errors	87
⛔ Unsupported	2

Errors per input

Errors in docs/guides/acquire-tokens.mdx

[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/networks-and-environments#running-a-local-network (at 18:61) | File not found. Check if file exists and path is correct

Errors in docs/guides/configure-providers.mdx

[ERROR] error: (at 206:64) | Cannot resolve root-relative link '/sdks/official/wallet-developer-guide': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 331:56) | Cannot resolve root-relative link '/sdks/official/midnight-js': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/getting-started/hello-world (at 26:133) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/deploy-mn-app (at 339:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/generating-dust-programmatically (at 254:172) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/networks-and-environments#running-a-local-network (at 143:27) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/run-proof-server (at 198:95) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/run-proof-server (at 28:61) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/leaderboard/overview (at 340:3) | File not found. Check if file exists and path is correct

Errors in docs/guides/networks-and-environments.mdx

[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/concepts/dust-architecture (at 377:420) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/getting-started/quickstart (at 18:433) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/acquire-tokens (at 381:211) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/acquire-tokens (at 465:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/configure-providers (at 277:148) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/configure-providers (at 415:103) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/configure-providers (at 464:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/generating-dust-programmatically (at 381:322) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/making-decision-on-contract-updatability (at 451:130) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/run-proof-server (at 25:63) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/run-proof-server (at 463:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/security-best-practices (at 455:134) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/security-best-practices (at 466:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/security-best-practices#pre-deployment-security-checklist (at 450:64) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/node-endpoints (at 461:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/relnotes/network (at 460:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tokens/overview (at 377:354) | File not found. Check if file exists and path is correct

Errors in docs/guides/security-best-practices.mdx

[ERROR] error: (at 642:3) | Cannot resolve root-relative link '/sdks/community/openzeppelin-compact-contracts': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/reference/explicit-disclosure (at 215:368) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/reference/explicit-disclosure (at 641:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/smart-contract-security (at 17:362) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/smart-contract-security (at 26:71) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/smart-contract-security (at 639:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/smart-contract-security#input-validation-and-access-control (at 304:46) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/compact/test-and-debug (at 643:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/concepts/how-midnight-works/keeping-data-private (at 640:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/concepts/how-midnight-works/keeping-data-private#the-commitmentnullifier-pattern (at 469:328) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/getting-started/hello-world (at 23:76) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/getting-started/installation (at 24:7) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/configure-providers (at 644:3) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/making-decision-on-contract-updatability (at 634:127) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tokens/shielded-token (at 113:295) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/bboard/smart-contract (at 469:452) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/bship/test-suite (at 626:131) | File not found. Check if file exists and path is correct

Errors in docs/nodes/node-endpoints.mdx

[ERROR] error: (at 211:40) | Cannot resolve root-relative link '/files/Insomnia_collection_2026-04-20.json': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 244:1) | Cannot resolve root-relative link '/img/insomnia_app.gif': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/guides/networks-and-environments (at 105:216) | File not found. Check if file exists and path is correct
[ERROR] https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.mainnet.midnight.network#/explorer (at 138:14) | Cannot find fragment
[ERROR] https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.preprod.midnight.network#/explorer (at 127:14) | Cannot find fragment
[ERROR] https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.preview.midnight.network#/explorer (at 116:14) | Cannot find fragment

Errors in docs/tutorials/bboard/bboard-cli-implementation.mdx

[ERROR] error: (at 1077:115) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 68:66) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/bboard/bboard-api-implementation (at 20:54) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/bboard/bboard-cli#run-the-cli (at 1116:66) | File not found. Check if file exists and path is correct

Errors in docs/tutorials/zk-loan/attestation-api.mdx

[ERROR] error: (at 481:139) | Cannot resolve root-relative link '/compact/reference/explicit-disclosure': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 492:25) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 495:5) | Cannot resolve root-relative link '/guides/run-proof-server': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 510:75) | Cannot resolve root-relative link '/relnotes/support-matrix': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/cli (at 372:155) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/cli (at 528:121) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/cli (at 536:6) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 16:1) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 179:169) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 26:49) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 477:241) | File not found. Check if file exists and path is correct

Errors in docs/tutorials/zk-loan/cli.mdx

[ERROR] error: (at 104:329) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 114:34) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 1739:78) | Cannot resolve root-relative link '/guides/networks-and-environments#running-a-local-network': To resolve root-relative links in local files, provide a root dir
[ERROR] error: (at 994:299) | Cannot resolve root-relative link '/concepts/how-midnight-works/midnight-combined-model': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/attestation-api (at 104:264) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/attestation-api (at 16:91) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/attestation-api (at 26:43) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/attestation-api (at 343:274) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 108:145) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 16:4) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 1753:36) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 26:12) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 285:80) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 30:177) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 38:252) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/tutorials/zk-loan/smart-contract (at 517:137) | File not found. Check if file exists and path is correct

Errors in sdks/official/midnight-js.mdx

[ERROR] error: (at 282:133) | Cannot resolve root-relative link '/api-reference/dapp-connector': To resolve root-relative links in local files, provide a root dir
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/guides/run-proof-server (at 27:77) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/relnotes/support-matrix (at 120:22) | File not found. Check if file exists and path is correct
[ERROR] file:///home/runner/work/midnight-docs/midnight-docs/sdks/official/wallet-developer-guide (at 213:176) | File not found. Check if file exists and path is correct
[ERROR] http://localhost:6300/ (at 155:17) | Connection refused - server may be down or port blocked
[ERROR] http://localhost:8088/api/v4/graphql (at 152:13) | Connection refused - server may be down or port blocked

Redirects per input

Redirects in docs/guides/acquire-tokens.mdx

Rewrite the lead paragraphs of the networks and security guides so the concept/procedure/reference module taxonomy stays authoring vocabulary; readers see plain sections.

…ding Scope the setNetworkId sentence to what the SDK source actually does (only the contracts package reads the network ID at runtime, for address normalization and transaction building); apply the same fix to the configure-providers guide it was inherited from. Tighten the mainnet funding step to say Cardano reward address, matching RegistrationData in the cnight-observation pallet.

Fold midnight-local-network.mdx into the assembly as a Running a local network procedure (verified against a live local stack: node 1.0.0, indexer 4.3.3, proof server 8.1.0) and a troubleshooting reference that adds the indexer first-start race observed during verification. Drop the stale pinned-version tables in favor of standalone.yml, correct the funding menu text to match the tool source, repoint every inbound link, and redirect both old routes without creating chains.

oduameh · 2026-08-05T11:07:30Z

Update: the Midnight local network guide is now merged into this assembly as the Running a local network procedure and Local network troubleshooting reference (see the updated PR description).

oduameh requested review from a team as code owners August 5, 2026 09:46

github-actions Bot reviewed Aug 5, 2026

View reviewed changes

vercel Bot deployed to Preview August 5, 2026 09:52 View deployment

docs: keep modular-docs vocabulary out of reader-facing prose

8ecb07f

Rewrite the lead paragraphs of the networks and security guides so the concept/procedure/reference module taxonomy stays authoring vocabulary; readers see plain sections.

github-actions Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread docs/guides/networks-and-environments.mdx

vercel Bot deployed to Preview August 5, 2026 10:16 View deployment

github-actions Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread docs/guides/networks-and-environments.mdx

vercel Bot deployed to Preview August 5, 2026 10:38 View deployment

github-actions Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread docs/guides/networks-and-environments.mdx

Comment thread docs/guides/networks-and-environments.mdx

Comment thread docs/guides/networks-and-environments.mdx

vercel Bot deployed to Preview August 5, 2026 11:07 View deployment

oduameh requested review from Olanetsoft and nstanford5 August 5, 2026 11:14

oduameh added the IN PROGRESS Actively being worked label Aug 5, 2026

Merge branch 'main' into docs/networks-and-environments

9511bda

vercel Bot deployed to Preview August 7, 2026 10:20 View deployment

Merge branch 'main' into docs/networks-and-environments

86c5f12

vercel Bot deployed to Preview August 7, 2026 10:52 View deployment

Merge branch 'main' into docs/networks-and-environments

00274ee

vercel Bot deployed to Preview August 7, 2026 11:00 View deployment

oduameh merged commit e709795 into main Aug 7, 2026
12 of 13 checks passed

oduameh deleted the docs/networks-and-environments branch August 7, 2026 11:03

Navigation Menu

Uh oh!

docs: add networks and environments guide - #1179

docs: add networks and environments guide#1179
oduameh merged 7 commits into
mainfrom
docs/networks-and-environments

oduameh commented Aug 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oduameh commented Aug 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

oduameh commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Update: local network guide merged into the assembly

Uh oh!

vercel Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Errors per input

Errors in docs/guides/acquire-tokens.mdx

Errors in docs/guides/configure-providers.mdx

Errors in docs/guides/networks-and-environments.mdx

Errors in docs/guides/security-best-practices.mdx

Errors in docs/nodes/node-endpoints.mdx

Errors in docs/tutorials/bboard/bboard-cli-implementation.mdx

Errors in docs/tutorials/zk-loan/attestation-api.mdx

Errors in docs/tutorials/zk-loan/cli.mdx

Errors in sdks/official/midnight-js.mdx

Redirects per input

Redirects in docs/guides/acquire-tokens.mdx

Redirects in docs/guides/configure-providers.mdx

Redirects in docs/guides/networks-and-environments.mdx

Redirects in docs/guides/security-best-practices.mdx

Redirects in docs/tutorials/bboard/bboard-cli-implementation.mdx

Redirects in docs/tutorials/zk-loan/attestation-api.mdx

Redirects in docs/tutorials/zk-loan/cli.mdx

Redirects in sdks/official/midnight-js.mdx

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oduameh commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

oduameh commented Aug 5, 2026 •

edited

Loading

vercel Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading

oduameh commented Aug 5, 2026 •

edited

Loading