Torii Endpoints ​

Torii (jap. 鳥居 - gates; Shinto shrine archway) is the Iroha module in charge of handling HTTP and WebSocket requests. It is the main application programmable interface to interact with Iroha. Such interactions include sending transactions, making queries, listening for blocks stream, and so on.

To establish two-way communication with the TORII endpoints, the following addresses must be specified in the Iroha 2 configuration files:

1. In the configs/client_cli/config.json client configuration file:

   • TORII_API_URL — connects to the TORII module responsible for handling incoming and outgoing connections.
     This address is the same as the API_URL address in the configs/peer/config.json peer configuration file.
   • TORII_TELEMETRY_URL — connects to the Prometheus endpoint address that is used as a metrics tool to monitor the network performance.

   INFO

   To learn more, see Client Configuration > Iroha Public Addresses.

2. In the configs/peer/config.json peer configuration file:

   • API_URL — connects to the TORII module responsible for handling incoming and outgoing connections.
     This address is the same as the TORII_API_URL address in the configs/client_cli/config.json client configuration file.
   • TELEMETRY_URL — connects to the Prometheus endpoint address that is used as a metrics tool to monitor the network performance.

   INFO

   To learn more, see Peer Configuration > Iroha Public Addresses.

API Version ​

• Protocol: HTTP
• Method: GET
• Encoding: JSON
• Endpoint: /api_version

Requests ​

A GET request to the endpoint.

Responses ​

Example:

200 OK: "1"

200 OK: "1"

Blocks Stream ​

• Protocols: HTTP upgraded to WebSocket
• Encoding: SCALE
• Endpoint: /block/stream

Handshake ​

Since the /block/stream endpoint handles continuous two-way data exchange, a WebSocket handshake between the client and server must first be performed to initiate communication with this endpoint.

The first HTTP request to this endpoint requires a standard set of WebSocket headers.

Example:

Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits

Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits

Data Exchange ​

After a successful handshake, the client must send a BlockSubscriptionRequest request with the starting block number provided (i.e., the height value). Then, upon sending the confirmation and BlockMessage messages, the server starts streaming all of the blocks, beginning with the block specified with height up to the most recent one, and then continues to stream new blocks as they are added to the blockchain.

Responses ​

Configuration / Retrieve ​

• Protocol: HTTP
• Method: GET
• Encoding: JSON
• Endpoint: /configuration

Requests ​

A GET request to the endpoint.

Responses ​

Example:

{
  "logger": {
    "level": "TRACE"
  }
}

{
  "logger": {
    "level": "TRACE"
  }
}

Configuration / Update ​

• Protocol: HTTP
• Method: POST
• Encoding: JSON
• Endpoint: /configuration

Requests ​

This endpoint expects a subset of configuration parameters serialized into JSON format. Currently, it only supports dynamic updating of the logger.level parameter.

Example:

{
  "logger": {
    "level": "DEBUG"
  }
}

{
  "logger": {
    "level": "DEBUG"
  }
}

Responses ​

Events ​

• Protocol: HTTP upgraded to WebSocket
• Encoding: SCALE
• Endpoint: /events

Transaction Events ​

The status of a transaction event can be one of the following:

• Validating — The transaction has been successfully submitted and is currently being validated by peers.
• Committed — The transaction has been successfully validated and is committed to the blockchain.
• Rejected — The transaction has been rejected by at least one peer and is not committed to the blockchain.

All transactions are designated with the Validating status upon creation, which later proceeds to either Committed or Rejected. However, due to the distributed nature of the network, some peers might receive events out of order (e.g., Committed before Validating).

Some peers in the network may be offline for the validation round. If a client connects to them while they are offline, the peers might not respond with the Validating status. But when the offline peers come back online they will automatically synchronize the blocks. These peers are then guaranteed to respond with either Committed or Rejected status, depending on the information found in the block.

Handshake ​

Since the /events endpoint handles continuous two-way data exchange, a WebSocket handshake between the client and server must first be performed to initiate communication with this endpoint.

