Torii Endpoints

About Parity SCALE Codec

Messages for certain TORII operations are encoded with the Parity SCALE Codec (SCALE) commonly used with the Parity Substrate blockchain framework, and other blockchains utilizing it.

For more information on SCALE, see the Substrate Documentation: Type encoding (SCALE) article and its official GitHub repository.

Torii (Japanese: 鳥居 — Shinto shrine gateway) is the Iroha 2 module in charge of handling HTTP and WebSocket requests. It is the main API for interacting with Iroha 2. Such interactions include sending transactions, making queries, listening for blocks stream, etc.

API Version

INFO

This operation requires the specific Iroha node being requested to be compiled with the telemetry feature enabled.

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

Requests

A GET request to the endpoint.

Responses

Code	Response	Description
200	OK	Returns the current version of the API used by the requested Iroha 2 node as a JSON
string.

Example:

json

"1"

INFO

The API version is retrieved from and is the same as the version of the genesis block, which means that at least a minimal subnet of four peers must be running, and the genesis block must already be submitted at the time of the request.

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.

Data Exchange

After establishing a WebSocket connection, 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.

Configuration / Retrieve

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

Requests

A GET request to the endpoint.

Via this endpoint, the client first provides the starting block number (i.e. height) in the subscription request. After sending the confirmation message, the server starts streaming all the blocks from the given block number up to the current block and continues to stream blocks as they are added to the blockchain.

Responses

Code	Response	Description
200	OK	Returns a subset of configuration parameters serialized into JSON format.

Example:

json

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

INFO

The subset of configuration parameters returned by this operation is equal to the one accepted by the Configuration / Update operation, i.e., it only contains the logger.level parameter as of now.

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.

INFO

The list of all accepted values is currently unavailable and will be a part of the configuration reference that is still WIP.

Until then, to get assistance with the acceptable values and their definitions, consult Receive Support for ways to contact us.

The progress on the configuration reference can be tracked in the following GitHub issue:
iroha-2-docs > Issue #392: Tracking issue for Configuration Reference as per RFC.

Example:

json

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

Responses

Code	Response	Description
202	Accepted	The request to update the configuration is accepted and is due to be processed.

Guarantees

A successful configuration update does not guarantee that the configuration is indeed updated. While a follow-up Configuration / Retrieve request will return updated values, the actual update is performed asynchronously.

Events

Protocols: 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.

Data Exchange

After establishing a WebSocket connection, the client must send an EventSubscriptionRequest request, after which the server sends an EventMessage response.

Health

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

Requests

A GET request to the endpoint.

Responses

Code	Response	Description
200	Health Status	Returns the current status of the peer submitting the request.

Example:

json

"Healthy"

Metrics

INFO

This operation requires the Iroha 2 network to be established with the telemetry feature enabled.

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

Responses

Code	Response	Description
200	Metrics	Returns a report on 8 out of 10 Prometheus metrics.

Example:

Example 200 Metrics response

bash

# 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

INFO

To learn more about metrics, see Metrics.

Pending Transactions

Protocol: HTTP
Method: GET
Encoding: SCALE
Endpoint: /pending_transactions

Requests

A GET request to the endpoint.

Responses

Code	Response	Description
200	OK	Returns a list of pending transactions as `SignedTransaction` objects encoded with `SCALE`; must be decoded by the client.

Query

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

Requests

This endpoint expects requests with two shapes:

Start a query:

Body: SignedQuery OR Get the next batch of a previously started query:
- Parameters:
  - cursor - specifies a cursor previously returned as part of query response Request

Responses

Code	Response	Body	Description
200	Success	`BatchedResponse<QueryOutputBox>`	Successful query request
400	Conversion Error	`QueryExecutionFail::Conversion(String)`	Invalid asset query for the actual asset type
400	Cursor Error	`QueryExecutionFail::UnknownCursor`	An invalid cursor was provided in the batch request
400	FetchSizeTooBig Error	`QueryExecutionFail::FetchSizeTooBig`	Fetch size specified in the query request is too large
400	InvalidSingularParameters Error	`QueryExecutionFail::InvalidSingularParameters`	Specified query parameters are not applicable to the (singular) query type
401	Signature Error	`QueryExecutionFail::Signature(String)`	The signature on the query is incorrect
403	Permission Error	`QueryExecutionFail::Permission(String)`	The user does not have permission to execute this query
404	Find Error	`QueryExecutionFail::Find(FindError)`	The queried object was not found

