[mkdocs] docs: add listen tx flow tutorial by zero4862 · Pull Request #916 · NemProject/nem

zero4862 · 2026-06-29T11:04:55Z

Adapts Listen tx flow tutorial to NEM and documents missing websocket channels and requests.

zero4862 · 2026-06-29T11:06:38Z

 :   Notifies subscribed clients every time a new block is added to the chain.

-=== "Request body"
+=== "Frame"


Changed from "Request body" to "Frame" so that's not confused with the new "Requests" concept.

Sounds good. But I'd call the tabs "Subscription frame" and "Notification body", so it's extra clear what they are.
I would even go as far as adding :material-arrow-up-bold: and :material-arrow-down-bold: (for example) at the beginning of the tab title so the direction of each message is explicit.

zero4862 · 2026-06-29T11:07:37Z


    [TransactionMetaDataPair](../rest/nem.md#model/TransactionMetaDataPair)
+
+#### `/account/mosaic/owned/{address}`


Discovered some more websocket channels while working on this tutorial.

zero4862 · 2026-06-29T11:08:46Z

+    }
+    ```
+
+## Requests


Added a new section to document requests properly. Originally I thought the registration only existed for account channels to work, but it turns out there are a few more that push snapshots of current data to channels.

More details in https://github.com/QuantumMechanics/nem-lightwallet/tree/master/lightwallet#nis-websocket-channels-and-data

Nice finding! And good idea to give it its own section.

Again, I would mention in the intro to this section (after the definition) that all requests are made via a SEND frame,
and the destination always begins with /w/api/ (so you can remove this detail from the definition).

It's also worth mentioning that some of these requests do not receive any answer in return, and some others get an answer through any of the channels above.

zero4862 · 2026-06-29T12:38:09Z

 port.
-The SockJS endpoint is `/w/messages`, for example: `http://localhost:7778/w/messages`.
+
+## Session


Before it only covered connection + subscription, now the full cycle with "requests" taken into account.

I don't understand what a "session" is.
Is it a STOMPS or SockJS concept? Or are you just describing a typical usage session?
You need to clarify this. Maybe rename the section "Typical Usage Session" ?

segfaultxavi

I have only reviewed the WebSocket reference page.
Apologies for spending so much time reviewing such a obscure corner of the docs, but I don't like the shape it has on Symbol and decided to fix it in this review.

I'll continue now to review the rest of the PR, but wanted to submit this early.

segfaultxavi · 2026-06-30T08:55:09Z

 To get **live updates** when an event occurs on the blockchain, NEM publishes
 [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).

 Client applications can open a WebSocket connection and subscribe to any of the available channels instead of needing
 to constantly poll the [REST API](../rest/nem.md) for updates.

 When an event occurs in a channel, the <node:> sends a notification to every subscribed client in real-time.


Suggested change

NEM publishes blockchain events over

[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), so applications can receive live updates

without constantly polling the [REST API](../rest/nem.md).

