docs: document non-ledger transactions (#1533)#1619
Open
m2ux wants to merge 5 commits into
Open
Conversation
Closes #1533 Scaffold commit for the work package to document the Midnight transaction format and the node's non-ledger transaction types in the Midnight docs. Documentation commits will follow. Signed-off-by: Mike Clay <mike.clay@shielded.io>
Add crate-level and item-level rustdoc across the node-owned non-ledger transaction surface: - midnight-primitives: crate doc; TransactionType/TransactionTypeV2 type and variant docs framing the classification as an off-node vocabulary consumed through metadata, not in-node dispatch, plus the V1 to V2 evolution; MidnightSystemTransactionExecutor and BridgeRecipient docs. - pallet-midnight: crate doc; send_mn_transaction doc with the ledger/non-ledger boundary and an Errors section; remove the stale scaffold and todo comments. - pallet-midnight-system: crate doc; send_mn_system_transaction doc with the root and governance gate and an Errors section; SystemTransactionApplied event docs. - pallet-cnight-observation: process_tokens inherent-path doc. - pallet-c2m-bridge: cross-link the bridge handler to the system transaction seam, framing a bridge transfer as an inherent that produces a system transaction. Documentation only; no code logic changed. Assisted by AI Signed-off-by: Mike Clay <mike.clay@shielded.io>
justinfrevert
previously approved these changes
Jun 5, 2026
Co-authored-by: justinfrevert <81839854+justinfrevert@users.noreply.github.com> Signed-off-by: Mike Clay <176900785+m2ux@users.noreply.github.com>
Contributor
Author
|
/bot rebuild-metadata |
Contributor
|
❌ Metadata rebuild failed. Check the workflow logs for details. |
Contributor
Author
|
/bot rebuild-metadata |
Contributor
|
❌ Metadata rebuild failed. Check the workflow logs for details. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Document the Midnight transaction format and the node's non-ledger transaction types across two surfaces: the public Midnight docs site and the node's crate documentation (rustdoc). Ledger-transaction internals are delegated to the ledger team; this work covers the node-owned non-ledger surface.
🐛 Issue 📐 Engineering
Motivation
The Midnight node accepts several categories of transactions. The ledger-side transactions are documented reasonably well, but the node-defined non-ledger transaction types — and the overall transaction format that ties them together — are under-documented in the public docs and in the crates themselves. Integrators, partner teams, and newer engineers currently have to read the source to understand what the node accepts and how those transactions are structured.
In line with shieldedtech/product#40, this work improves the documentation around the transaction format and the non-ledger transaction types the node provides, giving consumers a single trustworthy reference and reducing integration mistakes and support load.
Changes
Two surfaces:
midnight-docs, separate PR) — Expand the existingnetwork-architecture/transactions.mdx: a transaction-format/classification spine, an explicit ledger/non-ledger boundary with a:::infodeferral to the ledger team, and a per-category reference table (system transaction, timestamp, unknown, cNIGHT observation, bridge transfer). Consensus inherents are mentioned only, with a pointer toonchain-logic.//!docs forprimitives/midnight,pallets/midnight, andpallets/midnight-system; item docs for theTransactionType*classification enums and variants,send_mn_transaction,send_mn_system_transaction,SystemTransactionApplied,MidnightSystemTransactionExecutor, andBridgeRecipient. Thec2m-bridgecrate is the in-repo template and is preserved/cross-linked.📌 Submission Checklist
🔱 Fork Strategy
🗹 TODO before merging