Class TransactionReceiptExtensions

Extension methods for retrieving transaction receipts from the network.

Inheritance

object

TransactionReceiptExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Hiero

Assembly: Hiero.dll

Syntax

public static class TransactionReceiptExtensions

Methods

GetAllReceiptsAsync(ConsensusClient, TransactionId, CancellationToken, Action<IConsensusContext>?)

Retrieves all known receipts from the network having the given transaction ID. The method will wait for the disposition of at least one receipt to be known. Receipts with failure codes do not cause an exception to be raised.

Declaration

public static Task<TransactionReceipts> GetAllReceiptsAsync(this ConsensusClient client, TransactionId transaction, CancellationToken cancellationToken = default, Action<IConsensusContext>? configure = null)

Parameters

Type	Name	Description
ConsensusClient	client	The Consensus Node Client to query.
TransactionId	transaction	TransactionId identifier of the receipt.
CancellationToken	cancellationToken	Optional cancellation token.
Action<IConsensusContext>	configure	Optional callback method providing an opportunity to modify the execution configuration for just this method call. It is executed prior to submitting the request to the network.

Returns

Type	Description
Task<TransactionReceipts>	The receipts associated with the identified transaction, grouped into the transaction's own receipt, its child receipts and any duplicate-submission receipts. Any of those groups may be empty.

Remarks

The result separates the receipts into the three roles the network reports: the submitted transaction's own receipt (Parent), the receipts of any child transactions it spawned (Children), and the receipts of any duplicate submissions of the same transaction ID (Duplicates). Any of them may be empty.

Work the network performs on a transaction's behalf reports through the children, not the parent — for example the account created by a transfer to an alias:

var receipts = await client.GetAllReceiptsAsync(transferReceipt.TransactionId);
var address = receipts.Children.OfType<CreateAccountReceipt>().Single().Address;

Each receipt is returned as the most specific type the network's response supports (CreateAccountReceipt, CreateTokenReceipt and so on), falling back to TransactionReceipt when the response carries no type-specific identifier.

That resolution is best-effort. Four receipt kinds are identified by fields the wire format cannot distinguish from unset when their value is zero — TokenReceipt (a supply burned to nothing), NftMintReceipt, ConsensusNodeReceipt (node id 0) and RegisteredNodeReceipt — and resolve to the base type in those cases. The OfType idiom above quietly returns nothing rather than throwing, and Single<TSource>(IEnumerable<TSource>) will then fail; where a supply may reach zero, match with an is pattern and treat the base type as the zero case. No data is lost, since the fallback occurs only when the value is zero.

When the node has no verdict to give — it holds no receipt for the ID, stays too busy to answer, or still reports the receipt as unknown when the retries run out — the outcome is unknown and a ConsensusException is thrown. With ThrowIfNotSuccess set to

<pre><code class="lang-csharp">false</code></pre>

, the method returns instead, with a Parent whose status is ReceiptNotFound or Unknown. Nodes keep receipts for only about three minutes after consensus, so neither proves the transaction never executed; settle it on a mirror node. A parent receipt that reached consensus with a failure status is returned as it is, whatever the setting.

Exceptions

Type	Condition
ConsensusException	If the node gave no verdict: it holds no receipt for the transaction, stayed too busy to answer, or still reported it as unknown when the retries ran out. Not thrown when ThrowIfNotSuccess is false .

GetReceiptAsync(ConsensusClient, TransactionId, CancellationToken, Action<IConsensusContext>?)

Retrieves the receipt from the network matching the transaction id. Will wait for the disposition of the receipt to be known.

Declaration

public static Task<TransactionReceipt> GetReceiptAsync(this ConsensusClient client, TransactionId transaction, CancellationToken cancellationToken = default, Action<IConsensusContext>? configure = null)

Parameters

Type	Name	Description
ConsensusClient	client	The Consensus Node Client to query.
TransactionId	transaction	TransactionId identifier of the receipt.
CancellationToken	cancellationToken	Optional cancellation token.
Action<IConsensusContext>	configure	Optional callback method providing an opportunity to modify the execution configuration for just this method call. It is executed prior to submitting the request to the network.

Returns

Type	Description
Task<TransactionReceipt>	The receipt matching the transaction id. With ThrowIfNotSuccess false it is returned whatever its status, and when the node has no receipt for the id it is a stand-in whose status is ReceiptNotFound.

Remarks

The receipt is returned as the most specific type the network's response supports (CreateAccountReceipt, TokenReceipt and so on). That resolution is best-effort: four receipt kinds are identified by fields the wire format cannot distinguish from unset when their value is zero, and resolve to the base TransactionReceipt in that case — see TokenReceipt, NftMintReceipt, ConsensusNodeReceipt and RegisteredNodeReceipt. Prefer an is pattern over a hard cast, which would throw in those cases.

Exceptions

Type	Condition
TransactionException	If the transaction reached consensus and failed: its receipt's status is not Success.
ConsensusException	If the outcome is unknown: the transaction has not reached consensus within the retry window, or the node has no receipt for it (ReceiptNotFound) because it never saw it or no longer holds the receipt. Nodes keep receipts for about three minutes after consensus; settle an older or unknown transaction on a mirror node.