コンテンツにスキップ

WebSocket⚓︎

NEM は WebSocket でブロックチェーンイベントを公開します。 そのため、REST API を常にポーリングしなくても、アプリケーションでライブ更新を受信できます。

クライアントアプリケーションは、ネットワーク内の任意の ノード へ WebSocket 接続を開き、監視したい チャネル をサブスクライブします。 チャネルでイベントが発生すると、ノードはサブスクライブしているすべてのクライアントへリアルタイムで通知します。

一部のチャネルは、REST API と同様に、即時データを取得する リクエスト も受け付けます。 これにより、WebSocket だけを API として使い、ライブ通知とオンデマンド更新の両方を処理するアプリケーションを簡単にできます。

接続⚓︎

NEM は、HTTP API のポートとは別の専用ポート（デフォルト 7778）で、SockJS 上の STOMP メッセージングプロトコルを使って WebSocket を提供します。

SockJS エンドポイントは /w/messages です。例えば http://localhost:7778/w/messages です。

クライアントは通常、SockJS クライアントライブラリまたはネイティブ WebSocket API と、メッセージングを処理する STOMP クライアントライブラリを組み合わせて接続します。

ネイティブ WebSocket で接続する

SockJS は WebSocket に似たトランスポートを提供し、クロスブラウザー対応と、ネイティブ WebSocket が利用できない場合の HTTP ベースのフォールバックを備えています。

ネイティブ WebSocket をサポートするクライアントは、SockJS の WebSocket トランスポートエンドポイント /w/messages/websocket に直接接続できます。例えば ws://localhost:7778/w/messages/websocket です。

これは SockJS サーバーを利用しながら、SockJS クライアントライブラリなしで SockJS の WebSocket トランスポートを使う方法です。

STOMP セッション⚓︎

STOMP セッション
STOMP メッセージングプロトコルに従い、WebSocket 接続上で行うクライアントとノードの会話です。

クライアントは、STOMP フレーム をノードと交換してセッションを制御します。

  1. CONNECT フレームを送信して STOMP セッションを開始する。
  2. 監視する各 WebSocket チャネル に SUBSCRIBE フレームを送信する。 各サブスクリプションには、クライアントが定義する id が必要です。
  3. 明示的な登録が必要なチャネルの通知を有効にするため、オプションの 登録リクエスト を SEND フレームで送信する。
  4. サブスクライブしたチャネルのイベントごとに、ノードから MESSAGE フレームを受信する。
  5. 通知の受信を停止するため、サブスクライブした各チャネルに UNSUBSCRIBE フレームを送信する。
  6. セッションを終了するため、DISCONNECT フレームを送信する。

接続が静かに切断される可能性があります

WebSocket 接続は、例えば長時間アイドル状態だった後など、通知なしに切断される可能性があります。 ほとんどの STOMP クライアントは接続終了コールバックでこれを報告するため、再接続に適した場所です。

再接続すると新しいセッションが開始されるため、すべてのチャネルをもう一度サブスクライブする必要があります。

STOMP フレーム⚓︎

STOMP フレーム
STOMP プロトコルに従うプレーンテキストメッセージです。 コマンド、オプションの header:value 行、オプションの本文で構成されます。

クライアントとノードは、次のフレームタイプを交換します。

CONNECT⚓︎

STOMP セッションを開始します。 接続が開いた直後に、クライアントはこのフレームを 1 回送信する必要があります。 詳細は STOMP 仕様 を参照してください。

Example
CONNECT
accept-version:1.2
heart-beat:0,0

SUBSCRIBE⚓︎

クライアントが選んだ id と destination で WebSocket チャネル をサブスクライブします。 詳細は STOMP 仕様 を参照してください。

Example
SUBSCRIBE
id:sub-0
destination:/blocks
  • id は 1 つの接続内でのみ一意です（他のクライアントは同じ値を再利用できます）。 すべてのメッセージで subscription ヘッダーとして返され、後で UNSUBSCRIBE に使われます。
  • destination はチャネルを識別するため、同じ接続で複数のチャネルを監視できます。

MESSAGE⚓︎

ノードからチャネルデータを配信します。 ノードが送信する唯一のフレームタイプです。 詳細は STOMP 仕様 を参照してください。

Example
MESSAGE
destination:/blocks
subscription:sub-0
message-id:befkedjj-6247

{ ... }
  • destination は SUBSCRIBE フレームのチャネルと一致します。
  • subscription は SUBSCRIBE フレームの id と一致します。
  • message-id はサーバーが各メッセージに割り当てる一意の識別子です。
  • { ... } は本文で、形状は チャネル によって異なる JSON オブジェクトです。 下の メッセージ本文 タブを参照してください。