The first HTTP request to this endpoint requires a standard set of WebSocket headers.

Example:

Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits

Host: example.com:8000
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate, client_max_window_bits

Data Exchange ​

After a successful handshake, the client must send an EventSubscriptionRequest request, after which the server sends an EventMessage response.

Responses ​

Health ​

• Protocol: HTTP
• Method: GET
• Encoding: JSON
• Endpoint: /health

Requests ​

A GET request to the endpoint.

Responses ​

Example:

200 Health Status: "Healthy"

200 Health Status: "Healthy"

Metrics ​

• Protocol: HTTP
• Method: GET
• Encoding: JSON
• Endpoint: /metrics

Responses ​

Example:

# HELP accounts User accounts registered at this time
# TYPE accounts gauge
accounts{domain="genesis"} 1
accounts{domain="wonderland"} 1
# HELP block_height Current block height
# TYPE block_height counter
block_height 1
# HELP connected_peers Total number of currently connected peers
# TYPE connected_peers gauge
connected_peers 0
# HELP domains Total number of domains
# TYPE domains gauge
domains 2
# HELP tx_amount average amount involved in a transaction on this peer
# TYPE tx_amount histogram
tx_amount_bucket{le="0.005"} 0
tx_amount_bucket{le="0.01"} 0
tx_amount_bucket{le="0.025"} 0
tx_amount_bucket{le="0.05"} 0
tx_amount_bucket{le="0.1"} 0
tx_amount_bucket{le="0.25"} 0
tx_amount_bucket{le="0.5"} 0
tx_amount_bucket{le="1"} 0
tx_amount_bucket{le="2.5"} 0
tx_amount_bucket{le="5"} 0
tx_amount_bucket{le="10"} 0
tx_amount_bucket{le="+Inf"} 2
tx_amount_sum 26
tx_amount_count 2
# HELP txs Transactions committed
# TYPE txs counter
txs{type="accepted"} 1
txs{type="rejected"} 0
txs{type="total"} 1
# HELP uptime_since_genesis_ms Network up-time, from creation of the genesis block
# TYPE uptime_since_genesis_ms gauge
uptime_since_genesis_ms 54572974
# HELP view_changes Number of view_changes in the current round
# TYPE view_changes gauge
view_changes 0

# HELP accounts User accounts registered at this time
# TYPE accounts gauge
accounts{domain="genesis"} 1
accounts{domain="wonderland"} 1
# HELP block_height Current block height
# TYPE block_height counter
block_height 1
# HELP connected_peers Total number of currently connected peers
# TYPE connected_peers gauge
connected_peers 0
# HELP domains Total number of domains
# TYPE domains gauge
domains 2
# HELP tx_amount average amount involved in a transaction on this peer
# TYPE tx_amount histogram
tx_amount_bucket{le="0.005"} 0
tx_amount_bucket{le="0.01"} 0
tx_amount_bucket{le="0.025"} 0
tx_amount_bucket{le="0.05"} 0
tx_amount_bucket{le="0.1"} 0
tx_amount_bucket{le="0.25"} 0
tx_amount_bucket{le="0.5"} 0
tx_amount_bucket{le="1"} 0
tx_amount_bucket{le="2.5"} 0
tx_amount_bucket{le="5"} 0
tx_amount_bucket{le="10"} 0
tx_amount_bucket{le="+Inf"} 2
tx_amount_sum 26
tx_amount_count 2
# HELP txs Transactions committed
# TYPE txs counter
txs{type="accepted"} 1
txs{type="rejected"} 0
txs{type="total"} 1
# HELP uptime_since_genesis_ms Network up-time, from creation of the genesis block
# TYPE uptime_since_genesis_ms gauge
uptime_since_genesis_ms 54572974
# HELP view_changes Number of view_changes in the current round
# TYPE view_changes gauge
view_changes 0

Query ​

• Protocol: HTTP
• Method: POST
• Encoding: SCALE
• Endpoint: /query

Requests ​

This endpoint expects the following data:

• Body: VersionedSignedQuery
• Parameters (optional):
  • start — Specifies the id of a starting entry. A successful response will contain all entries newer than and including the id specified.\
  • limit — Specifies the exact number of retrieved id entries.\
  • sort_by_metadata_key — Specifies the metadata key of the id entries that will be returned.\
  • fetch_size — Specifies the maximum number of results that a response can contain.

Responses ​

Account Not Found 404 ​

Whether each prerequisite object was found and FindError:

Asset Not Found 404 ​

Whether each prerequisite object was found and FindError:

Status ​

• Protocol: HTTP
• Method: GET
• Encoding: JSON or SCALE
• Endpoint: /status

Requests ​

A GET request to the endpoint.

This endpoint also accepts the following:

• Header: Specifies the encoding of the retrieved data.
  Can be set to one of the following:
  • Accept: application/x-parity-scale — the retrieved data is encoded with SCALE.
  • Accept: application/json — the retrieved data is encoded with JSON.

If no header is specified in the request, the Accept: application/json header is used by default.

Responses ​

The response body has the following structure:

struct Status {
    /// Number of connected peers, except for the reporting peer itself
    peers: u64,
    /// Number of committed blocks
    blocks: u64,
    /// Number of accepted transactions
    txs_accepted: u64,
    /// Number of rejected transactions
    txs_rejected: u64,
    /// Uptime since genesis block creation
    uptime: Uptime,
    /// Number of view changes in the current round
    view_changes: u64,
    /// Number of the transactions in the queue
    queue_size: u64,
}

struct Uptime {
    secs: u64,
    nanos: u32
}

struct Status {
    /// Number of connected peers, except for the reporting peer itself
    peers: u64,
    /// Number of committed blocks
    blocks: u64,
    /// Number of accepted transactions
    txs_accepted: u64,
    /// Number of rejected transactions
    txs_rejected: u64,
    /// Uptime since genesis block creation
    uptime: Uptime,
    /// Number of view changes in the current round
    view_changes: u64,
    /// Number of the transactions in the queue
    queue_size: u64,
}

struct Uptime {
    secs: u64,
    nanos: u32
}

{
  "peers": 4,
  "blocks": 5,
  "txs_accepted": 31,
  "txs_rejected": 3,
  "uptime": {
    "secs": 5,
    "nanos": 937000000
  },
  "view_changes": 2,
  "queue_size": 18
}

{
  "peers": 4,
  "blocks": 5,
  "txs_accepted": 31,
  "txs_rejected": 3,
  "uptime": {
    "secs": 5,
    "nanos": 937000000
  },
  "view_changes": 2,
  "queue_size": 18
}

10 14 7C 0C 14 40 7C D9 37 08 48

10 14 7C 0C 14 40 7C D9 37 08 48

Sub-routing ​

It is also possible to retrieve the data of a specific struct group or variable within it by adding their path to the endpoint address. The sub-routed values are only returned in the JSON format.

Examples:

struct Status {
  "peers": 4,
  "blocks": 5,
  "txs_accepted": 31,
  "txs_rejected": 3,
  "uptime": {
    "secs": 5,
    "nanos": 937000000
  },
  "view_changes": 2,
  "queue_size": 18
}

struct Uptime {
    secs: 5,
    nanos: 937000000
}

struct Status {
  "peers": 4,
  "blocks": 5,
  "txs_accepted": 31,
  "txs_rejected": 3,
  "uptime": {
    "secs": 5,
    "nanos": 937000000
  },
  "view_changes": 2,
  "queue_size": 18
}

struct Uptime {
    secs: 5,
    nanos: 937000000
}

4

4

{
  "secs": 5,
  "nanos": 937000000
}

{
  "secs": 5,
  "nanos": 937000000
}

5

5

Transaction ​

• Protocol: HTTP
• Method: POST
• Encoding: SCALE
• Endpoint: /transaction

Requests ​

This endpoint expects the following data:

• Body: VersionedSignedTransaction

Responses ​