Skip to content

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

CodeResponseDescription
200OKReturns 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.

Responses

CodeResponseDescription
200OKReturns 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

CodeResponseDescription
202AcceptedThe 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

CodeResponseDescription
200Health StatusReturns 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

CodeResponseDescription
200MetricsReturns 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

CodeResponseDescription
200OKReturns 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:

OR

Get the next batch of a previously started query:

  • Parameters:
    • cursor - specifies a cursor previously returned as part of query response

Request

Responses

CodeResponseBodyDescription
200SuccessBatchedResponse<QueryOutputBox>Successful query request
400Conversion ErrorQueryExecutionFail::Conversion(String)Invalid asset query for the actual asset type
400Cursor ErrorQueryExecutionFail::UnknownCursorAn invalid cursor was provided in the batch request
400FetchSizeTooBig ErrorQueryExecutionFail::FetchSizeTooBigFetch size specified in the query request is too large
400InvalidSingularParameters ErrorQueryExecutionFail::InvalidSingularParametersSpecified query parameters are not applicable to the (singular) query type
401Signature ErrorQueryExecutionFail::Signature(String)The signature on the query is incorrect
403Permission ErrorQueryExecutionFail::Permission(String)The user does not have permission to execute this query
404Find ErrorQueryExecutionFail::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.

Account Not Found 404

Whether each prerequisite object was found and FindError:

DomainAccountFindError
N-FindError::Domain(DomainId)
YNFindError::Account(AccountId)

Asset Not Found 404

Whether each prerequisite object was found and FindError:

DomainAccountAsset DefinitionAssetFindError
N---FindError::Domain(DomainId)
YN--FindError::Account(AccountId)
Y-N-FindError::AssetDefinition(AssetDefinitionId)
YYYNFindError::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

CodeResponseDescription
200OKReturns 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

CodeResponseDescription
200Iroha StatusReturns the Iroha network status report encoded as specified in the header of the request.

The response body has the following structure:

rust
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
}
Examples

The following examples represent the same data:

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:

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

Transaction

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

Requests

This endpoint expects the following data:

Responses

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