docs: document non-ledger transactions and classification#980
Conversation
Augment the network-architecture transactions page with the transaction format classification vocabulary, the ledger/non-ledger ownership boundary, and a reference of the node-owned non-ledger transaction categories (system transaction, timestamp, unknown, cNIGHT observation, bridge transfer) plus a mention of the consensus inherents. The classification is framed as an off-node vocabulary consumed through runtime metadata, not an in-node dispatch mechanism, and the bridge transfer is presented as an inherent that produces a system transaction. Assisted by AI
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| The Midnight node supports the standard Polkadot SDK transaction format, but these default-style transactions are uncommon in practice. Midnight relies on a proof-based verification model that is tightly coupled with the Midnight Ledger design. | ||
|
|
||
| A block is an ordered list of extrinsics. As on any [Substrate](/concepts/network-architecture/onchain-logic) chain, those extrinsics fall into two kinds: transactions that users or tooling submit into the transaction pool, and inherents that the block author injects directly (no signature, not gossiped) and every other node re-checks. Midnight layers a second distinction on top of this — between ledger transactions and non-ledger transactions — which this page describes. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inherents'?
| - `UnknownTx` — any transaction the classifier does not recognize, such as a future or unknown variant. | ||
|
|
||
| :::info | ||
| This classification is a vocabulary for off-node consumers. Indexers, the toolkit, and other downstream tooling read it through runtime metadata to label a decoded transaction. The node does **not** match on these categories to decide how to process a transaction — dispatch happens through the runtime's pallet calls and inherents, not through this enumeration. An earlier `TransactionType` enumeration carried an optional decoded transaction; `TransactionTypeV2` supersedes it by carrying the full decode result, so a consumer can see why a payload failed to decode. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'runtime's'?
| - `UnknownTx` — any transaction the classifier does not recognize, such as a future or unknown variant. | ||
|
|
||
| :::info | ||
| This classification is a vocabulary for off-node consumers. Indexers, the toolkit, and other downstream tooling read it through runtime metadata to label a decoded transaction. The node does **not** match on these categories to decide how to process a transaction — dispatch happens through the runtime's pallet calls and inherents, not through this enumeration. An earlier `TransactionType` enumeration carried an optional decoded transaction; `TransactionTypeV2` supersedes it by carrying the full decode result, so a consumer can see why a payload failed to decode. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inherents'?
|
|
||
| ### System transaction | ||
|
|
||
| A system transaction applies a state change to the ledger through a privileged, audited channel rather than through the user transaction pool. Governance submits it with root origin, and the node gates it against an allow-check before applying it, so only the system transactions governance is permitted to run reach the ledger. When the node applies one, it emits a `SystemTransactionApplied` event that carries the transaction hash and its serialized form, which lets an indexer correlate the effect on the ledger with the originating call. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Midnight.SecondPerson] Address the reader directly using 'you'.
|
|
||
| ### Timestamp | ||
|
|
||
| The block author supplies the block timestamp as an inherent, and the standard timestamp pallet applies it. The classification vocabulary surfaces it as `TimestampTx`, so a downstream decoder can read the block's timestamp as a first-class transaction value. The timestamp is not a separately submitted transaction; it is the classification of the inherent's value. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inherent's'?
|
|
||
| A bridge transfer moves tokens from Cardano to Midnight. It is **not** a user-submittable transaction and is not a peer of a ledger transaction. The block author injects the observed Cardano transfer as an inherent; the bridge handler then validates it against the approved-transfers list (single-use, to prevent replay), constructs the corresponding ledger system transaction, and applies it through the system transaction path. | ||
|
|
||
| The net effect on the ledger therefore arrives as a system transaction, while the bridge emits its own event (such as a user transfer, reserve transfer, or invalid transfer) so that an indexer can correlate the Cardano-side movement with the Midnight-side result. Model a bridge transfer as an inherent that produces a system transaction, never as a standalone transaction type. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Midnight.Repitition] 'a' is repeated!
|
|
||
| The net effect on the ledger therefore arrives as a system transaction, while the bridge emits its own event (such as a user transfer, reserve transfer, or invalid transfer) so that an indexer can correlate the Cardano-side movement with the Midnight-side result. Model a bridge transfer as an inherent that produces a system transaction, never as a standalone transaction type. | ||
|
|
||
| ## Consensus inherents |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inherents'?
|
|
||
| ## Consensus inherents | ||
|
|
||
| Beyond the categories above, the block author also injects consensus inherents that the Cardano Partner-Chains SDK supplies — the AURA slot, the main-chain hash, and authority selection. These are consensus infrastructure rather than Midnight transaction categories; see [onchain logic and state](/concepts/network-architecture/onchain-logic) and [consensus](/concepts/network-architecture/consensus) for how they fit block production and finality. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inherents'?
|
|
||
| ## Consensus inherents | ||
|
|
||
| Beyond the categories above, the block author also injects consensus inherents that the Cardano Partner-Chains SDK supplies — the AURA slot, the main-chain hash, and authority selection. These are consensus infrastructure rather than Midnight transaction categories; see [onchain logic and state](/concepts/network-architecture/onchain-logic) and [consensus](/concepts/network-architecture/consensus) for how they fit block production and finality. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'onchain'?
🚀 Preview Deployment✅ Deployment Ready 🔗 Preview URL: https://pr-980-midnight-docs.vercel.app 📝 Latest commit: This preview updates automatically when you push new commits to this PR. |
Add the Substrate domain terms inherent/inherents and the house spelling onchain to the Midnight vocabulary accept-list, and reword the ledger-ownership sentence into the active voice. The remaining spelling and style alerts are false positives left as-is: legitimate possessives, a compound noun, the alpha repetition rule, and a passive construction that accurately describes a system-imposed constraint. Assisted by AI
|
I went through the eleven Vale alerts and pushed a follow-up commit (0bcee43). The spelling alerts on inherent, inherents, and onchain are legitimate domain vocabulary rather than typos, so I added those terms to the Midnight accept-list, which is how this repo already handles words like extrinsic and Substrate. Worth noting the repo config disables the spelling style outright, so these alerts came from the action's default rules rather than house policy. Onchain in particular is already in active use as the title of the sibling onchain-logic page. I also took the active-voice suggestion on the ledger-ownership sentence and reworded it, which reads better with no loss of meaning. I left the rest as-is. The runtime possessive is just standard English that the default speller flagged on the apostrophe. The repetition alert does not correspond to an actual repeated word on that line; it is the experimental alpha rule misfiring. And the second-person and remaining active-voice alerts both land on a sentence where the passive is doing real work: the user transaction pool is a compound noun rather than the reader being addressed, and describing what governance is permitted to run is an accurate way to state a system-imposed gating constraint that an active rewrite would distort. Posted by an agent on behalf of Mike Clay. |
| | --- | --- | --- | --- | --- | | ||
| | Ledger transaction | User or tooling (pool) | Unsigned, proof-validated | `pallet-midnight` (envelope) | Ledger events (contract call, deploy, applied) | | ||
| | System transaction | Governance | Root, governance-gated | `pallet-midnight-system` | `SystemTransactionApplied` event | | ||
| | Timestamp | Block author (inherent) | Inherent | `pallet-timestamp` | Classified as `TimestampTx` | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Terms] Use 'inherent' instead of 'Inherent'.
| | System transaction | Governance | Root, governance-gated | `pallet-midnight-system` | `SystemTransactionApplied` event | | ||
| | Timestamp | Block author (inherent) | Inherent | `pallet-timestamp` | Classified as `TimestampTx` | | ||
| | Unknown | Classifier fallback | None (off-node label) | classification vocabulary | Decoded as `UnknownTx` | | ||
| | cNIGHT observation | Block author (inherent) | Inherent | `pallet-cnight-observation` | Recorded Cardano token movements | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Terms] Use 'inherent' instead of 'Inherent'.
| | Timestamp | Block author (inherent) | Inherent | `pallet-timestamp` | Classified as `TimestampTx` | | ||
| | Unknown | Classifier fallback | None (off-node label) | classification vocabulary | Decoded as `UnknownTx` | | ||
| | cNIGHT observation | Block author (inherent) | Inherent | `pallet-cnight-observation` | Recorded Cardano token movements | | ||
| | Bridge transfer | Block author (inherent), then system transaction | Inherent, then root path | `pallet-c2m-bridge` | Bridge transfer event plus a system transaction | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Terms] Use 'inherent' instead of 'Inherent'.
nstanford5
left a comment
nstanford5
left a comment
There was a problem hiding this comment.
@m2ux commits need verified signatures
2 participants
Summary
Augments the network-architecture transactions page to document the Midnight transaction format, its classification vocabulary, and the node-owned non-ledger transaction categories. This is the docs-site half of the work for midnightntwrk/midnight-node#1533; the rustdoc half lands in midnightntwrk/midnight-node#1619.
What changed
TransactionTypeV2as an off-node vocabulary consumed through runtime metadata, not an in-node dispatch mechanism.:::infoadmonition linking the ledgers concept page and the ledger API reference.Verification
Docusaurus build, Vale, markdown link-check, and Prettier run as the repo's CI gates.
Assisted by AI