Postchain REST API

Version 17 · OpenAPI 3.0.3

GTV

GTV (Generic Transfer Value) is DER encoded ASN.1 with this schema:

  Messages DEFINITIONS ::= BEGIN
    DictPair ::= SEQUENCE {
      name UTF8String,
      value RawGtv
    }
    RawGtv ::= CHOICE {
      null [0] NULL,
      byteArray [1] OCTET STRING,
      string [2] UTF8String,
      integer [3] INTEGER,
      dict [4] SEQUENCE OF DictPair,
      array [5] SEQUENCE OF RawGtv,
      bigInteger [6] INTEGER
    }
  END

GTX

GTX (Generic Transaction) is a way to encode signed transactions in GTV. The structure is:

[
  [
    blockchainRid,
    [
      [ "operation1", [arg1, arg2, arg3, ...] ],
      [ "operation2", [arg1, arg2, arg3, ...] ],
      ...
    ],
    [ signerPubKey1, signerPubKey2, ... ]
  ],
  [ signature1, signature2, .. ]
]

The blockchain RID, signer public keys and signatures are encoded as byteArray. The signatures are made with ECDSA with the secp256k1 curve. The hash to sign, which is also used as transaction RID in this API, is SHA-256 computed recursively, as a Merkle tree. For each node in the tree, a prefix byte is added to data to hash: - 1 for a leaf - 7 for start of an array - 8 for start of a dict - 0 otherwise

The exact procedure to calculate the hash can be discovered in the source code in Kotlin or TypeScript.

block

Fetch block(s)

GET /blocks/{blockchainRid}

Fetch blocks info

This operation retrieves information about blocks from the specified chain.

You can define either a timeframe or block height boundaries to fetch the blocks you're interested in.

Parameters

Responses

200 Found

application/json

type: array
items:
  $ref: '#/components/schemas/blockInfo'

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /blocks/{blockchainRid}/{blockRid}

Fetch block info by block RID

This operation retrieves block details from the specified chain using the block RID. By setting the Accept: application/octet-stream header, the response will be returned as a binary GTV; otherwise, it defaults to JSON.

Parameters

Responses

200 OK

application/json

oneOf:
- $ref: '#/components/schemas/blockInfo'
- $ref: '#/components/schemas/nullValue'

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

GET /blocks/{blockchainRid}/height/{height}

Fetch block info by block height

This method retrieves block details from the specified chain using the block height.

If you specify the Accept: application/octet-stream header, the response will be in binary GTV format; otherwise, it defaults to JSON.

Parameters

Responses

200 OK

application/json

oneOf:
- $ref: '#/components/schemas/blockInfo'
- $ref: '#/components/schemas/nullValue'

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

GET /blocks/{blockchainRid}/confirm/{blockRid}

Confirm block by block RID

Sign the block and return the block signature if the block is committed.

By specifying the Accept: application/octet-stream header, the response will be in binary GTV format; otherwise, it defaults to JSON.

Parameters

Responses

200 OK

application/json

oneOf:
- $ref: '#/components/schemas/blockSignature'
- $ref: '#/components/schemas/nullValue'

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

blockchain

Blockchain information

GET /blockchain/{blockchainRid}/height

Fetch height of next block to be built/synced

This operation fetches the block height for the next block to be built/synced.

Parameters

Responses

200 OK

application/json

Schema: blockHeight

Example

{
  "blockHeight": 4711
}

404 Chain not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

GET /version/{blockchainRid}

Get API version for the subnode running the given blockchain

Responses

200 OK

application/json

Schema: version

Example: version

{
  "version": 15
}

configuration

Manage blockchain configurations

GET /config/{blockchainRid}

Fetch blockchain configuration

Retrieve the configuration of a chain. By specifying the height, you can fetch the active configuration at that particular block.

If you include the Accept: application/octet-stream header, the response will be in binary GTV format; otherwise, it defaults to XML.

Parameters

Responses

200 Found

text/xml

Example

