diff --git a/src/guide/advanced/metrics.md b/src/guide/advanced/metrics.md index 7a47420e8..1c47144b5 100644 --- a/src/guide/advanced/metrics.md +++ b/src/guide/advanced/metrics.md @@ -1,29 +1,39 @@ # Metrics -To conveniently and thoroughly monitor the performance of the network, we -recommend using [`prometheus`](https://prometheus.io/). Prometheus is a -program that can monitor your Iroha peer over a separate socket and provide -different kinds of performance metrics. +To conveniently and thoroughly monitor the performance of your instance of the Iroha network, we recommend using [`Prometheus`](https://prometheus.io/). Prometheus is a program that can monitor your Iroha peer over a separate socket and provide different kinds of performance metrics. -This data can help you find performance bottlenecks and optimise your Iroha -configuration. +This data can help you find performance bottlenecks and optimise your Iroha configuration. + +#### `/metrics` Endpoint + +See [Reference > Torii Endpoints: Metrics](../../reference/torii-endpoints.md#metrics). ## How to use metrics -To use metrics, you need to configure the `/metrics` endpoint in the -[Iroha configuration](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). -By default, the endpoint is exposed at `127.0.0.1:8180/metrics`. If the -port is not available, Iroha will still start and work normally, but -metrics won't be accessible. + + +Work in Progress. + +This topic will be updated as part of the new configuration reference. + +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](https://github.com/hyperledger/iroha-2-docs/issues/392). + +::: note -After that, use the IP address to access the data from the running Iroha -instance. For example: +For examples, see [Sample Configuration Files](../configure/sample-configuration.md). + +::: + +After the above is configured, you can use the IP address set in the `"TORII_TELEMETRY_URL"` variable to access the metrics data from within a running Iroha instance. + +**Example**: ```bash -$ curl http://127.0.0.1:8080/metrics +$ curl http://127.0.0.1:8180/metrics ``` -This will give you a result like this: +This returns a result similar to the following: ```bash # HELP blocks_height Total number of blocks in chain @@ -42,8 +52,3 @@ total_number_of_transactions 216499 # TYPE number_of_signatures_in_last_block gauge number_of_signatures_in_last_block 5 ``` - -## `/metrics` endpoint - -Refer to the -[API specification](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/api_spec.md#metrics). diff --git a/src/guide/advanced/running-iroha-on-bare-metal.md b/src/guide/advanced/running-iroha-on-bare-metal.md index 409f9d874..c6816a418 100644 --- a/src/guide/advanced/running-iroha-on-bare-metal.md +++ b/src/guide/advanced/running-iroha-on-bare-metal.md @@ -23,8 +23,8 @@ You can always check [peer configuration options](/guide/configure/peer-configuration.md) for more details. -The complete list of options is available in the -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). + ::: diff --git a/src/guide/configure/configuration-types.md b/src/guide/configure/configuration-types.md index c10a61ddd..e5380e7fa 100644 --- a/src/guide/configure/configuration-types.md +++ b/src/guide/configure/configuration-types.md @@ -6,10 +6,10 @@ double `Option>`. In this section we explain the difference between `Option<..>` and `Option>` used for configuration types. You can find more about -available configuration options in -[peer configuration](peer-configuration.md). The full list of available -options is in -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). +available configuration options in the [Peer Configuration](peer-configuration.md) topic. + + ## `Option<..>` diff --git a/src/guide/configure/peer-configuration.md b/src/guide/configure/peer-configuration.md index 565589746..cb5c730d3 100644 --- a/src/guide/configure/peer-configuration.md +++ b/src/guide/configure/peer-configuration.md @@ -29,8 +29,8 @@ following: - [Public and private keys for the genesis account](#genesis) (`ACCOUNT_PUBLIC_KEY` and `ACCOUNT_PRIVATE_KEY`) -For the full list of configuration options, refer to -[Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md). + ::: info @@ -88,10 +88,8 @@ trusted peers: `TORII` is the module in charge of handling incoming and outgoing connections. -Here we only cover the required configurations: `API_URL`, `P2P_ADDR`, and -`TELEMETRY_URL`. Check -[`TORII` configuration reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#torii) -for all available options. + ### `API_URL` @@ -153,8 +151,8 @@ configurations, such as: - `GENESIS_SUBMISSION_DELAY_MS`: the delay before the genesis block submission after the minimum number of peers were discovered. -You can find more details in -[`GENESIS` Iroha Configuration Reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#genesis). + ## Logger @@ -202,5 +200,5 @@ _warehouse_). The `BLOCK_STORE_PATH` specifies where the blocks are stored. You can change it to a custom location if for some reason the default location (`./storage`) is not available or desirable. -For more details, check -[`KURA` configuration reference](https://github.com/hyperledger/iroha/blob/iroha2-dev/docs/source/references/config.md#kura). + diff --git a/src/guide/configure/sample-configuration.md b/src/guide/configure/sample-configuration.md index 75e6c8b99..e8033adea 100644 --- a/src/guide/configure/sample-configuration.md +++ b/src/guide/configure/sample-configuration.md @@ -2,9 +2,12 @@ Here you can find sample configuration files for Iroha 2: -- Peer Configuration (`configs/peer/config.json`). Refer to [peer configuration](peer-configuration.md) for details. -- Genesis Block (`configs/peer/genesis.json`). Refer to [genesis block](genesis.md) for details. -- Client Configuration (`configs/client_cli/config.json`). Refer to [client configuration](client-configuration.md) for details. +- Peer Configuration [`configs/peer/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/config.json).\ + For details, see [Peer Configuration](peer-configuration.md). +- Genesis Block [`configs/peer/genesis.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/peer/genesis.json).\ + For details, see [Genesis Block](genesis.md). +- Client Configuration [`configs/client/config.json`](https://github.com/hyperledger/iroha/blob/iroha2-dev/configs/client/config.json).\ + For details, see [Client Configuration](client-configuration.md). ::: code-group @@ -15,4 +18,3 @@ Here you can find sample configuration files for Iroha 2: <<< @/snippets/client-cli-config.json ::: - diff --git a/src/reference/torii-endpoints.md b/src/reference/torii-endpoints.md index 8d9cd7e94..811ae9b33 100644 --- a/src/reference/torii-endpoints.md +++ b/src/reference/torii-endpoints.md @@ -1,46 +1,114 @@ # Torii Endpoints - +::: tip About Parity SCALE Codec + +Messages for certain `TORII` operations are encoded with the Parity SCALE Codec (`SCALE`) commonly used with the [Parity Substrate](https://www.parity.io/technologies/substrate/) blockchain framework, and other blockchains utilizing it. + +For more information on `SCALE`, see the [Substrate Documentation: Type encoding (SCALE)](https://docs.substrate.io/reference/scale-codec/) article and its [official GitHub repository](https://github.com/paritytech/parity-scale-codec). + + + +::: + +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 -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/api_version` +::: info + +This operation requires the specific Iroha node being requested to be compiled with the `telemetry` feature enabled. -**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. +::: + +- **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](../guide/configure/genesis.md), 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 -- **Protocol:** HTTP -- **Protocol Upgrade:**`WebSocket -- **Endpoint:** `/block/stream` +- **Protocols**: `HTTP` upgraded to `WebSocket` +- **Encoding**: `SCALE` +- **Endpoint**: `/block/stream` + +#### Handshake -The client should send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) to initiate -communication after the WebSocket handshake. Then the server sends a -[`BlockMessage`](/reference/data-model-schema#blockmessage). Messages are SCALE-encoded[^1]. +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. -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. +#### Data Exchange + +After establishing a `WebSocket` connection, the client must send a [`BlockSubscriptionRequest`](/reference/data-model-schema#blocksubscriptionrequest) request with the starting block number provided (i.e., the `height` value). Then, upon sending the confirmation and [`BlockMessage`](/reference/data-model-schema#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` -- **Endpoint:** `/configuration` -- **Responses:** with a JSON-serialized subset of configuration parameters. The subset of returned parameters is equal to - the one accepted by the [Configuration > Update endpoint](#configuration-update), i.e. it only contains the - `logger.level` parameter as of now. +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/configuration` + +#### Requests -**Example response:** +A `GET` request to the endpoint. + +#### Responses + +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------- | +| 200 | OK | Returns a subset of configuration parameters serialized into JSON format. | + +**Example**: ```json { @@ -50,20 +118,35 @@ current block and continues to stream blocks as they are added to the blockchain } ``` +::: info + +The subset of configuration parameters returned by this operation is equal to the one accepted by the [Configuration / Update](#configuration-update) operation, i.e., it only contains the `logger.level` parameter as of now. + +::: + ## Configuration / Update -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/configuration` -- **Expects:** a JSON-serialized subset of configuration parameters. -- **Response:** `202 ACCEPTED` +- **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. -This endpoint only supports dynamic updating of the `logger.level` parameter for now. +::: info -For possible values please refer to the configuration reference (TODO: -[Tracking issue for configuration reference](https://github.com/hyperledger/iroha-2-docs/issues/392)). +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](../guide/support.md) 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](https://github.com/hyperledger/iroha-2-docs/issues/392). + +::: -**Example request:** +**Example**: ```json { @@ -73,43 +156,62 @@ For possible values please refer to the configuration reference (TODO: } ``` +#### Responses + +| Code | Response | Description | +| :--: | -------- | ------------------------------------------------------------------------------- | +| 202 | Accepted | The request to update the configuration is accepted and is due to be processed. | + ::: tip Guarantees -A successful configuration update does not guarantee that the configuration is indeed updated. While -consecutive [configuration retrievals](#configuration-retrieve) will return updated values, the actual update is -performed asynchronously. +A successful configuration update does not guarantee that the configuration is indeed updated. While a follow-up [Configuration / Retrieve](#configuration-retrieve) request will return updated values, the actual update is performed asynchronously. ::: ## Events -- **Protocol:** HTTP -- **Protocol Upgrade:** WebSocket -- **Endpoint:** `/events` - -After a handshake, the client should send an -[`EventSubscriptionRequest`](/reference/data-model-schema#eventsubscriptionrequest). Then the server sends an -[`EventMessage`](/reference/data-model-schema#eventmessage). Messages are SCALE-encoded[^1]. +- **Protocols**: `HTTP` upgraded to `WebSocket` +- **Encoding**: `SCALE` +- **Endpoint**: `/events` ### Transaction Events -Transaction event statuses can be either `Validating`, `Committed` or `Rejected`. +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`). -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 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. -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. +#### 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`](/reference/data-model-schema#eventsubscriptionrequest) request, after which the server sends an [`EventMessage`](/reference/data-model-schema#eventmessage) response. ## Health -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/health` +- **Protocol**: `HTTP` +- **Method**: `GET` +- **Encoding**: `JSON` +- **Endpoint**: `/health` + +#### Requests -Responses with `200 OK` and a current status of peer as a JSON string: +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" @@ -117,15 +219,28 @@ Responses with `200 OK` and a current status of peer as a JSON string: ## Metrics -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/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 -**Responses:** +| Code | Response | Description | +| :--: | -------- | --------------------------------------------------- | +| 200 | Metrics | Returns a report on 8 out of 10 Prometheus metrics. | -`200 OK` reports 8 of 10 metrics: +**Example**: -::: details Sample Prometheus metrics +::: details Example `200 Metrics` response ```bash # HELP accounts User accounts registered at this time @@ -172,37 +287,63 @@ view_changes 0 ::: -Learn [how to use metrics](/guide/advanced/metrics). +::: info + +To learn more about metrics, see [Metrics](../guide/advanced/metrics.md). + +::: + +## 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`](data-model-schema.md#signedtransaction) objects encoded with `SCALE`; must be decoded by the client. | ## Query -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/query` -- **Expects:** - - **Body:** SCALE-encoded[^1] [`VersionedSignedQuery`](/reference/data-model-schema#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](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#derivable) and - [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) 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. - - **`fetch_size`:** An optional parameter in queries. Use it to specify the exact number of results returned by a - query. - -**Responses:** - -| Response | Status | Body | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------ | -| Success | 200 | [`VersionedBatchedResponse`](/reference/data-model-schema#versionedbatchedresponse-value) | -| Conversion Error | 400 | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | -| Evaluate Error | 400 | [`QueryExecutionFail::Evaluate(String)`](/reference/data-model-schema#queryexecutionfail) | -| Signature Error | 401 | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | -| Permission Error | 403 | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | -| Find Error | 404 | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | +- **Protocol**: `HTTP` +- **Method**: `POST` +- **Encoding**: `SCALE` +- **Endpoint**: `/query` + +#### Requests + +This endpoint expects the following data: + + - **Body**: [`VersionedSignedQuery`](/reference/data-model-schema#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 + +| Code | Response | Body | +| :--: | ---------------- | ------------------------------------------------------------------------------------------------ | +| 200 | Success | [`VersionedBatchedResponse`](/reference/data-model-schema#versionedbatchedresponse-value) | +| 400 | Conversion Error | [`QueryExecutionFail::Conversion(String)`](/reference/data-model-schema#queryexecutionfail) | +| 400 | Evaluate Error | [`QueryExecutionFail::Evaluate(String)`](/reference/data-model-schema#queryexecutionfail) | +| 401 | Signature Error | [`QueryExecutionFail::Signature(String)`](/reference/data-model-schema#queryexecutionfail) | +| 403 | Permission Error | [`QueryExecutionFail::Permission(String)`](/reference/data-model-schema#queryexecutionfail) | +| 404 | Find Error | [`QueryExecutionFail::Find(FindError)`](/reference/data-model-schema#queryexecutionfail) | + +::: info + +The `200 Success` response returns results that are ordered by `id`, which use Rust's [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) and [Ord](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits. + +::: ### Account Not Found 404 @@ -224,17 +365,66 @@ Whether each prerequisite object was found and [`FindError`](/reference/data-mod | Y | - | N | - | [`FindError::AssetDefinition(AssetDefinitionId)`](/reference/data-model-schema#finderror) | | Y | Y | Y | N | [`FindError::Asset(AssetId)`](/reference/data-model-schema#finderror) | +## 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](data-model-schema.md) as JSON objects. | + ## Status -- **Protocol:** HTTP -- **Method:** `GET` -- **Endpoint:** `/status` -- **Expects:** an optional `Accept: application/x-parity-scale` request header to encode response with SCALE[^1]. - Otherwise, will fall back to `application/json`. -- **Responses**: with `Content-Type` set either to `application/json` or `application/x-parity-scale`, and an - accordingly encoded response body. +::: 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 -Response body is of the following `Status` structure: +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: ```rust struct Status { @@ -260,25 +450,9 @@ struct Uptime { } ``` -::: warning 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). -For more details, see related [issue](https://github.com/hyperledger/iroha/issues/3964). +::: details Examples -::: - -::: tip Compact Form in SCALE - -Fields with type `u64` serialized in the [Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). - -::: - -::: details Sample responses - -These samples represent the same data: +The following examples represent the same data: ::: code-group @@ -303,13 +477,43 @@ These samples represent the same data: ::: +::: warning 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse). + +For more details, see the related [GitHub issue](https://github.com/hyperledger/iroha/issues/3964). + +::: + +::: tip Compact Form in SCALE + +Fields with `u64` type are serialized in the [Compact form](https://docs.substrate.io/reference/scale-codec/#fn-1). + +::: + ### 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. +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**: ::: code-group +```json [/status] +{ + "peers": 4, + "blocks": 5, + "txs_accepted": 31, + "txs_rejected": 3, + "uptime": { + "secs": 5, + "nanos": 937000000 + }, + "view_changes": 2, + "queue_size": 18 +} +``` + ```json [/status/peers] 4 ``` @@ -329,23 +533,21 @@ returns the corresponding JSON value. ## Transaction -- **Protocol:** HTTP -- **Method:** `POST` -- **Endpoint:** `/transaction` -- **Expects:** - - **Body:** SCALE-encoded[^1] [`VersionedSignedTransaction`](/reference/data-model-schema#versionedsignedtransaction) +- **Protocol**: `HTTP` +- **Method**: `POST` +- **Encoding**: `SCALE` +- **Endpoint**: `/transaction` + +#### Requests -**Responses:** +This endpoint expects the following data: -| Status | Description | -| ------ | ---------------------------------------------------------------------- | -| 200 | Transaction Accepted (But not guaranteed to have passed consensus yet) | -| 400 | Transaction Rejected (Malformed) | -| 401 | Transaction Rejected (Improperly signed) | + - **Body**: [`VersionedSignedTransaction`](/reference/data-model-schema#versionedsignedtransaction) -[^1]: - For more information on Parity SCALE Codec check - [Substrate Dev Hub](https://docs.substrate.io/reference/scale-codec/) and codec's - [GitHub repository](https://github.com/paritytech/parity-scale-codec). +#### 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. |