INFO

The 200 Success response returns results that are ordered by id, which use Rust's PartialOrd and Ord traits.

Lazily Evaluated Pagination

TODO: explain how it works. Explain that this behaviour is configured with torii.query_idle_time_ms.

Account Not Found 404

Whether each prerequisite object was found and FindError:

Domain	Account	`FindError`
N	-	`FindError::Domain(DomainId)`
Y	N	`FindError::Account(AccountId)`

Asset Not Found 404

Whether each prerequisite object was found and FindError:

Domain	Account	Asset Definition	Asset	`FindError`
N	-	-	-	`FindError::Domain(DomainId)`
Y	N	-	-	`FindError::Account(AccountId)`
Y	-	N	-	`FindError::AssetDefinition(AssetDefinitionId)`
Y	Y	Y	N	`FindError::Asset(AssetId)`

Schema

INFO

This operation requires the Iroha 2 network to be established with the schema feature enabled.

Protocol: HTTP
Method: GET
Encoding: JSON
Endpoint: /schema

Requests

A GET request to the endpoint.

Responses

Code	Response	Description
200	OK	Returns the Rust data structures and types of the entire Data Model Schema as JSON objects.

Status

INFO

This operation requires the Iroha 2 network to be established with the telemetry feature enabled.

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

Code	Response	Description
200	Iroha Status	Returns the Iroha network status report encoded as specified in the header of the request.

The response body has the following structure:

200 OK reports status as JSON:

Sample response

json5

// Note: while this snippet is JSON5 (for better readability),
//       the actual response is JSON
{
  /**
   * Number of connected peers, except for the reporting peer itself
   */
  peers: 3,
  /**
   * Number of committed blocks (block height)
   */
  blocks: 1,
  /**
   * Total number of accepted transactions
   */
  txs_accepted: 3,
  /**
   * Total number of rejected transactions
   */
  txs_rejected: 0,
  /**
   * Uptime with nanosecond precision since creation of the genesis block
   */
  uptime: {
    secs: 5,
    nanos: 937000000,
  },
  /**
   * Number of view changes in the current round
   */
  view_changes: 0,
}

Examples

The following examples represent the same data:

JSONSCALE

json

{
  "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

JSON Precision Lost

Almost all fields in the Status structure are 64-bit integers, and they are encoded in JSON as-is. Since native JSON's number type according to the specification effectively is f64, the precision might be lost on deserialization, for example, in JavaScript's JSON.parse.

For more details, see the related GitHub issue.

Compact Form in SCALE

Fields with u64 type are serialized in the Compact form.

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:

/status/status/peers/status/uptime/status/uptime/secs

json

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

json

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

json

Transaction

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

Requests

This endpoint expects the following data:

Body: SignedTransaction

Responses

Code	Response	Description
200	Transaction Accepted	Transaction has been accepted, but is not yet guaranteed to have passed consensus.
400	Transaction Rejected (Malformed)	Transaction is rejected due to being malformed.
401	Transaction Rejected (Improperly signed)	Transaction is rejected due to being improperly signed.

Torii Endpoints ​

API Version ​

Requests ​

Responses ​

Blocks Stream ​

Handshake ​

Data Exchange ​

Configuration / Retrieve ​

Requests ​

Responses ​

Configuration / Update ​

Requests ​

Responses ​

Events ​

Transaction Events ​

Data Exchange ​

Health ​

Requests ​

Responses ​

Metrics ​

Responses ​

Pending Transactions ​

Requests ​

Responses ​

Query ​

Requests ​

Responses ​

Account Not Found 404 ​

Asset Not Found 404 ​

Schema ​

Requests ​

Responses ​

Status ​

Requests ​

Responses ​

Sub-routing ​

Transaction ​

Requests ​

Responses ​

Torii Endpoints

API Version

Requests

Responses

Blocks Stream

Handshake

Data Exchange

Configuration / Retrieve

Requests

Responses

Configuration / Update

Requests

Responses

Events

Transaction Events

Data Exchange

Health

Requests

Responses

Metrics

Responses

Pending Transactions

Requests

Responses

Query

Requests

Responses

Account Not Found 404

Asset Not Found 404

Schema

Requests

Responses

Status

Requests

Responses

Sub-routing

Transaction

Requests

Responses