Hive Developer Portal
Understanding Transaction Status
How to use the Hive API to check the status of a transaction for a given trx_id
value.
The overarching goal is to stop using condenser_api.broadcast_transaction_synchronous
but we still want the benefits.
- Why Client-side Computation?
- Why After Broadcast?
- Why In General?
- Client-side Computation
- After Broadcast
- Polling
Why Client-side Computation?
The primary reason to compute the trx_id
before broadcast is to track the transaction when quality of service is impacted. If the trx_id
is known before condenser_api.broadcast_transaction
, but the response times out, we can still track the transaction.
Why After Broadcast?
Assuming quality of service has not been impacted, solely relying on the condenser_api.broadcast_transaction
response should not be a problem.
Why In General?
Whichever method we use above to get trx_id
, we can track it if anything goes wrong while we wait for it to be included in a block. Then, even after it’s included, we can still track a transaction while we wait for 2/3rds of the witnesses to verify (thus irreversable). We can poll transaction_status_api
until we’re satisfied that the trx_id
has been included.
Client-side Computation
First, create a transaction, for example:
{
"ref_block_num":20,
"ref_block_prefix":2890012981,
"expiration":"2018-10-15T19:52:09",
"operations":[
{
"type":"transfer_to_vesting_operation",
"value":{
"from":"alice",
"to":"bob",
"amount":{"amount":"8204", "precision":3, "nai":"@@000000021"}
}
}
],
"extensions":[]
}
From this, we create a serialization, call it hex
:
1400351942ace9efc45b010305616c69636503626f620c2000000000000003535445454d00000
Next, we convert hex
to binary, call it bytes
and digest bytes
, with sha256, call it digest
:
eba610257ad6c60d89f84ce54d3e10b52c18d4cce5547867e2450aeac80d9530
Last, we truncate digest
to 20 bytes / 40 hex digits:
eba610257ad6c60d89f84ce54d3e10b52c18d4cc
This is the computed trx_id
.
After Broadcast
If your client does not support client-side id computation, you can still get the trx_id
from the result of condenser_api.broadcast_transaction
.
The combination of condenser_api.broadcast_transaction
and transaction_status_api.find_transaction
, described below, allows us to avoid using condenser_api.broadcast_transaction_synchronous
, which is being deprecated.
Polling
Now that we have trx_id
, we can poll transaction_status_api.find_transaction
, for example:
curl -s --data '{"jsonrpc":"2.0", "method":"transaction_status_api.find_transaction", "params":{"transaction_id":"eba610257ad6c60d89f84ce54d3e10b52c18d4cc"}, "id":1}' https://api.hive.blog
Which returns:
{"jsonrpc":"2.0","result":{"status":"unknown"},"id":1}
We can provide the expiration:
curl -s --data '{"jsonrpc":"2.0", "method":"transaction_status_api.find_transaction", "params":{"transaction_id":"eba610257ad6c60d89f84ce54d3e10b52c18d4cc","expiration":"2018-10-15T19:52:09"}, "id":1}' https://api.hive.blog
Which returns:
{"jsonrpc":"2.0","result":{"status":"too_old"},"id":1}
Possible status
results are:
Status | Meaning |
---|---|
unknown |
Expiration time in future, transaction not included in block or mempool |
within_mempool |
Transaction in mempool |
within_reversible_block |
Transaction has been included in block, block not irreversible (result will also contain block_num ) |
within_irreversible_block |
Transaction has been included in block, block is irreversible (result will also contain block_num ) |
expired_reversible |
Transaction has expired, transaction is not irreversible (transaction could be in a fork) |
expired_irreversible |
Transaction has expired, transaction is irreversible (transaction cannot be in a fork) |
too_old |
Transaction is too old, I don’t know about it |