Torii Endpoints

API Version

Protocol: HTTP
Method: GET
Endpoint: /api_version

Responses:

200 OK: The current version of API used by Iroha returned as a JSON string. Grabbed from the genesis block's version, so at least a minimal subnet of 4 peers should be running and the genesis be submitted at the time of request.

json

"1"

"1"

Blocks Stream

Protocol: HTTP
Protocol Upgrade: WebSocket
Endpoint: /block/stream

The client should send a BlockSubscriptionRequest to initiate communication after the WebSocket handshake. Then the server sends a BlockMessage. Messages are SCALE-encoded^[1].

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.

Configuration > Retrieve

Protocol: HTTP
Method: GET
Endpoint: /configuration
Responses: with JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to the one accepted by Configuration > Update endpoint, i.e. it contains only logger.level parameter as of now.

Example response:

json

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

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

Configuration > Update

Protocol: HTTP
Method: POST
Endpoint: /configuration
Expects: a JSON-serialized subset of configuration parameters.

This endpoint currently supports only dynamic updating of the logger.level parameter.

Example request:

json

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

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

Events

Protocol: HTTP
Protocol Upgrade: WebSocket
Endpoint: /events

After a handshake, the client should send an EventSubscriptionRequest. Then the server sends an EventMessage. Messages are SCALE-encoded^[1:1].

Transaction Events

Transaction event statuses can be either Validating, Committed or Rejected.

Transaction statuses proceed from Validating 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 the 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 synchronize the blocks. They are then guaranteed to respond with the Committed (or Rejected) status depending on the information found in the block.

Health

Protocol: HTTP
Method: GET
Endpoint: /health

Responses with 200 OK and a current status of peer as a JSON string:

json

"Healthy"

"Healthy"

Metrics

Protocol: HTTP
Method: GET
Endpoint: /metrics

Responses:

200 OK reports 8 of 10 metrics:

Sample Prometheus metrics

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

# 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

Learn how to use metrics.

Query

Protocol: HTTP
Method: POST
Endpoint: /query
Expects:
- Body: SCALE-encoded^[1:2]VersionedSignedQuery
- Query parameters:
  - start: An optional parameter in queries where results can be indexed. Use to return results from a specified point. Results are ordered by id, which uses Rust's PartialOrd and Ord traits.
  - limit: An optional parameter in queries where results can be indexed. Use to return a specific number of results.
  - sort_by_metadata_key: An optional parameter in queries. Use to sort results containing metadata with a given key.

Responses:

Response	Status	Body
Success	200	`VersionedBatchedResponse<Value>`
Conversion Error	400	`QueryExecutionFail::Conversion(String)`
Evaluate Error	400	`QueryExecutionFail::Evaluate(String)`
Signature Error	401	`QueryExecutionFail::Signature(String)`
Permission Error	403	`QueryExecutionFail::Permission(String)`
Find Error	404	`QueryExecutionFail::Find(FindError)`

Lazily Evaluated Pagination

TODO: explain how it works. Explain that this behaviour is configured with torii.query_results_per_fetch and torii.query_idle_time.

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)`

Status

Protocol: HTTP
Method: GET
Endpoint: /status

Responses:

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,
}

// 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,
}

WARNING

Almost all fields are 64-bit integers and should be handled with care in JavaScript. Only the uptime.nanos field is a 32-bit integer. See iroha_telemetry::metrics::Status

Sub-routing

To obtain the value of a specific field, one can append the name of the field to the path, e.g. /status/peers. This returns the corresponding JSON value, inline, so strings are quoted, numbers are not quoted, and maps are presented as in example above.

Transaction

Protocol: HTTP
Method: POST
Endpoint: /transaction
Expects:
- Body: SCALE-encoded^[1:3]VersionedSignedTransaction

Responses:

Status	Description
200	Transaction Accepted (But not guaranteed to have passed consensus yet)
400	Transaction Rejected (Malformed)
401	Transaction Rejected (Improperly signed)

TIP

Maximum allowed Content-Length for this endpoint is configured with torii.max_content_length.

For more information on Parity SCALE Codec check Substrate Dev Hub and codec's GitHub repository.
(https://github.com/hyperledger/iroha-2-docs/issues/367) ↩︎ ↩︎ ↩︎ ↩︎

Torii Endpoints ​

API Version ​

Blocks Stream ​

Configuration > Retrieve ​

Configuration > Update ​

Events ​

Transaction Events ​

Health ​

Metrics ​

Query ​

Account Not Found 404 ​

Asset Not Found 404 ​

Status ​

Sub-routing ​

Transaction ​

Torii Endpoints

API Version

Blocks Stream

Configuration > Retrieve

Configuration > Update

Events

Transaction Events

Health

Metrics

Query

Account Not Found 404

Asset Not Found 404

Status

Sub-routing

Transaction