"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<dict>\n    <entry key=\"blockstrategy\">\n        <dict>\n            <entry key=\"name\">\n                <string>net.postchain.base.BaseBlockBuildingStrategy</string>\n            </entry>\n        </dict>\n    </entry>\n    <entry key=\"configurationfactory\">\n        <string>net.postchain.gtx.GTXBlockchainConfigurationFactory</string>\n    </entry>\n    <entry key=\"gtx\">\n        <dict>\n            <entry key=\"modules\">\n                <array>\n                    <string>net.postchain.configurations.GTXTestModule</string>\n                    <string>net.postchain.gtx.StandardOpsGTXModule</string>\n                </array>\n            </entry>\n        </dict>\n    </entry>\n    <entry key=\"signers\">\n        <array>\n            <bytea>03A301697BDFCD704313BA48E51D567543F2A182031EFD6915DDC07BBCC4E16070</bytea>\n            <bytea>031B84C5567B126440995D3ED5AABA0565D71E1834604819FF9C17F5E9D5DD078F</bytea>\n            <bytea>03B2EF623E7EC933C478135D1763853CBB91FC31BA909AEC1411CA253FDCC1AC94</bytea>\n            <bytea>0203C6150397F7E4197FF784A8D74357EF20DAF1D09D823FFF8D3FC9150CBAE85D</bytea>\n        </array>\n    </entry>\n</dict>\n"

application/octet-stream

400 Invalid height

application/json

Schema: error

Example: configurationNotFound

