Skip to main content

Querying the Blockchain

This page describes how to query the Network in order to fetch data such as transactions and blocks (hyperblocks).

note

On this page, we refer to the Gateway (Proxy) REST API - i.e. the one backed by an observing squad.

Querying broadcasted transactions​

In order to fetch a previously-broadcasted transaction, use:

note

Fetching a recently broadcasted transaction may not return the hyperblock coordinates (hyperblock nonce and hyperblock hash) in the response. However, once the transaction is notarized on both shards (with acknowledgement from the metachain), the hyperblock coordinates will be set and present in the response.

In order to inspect the status of a transaction, use:

For the difference between the shallow status and the process status, see the next section.

Transaction Status​

Shallow status​

The shallow status of a transaction indicates whether a transaction has been handled and executed by the network. However, the shallow status does not provide information about the transaction's processing outcome, and does not capture processing errors. That is, transactions processed with errors (e.g. user error or out of gas) have the status success (somehow counterintuitively).

note

The shallow status is, generally speaking, sufficient for integrators that are only interested into simple transfers (of EGLD or custom tokens).

The shallow status of a transaction can be one of the following:

  • success - the transaction has been fully executed - with respect to the network's sharded architecture, it has been executed in both source and destination shards.
  • invalid - the transaction has been marked as invalid for execution at sender's side (e.g., not enough balance at sender's side, sending value to non-payable contracts etc.).
  • pending - the transaction has been accepted in the mempool or accepted and partially executed (in the source shard).

Process status​

The process status of a transaction indicates whether a transaction has been processed successfully or not.

note

The process status is, generally speaking, useful for integrators that are interested in smart contract interactions.

note

Fetching the process status of a transaction is less efficient than fetching the shallow status.

The process status of a transaction can be one of the following:

  • success - the transaction has been fully executed - with respect to the network's sharded architecture, it has been executed in both source and destination shards.
  • fail - the transaction has been processed, but with errors (e.g., user error or out of gas), or it has been marked as invalid (see shallow status).
  • pending - the transaction has been accepted in the mempool or accepted and partially executed (in the source shard).
  • unknown - the processing status cannot be precisely determined yet.

Querying hyperblocks and fully executed transactions​

In order to query executed transactions, please follow:

Querying finality information​

In order to fetch the nonce (the height) of the latest final (hyper) block, one would perform the following request against the on-premises Proxy instance:

curl http://myProxy:8079/network/status/4294967295

Above, 4294967295 is a special number - the ID of the Metachain.

From the response, one should be interested into the field erd_highest_final_nonce, which will point to the latest final hyperblock.

  "data": {
    "status": {
      "erd_highest_final_nonce": 54321
      ...
    }
  },
  ...
}