Class ConsensusClient
Hiero Network Consensus (Gossip) Node Client
Implements
Inherited Members
Namespace: Hiero
Assembly: Hiero.dll
Syntax
public sealed class ConsensusClient : IAsyncDisposableRemarks
This component facilitates interaction with the Hiero Network.
It manages the communication channels with the network and
serialization of requests and responses. This library generally
shields the client code from directly interacting with the
underlying protobuf communication layer but does provide hooks
allowing advanced low-level manipulation of messages if necessary.
Thread safety. An instance is safe for concurrent use and is intended to be shared — a singleton registered with dependency injection is the expected pattern. Each operation builds its own child context, so concurrent calls share no mutable state, and the underlying gRPC channels are pooled in a thread-safe cache.
Configure(Action<IConsensusContext>) is the exception. It mutates this instance's own
context in place, which every in-flight operation reads through, and is
meant for setup before the client is used or while it is otherwise idle.
To vary settings on a live client, pass the per-call configure
argument — it applies only to that one call — or take a separately
configured instance with Clone(Action<IConsensusContext>?).
Constructors
| Edit this page View SourceConsensusClient(Action<IConsensusContext>?)
Creates a new instance of a Hiero Network ConsensusClient.
Declaration
public ConsensusClient(Action<IConsensusContext>? configure = null)Parameters
| Type | Name | Description |
|---|---|---|
| Action<IConsensusContext> | configure | Optional configuration method that can set the location of the network node accessing the network and how transaction fees shall be paid for. |
Remarks
Creating a new instance of a
ConsensusClientinitializes a new instance of a client. It will have a separate cache of GRPC channels to the network and will maintain a separate configuration from other clients. The constructor takes an optional callback method that configures the details on how the client should connect to the network and what accounts generally pay transaction fees and other details. See the IConsensusContext documentation for configuration details.
ConsensusClient(Func<ConsensusNodeEndpoint, GrpcChannel>, Action<IConsensusContext>?)
Creates a new instance of a Hiero Network ConsensusClient with a custom gRPC channel factory.
Declaration
public ConsensusClient(Func<ConsensusNodeEndpoint, GrpcChannel> channelFactory, Action<IConsensusContext>? configure = null)Parameters
| Type | Name | Description |
|---|---|---|
| Func<ConsensusNodeEndpoint, GrpcChannel> | channelFactory | A custom callback method returning a new channel given the target ConsensusNodeEndpoint.
Note, this method is only called once for each unique ConsensusNodeEndpoint requested by
the ConsensusClient (which is a function of the current context's ConsensusNodeEndpoint parameter).
The factory replaces the default one entirely, including its TLS certificate pinning:
consensus nodes' |
| Action<IConsensusContext> | configure | Optional configuration method that can set the location of the network node accessing the network and how transaction fees shall be paid for. |
Remarks
Creating a new instance of a
ConsensusClientinitializes a new instance of a client. It will have a separate cache of GRPC channels to the network and will maintain a separate configuration from other clients. The constructor takes an optional callback method that configures the details on how the client should connect to the network and what accounts generally pay transaction fees and other details. See the IConsensusContext documentation for configuration details.
Methods
| Edit this page View SourceClone(Action<IConsensusContext>?)
Creates a new instance of the client having a shared base configuration with its parent. Changes to the parent’s configuration will reflect in this instance’s configuration while changes in this instance’s configuration will not be reflected in the parent configuration.
Declaration
public ConsensusClient Clone(Action<IConsensusContext>? configure = null)Parameters
| Type | Name | Description |
|---|---|---|
| Action<IConsensusContext> | configure | The callback method receiving the IConsensusContext object providing the configuration details of this client instance. Values can be retrieved and set within the context of the method invocation. |
Returns
| Type | Description |
|---|---|
| ConsensusClient | A new instance of a client object. |
Configure(Action<IConsensusContext>)
Updates the configuration of this instance of a client through implementation of the supplied IConsensusContext callback method.
Declaration
public void Configure(Action<IConsensusContext> configure)Parameters
| Type | Name | Description |
|---|---|---|
| Action<IConsensusContext> | configure | The callback method receiving the IConsensusContext object providing the configuration details of this client instance. Values can be retrieved and set within the context of the method invocation. |
Remarks
Mutates this client's own context in place. Every operation already in
flight reads its inherited settings through that context, so calling
this concurrently with active work can let a call observe a partially
applied configuration. Configure before use, or while the client is
idle. For a live client, prefer the per-call configure argument
(scoped to that call alone) or Clone(Action<IConsensusContext>?) for a separately
configured instance.
DisposeAsync()
.NET Asynchronous dispose method.
Declaration
public ValueTask DisposeAsync()Returns
| Type | Description |
|---|---|
| ValueTask | An Async Task. |
Remarks
Closes any GRPC channels solely owned by this
ConsensusClientinstance.
ExecuteAsync<T>(TransactionParams<T>, Action<IConsensusContext>?)
Creates, signs, submits a transaction and waits for a response from the target consensus node, returning a receipt.
Declaration
public Task<T> ExecuteAsync<T>(TransactionParams<T> transactionParams, Action<IConsensusContext>? configure = null) where T : TransactionReceiptParameters
| Type | Name | Description |
|---|---|---|
| TransactionParams<T> | transactionParams | The details of the transaction to create, sign and submit. |
| Action<IConsensusContext> | configure | Optional callback to configure the calling context immediately before assembling the transaction for submission. |
Returns
| Type | Description |
|---|---|
| Task<T> | A receipt object. |
Type Parameters
| Name | Description |
|---|---|
| T | The type of receipt to return. |
Exceptions
| Type | Condition |
|---|---|
| PrecheckException | If the gateway node refused the transaction. Only a code about the transaction itself proves it did not execute; any other code leaves the outcome unknown, so settle it by its transaction id on a mirror node rather than resubmitting it (see PrecheckException). |
| TransactionException | If the consensus node returned a failure code and throw on failure is set to in the client context configuration. |
| ConsensusException | If the outcome could not be confirmed: the transaction may have executed, so settle it by its transaction id on a mirror node rather than resubmitting it. |
SubmitAsync<T>(TransactionParams<T>, Action<IConsensusContext>?)
Creates, signs, submits a transaction and waits for a response from the target consensus node. Returning the precheck response code. A PrecheckException may be thrown under certain invalid input scenarios.
Declaration
public Task<ResponseCode> SubmitAsync<T>(TransactionParams<T> transactionParams, Action<IConsensusContext>? configure = null) where T : TransactionReceiptParameters
| Type | Name | Description |
|---|---|---|
| TransactionParams<T> | transactionParams | Transaction input parameters. |
| Action<IConsensusContext> | configure | Optional callback to configure the calling context immediately before assembling the transaction for submission. |
Returns
| Type | Description |
|---|---|
| Task<ResponseCode> | The precheck ResponseCode returned from the request after waiting for submission retries if applicable. |
Type Parameters
| Name | Description |
|---|---|
| T | The type of TransactionReceipt tied to the transaction parameters. This method produces no receipt; it returns only the precheck code. |
Remarks
This method will wait for the target consensus node to respond with a code other than Busy or InvalidTransactionStart if applicable, until such time as the retry count is exhausted, in which case it is possible to receive a Busy response.
The code returned is the node's answer to the submission, not the transaction's outcome. Ok means only that the node accepted it and the network has yet to decide, and a final Busy leaves the outcome unknown, since an earlier attempt in the call may have been accepted. This method does not return the transaction id, so choose one first with CreateNewTransactionId(ConsensusClient, Action<IConsensusContext>?), set it as TransactionId, and keep it: it is the only way to learn the outcome, from a receipt or a mirror node.
ToString()
Returns a human-readable debug string describing this client instance.
Declaration
public override string ToString()Returns
| Type | Description |
|---|---|
| string |