{
  "error": "Failed to find configuration"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

POST /config/{blockchainRid}

Validate blockchain configuration

Verify if a configuration is valid for a blockchain in its current state. This operation only checks the validity of the configuration without applying it. The configuration can be submitted either as XML (using text/xml content type) or GTV (using application/octet-stream content type).

Nodes running in managed mode require a signature to be included, allowing only the blockchain provider to verify the configuration.

Parameters

Request body

text/xml

Example

"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<dict>\n    <entry key=\"blockstrategy\">\n        <dict>\n            <entry key=\"name\">\n                <string>net.postchain.base.BaseBlockBuildingStrategy</string>\n            </entry>\n        </dict>\n    </entry>\n    <entry key=\"configurationfactory\">\n        <string>net.postchain.gtx.GTXBlockchainConfigurationFactory</string>\n    </entry>\n    <entry key=\"gtx\">\n        <dict>\n            <entry key=\"modules\">\n                <array>\n                    <string>net.postchain.configurations.GTXTestModule</string>\n                    <string>net.postchain.gtx.StandardOpsGTXModule</string>\n                </array>\n            </entry>\n        </dict>\n    </entry>\n</dict>\n"

application/octet-stream

Responses

200 OK

application/json

type: object

400 Invalid configuration

application/json

Schema: error

Example: invalidConfiguration

{
  "error": "Invalid configuration"
}

401 Signature is required, invalid or not the dapp provider of this blockchain

application/json

Schema: error

Example: invalidConfiguration

{
  "error": "Configuration must be signed by blockchain provider"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /config/{blockchainRid}/next_height

Fetch the next blockchain configuration height

This method retrieves the block height at which the next configuration update will occur. For example, if the current block height is 10 and the update is scheduled for block height 25, querying with a request specifying block height 15 will return 25, as it is the closest configuration update block height for that blockchain.

Parameters

Responses

200 OK

application/json

oneOf:
- $ref: '#/components/schemas/blockHeight'
- $ref: '#/components/schemas/nullValue'

Example

{
  "blockHeight": 4711
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /config/{blockchainRid}/features

Fetch the blockchain configuration features

Retrieves the configuration features for a given blockchain. Currently, only the merkle hash version can be obtained by invoking this operation.

When specyfing the height, the method will fetch the active configuration at that height.

If the Accept: application/octet-stream header is specified, then the operation will return a binary GTV response, otherwise defaults to JSON.

Parameters

Responses

200 OK

application/json

Example

{
  "blockHeight": {
    "merkle_hash_version": 2
  }
}

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

error

Information about errors

GET /errors/{blockchainRid}

Fetch blockchain errors

This method retrieves the last 5 blockchain errors for a given blockchain RID.

Parameters

Responses

200 Found

application/json

type: array
items:
  type: string

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

experimental

Experimental endpoints, use with caution

GET /blockchain/{blockchainRid}/nodestate

Experimental - Fetch current state of blockchain node

This endpoint is currently in beta and may be subject to changes.
Retrieve the current state of the blockchain node, which includes both the blockchain and node states.

Parameters

Responses

200 OK

application/json

type: object
required:
- state
properties:
  state:
    type: string
    enum:
    - RUNNING_HISTORIC
    - RUNNING_VALIDATOR
    - RUNNING_READ_ONLY
    - PAUSED_READ_ONLY
    - FORCED_READ_ONLY
    - IMPORTING_FORCED_READ_ONLY
    - UNARCHIVING_FORCED_READ_ONLY
    - UNARCHIVING_VALIDATOR
    - UNARCHIVING_READ_ONLY
    description: '* RUNNING_HISTORIC - Running in Historic context
      * RUNNING_VALIDATOR - Running as Validator
      * RUNNING_READ_ONLY - Running in read-only mode
      * PAUSED_READ_ONLY - Paused in read-only mode
      * FORCED_READ_ONLY - Node is forced to read-only mode
      * IMPORTING_FORCED_READ_ONLY - Importing blockchain and is running in forced read-only mode
      * UNARCHIVING_FORCED_READ_ONLY - Unarchiving blockchain and is running in forced read-only mode
      * UNARCHIVING_VALIDATOR - Unarchiving blockchain and is running as Validator
      * UNARCHIVING_READ_ONLY - Unarchiving blockchain and is running in read-only mode
      '

Example

{
  "state": "RUNNING_VALIDATOR"
}

404 Chain not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

node

Node information

GET /node/{blockchainRid}/my_status

Query node EBFT status

This operation is used to determine the current node operational status, which is helpful for debugging purposes.

There are three statuses that the operation can return: - WaitBlock - The node is waiting for the primary node to build a block. - HaveBlock - The node has fetched the newly built block from the primary node and verified its validity. - Prepared - This status indicates that the node has received status updates from 2f other nodes, confirming that they are in the "HaveBlock" state and that they all hold the same block.

Returns a JSON object containing the the current node status.

Parameters

Responses

200 - `state` - The state of the node. - `height` - The current block height. - `serial` - The unique identifier of the protocol state. - `round` - The current round of the consensus protocol. - `revolting` - Indicates whether the node is rejecting or aborting the current process.

application/json

Schema: nodeStatus

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /node/{blockchainRid}/statuses

Query all nodes EBFT statuses

This operation is used to determine the current operational status of multiple nodes in the cluster, which is helpful for debugging purposes.

There are three statuses that the operation can return: - WaitBlock - The node is waiting for the primary node to build a block. - HaveBlock - The node has fetched the newly built block from the primary node and verified its validity. - Prepared - This status indicates that the node has received status updates from 2f other nodes, confirming that they are in the "HaveBlock" state and that they all hold the same block.

Returns an array of JSON objects, each containing the current node status.

Parameters

Responses

200 - `state` - The state of the node. - `height` - The current block height. - `serial` - The unique identifier of the protocol state. - `round` - The current round of the consensus protocol. - `revolting` - Indicates whether the node is rejecting or aborting the current process.

application/json

type: array
items:
  $ref: '#/components/schemas/nodeStatus'

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /brid/iid_{chainIid}

Get blockchain RID

Retrieves the current blockchain RID for a given chain ID.

Usually, this method is used to obtain the blockchain RID of the Directory Chain; To do that, specify 0 in the chainId property.

Parameters

Responses

200 OK. The response is an unquoted string in plain/text format.

text/plain

Schema: hash

Example

"0398A1E7B0F87709AFD14CD1821EAAAFB41931A8097FFA2D83E5FE10DA7E4DD5"

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with chain Iid: <iid> in DB. Did you add this BC to the node?"
}

GET /version

Get API version

Retrieves the current version of the REST API. Every time the API is updated, the version is incremented by 1.

Responses

200 OK

application/json

Schema: version

Example: version

{
  "version": 14
}

GET /infrastructure_version

Get infrastructure version

Retrieves the current version of the Postchain software that the node is running.

Responses

200 OK

application/json

Schema: infrastructureVersion

Example: infrastructure_version

{
  "postchain": "3.16.4",
  "infrastructure": "net.postchain.d1.D1InfrastructureFactory",
  "infrastructure-version": "3.16.15",
  "rest-api": "14",
  "database-server-version": "16.7"
}

GET /infrastructure_version/{blockchainRid}

Get infrastructure version for the subnode running the given blockchain

Responses

200 OK

application/json

Schema: infrastructureVersion

Example: infrastructure_version

{
  "postchain": "3.16.5",
  "infrastructure": "net.postchain.d1.D1MasterInfrastructureFactory",
  "infrastructure-version": "3.16.16",
  "rest-api": "15",
  "database-server-version": "16.7"
}

GET /highest_block_height_anchoring_check/{blockchainRid}

Check anchoring status for a blockchain

Returns the highest block height of the chain which has been anchored to Cluster Anchoring Chain (CAC), System Anchoring Chain (SAC) and Etheruem (ETH).

Results are computed periodically using a configurable interval of time for each anchoring level: CAC, SAC and ETH.

Parameters

Responses

200 OK

application/json

Schema: highestBlockHeightAnchoringCheck

Example

{
  "highestBlockHeightAnchoringCheck": {
    "cac": {
      "height": 126,
      "match": true
    },
    "sac": {
      "height": 126,
      "match": true
    },
    "evm": {
      "error": "Unable to verify last anchored height on EVM."
    }
  }
}

404 Chain not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

query

Make a query

GET /query/{blockchainRid}

Make query

This operation enables querying either a node on the Chromia network or a local node.

To invoke it, you must include a type argument in the query string parameters. The type argument corresponds to the name of the query defined in the Rell code.

You can pass additional arguments for the Rell query defined in the code to this method using the standard REST syntax: /type=my_query&arg1=value&arg2=value. Here, type represents the name of the query, and arg1 and arg2 are the query arguments.

This operation is intended for development, testing, and simple web applications. For more complex production use cases, it is recommended to use /query_gtv instead.

Parameters

Responses

200 OK

application/json

description: Query result as JSON

400 Invalid query

application/json

Schema: error

Example: missingQueryType

{
  "error": "Missing query type"
}

Example: unknownQuery

{
  "error": "Unknown query: the_query"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

POST /query/{blockchainRid}

Make query

Deprecated

This operation is deprecated, and will be removed at some point, use GET /query or /query_gtv instead.

To invoke this operation, you must include the type property in the JSON body. The type property corresponds to the name of the query defined in the Rell code.

If your query contains multiple arguments, then you must pass their names and values in the corresponding order as specified in the query.

Parameters

Request body

application/json

Schema: query

Responses

200 OK

application/json

description: Query result as JSON

400 Invalid query

application/json

Schema: error

Example: missingQueryType

{
  "error": "Missing query type"
}

Example: unknownQuery

{
  "error": "Unknown query: the_query"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /dquery/{blockchainRid}

Make direct query

Deprecated

By invoking this operation, you request a specific web resource from the front-end application's decentralized storage. This resource can be a picture, video, code, or anything else.

Returns raw data without JSON wrapping.

This operation is deprecated and will be removed at some point of time; use /web_query instead.

Parameters

Responses

200 OK

400 Invalid query

application/json

Schema: error

Example: missingQueryType

{
  "error": "Missing query type"
}

Example: unknownQuery

{
  "error": "Unknown query: the_query"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /web_query/{blockchainRid}/{type}

Make web query

By invoking this operation, you request a specific web resource from the front-end application's decentralized storage. This resource can be a picture, video, code, or anything else.

Returns raw data without JSON wrapping.

Parameters

Responses

200 OK

400 Invalid query

application/json

Schema: error

Example: missingQueryType

{
  "error": "Missing query type"
}

Example: unknownQuery

{
  "error": "Unknown query: the_query"
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /query_gtv/{blockchainRid}

Make a query with GTV encoded response

Make a query with GTV encoded response to a chain. Response body contains binary GTV value.

Parameters

Responses

200 OK

application/octet-stream

400 Invalid query

application/octet-stream

404 Not found

application/octet-stream

POST /query_gtv/{blockchainRid}

Make a GTV encoded query

Make a GTV encoded query to the specified chain.

Request body contains binary GTV array with the query name as first element (string) and the named parameters as second element (dict).

Response body contains binary GTV value.

Parameters

Request body

application/octet-stream

Responses

200 OK

application/octet-stream

400 Invalid query

application/octet-stream

404 Not found

application/octet-stream

transaction

Submit or fetch transaction(s)

POST /tx/{blockchainRid}

Submit transaction

This operation submits a transaction to the chain.

The request body can either include a hex-encoded GTX transaction in a JSON wrapper or a binary GTV (by specifying Content-Type: application/octet-stream).

Please note that read replicas do not support this endpoint.

Parameters

Request body

application/json

Schema: tx

application/octet-stream

Responses

200 Transaction queued

application/json

type: object

application/octet-stream

400 Bad request

application/json

Schema: error

Example: couldNotParseJson

{
  "error": "Could not parse json"
}

Example: incorrectTransaction

{
  "error": "Transaction <hex-string> is not correct"
}

Example: invalidTxFormat

{
  "error": "Invalid tx format. Expected {\"tx\": <hex-string>}"
}

Example: invalidTx

{
  "error": "Transaction is invalid"
}

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

application/octet-stream

409 Transaction already in queue

application/json

Schema: error

Example: transactionAlreadyInQueue

{
  "error": "Transaction already in queue"
}

application/octet-stream

503 Transaction queue is full

application/json

Schema: error

Example: queueFull

{
  "error": "Transaction queue is full"
}

application/octet-stream

GET /tx/{blockchainRid}/waiting

Fetch list of waiting transaction RIDs

Fetch a list of all waiting transaction RIDs from a chain. Read replicas do not support this endpoint.

Parameters

Responses

200 Found

application/json

type: array
items:
  $ref: '#/components/schemas/hash'

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /tx/{blockchainRid}/waiting/{txRid}

Fetch waiting transaction

This operation fetches a waiting transaction from the specified chain.

Will return a binary response with application/octet-stream content-type.

Read replicas do not support this endpoint.

Parameters

Responses

200 Found

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

Example: txNotFound

{
  "error": "Can't find waiting transaction with RID: <hex-string>"
}

application/octet-stream

GET /tx/{blockchainRid}/rejected

Fetch list of rejected transactions

Fetches the list of rejected transaction RIDs and the corresponding rejection reasons.

Read replicas do not support this endpoint.

Parameters

Responses

200 Found

application/json

type: array
items:
  type: object
  required:
  - txRID
  - rejectReason
  - rejectTimestamp
  properties:
    txRID:
      $ref: '#/components/schemas/hash'
    rejectReason:
      type: string
    rejectTimestamp:
      $ref: '#/components/schemas/timestamp'

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /tx/{blockchainRid}/{txRid}

Fetch transaction

Retrieve transaction data from a given blockchain.

When the Accept: application/octet-stream header is specified, the operation will return a binary GTV response.

If the Accept: application/json header is specified, returns a JSON object containing the HEX encoded transaction details.

Parameters

Responses

200 Found

application/json

Schema: tx

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

Example: txNotFound

{
  "error": "Can't find transaction with RID: <hex-string>"
}

application/octet-stream

GET /transactions/{blockchainRid}/{txRid}

Fetch transaction info

This operation retrieves the information about a transaction from a given blockchain.

Parameters

Responses

200 - `blockRID` - Unique identifier of the block. - `blockHeight` - The current height of the block. - `witness` - Data that proves the validity of the transaction. - `txRID` - Unique identifier of the transaction. - `txHash` - Transaction hash. - `txData` - Transaction data. - `blockHeader` - Public key of nodes who are witnesses to this block. - `witnesses` - Hex encoded raw witness data. - `witnessSignatures` - Signatures of nodes who are witnesses to this block. - `timestamp` - Timestamp, milliseconds since midnight, January 1, 1970 UTC.

application/json

Schema: txInfo

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

Example: txNotFound

{
  "error": "Can't find transaction with RID: <hex-string>"
}

GET /transactions/{blockchainRid}

Fetch transactions info

Fetches a list of the most recent transactions from a specified blockchain, allowing you to retrieve up to 500 of the latest transactions.

Parameters

Responses

200 - `blockRID` - Unique identifier of the block. - `blockHeight` - The current height of the block. - `witness` - Data that proves the validity of the transaction. - `txRID` - Unique identifier of the transaction. - `txHash` - Transaction hash. - `txData` - Transaction data. - `blockHeader` - Public key of nodes who are witnesses to this block. - `witnesses` - Hex encoded raw witness data. - `witnessSignatures` - Signatures of nodes who are witnesses to this block. - `timestamp` - Timestamp, milliseconds since midnight, January 1, 1970 UTC.

application/json

type: array
items:
  $ref: '#/components/schemas/txInfo'

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /transactions/{blockchainRid}/count

Fetch number of successful transactions

Retrieves the number of successfully processed transactions in a given blockchain.

Parameters

Responses

200 Found

application/json

Schema: transactionsCount

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

GET /tx/{blockchainRid}/{txRid}/confirmationProof

Fetch transaction confirmation proof

Fetches the confirmation proof for a transaction on the specified blockchain.

When the Accept: application/octet-stream header is specified, a binary GTV response is returned. If the Accept: application/json header is specified, a JSON object is returned, containing HEX encoded transaction data.

Parameters

Responses

200 Found

application/json

Schema: confirmationProof

application/octet-stream

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

Example: txNotFound

{
  "error": "Can't find transaction with RID: <hex-string>"
}

application/octet-stream

GET /tx/{blockchainRid}/{txRid}/status

Fetch transaction status

Fetch the status of a transaction on the specified blockchain.

There are three transaction statuses: - Waiting - Transaction is waiting to be included in the block. - Confirmed - Transaction is included in the block. - Rejected - Transaction has been rejected

Note: The node stores up to 1000 rejected transaction statuses per chain in memory. Once this limit is reached, the oldest entry is discarded to make room for a new one.
Read replicas do not support this endpoint; use GET /transactions/{blockchainRid}/{txRid}?tx-data=false instead.

Parameters

Responses

200 OK

application/json

oneOf:
- $ref: '#/components/schemas/unknown'
- $ref: '#/components/schemas/waiting'
- $ref: '#/components/schemas/confirmed'
- $ref: '#/components/schemas/rejected'
discriminator:
  propertyName: status

Example: unknown

{
  "status": "unknown"
}

Example: waiting

{
  "status": "waiting"
}

Example: confirmed

{
  "status": "confirmed"
}

Example: rejected

{
  "status": "rejected",
  "rejectReason": "[module:operation(dapp/module/module.rell:17)] Operation 'module:operation' failed: Requirement error",
  "rejectTimestamp": 1740659274153
}

404 Not found

application/json

Schema: error

Example: chainNotFound

{
  "error": "Can't find blockchain with blockchainRID: <hex-string>"
}

Schemas

tx

type: object
required:
- tx
properties:
  tx:
    type: string
    pattern: '[0-9a-fA-F]{2,}'
    description: Hex encoded GTX transaction
    example: A581B83081B5A56B3069A12204200398A1E7B0F87709AFD14CD1821EAAAFB41931A8097FFA2D83E5FE10DA7E4DD5A51A3018A5163014A20E0C0C6D795F6F7065726174696F6EA5023000A5273025A1230421032BF0FCF83A287FB5EC71E4DAEA5DE892804A5BBBED6130DBCDDB871015C34EA0A5463044A14204404B425779BF8BD5ED503837337BBE102B7013F791F3BCFB812726EA93E076A3267656EC773AA10617E1ABDB25E97AB1CF2992CDB3E059D668C90BDA6BB91FE836

txInfo

type: object
required:
- blockRID
- blockHeight
- blockHeader
- witness
- witnesses
- witnessSignatures
- timestamp
- txRID
- txHash
properties:
  blockRID:
    $ref: '#/components/schemas/hash'
  blockHeight:
    type: integer
    format: int64
  blockHeader:
    $ref: '#/components/schemas/hex'
  witness:
    type: string
    pattern: '[0-9a-fA-F]{2,}'
    description: Hex encoded raw witness data
  witnesses:
    type: array
    description: Public key of nodes who are witnesses to this block
    items:
      $ref: '#/components/schemas/hex'
  witnessSignatures:
    type: array
    description: Signatures of nodes who are witnesses to this block
    items:
      $ref: '#/components/schemas/hex'
  timestamp:
    $ref: '#/components/schemas/timestamp'
  txRID:
    $ref: '#/components/schemas/hash'
  txHash:
    $ref: '#/components/schemas/hash'
  txData:
    $ref: '#/components/schemas/hex'

confirmationProof

type: object
required:
- proof
properties:
  proof:
    $ref: '#/components/schemas/hex'

unknown

type: object
required:
- status
properties:
  status:
    type: string
    enum:
    - unknown

waiting

type: object
required:
- status
properties:
  status:
    type: string
    enum:
    - waiting

confirmed

type: object
required:
- status
properties:
  status:
    type: string
    enum:
    - confirmed

rejected

type: object
required:
- status
- rejectReason
- rejectTimestamp
properties:
  status:
    type: string
    enum:
    - rejected
  rejectReason:
    type: string
  rejectTimestamp:
    $ref: '#/components/schemas/timestamp'

blockInfo

type: object
required:
- rid
- prevBlockRID
- header
- height
- transactions
- witness
- witnesses
- witnessSignatures
- timestamp
properties:
  rid:
    $ref: '#/components/schemas/hash'
  prevBlockRID:
    $ref: '#/components/schemas/hash'
  header:
    $ref: '#/components/schemas/hex'
  height:
    type: integer
    format: int64
  transactions:
    type: array
    items:
      type: object
      required:
      - rid
      - hash
      properties:
        rid:
          $ref: '#/components/schemas/hash'
        hash:
          $ref: '#/components/schemas/hash'
        data:
          $ref: '#/components/schemas/hex'
  witness:
    type: string
    pattern: '[0-9a-fA-F]{2,}'
    description: Hex encoded raw witness data
  witnesses:
    type: array
    description: Public key of nodes who are witnesses to this block
    items:
      $ref: '#/components/schemas/hex'
  witnessSignatures:
    type: array
    description: Signatures of nodes who are witnesses to this block
    items:
      $ref: '#/components/schemas/hex'
  timestamp:
    $ref: '#/components/schemas/timestamp'

blockHeight

type: object
required:
- blockHeight
properties:
  blockHeight:
    type: integer
    format: int64

blockSignature

type: object
required:
- subjectID
- data
properties:
  subjectID:
    $ref: '#/components/schemas/hex'
  data:
    $ref: '#/components/schemas/hex'

query

Named arguments to query as additional properties

description: Named arguments to query as additional properties
type: object
required:
- type
properties:
  type:
    type: string
    description: Query name
additionalProperties: true
example:
  type: my_query
  arg1: 17
  arg2: foo

nodeStatus

type: object
required:
- state
- height
- serial
- round
- revolting
properties:
  state:
    type: string
    enum:
    - WaitBlock
    - HaveBlock
    - Prepared
    description: '* WaitBlock - before PRE-PREPARE
      * HaveBlock - after PRE-PREPARE, PREPARE message is sent
      * Prepared - _prepared_ state, COMMIT message is sent
      '
  height:
    type: integer
    format: int64
  serial:
    type: integer
    format: int64
  round:
    type: integer
    format: int64
  revolting:
    type: boolean
example:
  state: WaitBlock
  height: 4711
  serial: 135639938065
  round: 0
  revolting: false

error

type: object
required:
- error
properties:
  error:
    type: string
    description: Error message

hash

Hex encoded hash

type: string
pattern: '[0-9a-fA-F]{64}'
description: Hex encoded hash

hex

Hex encoded data

type: string
pattern: '[0-9a-fA-F]{0,}'
description: Hex encoded data

height

Block height

type: integer
description: Block height

timestamp

Timestamp, milliseconds since midnight, January 1, 1970 UTC.

type: integer
minimum: -1
format: int64
description: Timestamp, milliseconds since midnight, January 1, 1970 UTC.
example: 1740659274153

nullValue

type: 'null'

version

type: object
required:
- version
properties:
  version:
    type: integer
    minimum: 1
    format: int32
    description: API version

infrastructureVersion

type: object
properties:
  postchain:
    type: string
    description: Postchain version
  infrastructure:
    type: string
    description: Infrastructure name
  infrastructure-version:
    type: string
    description: Infrastructure version
  rest-api:
    type: string
    description: REST API version
  database-server-version:
    type: string
    description: Database server version

transactionsCount

type: object
required:
- transactionsCount
properties:
  transactionsCount:
    type: integer
    format: int64

signature

Signature(s) made up of pubkey and signed data

type: string
pattern: (([0-9a-fA-F]+:[0-9a-fA-F]+)(,|$))+
description: Signature(s) made up of pubkey and signed data

highestBlockHeightAnchoringCheck

type: object
properties:
  cac:
    $ref: '#/components/schemas/anchoringChainCheck'
  sac:
    $ref: '#/components/schemas/anchoringChainCheck'
  evm:
    $ref: '#/components/schemas/anchoringChainCheck'

anchoringChainCheck

type: object
properties:
  height:
    type: integer
    description: Blockchain height that was verified if anchored.
  match:
    type: boolean
    description: Result of matching the blockchain block rid against the anchored block rid.
  error:
    type: string
    description: Error message that occurred during verification process.