SEND⚓︎

/w/api 宛先へ WebSocket リクエスト を送信します。 詳細は STOMP 仕様 を参照してください。

Example
SEND
destination:/w/api/account/subscribe

{ "account": "{address}" }

UNSUBSCRIBE⚓︎

id でサブスクリプションをキャンセルします。 詳細は STOMP 仕様 を参照してください。

Example
UNSUBSCRIBE
id:sub-0

DISCONNECT⚓︎

セッションを終了します。 詳細は STOMP 仕様 を参照してください。

Example
DISCONNECT

チャネル⚓︎

WebSocket チャネル
ノードの通知をチャネルにまとめます。 クライアントは受信したい通知を持つ各チャネルをサブスクライブします。

すべてのチャネルは SUBSCRIBE フレームでサブスクライブします。

ここでは、報告するイベントの種類ごとに利用可能なチャネルをまとめます。

ブロックチャネル⚓︎

チェーンに追加された新しいブロックを報告するチャネルです。

/blocks⚓︎

blocks

新しいブロックがチェーンに追加されるたびに、サブスクライブしたクライアントへ通知します。

ノードがピアに追いついている場合や ロールバック の後など、一度に複数のブロックが追加されると、チャネルは バースト を送信します。ブロックごとに 1 通知を、チェーン順に短い間隔で配信します。

ロールバック後は、新しいブロックがすでに報告したブロックを置き換えるため、以前の通知より低いブロック高さを通知することがあります。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/blocks

MESSAGE
destination:/blocks
subscription:sub-0
message-id:...

{ ... }
Block JSON 本文が続きます。

/blocks/new⚓︎

blocks/new

チェーンが変更されるたびに、追加または置き換えられた最初のブロックの高さを含む通知を、更新ごとに 1 つ送信します。

blocks WS とは異なり、含まれるブロック数に関係なく、チェーン更新ごとに 1 通知だけ送信します。 例えば 5 ブロックが一度に追加された場合、blocks WS は 5 通知を送信しますが、このチャネルは最初のブロックの高さを含む 1 通知だけを送信します。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/blocks/new

MESSAGE
destination:/blocks/new
subscription:sub-0
message-id:...

{ "height": 1234567 }

トランザクションチャネル⚓︎

関係するアカウントにかかわらず、トランザクションの活動を報告するチャネルです。

/unconfirmed⚓︎

unconfirmed

関係するアカウントにかかわらず、トランザクションが 未承認トランザクションプール に入るたびにサブスクライブしたクライアントへ通知します。

ここには 連署 を含むすべてのトランザクションタイプが現れます。連署は アカウントチャネル では報告されません。 マルチシグトランザクション は外側のマルチシグトランザクションとして現れ、その内部に内部トランザクションがネストされます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/unconfirmed

MESSAGE
destination:/unconfirmed
subscription:sub-0
message-id:...

{ ... }
Transaction JSON 本文が続きます。

アカウントチャネル⚓︎

残高、トランザクション、所有するモザイクやネームスペースなど、特定のアカウントの活動を報告するチャネルです。

アドレス形式

チャネルの destination またはリクエスト本文にアドレスが現れる場合は、エンコードされたアドレス 形式を使います。 大文字と数字のみで、ハイフンはありません。

例: TBULEAUG2CZQISUR442HWA6UAKGWIXHDABJVIPS4。

アカウントチャネルは、アカウントの状態が変わらない場合でも、アカウントがトランザクションに 関係する たびに通知します。

関係するとみなされるアカウントは、トランザクションタイプによって異なります。

トランザクションタイプ 関係するアカウント
転送 署名者と受取人。
インポータンス転送 署名者とリモートアカウント。
マルチシグアカウント変更 追加または削除されたすべての連署人と署名者。
ネームスペース登録 署名者。
モザイク定義の作成 署名者、および定義に徴収手数料が含まれる場合は徴収手数料の受取人。
モザイク供給量の変更 署名者、およびモザイク定義に徴収手数料が含まれる場合は徴収手数料の受取人。
マルチシグ 開始した連署人、マルチシグアカウント、内部トランザクションに含まれるその他のアカウント。

マルチシグトランザクション

開始した連署人と内部送金の受取人など、複数の役割を持つアカウントには、役割ごとに 1 通知が届きます。

マルチシグトランザクション に複数の署名が必要な場合、追加の各連署人は別の 連署 を送信して承認します。 連署はグローバルな unconfirmed WS チャネルにだけ現れます。 マルチシグアカウントや送信した連署人のチャネルを含め、アカウントチャネルには届きません。

