Status Streaming In Hyperledger Iroha

So, you have created your first transaction or batch of transactions in Iroha, and treasure it so much. Congratulations!

And now, you want to monitor each step of your transaction’s life? Let’s go for it.

To eliminate the need to poll a transaction’s status, we created the StatusStream feature to subscribe to a transaction’s status, and keep you up-to-date about what’s going on inside this magic box called Iroha.

The general scheme of using StatusStream is pretty straightforward:

1. You create a transaction
2. You subscribe to its StatusStream
3. You send the transaction
4. You begin to receive updates on its status

Easy, right?

You can also subscribe after the transaction has been sent, but beware that quite logically, in this case you might not receive the initial statuses, only those after you subscribed.

Let’s see what it looks like in Kotlin, using Iroha’s Java library:

val tx = Transaction.builder(adminId)
    .transferAsset(adminId, "test@test", "coin#test", "", "0.1")
    .sign(adminKeypair)
    .build()
thread(start = true) {
    irohaAPI.txStatus(Utils.hash(tx)).blockingSubscribe {
        println(it)
    }
}
irohaAPI.transactionSync(tx)

And here is what we will get in the logs with that:

tx_status: NOT_RECEIVED
tx_hash:"f286893cd029b19b11172ff01b3d07579041ccf61da2a716ee026e8f5f2ec542"
tx_status: STATELESS_VALIDATION_SUCCESS
tx_hash:"f286893cd029b19b11172ff01b3d07579041ccf61da2a716ee026e8f5f2ec542"
tx_status: ENOUGH_SIGNATURES_COLLECTED
tx_hash:"f286893cd029b19b11172ff01b3d07579041ccf61da2a716ee026e8f5f2ec542"
tx_status: STATEFUL_VALIDATION_FAILED
tx_hash:"f286893cd029b19b11172ff01b3d07579041ccf61da2a716ee026e8f5f2ec542"
err_or_cmd_name: "TransferAsset"
error_code: 2
tx_status: REJECTED
tx_hash:"f286893cd029b19b11172ff01b3d07579041ccf61da2a716ee026e8f5f2ec542"

So, what do these statuses mean?

There is a ‘status pipeline’ for a transaction in Iroha and it looks like this:

First of all, it is important to note that there are only 3 final statuses that will be sent from a non-malicious node:

STATELESS_VALIDATION_FAILED,

COMMITTED,

and REJECTED.

These statuses are final for the status stream, meaning that once one of these statuses is reached, status streaming stops.

This doesn’t necessarily mean that the transaction itself has stopped: statuses can be skipped for a particular node (peer), for instance if it’s too slow and the consensus was reached without it.
In this situation, the transaction’s lifecycle is not over on the network, even if the status stream for one particular node has stopped, and it is therefore normal to get NOT_RECEIVED or STATELESS_VALIDATION_SUCCESS statuses, and then COMMITTED.
So it is possible to receive the status MST_EXPIRED for your node, while the transaction was still received in time by other nodes and confirmed by them. In this case, your own node is not required for consensus, and will simply synchronise with other nodes on COMMITTED or REJECTED.

Now, let’s review the various statuses StatusStream can send:

NOT_RECEIVED: The requested peer does not have information about this transaction. At least not yet ;)
Followed by: any other status.

ENOUGH_SIGNATURES_COLLECTED: This means a multisignature transaction has received enough signatures, and is now going to be validated by the peer.
Followed by: stateless validation, that can be either STATELESS_VALIDATION_SUCCESS, or STATELESS_VALIDATION_FAILED.

MST_PENDING: This means a multisignature transaction still has to be signed by more keys, as requested in the quorum field.
Followed by: ENOUGH_SIGNATURES_COLLECTED, or MST_EXPIRED.

MST_EXPIRED: This means a multisignature transaction is no longer valid, and is going to be deleted by the peer.
Followed by: COMMITTED (especially in the case where the node is too slow and have the transaction expired, but other nodes have validated it), or REJECTED.

STATELESS_VALIDATION_SUCCESS: The transaction has successfully passed stateless validation, meaning that it was produced correctly by the client.
This status is returned to the client that produced the transaction, immediately after the transaction was sent.
Followed by: STATEFUL_VALIDATION_SUCCESS, or STATEFUL_VALIDATION_FAILED.

STATELESS_VALIDATION_FAILED: The transaction was produced with some errors by the client, and therefore doesn’t meet stateless validation constraints.
This status is returned to the client that produced the transaction, immediately after the transaction was sent. It will also return the reason of failure, meaning what stateless validation constraint was not met.
As this is one of the final statuses in status streaming, after this status is received, the stream will close. Only in the case of a malicious node, will this status not be final.

STATEFUL_VALIDATION_SUCCESS: The transaction has successfully passed stateful validation.
Followed by: COMMITTED, or REJECTED.

STATEFUL_VALIDATION_FAILED: The transaction includes commands that violate validation rules because they contradict the state of the chain: for instance, asset balances, account permissions, etc.
The status will also return the reason of failure, meaning what rule was violated.
Followed by: COMMITTED, or REJECTED.

COMMITTED: The transaction received enough votes and is now part of a block, waiting in the block store at the moment. Final status.

REJECTED: The transaction was rejected during the stateful validation step, in the previous consensus rounds. Final status.
To prevent replay attacks, rejected transactions’ hashes are stored in the block store.

Finally, you must know that there are 2 reasons why the StatusStream can be terminated:

1. If one of the 3 final statuses (i.e., STATELESS_VALIDATION_FAILED, COMMITTED, or REJECTED) is reached.
2. If there were no changes in the transaction’s status for several rounds.

In either of these cases, StatusStream will stop.

I hope this was useful and that transaction status streaming in Hyperledger Iroha is now all clear to you!

If you have any questions about Hyperledger Iroha or StatusStream, please always feel free to contact the community in the chat: https://chat.hyperledger.org/channel/iroha, or on telegram, or leave your questions or topic suggestions for future articles in the comments below.

More information:
About Decentralized Autonomous Economy Sora, based on Hyperledger Iroha: www.sora.org
About Soramitsu, creator of Sora and main contributor of Hyperledegr Iroha: www.soramitsu.co.jp