[slowbackspace]

Summary

The Midnight docs were last updated for indexer 4.0 (midnight-indexer-api.graphql was 1132 lines). Ops master deploys indexer 8036abb, whose schema-v4.graphql is byte-identical to the v4.4.0-rc.5 tag (2558 lines). This updates the docs to match.

• Schema: replaced midnight-indexer-api.graphql with the deployed one. Nothing breaks for existing queries. There are 45 new types (bridge, contract events, DUST generations, Merkle tree updates), new queries and subscriptions, and several deprecations (fees → fee, merkleTreeRoot/startIndex/endIndex → zswap*, collapsedMerkleTree → zswapCollapsedUpdate, highest*EndIndex → highest*ZswapEndIndex). SpectaQL already renders the deprecations.
• Beta marking: SpectaQL ignores custom directives, so the 59 @beta items would have rendered as stable API. src/scripts/midnight-docs-schema.ts runs in build:midnight-docs. It writes a docs-only copy of the schema to .cache/spectaql/ with a "Beta:" note on each @beta item. The schema published at docs/midnight/midnight-indexer-api.graphql stays identical to upstream. graphql is added as a devDependency (it was only a transitive dependency of SpectaQL).
• bridgeEvents subscription hidden: on Blockfrost mainnet and preprod, every bridgeEvents subscription closes with 4006 (the upstream's 1006, rewritten by @fastify/http-proxy in vindler) before sending any event. The script drops it from the docs-only schema, and it isn't mentioned in the prose. The HTTP bridgeEvents query works and stays documented.
• Examples fixed: two examples did not validate against the old schema or the new one:
  • The transaction query used fees { paidFees estimatedFees } on the Transaction interface. It now uses ... on RegularTransaction { fee }.
  • The shielded subscription used sendProgressUpdates, ViewingUpdate and highestIndex, none of which exist. It is rewritten around RelevantTransaction / ShieldedTransactionsProgress.
• New prose:
  • The version is now stated as v4.4, with a note on beta items.
  • connect(options: { startIndex }) and the index resume argument.
  • The new subscriptions: both nullifier subscriptions, plus the beta contractEvents, dustGenerations, bridgePoolUpdates and bridgeBalance.
  • A "WebSocket Close Codes" section covering 4004/4005/4006 (1004/1005/1006 rewritten by the proxy) and vindler's own 4429 (Rate limit exceeded) and 1013 (WebSocket send queue exceeded).
• Cleanup: removed src/schemas/midnight/*.yaml. Nothing references them since src/paths/midnight was removed, and the yarn bundle output is unchanged without them.
• README: added the missing download command for the schema and documented the beta preprocessing step.

Upstream main also adds stateAt on Contract/contract actions and a BlockReference type. These aren't deployed yet, so they aren't included.

Testing

• yarn bundle: openapi.yaml, openapi.json and blockfrost-openapi.yaml are unchanged. yarn tsc --noEmit is clean and vitest passes (42/42).
• Introspected midnight-mainnet.blockfrost.io: all 709 type, field, argument and enum signatures match the pinned schema.
• Ran every example in spectaql.yaml against mainnet:
  • All HTTP examples return data.
  • The blocks subscription works with both header and ?project_id= auth.
  • The full shielded flow works with a freshly generated mainnet viewing key: connect with and without options.startIndex, the documented shieldedTransactions query returns ShieldedTransactionsProgress events, then disconnect.
• Smoke-tested the listed subscriptions:
  • contractActions, dustLedgerEvents, zswapLedgerEvents, bridgePoolUpdates and bridgeBalance emit events.
  • The nullifier subscriptions finish after toBlock.
  • Not tested live: unshieldedTransactions and dustGenerations, because no suitable address was found.

[vercel]

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

Project	Deployment	Actions	Updated
openapi	Ready	Preview	Oct 27, 2026 10:44am UTC

[Copilot]

🟡 Changes recommended

Unescaped $sid references break the rendered GraphQL example, while incomplete subscription recovery guidance can cause invalid queries or false expectations of replay.

2 open issues

• Document valid recovery cursors for each subscription · New
• Escape unset sid variables in rendered GraphQL documentation · New

What changed in this PR

Updates Blockfrost’s Midnight API documentation to the deployed indexer v4.4 schema, keeping the downloadable schema unchanged from upstream.

Changes:

• Refreshes the schema with new APIs and deprecations, adds visible beta labels, and hides the unsupported bridgeEvents subscription from rendered docs.
• Updates examples, subscription guidance, WebSocket close codes, and schema-update instructions.
• Removes unused Midnight OpenAPI schemas and integrates schema preprocessing into the documentation build.

File	Description
yarn.lock	Locks the new direct GraphQL dependency.
src/​scripts/​midnight-docs-schema.ts	Adds beta labels and filters unsupported documentation fields.
src/​schemas/​midnight/​zswap_ledger_event.yaml	Removes unused Zswap event schema.
src/​schemas/​midnight/​unshielded_utxo.yaml	Removes unused unshielded UTXO schema.
src/​schemas/​midnight/​transaction.yaml	Removes unused transaction schema.
src/​schemas/​midnight/​transaction_result.yaml	Removes unused transaction result schema.
src/​schemas/​midnight/​transaction_fees.yaml	Removes unused transaction fee schema.
src/​schemas/​midnight/​system_parameters.yaml	Removes unused system parameters schema.
src/​schemas/​midnight/​graphql_request.yaml	Removes unused GraphQL request schema.
src/​schemas/​midnight/​graphql_error.yaml	Removes unused GraphQL error schema.
src/​schemas/​midnight/​dust_output.yaml	Removes unused DUST output schema.
src/​schemas/​midnight/​dust_ledger_event.yaml	Removes unused DUST ledger event schema.
src/​schemas/​midnight/​dust_generation_status.yaml	Removes unused DUST generation status schema.
src/​schemas/​midnight/​d_parameter.yaml	Removes unused D-parameter schema.
src/​schemas/​midnight/​d_parameter_change.yaml	Removes unused D-parameter history schema.
src/​schemas/​midnight/​contract_deploy.yaml	Removes unused contract deployment schema.
src/​schemas/​midnight/​contract_balance.yaml	Removes unused contract balance schema.
src/​schemas/​midnight/​contract_action.yaml	Removes unused contract action schema.
src/​schemas/​midnight/​block.yaml	Removes unused block schema.
spectaql.yaml	Uses the processed schema and updates API guidance and examples.
README.md	Documents schema downloading and beta preprocessing.
package.json	Integrates preprocessing and adds GraphQL as a dev dependency.
midnight-indexer-api.graphql	Updates the source schema to deployed v4.4.
docs/​midnight/​midnight-indexer-api.graphql	Updates the downloadable upstream schema.
CHANGELOG.md	Records documentation updates, example fixes, and cleanup.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues block the Midnight API documentation update.

No open issues 🎉

2 resolved since last review

• Escape unset sid variables in rendered GraphQL documentation
• Document valid recovery cursors for each subscription

_{Review effort: Balanced}