/account/{address}⚓︎

account/{address}

アドレスが関係する承認済みブロックごとに、アカウントの現在の状態を通知します。トランザクションで 関係する 場合と、ブロックをハーベスティングした場合が含まれます。 先にアドレスを 登録 する必要があります。

トランザクションに関係しても、アカウントが変化したとは限りません。 例えば XEM を 0 転送した受取人は、残高が変わらなくても通知されます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/account/{address}

MESSAGE
destination:/account/{address}
subscription:sub-0
message-id:...

{ ... }
AccountMetaDataPair JSON 本文が続きます。

/unconfirmed/{address}⚓︎

unconfirmed/{address}

アカウントに 関係する トランザクションが 未承認トランザクションプール に入るたびに、サブスクライブしたクライアントへ通知します。 先にアドレスを 登録 する必要があります。

トランザクションはまだブロックに含まれていないため、meta.height フィールドには JSON パーサーが安全に表現できる最大の整数であるプレースホルダー 9007199254740991 が含まれます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/unconfirmed/{address}

MESSAGE
destination:/unconfirmed/{address}
subscription:sub-0
message-id:...

{ ... }
TransactionMetaDataPair JSON 本文が続きます。

/transactions/{address}⚓︎

transactions/{address}
アカウントに 関係する トランザクションを承認済みブロックが含むたびに、サブスクライブしたクライアントへ通知します。 先にアドレスを 登録 する必要があります。
サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/transactions/{address}

MESSAGE
destination:/transactions/{address}
subscription:sub-0
message-id:...

{ ... }
TransactionMetaDataPair JSON 本文が続きます。

/account/mosaic/owned/{address}⚓︎

account/mosaic/owned/{address}

承認済みブロックによってアカウントのモザイクが変わった可能性があるたびに、アカウントのモザイクを通知します。 アカウントのモザイクとは、残高を保有するモザイクと、作成したモザイクです。

モザイク関連のトランザクションがアカウントに 関係する ブロックに含まれると、通知バーストを送信します。 モザイクを運ぶ転送は、署名者、受取人、徴収手数料の受取人へ通知します。 モザイク定義の作成とモザイク供給量の変更は、モザイク作成者と徴収手数料の受取人へ通知します。

トランザクションがアカウントのモザイクを変更する必要はありません。 例えばモザイクを 0 単位転送しても、送信者と受取人の両方へ通知します。

各バーストにはアカウントのモザイク一覧全体が含まれ、変更されたモザイクにかかわらずモザイクごとに 1 通知が届きます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/account/mosaic/owned/{address}

MESSAGE
destination:/account/mosaic/owned/{address}
subscription:sub-0
message-id:...

{ ... }
Mosaic JSON 本文が続きます。

/account/mosaic/owned/definition/{address}⚓︎

account/mosaic/owned/definition/{address}

承認済みブロックによって変わった可能性があるたびに、アカウントのモザイク定義を通知します。

 WS と同じトランザクションによって発生し、同じモザイクを対象とします。 各バーストにはアカウントのモザイク定義一覧全体が含まれ、変更されたモザイクにかかわらず定義ごとに 1 通知が届きます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/account/mosaic/owned/definition/{address}

MESSAGE
destination:/account/mosaic/owned/definition/{address}
subscription:sub-0
message-id:...

{ ... }
MosaicDefinitionSupplyTuple JSON 本文が続きます。

/account/namespace/owned/{address}⚓︎

account/namespace/owned/{address}

承認済みブロックによって変わった可能性があるたびに、アカウントが所有するネームスペースを通知します。

アカウントが署名したネームスペース提供トランザクションをブロックが含むと、通知バーストを送信します。 各バーストには所有するネームスペース一覧全体が含まれ、ネームスペースごとに 1 通知が届きます。

サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/account/namespace/owned/{address}

MESSAGE
destination:/account/namespace/owned/{address}
subscription:sub-0
message-id:...

{ ... }
Namespace JSON 本文が続きます。

/recenttransactions/{address}⚓︎

recenttransactions/{address}
w/api/account/transfers/all REQ への応答としてのみ、アカウントの最新 25 件の承認済みトランザクションを通知します。
サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/recenttransactions/{address}

MESSAGE
destination:/recenttransactions/{address}
subscription:sub-0
message-id:...

{ ... }
data フィールドにラップされた TransactionMetaDataPair の一覧が続きます。

システムチャネル⚓︎

ブロックチェーンイベントではなく、ノードの状態とリクエストエラーを報告するチャネルです。

/node/info⚓︎

