> For the complete documentation index, see [llms.txt](https://nimiq-top.gitbook.io/nimiq-top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nimiq-top.gitbook.io/nimiq-top/ntmp/overview.md). # Overview **Status:** Draft 0.1\ **Date:** 2026-08-27 NTMP (Nimiq Transaction Messaging Protocol) turns the Nimiq blockchain into a standardized asynchronous message transport. Requests, responses, and all associated protocol data are conveyed exclusively through Nimiq Basic Transactions. Client and service neither need to be online at the same time nor ever need to open a direct network connection to each other. ## 1. What Does NTMP Mean? **NTMP** stands for **Nimiq Transaction Messaging Protocol**. NTMP is not a new blockchain or consensus mechanism. It is an application protocol that uses existing Nimiq transactions and their security properties as a communication medium. ## 2. Motivation Nimiq is currently used mainly as a payment network in applications: a transaction transfers Luna or NIM from one address to another. A Basic Transaction can, however, carry up to 64 bytes of additional data. This field can contain not only a payment reference, but also a small part of a standardized message. A blockchain has several useful properties for asynchronous communication: * An included and finalized transaction is cryptographically verifiable, ordered, and cannot be modified later without detection. * A message is not held only by a single application server; it is replicated as part of the blockchain history. * A recipient does not have to be reachable when a message is sent. It can find and process relevant transactions for its address later. * Transaction hashes, block positions, and finality provide stable public references for message boundaries, correlation, deduplication, and receipts. * Once published, a record remains anchored in the chain history and can be retrieved again from different places and devices, provided a sufficiently complete history source is available. Nimiq's browser support is the decisive advantage for NTMP. With the built-in Nimiq Web Client, a web application can participate in the network, inspect chain data, and create, sign, send, and observe transactions without depending on a publicly accessible centralized blockchain RPC. A browser-only application can therefore use Nimiq not merely for monetary transactions, but as a shared, globally reachable communication medium. In addition, Nimiq's one-second block time means that a message can potentially reach its recipient within only a few seconds. The blockchain provides integrity, native transaction sender control, temporal ordering, replication, and tamper detection. It does **not provide confidentiality automatically**. Unencrypted transaction data is globally readable and remains permanently visible. End-to-end confidentiality, session authentication, and downgrade protection are provided only by the higher NTMP cryptographic layers. The chain also does not guarantee that every lightweight client retains the complete history locally without limit. Applications that remain offline for long periods may additionally require their own History Node or a trust-minimized indexer. Such infrastructure helps locate historical transactions; it is not a direct communication channel between client and service. ## 3. What NTMP Enables NTMP can be used as anything from a small fragmentation standard to a complete communication stack. In particular, it enables: * arbitrary short binary messages that are canonically split across multiple transactions when they exceed 64 bytes, then reconstructed reliably; * unambiguous message boundaries through an exclusive Message Address, a start transaction hash, and a final commit hash; * public, signed, or otherwise authenticated records; * end-to-end-encrypted messages and logically long-lived sessions; * asynchronous request/reply, service calls, receipts, rejections, and idempotent processing; * offline-capable inboxes, restart recovery, retries, and reorg handling; * messenger-like communication without an open socket connection; * client-funded responses, preventing a public service from being forced to produce large unfunded responses to small requests; * encrypted Service Discovery with cryptographically bound price offers in the future. A developer does not have to implement the entire stack. An application can use only the standardized Fragment Transport, combine Fragment Transport with Message Commits, or build complete encrypted sessions and request/reply semantics on top. ## 4. What NTMP Deliberately Is Not NTMP is not a universal replacement for conventional Internet protocols: * It is not a real-time TCP stream and holds no physical connection open. Latency and delivery depend on block production, finality, and history access. * It is not intended for large files, video, high-frequency events, or unbounded data streams. Large content belongs off-chain; NTMP can anchor its cryptographic hash. * Encryption does not conceal senders, recipients, transaction counts, values, timing, or approximate message sizes. * Published transactions cannot be removed from blockchain history. A local “delete message” feature cannot change that property. * Account pruning at a zero Luna balance removes temporary account state, but not historical transactions. * The current X25519 MVP is not post-quantum secure. `TODO(PQ-MIGRATION)` remains a prerequisite for making such a security claim. * A fee of 0 and today's network parameters are not assumed to be permanent; `TODO(FEE-MODEL)` remains part of the design. NTMP is deliberately designed to use the blockchain responsibly: low default limits, a minimal transaction count, no additional cover transactions by default, and complete draining of temporary addresses under honest conditions to reduce Account Tree state. ## 5. What This Documentation Defines The specification progresses from a small, independently usable transport rule to the complete protocol: 1. Common canonical binary encoding and the Nimiq transaction profile. 2. Safe, standardized fragmentation of an opaque message across multiple transactions. 3. Reconstruction despite out-of-order retrieval, retries, duplicates, and unrelated transactions. 4. Message Addresses, commit/abort operations, unambiguous start/end markers, and account cleanup. 5. Chain reliability including finality, reorgs, a persistent outbox, and restart recovery. 6. Negotiation of rendezvous, session, and response addresses, plus recoverable Nimiq keys. 7. Sessions with authenticated and encrypted messages, rekeying, and recovery profiles. 8. Higher-level request/reply semantics with correlation, idempotency, response budgets, and structured errors. 9. Future Service Discovery, prekeys, and cryptographically bound price offers. ### Documents and Responsibilities | Document | Responsibility | Status | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------- | | [Core Encoding](/nimiq-top/ntmp/core-encoding.md) | common binary encoding, `CompactUint`, and parser rules | Draft Candidate | | [Nimiq Chain Profile v1](/nimiq-top/ntmp/chain-profile-v1.md) | permitted Nimiq transactions, values, fees, history, and Account Tree behavior | Draft Candidate | | [Fragment Transport v1](/nimiq-top/ntmp/fragment-transport-v1.md) | splitting and reconstructing opaque bytes at exactly one exclusive address | Draft Candidate | | [Message Envelope](/nimiq-top/ntmp/message-envelope.md) | Message Address, commit/abort, boundaries, content class, and cleanup | Draft Candidate | | [Chain Reliability](/nimiq-top/ntmp/chain-reliability.md) | finality, reorgs, retries, restart recovery, and outbox | Draft | | [Routing and Keys](/nimiq-top/ntmp/routing-and-keys.md) | rendezvous/session addresses, Hub authorization, and key derivation | Draft | | [Session Crypto](/nimiq-top/ntmp/session-crypto.md) | X25519 MVP, AEAD, rekeying, recovery profiles, and PQ migration | Draft | | [Request/Reply](/nimiq-top/ntmp/request-and-reply.md) | correlation, idempotency, funding, responses, and rejection | Draft | | [Service Discovery](/nimiq-top/ntmp/service-discovery.md) | future discovery, catalog, and pricing protocols | `TODO(SERVICE-DISCOVERY)` | The terms **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are normative. A document with `Draft` status may still change incompatibly before version 1.0. ## 6. Layers ``` Request/Reply and future Service Discovery | authenticated inner record | Session Crypto and Routing/Keys | Message Envelope with Commit/Abort | opaque Fragment Transport | Nimiq Chain Profile v1 ``` ![NTMP protocol layers from the Nimiq Chain Profile through Request/Reply, including metadata that remains public](https://content.gitbook.com/content/JWc8aVqhn1UZpMF4rZPd/blobs/KYwlBrD3iqwFZVMGNpkH/assets/protocol-layers.svg) Each layer interprets only its own fields. In particular, Fragment Transport has no knowledge of sessions, encryption, requests, Message Commits, or application types. ## 7. Production Message Flow A fresh Basic Address `M`, controlled by the sender, is used for every higher-level message: ``` Payer P -- Fragment 0 .. n-1 ----------------------> Message Address M Message Address M -- MESSAGE_COMMIT, remaining funds --> Session Inbox R ``` 1. The higher layer serializes and, where applicable, encrypts a record. 2. Fragment Transport writes canonically indexed parts to the exclusive Message Address `M`. 3. After sufficient inclusion, `M` sends exactly one `MESSAGE_COMMIT` to the stable recipient address `R`. 4. The commit identifies the start transaction hash, fragment count, and a payload commitment. After finality, its own transaction hash is the public message ID and end marker. 5. The commit transfers the entire spendable balance from `M`. Under honest conditions, the account state for `M` becomes zero and is removed from the current Account Tree. Address `M` is the exclusive namespace for the message. The production profile therefore has no additional `message_id` or `record_id`. Fragment indices remain necessary because chain, broadcast, and retrieval order do not define payload order. ## 8. Cross-Layer Invariants * Basic Transactions contain at most 64 bytes of data. * All counts and sizes are checked against hard semantic limits before scanning, allocation, decryption, or decompression. * A wire-representable size is never automatically a permitted payload size. * Unrelated transactions and dust are not interpreted as fragments. * State-changing requests are idempotent; the finalized request commit hash is their stable key. * Encrypted profiles process no plaintext before successful authentication of the complete AEAD payload. * A security profile must never be silently downgraded to cleartext or a weaker suite. * Temporary address keys remain available at least until a final commit or abort, a reorg safety margin, and a verified zero balance. * NTMP minimizes transaction count and account state. Cover traffic or padding to additional transactions is not the default. ## 9. Current Implementation Status The browser prototype uses the built-in Nimiq Web Client, fixed test configuration, and X25519. It already demonstrates compact fragments and encrypted sequential requests, but does not yet implement the production `MESSAGE_ADDRESS_COMMIT` profile. Shared-inbox variants remain documented as experiments and are not declared the production v1 target. **TODO(PQ-MIGRATION):** The X25519 MVP is not post-quantum secure. Before making a PQ production claim, the ML-KEM hybrid profile, downgrade protection, test vectors, and an independent review must be implemented. **TODO(FEE-MODEL):** The current test profile assumes a fee of 0 Luna. All budgets and serializations must be prepared for variable future fees. **TODO(SERVICE-DISCOVERY):** Until encrypted in-session discovery is defined, the rendezvous address, service, and X25519 public key remain statically configured. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nimiq-top.gitbook.io/nimiq-top/ntmp/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.