After a client submits a transaction to Hedera, the client may seek confirmation that the transaction was added to consensus state and also to perhaps retrieve information associated with that addition. As an example, if the transaction is a transfer of hbars for the purchase of a coffee, then the coffee shop will likely want confirmation that its account received the customer’s payment before pouring the over-priced latte.
Hedera supports confirmation mechanisms that vary in:
1. How the creation of the confirmation is initiated
2. The level of detail in the confirmation
3. How long the confirmation is available for retrieval
4. The trust that can be ascribed to the confirmation
Generally, the greater the level of detail, or the longer the availability, or the greater the trust that can be ascribed to the confirmation — the greater the cost for that confirmation. Hedera clients can therefore choose a mechanism for which the costs are appropriate to the nature and sensitivity of the transactions they submit.
We list below 5 different confirmation mechanisms from which clients can choose.
When a client submits a transaction to a particular node with a request that the transaction be submitted to the network, the node will perform a quick check of the transaction and respond to the client with the result before submitting it. The check includes determining whether the transaction is well formed and the client can pay the fees associated with the transaction. If the check is “OK”, then the response will indicate so and the node will then submit the transaction to the network. The response the node sends the client is therefore an acknowledgement that an honest node will subsequently submit the transaction to this network. From this acknowledgement, the client can obtain some confidence that the transaction will subsequently change consensus state. But of course, the node could lie about submitting the transaction, or some other error could prevent the transaction from reaching consensus. Consequently, this acknowledgment in general provides minimal confidence to the client and zero information about the impact of that transaction. But this low confidence might be acceptable given the immediate nature and zero additional cost for low value transactions, such as a micropayment. Additionally, it may be the case that the client has confidence in a particular node’s responses, based on a previous history of successful transactions.
While the client will pay a fee for the transaction itself, there is no additional fee for the response. Consequently, this confirmation mechanism is free to the client.
2. Subsequent Query
A client can obtain confidence that their transaction reached consensus by querying for the status of the relevant portion of the state. For instance, if a transaction is the transfer of hbars from the customer to the coffee shop, then the coffee shop could obtain confirmation of that by querying for the balance of their account and verifying the increase. Similarly, if the transaction were a request to update a file on the ledger, then the client could query for the properties of that file. In general, the client will pay a fee to whichever node processes and responds to this query.
After a transaction has been submitted to the network and successfully reached consensus, all nodes will become aware of that fact and create a ‘receipt’ to this effect. The client that sent the transaction can subsequently ask a node (it need not be the same node that initially submitted it) for the status of the transaction by querying for the receipt for that transaction. A receipt provides minimal information — merely whether or not the transaction was successfully added to consensus state or not (or that it has not yet reached consensus) and the identifier of any object created if successful. As receipts impose a minimal burden on the network, there is no charge to the client. A receipt can be corrupted by the node responding to the query if that node is malicious. Similar to a transaction response, a receipt might be more trusted if the client has a good history with a particular node.
Receipts are created automatically by the nodes of the network. Receipts exist for 3 minutes before being deleted. The client must query for the receipt within that period.
As an alternative to the minimal information provided by a receipt, a client can query for a ‘record’ associated with a transaction. Records include additional information beyond that which a receipt provides — such as the timestamp the transaction received and the results of a smart contract function call. Consequently, records are not free — clients requesting a record must pay a fee (paid when they query for that record). The cheapest form of record can be corrupted, just like a receipt by a malicious node, but it is possible to protect against that by requesting a state proof for the record as described below.
Before a client can query for a record, the record must necessarily have been created. There are three scenarios for record creation:
1. The client specifically requests the creation of a record when submitting the original transaction. In this case, the record will be created and will exist for 1 hour before being deleted. The client that requested the record will pay a fee for the storage of this record for this time
2. If a transaction is transferring a certain number of hbars in or out of an account, then a record will be created automatically. The owner of an account can set these thresholds. If a record is created in this manner, then it will exist for 24 hours before being deleted. The account on which the threshold was set will pay a fee for the storage of this record for this time
3. If not specifically requested (as in #1 or #2 above) a record will be automatically created, but will exist for only 3 minutes before being deleted. There is no fee for this type of record
Regardless of how it is created, the client must query for the record before the network deletes it.
5. Record + State Proof
When querying for a record (but not a receipt), a client can optionally indicate that it desires the network to return a ‘state proof’ in addition to the record. A state proof documents network consensus on the contents of that record in the consensus state — this collective assertion includes signatures of most of the network nodes. Because state proofs are cryptographically signed by a super majority of the network, they are secure and potentially admissible in a court of law. However, returning a state proof in addition to the record will require more bandwidth and so will be more costly to the client. Therefore, records may be best used for important or high value transactions for which the costs of a secure confirmation are warranted.
In addition to requesting a state proof for the record of a transaction, a client can ask for a state proof for any other piece of the consensus state.
Hedera provides a range of confirmation mechanisms by which a client can obtain confirmation as to the consensus of a transaction and its effect on consensus state. The different mechanisms vary both in the detail provided in the confirmation and how much confidence that the client can ascribe to it — as well as the cost to the client. Clients can choose the right confirmation mechanism appropriate to the value and sensitivity of their transactions. The confirmation mechanism for a $4 cup of coffee will likely not be the same as for a microtransaction worth $0.0005 or for a transaction recording the delivery of a shipping container full of pharmaceutical supplies.