node/info
w/api/node/info REQ への応答としてのみ、ノードの情報をサブスクライブしたクライアントへ通知します。
サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/node/info

MESSAGE
destination:/node/info
subscription:sub-0
message-id:...

{ ... }
Node JSON 本文が続きます。

/errors⚓︎

errors
/w/api の WebSocket リクエスト が失敗したとき、例えばアドレスのペイロードが無効なときに、サブスクライブしたクライアントへ通知します。 クライアントは接続直後にこのチャネルをサブスクライブできるため、問題が静かに破棄されず、ここに現れます。
サブスクリプションフレーム 通知フレーム 
SUBSCRIBE
id:sub-0
destination:/errors

MESSAGE
destination:/errors
subscription:sub-0
message-id:...

{
    "timeStamp": 67191609,
    "status": 400,
    "error": "Bad Request",
    "message": "account is not valid"
}

リクエスト⚓︎

WebSocket リクエスト
クライアントから送信するメッセージで、ノードに次のいずれかを配信させます。 登録 が必要なチャネルの通知、またはブロックチェーンの状態の スナップショット を含む即時通知です。

リクエストは 読み取り専用 で、チェーンの状態を変更しません。

すべてのリクエストは SEND フレームで、/w/api/ から始まる宛先へ送信します。 応答を返さないリクエストもあれば、上の チャネル のいずれかを通して結果を返すリクエストもあります。

登録リクエスト⚓︎

一部の アカウントチャネル は、アドレスを登録するまで何も送信しません。 これらのリクエストで登録すると、チャネルが通知を配信し始めます。

登録は共有されます

ノードは、接続しているすべてのクライアントで共有する登録アドレスの一覧を 1 つ保持します。 どのクライアントかがアドレスを登録すると、そのアカウントのチャネルをサブスクライブしているすべてのクライアントが、再登録なしでそのアドレスの通知を受け取ります。 登録はノードが再起動するまで有効です。

/w/api/account/subscribe⚓︎

w/api/account/subscribe
アドレスを登録し、ノードが アカウントチャネル に通知を送信し始めるようにします。
リクエストフレーム 
SEND
destination:/w/api/account/subscribe

{ "account": "{address}" }

/w/api/account/get⚓︎

w/api/account/get
w/api/account/subscribe REQ と同じようにアドレスを登録し、アカウントの現在の状態を含む通知を account/{address} WS に送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/get

{ "account": "{address}" }

スナップショットリクエスト⚓︎

各リクエストは、新しいイベントを待たずに、現在のデータのスナップショットをノードからチャネルへ即時送信させます。

これにより、REST API をポーリングする代わりに、ライブ更新と同じチャネルを通してオンデマンドで現在のデータを取得できます。

/w/api/account/transfers/all⚓︎

w/api/account/transfers/all
アカウントの最新 25 件までの承認済みトランザクションを recenttransactions/{address} WS に送信し、w/api/account/transfers/unconfirmed REQ と同じ方法で承認待ちのトランザクションも送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/transfers/all

{ "account": "{address}" }

/w/api/account/transfers/unconfirmed⚓︎

w/api/account/transfers/unconfirmed
アカウントの最新の承認待ちトランザクションを最大 10 件、unconfirmed/{address} WS とグローバルな unconfirmed WS チャネルに送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/transfers/unconfirmed

{ "account": "{address}" }

/w/api/account/mosaic/owned⚓︎

w/api/account/mosaic/owned
アカウントが所有するモザイクを含む通知を account/mosaic/owned/{address} WS に送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/mosaic/owned

{ "account": "{address}" }

/w/api/account/mosaic/owned/definition⚓︎

w/api/account/mosaic/owned/definition
アカウントが所有するモザイク定義を含む通知を account/mosaic/owned/definition/{address} WS に送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/mosaic/owned/definition

{ "account": "{address}" }

/w/api/account/namespace/owned⚓︎

w/api/account/namespace/owned
アカウントが所有するネームスペースを含む通知を account/namespace/owned/{address} WS に送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/account/namespace/owned

{ "account": "{address}" }

/w/api/block/last⚓︎

w/api/block/last

最新ブロックを含む通知を blocks WS に送信するようノードに要求します。

ノードはブロックが今追加されたかのように処理するため、そのブロックに関係するアカウントの アカウントチャネル にも再び通知します。

リクエストフレーム 
SEND
destination:/w/api/block/last

/w/api/node/info⚓︎

w/api/node/info
ノード自身の情報を含む通知を node/info WS に送信するようノードに要求します。
リクエストフレーム 
SEND
destination:/w/api/node/info