Client applications open a WebSocket connection to any <node:> in the network and subscribe to the [channels](#channels)

they want to monitor.

When an event occurs on a channel, the node notifies every subscribed client in real time.

Some channels also accept [requests](#requests) for immediate data, similar to the REST API.

This can simplify applications that use WebSockets as their only API for both live notifications and on-demand updates.

In this way:

We establish the terminology we are going to use: clients SUBSCRIBE and REQUEST, nodes NOTIFY. I don't like "push" or "send" because they work in both directions so they can be ambiguous.

We introduce requests early on so they are not a surprise later, and we state their purpose.

We introduce the node upfront, otherwise, you mention "the node" and it's not clear which node is that.

segfaultxavi · 2026-06-30T08:59:39Z

 port.
-The SockJS endpoint is `/w/messages`, for example: `http://localhost:7778/w/messages`.
+
+## Session


I don't understand what a "session" is.
Is it a STOMPS or SockJS concept? Or are you just describing a typical usage session?
You need to clarify this. Maybe rename the section "Typical Usage Session" ?

segfaultxavi · 2026-06-30T09:11:05Z

+## Session
+
+The SockJS endpoint is `/w/messages`, for example `http://localhost:7778/w/messages`.
+A client that does not use SockJS can open a plain WebSocket to `/w/messages/websocket` directly.


You can't just throw the non-SockJS API here without any more information and never mention it again :D
Also, putting it in the section intro, makes it look like it is an important part of the process.

I would move all mention of the non-SockJS SPI to an info box at the end of this section AND provide more information.
So if SockJS is not used, what is the protocol? What changes? Is there anywhere the user can go to know more if they are interested in this topic?

segfaultxavi · 2026-06-30T09:30:32Z


-After opening the SockJS connection, the client drives the session with STOMP frames.
-A _frame_ is a plain-text message made of a command, optional `header:value` lines, and an optional body.
+Frame


This glossary term is global, so we risk collisions if we use too generic words.
Since this is a pretty niche usage, I would call it "STOMP Frame" instead.

The section title should probably be called "STOMP Frames" too.

Same problem with "Channel" and "Request" below, although those are probably related to WebSocket or SockJS, not STOMP.

segfaultxavi · 2026-06-30T09:53:08Z

+    !!! note "Some channels require registration"
+
+        Some channels, like [account channels](#account-channels), deliver nothing until they receive a registration
+        request.
+        A client must send this request before subscribing to the channels it enables.
+
+        See [registration requests](#registration-requests) for the full list.


Instead of making this an info box, which interrupts the flow of the session, I would make it an optional step:

Suggested change

!!! note "Some channels require registration"

Some channels, like [account channels](#account-channels), deliver nothing until they receive a registration

request.

A client must send this request before subscribing to the channels it enables.

See [registration requests](#registration-requests) for the full list.

3. Send an optional [registration request](#registration-requests) to receive notifications for channels which

do not send them automatically.

Also, we avoid "nothing", which is too strong a word.

segfaultxavi · 2026-06-30T13:35:45Z

+Request
+:   A message the client sends to a `/w/api/...` destination to make the node act once.
+    It either **registers** (a prerequisite some channels require before they deliver) or pushes a **snapshot** of
+    current data to a channel.


Suggested change

Request

: A message the client sends to a `/w/api/...` destination to make the node act once.

It either **registers** (a prerequisite some channels require before they deliver) or pushes a **snapshot** of

current data to a channel.

Request

: A message sent by the client to make the node deliver:

either notifications on channels that require **registration**,

or an immediate response containing a **snapshot** of the state of the blockchain.

I think it reads more clearly, but we can iterate.

segfaultxavi · 2026-06-30T13:39:53Z

+req:w&#47;api&#47;account&#47;subscribe
+:   Registers the address so that [account channels](#account-channels) begin delivering events.
+    It pushes nothing back to any channel.


Suggested change

req:w/api/account/subscribe

: Registers the address so that [account channels](#account-channels) begin delivering events.

It pushes nothing back to any channel.

req:w/api/account/subscribe

: Makes the node start sending notifications about the selected [account channel](#account-channels).

segfaultxavi · 2026-06-30T13:42:52Z

+Every request is **read-only**.
+It never changes the chain, only registers interest in receiving events or replays existing data.
+
+### Registration requests


I would add a short intro explaining why these are needed.

Instead of "SEND frame" I would title the code blocks ":material-arrow-up-bold: Registration frame".
Maybe even use the same table layout as above (if we decide to use it), for consistency, even when it would only have one column here.

segfaultxavi · 2026-06-30T13:46:37Z

+#### `/w/api/account/get`
+
+req:w&#47;api&#47;account&#47;get
+:   Registers the address and pushes its current state to <ws:account&#47;{address}>.


Is this exactly the same as the previous one, but triggering an immediate notification?
If so, I would explain it in this way.
Always make it explicit who is sending each message and avoid using "push" on its own.

segfaultxavi · 2026-06-30T13:47:06Z

+{ "account": "{address}" }
+```
+
+### Snapshot requests


Again, short intro explaining why these are needed.

The definitions of all requests are a bit confusing. I would begin them with something like:
"This request forces the node to send an immediate notification containing..."

Instead of "SEND frame" I would title the code blocks ":material-arrow-up-bold: Request frame".
Maybe even use the same table layout as above (if we decide to use it), for consistency, even when it would only have one column here.

segfaultxavi

Comments for the tutorial proper now.

segfaultxavi · 2026-06-30T14:06:32Z


-NODE_URL = os.getenv('NODE_URL', 'http://libertalia.nemtest.net:7778')
-print(f'Using node {NODE_URL}')
+NODE_HOST = os.getenv('NODE_HOST', 'libertalia.nemtest.net')


I understand this change simplifies creating URLs for the WebSocket tutorials, but I think this forces us to change ALL other tutorials to follow the same pattern.
Otherwise, different tutorials use different environment variables and it's a bit messy.

Do you want to apply this pattern to the rest of tutorials, including Symbol? :)

segfaultxavi · 2026-06-30T14:09:05Z

+NODE_URL = f'http://{NODE_HOST}:7890'
+WS_URL = f'http://{NODE_HOST}:7778'


Suggested change

NODE_URL = f'http://{NODE_HOST}:7890'

WS_URL = f'http://{NODE_HOST}:7778'

NODE_REST_URL = f'http://{NODE_HOST}:7890'

NODE_WS_URL = f'http://{NODE_HOST}:7778'

For consistency.

segfaultxavi · 2026-06-30T14:13:36Z

+		print(f'Connected to {WS_URL}')
+		# [<step-2]
+		# Register the account and confirm it is active [>step-3]
+		account = f'/account/{MONITOR_ADDRESS}'


Suggested change

account = f'/account/{MONITOR_ADDRESS}'

destination = f'/account/{MONITOR_ADDRESS}'

Because this is the meaning of this field for the SUBSCRIBE frame
(and this is how you called it below).

segfaultxavi · 2026-06-30T14:14:25Z

+		await stomp_subscribe(websocket, account, 'id-0')
+		await stomp_send(websocket, '/w/api/account/get',
+			json.dumps({'account': MONITOR_ADDRESS}))
+		async for raw in websocket:


Maybe raw_frame?

segfaultxavi · 2026-06-30T14:25:42Z

+To receive notifications on an account's transaction channels, the address must first be **registered** with the node.
+
+The code registers the address by sending a <req:w&#47;api&#47;account&#47;get> request, which both registers it and
+replies with the account's current state on the <ws:account&#47;{address}> channel.


Suggested change

replies with the account's current state on the <ws:account/{address}> channel.

triggers a reply containing the account's current state on the <ws:account/{address}> channel.

segfaultxavi · 2026-06-30T14:54:37Z

+					print(f'{name}: hash={message_hash[:16]}...')
+					is_match = message_hash.upper() == expected_hash
+					if name == 'confirmed' and is_match:
+						short = transaction_hash[:16]


short_hash for clarity and consistency with JS.

segfaultxavi · 2026-06-30T15:03:36Z

+To catch that reply, the code subscribes to the channel using `id-0`, then waits.
+Once the reply arrives, the registration is active and the temporary subscription is dropped.


Suggested change

To catch that reply, the code subscribes to the channel using `id-0`, then waits.

Once the reply arrives, the registration is active and the temporary subscription is dropped.

To verify that the subscription is successful, the code first temporarily subscribes to the

<ws:account/{address}> channel, sends the registration request, and waits for that reply.

Once the reply arrives, the registration is active and the temporary subscription to the

general account messages channel is dropped, using the same `id-0` used during registration.

segfaultxavi · 2026-06-30T15:50:57Z

+
+{{ tutorial.code_snippet_tagged('step-4') }}
+
+With the account registered, the code subscribes to two address-scoped channels:


Suggested change

With the account registered, the code subscribes to two address-scoped channels:

With the account's address registered, the code subscribes to two address-scoped channels:

So the connection between the account and the channels below is extra clear.

segfaultxavi · 2026-06-30T15:55:15Z

+
+{{ tutorial.code_snippet_tagged('step-5') }}
+
+This tutorial builds a minimal [Transfer Transaction](../transactions/transfer-xem.md) to the monitored address, with a


I would make this link point to the Textbook, and then, below, instead of "as usual", I would say "following the same procedure as in the Transfer Transaction Tutorial", and include the tutorial link there.

segfaultxavi · 2026-06-30T15:56:54Z

+Each message follows the [TransactionMetaDataPair](../reference/rest/nem.md#model/TransactionMetaDataPair) schema, whose
+`meta.hash.data` field holds the transaction hash.
+
+When a message from the `/transactions/{address}` channel arrives whose hash matches the announced transaction, the


Suggested change

When a message from the `/transactions/{address}` channel arrives whose hash matches the announced transaction, the

When a message from the <ws:transactions/{address}> channel arrives whose hash matches the announced transaction, the

Same in another place below.

zero4862 commented Jun 29, 2026

View reviewed changes

Comment thread mkdocs/config/mkdocs.base.yml

zero4862 commented Jun 29, 2026

View reviewed changes

zero4862 force-pushed the docs-listen-transaction-flow branch from 209c9cd to 50f1500 Compare June 29, 2026 11:15

[mkdocs] docs: listen tx flow tutorial

b936694

zero4862 force-pushed the docs-listen-transaction-flow branch from 50f1500 to b936694 Compare June 29, 2026 11:48

zero4862 added 2 commits June 29, 2026 13:16

[mkdocs] docs: adapt listen-new-blocks code to use WS_URL

8a9843a

[mkdocs] docs: simplify connection steps, move syntax to frames

95580e3

zero4862 commented Jun 29, 2026

View reviewed changes

zero4862 marked this pull request as ready for review June 29, 2026 12:45

zero4862 requested a review from segfaultxavi June 29, 2026 12:46

segfaultxavi requested changes Jun 30, 2026

View reviewed changes


		[TransactionMetaDataPair](../rest/nem.md#model/TransactionMetaDataPair)

		#### `/account/mosaic/owned/{address}`

+NEM publishes blockchain events over
+[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), so applications can receive live updates
+without constantly polling the [REST API](../rest/nem.md).
+Client applications open a WebSocket connection to any <node:> in the network and subscribe to the [channels](#channels)
+they want to monitor.
+When an event occurs on a channel, the node notifies every subscribed client in real time.
+Some channels also accept [requests](#requests) for immediate data, similar to the REST API.
+This can simplify applications that use WebSockets as their only API for both live notifications and on-demand updates.

		NODE_URL = f'http://{NODE_HOST}:7890'
		WS_URL = f'http://{NODE_HOST}:7778'

	account = f'/account/{MONITOR_ADDRESS}'
	destination = f'/account/{MONITOR_ADDRESS}'

	replies with the account's current state on the <ws:account/{address}> channel.
	triggers a reply containing the account's current state on the <ws:account/{address}> channel.

		To catch that reply, the code subscribes to the channel using `id-0`, then waits.
		Once the reply arrives, the registration is active and the temporary subscription is dropped.

-To catch that reply, the code subscribes to the channel using `id-0`, then waits.
-Once the reply arrives, the registration is active and the temporary subscription is dropped.
+To verify that the subscription is successful, the code first temporarily subscribes to the
+<ws:account&#47;{address}> channel, sends the registration request, and waits for that reply.
+Once the reply arrives, the registration is active and the temporary subscription to the
+general account messages channel is dropped, using the same `id-0` used during registration.


		{{ tutorial.code_snippet_tagged('step-4') }}

		With the account registered, the code subscribes to two address-scoped channels:

	With the account registered, the code subscribes to two address-scoped channels:
	With the account's address registered, the code subscribes to two address-scoped channels:


		{{ tutorial.code_snippet_tagged('step-5') }}

		This tutorial builds a minimal [Transfer Transaction](../transactions/transfer-xem.md) to the monitored address, with a

	When a message from the `/transactions/{address}` channel arrives whose hash matches the announced transaction, the
	When a message from the <ws:transactions/{address}> channel arrives whose hash matches the announced transaction, the

Uh oh!

Conversation

zero4862 commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

zero4862 Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

segfaultxavi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

segfaultxavi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zero4862 commented Jun 29, 2026 •

edited

Loading

zero4862 Jun 29, 2026 •

edited

Loading

zero4862 Jun 29, 2026 •

edited

Loading

zero4862 Jun 29, 2026 •

edited

Loading