Class ConcordiumClient

Namespace

Concordium.Sdk.Client

Assembly

Concordium.Sdk.dll

A client for interacting with the Concordium gRPC API V2 exposed by nodes.

public sealed class ConcordiumClient : IDisposable

Inheritance

object

ConcordiumClient

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ConcordiumClient(Uri, ConcordiumClientOptions)

Initializes a new instance of the ConcordiumClient class.

public ConcordiumClient(Uri endpoint, ConcordiumClientOptions options)

Parameters

endpoint Uri

Endpoint required by the client.

options ConcordiumClientOptions

Options needed for initialization of client.

ConcordiumClient(Uri, ushort, ulong?, GrpcChannelOptions?)

DEPRECATED - Use overload which accepts ConcordiumClientOptions

Initializes a new instance of the ConcordiumClient class.

Optionally use rawChannelOptions to specify connection settings such as the retry policy or keepalive ping.

By default the policy is not to retry if a connection could not be established.

See https://github.com/grpc/grpc/blob/master/doc/keepalive.md for default values for the keepalive ping parameters.

[Obsolete("Use ConcordiumClient with overload which accepts ConcordiumClientOptions")]
public ConcordiumClient(Uri endpoint, ushort port, ulong? timeout = 30, GrpcChannelOptions? rawChannelOptions = null)

Parameters

endpoint Uri

Endpoint of a resource where the V2 API is served. Any port specified in the URL is ignored.

port ushort

Port of the resource where the V2 API is served. This will override any port specified in endpoint.

timeout ulong?

The maximum permitted duration of a call made by this client, in seconds. null allows the call to run indefinitely.

rawChannelOptions GrpcChannelOptions

The options for the channel that is used to communicate with the node.

Properties

Raw

The raw client.

public RawClient Raw { get; init; }

Property Value

RawClient

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetAccountInfoAsync(IAccountIdentifier, IBlockHashInput, CancellationToken)

Get the information for the given account in the given block.

public Task<QueryResponse<AccountInfo>> GetAccountInfoAsync(IAccountIdentifier accountIdentifier, IBlockHashInput blockHash, CancellationToken token = default)

Parameters

accountIdentifier IAccountIdentifier

Identifier of the account.

blockHash IBlockHashInput

A hash of the block

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<AccountInfo>>

Account information at the given block.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates either block or account was not found.

GetAccountListAsync(IBlockHashInput, CancellationToken)

Get the list of accounts in the given block. The stream will end when all accounts that exist in the state at the end of the given block have been returned.

public Task<QueryResponse<IAsyncEnumerable<AccountAddress>>> GetAccountListAsync(IBlockHashInput input, CancellationToken token = default)

Parameters

input IBlockHashInput

A hash of block

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<AccountAddress>>>

Accounts at given block

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block account was not found.

GetAncestors(IBlockHashInput, ulong, CancellationToken)

Get a stream of ancestors for the provided block. Starting with the provided block itself, moving backwards until no more ancestors or the requested number of ancestors has been returned.

public Task<QueryResponse<IAsyncEnumerable<BlockHash>>> GetAncestors(IBlockHashInput blockHash, ulong limit, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

The block to get ancestors of

limit ulong

The maximum number of ancestors returned

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<BlockHash>>>

A stream of ancestors.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetBakerListAsync(IBlockHashInput, CancellationToken)

Get all the bakers at the end of the given block.

public Task<QueryResponse<IAsyncEnumerable<BakerId>>> GetBakerListAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block hash from where state of baker list will be returned.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<BakerId>>>

List of baker ids.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlockChainParametersAsync(IBlockHashInput, CancellationToken)

Get the chain parameters in effect after a given block.

public Task<QueryResponse<IChainParameters>> GetBlockChainParametersAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block hash from where chain parameters will be given.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IChainParameters>>

Chain parameters at given block.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlockFinalizationSummaryAsync(IBlockHashInput, CancellationToken)

Get the information about a finalization record in a block. A block can contain zero or one finalization record. If a record is contained then this query will return information about the finalization session that produced it, including the finalizers eligible for the session, their power, and whether they signed this particular record. If the block contains zero finalization record the finalization summary is null. If the block does not exist an exception is thrown is returned.

public Task<QueryResponse<FinalizationSummary?>> GetBlockFinalizationSummaryAsync(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block from where finalization summary will be given.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<FinalizationSummary>>

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlockInfoAsync(IBlockHashInput, CancellationToken)

Get information, such as height, timings, and transaction counts for the given block.

public Task<QueryResponse<BlockInfo>> GetBlockInfoAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block from where information will be returned.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<BlockInfo>>

Block information from requested block.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlockItemStatus(TransactionHash, CancellationToken)

Get the status of and information about a specific block item given a transaction hash.

public ITransactionStatus GetBlockItemStatus(TransactionHash transactionHash, CancellationToken token = default)

Parameters

transactionHash TransactionHash

Transaction Hash which is included in blocks returned.

token CancellationToken

Cancellation token

Returns

ITransactionStatus

A common return type for TransactionStatus.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetBlockItemStatusAsync(TransactionHash, CancellationToken)

Get the status of and information about a specific block item given a transaction hash.

public Task<ITransactionStatus> GetBlockItemStatusAsync(TransactionHash transactionHash, CancellationToken token = default)

Parameters

transactionHash TransactionHash

Transaction Hash which is included in blocks returned.

token CancellationToken

Cancellation token

Returns

Task<ITransactionStatus>

Task which wraps a common return type for TransactionStatus.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetBlockItems(IBlockHashInput, CancellationToken)

Get the items of a block.

public Task<QueryResponse<IAsyncEnumerable<BlockItem>>> GetBlockItems(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Identifies what block to get the information from.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<BlockItem>>>

A stream of block items.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetBlockPendingUpdates(IBlockHashInput, CancellationToken)

Get the pending updates to chain parameters at the end of a given block. The stream will end when all the pending updates for a given block have been returned.

public Task<QueryResponse<IAsyncEnumerable<PendingUpdate>>> GetBlockPendingUpdates(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

The block to get ancestors of

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<PendingUpdate>>>

The pending updates.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetBlockSpecialEvents(IBlockHashInput, CancellationToken)

Get a the special events in a given block. The stream will end when all the special events for a given block have been returned. These are events generated by the protocol, such as minting and reward payouts. They are not directly generated by any transaction.

public Task<QueryResponse<IAsyncEnumerable<ISpecialEvent>>> GetBlockSpecialEvents(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<ISpecialEvent>>>

Special events at given block

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlockTransactionEvents(IBlockHashInput, CancellationToken)

Get the transaction events in a given block. The stream will end when all the transaction events for a given block have been returned.

public Task<QueryResponse<IAsyncEnumerable<BlockItemSummary>>> GetBlockTransactionEvents(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block from where transactions events will be returned.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<BlockItemSummary>>>

Summary of a block item with transactional meta data.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetBlocks(CancellationToken)

Return a stream of blocks that arrive from the time the query is made onward. This can be used to listen for incoming blocks.

public IAsyncEnumerable<ArrivedBlockInfo> GetBlocks(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

IAsyncEnumerable<ArrivedBlockInfo>

A stream of blocks that arrive from the time the query is made onward.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetBlocksAtHeightAsync(IBlockHeight, CancellationToken)

Get a list of live blocks at a given height.

public Task<IList<BlockHash>> GetBlocksAtHeightAsync(IBlockHeight blockHeight, CancellationToken token = default)

Parameters

blockHeight IBlockHeight

Block height from where blocks should be returned.

token CancellationToken

Cancellation Token.

Returns

Task<IList<BlockHash>>

List of live blocks.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetBranches(CancellationToken)

Get the current branches of blocks starting from and including the last finalized block.

public Branch GetBranches(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

Branch

The current branches of blocks.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetBranchesAsync(CancellationToken)

Get the current branches of blocks starting from and including the last finalized block.

public Task<Branch> GetBranchesAsync(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

Task<Branch>

The current branches of blocks.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetConsensusInfoAsync(CancellationToken)

Get information about the current state of consensus. This is an overview of the node's current view of the chain.

public Task<ConsensusInfo> GetConsensusInfoAsync(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

Task<ConsensusInfo>

Current consensus information.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetFinalizedBlocks(CancellationToken)

Return a stream of blocks that are finalized from the time the query is made onward. This can be used to listen for newly finalized blocks. Note that there is no guarantee that blocks will not be skipped if the client is too slow in processing the stream, however blocks will always be sent by increasing block height.

public IAsyncEnumerable<FinalizedBlockInfo> GetFinalizedBlocks(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

IAsyncEnumerable<FinalizedBlockInfo>

A stream of finalized blocks that arrive from the time the query is made onward.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. Unimplemented indicates that this endpoint is disabled in the node.

GetIdentityProvidersAsync(IBlockHashInput, CancellationToken)

Get the identity providers registered as of the end of a given block. The stream will end when all the identity providers have been returned.

public Task<QueryResponse<IAsyncEnumerable<IpInfo>>> GetIdentityProvidersAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block hash from where identity providers state will be returned

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<IpInfo>>>

Identity providers info

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetInstanceInfoAsync(IBlockHashInput, ContractAddress, CancellationToken)

Get information about a smart contract instance as it appears at the end of a given block.

public Task<QueryResponse<IInstanceInfo>> GetInstanceInfoAsync(IBlockHashInput blockHashInput, ContractAddress contractAddress, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block hash from where smart contract information will be given.

contractAddress ContractAddress

Address of smart contract instance.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IInstanceInfo>>

Information about the given smart contract instance.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block or smart contract instance was not found.

GetInstanceListAsync(IBlockHashInput, CancellationToken)

Get the addresses of all smart contract instances in a given block.

public Task<QueryResponse<IAsyncEnumerable<ContractAddress>>> GetInstanceListAsync(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block hash from where contracts will be given.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<ContractAddress>>>

Stream of contracts in given block.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetModuleListAsync(IBlockHashInput, CancellationToken)

Get all smart contract modules that exist at the end of a given block.

public Task<QueryResponse<IAsyncEnumerable<ModuleReference>>> GetModuleListAsync(IBlockHashInput blockHashInput, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block hash from where modules will be given.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<IAsyncEnumerable<ModuleReference>>>

Stream of modules in given block.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetModuleSourceAsync(IBlockHashInput, ModuleReference, CancellationToken)

Returns the source of a smart contract module.

public Task<QueryResponse<VersionedModuleSource>> GetModuleSourceAsync(IBlockHashInput blockHashInput, ModuleReference moduleReference, CancellationToken token = default)

Parameters

blockHashInput IBlockHashInput

Block hash from where module source will be given.

moduleReference ModuleReference

Module reference from where source is requested.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<VersionedModuleSource>>

Mapped versioned module source instances.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates either the block or the smart contract module was not found.

GetNextAccountSequenceNumber(AccountAddress, CancellationToken)

Query the chain for the next sequence number of the account with the supplied address.

Specifically, this is the best guess as to what the next account sequence number (nonce) should be for the given account.

If all account transactions are finalized then this information is reliable.

Otherwise this is the best guess, assuming all other transactions will be committed to blocks and eventually finalized.

public (AccountSequenceNumber, bool) GetNextAccountSequenceNumber(AccountAddress accountAddress, CancellationToken token = default)

Parameters

accountAddress AccountAddress

An address of the account to get the next sequence number of.

token CancellationToken

Cancellation token

Returns

(AccountSequenceNumber, bool)

A tuple containing the best guess of the next sequence number for the supplied account.

The boolean returned parameter indicates whether all transactions associated with the account are finalized. If all associated transactions are finalized the sequence number is reliable and the boolean parameter will be

true

.

The query will return the initial account nonce for non-existing accounts and hence NOT throw exceptions in this case.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetNextAccountSequenceNumberAsync(AccountAddress, CancellationToken)

Spawn a task which queries the chain for the next sequence number of the account with the supplied address.

Specifically, this is the best guess as to what the next account sequence number (nonce) should be for the given account.

If all account transactions are finalized then this information is reliable.

Otherwise this is the best guess, assuming all other transactions will be committed to blocks and eventually finalized.

public Task<(AccountSequenceNumber, bool)> GetNextAccountSequenceNumberAsync(AccountAddress accountAddress, CancellationToken token = default)

Parameters

accountAddress AccountAddress

An address of the account to get the next sequence number of.

token CancellationToken

Cancellation token

Returns

Task<(AccountSequenceNumber, bool)>

A task which returns a tuple containing the best guess of the next sequence number for the supplied account and a boolean indicating whether all transactions associated with the account are finalized. If the latter is the case, then the sequence number is reliable.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetNodeInfoAsync(CancellationToken)

Retrieve information about the node. The response contains meta information about the node such as the version of the software, the local time of the node etc.

The response also yields network related information such as the node ID, bytes sent/received etc.

Finally depending on the type of the node (regular node or 'bootstrapper') the response also yields baking information if the node is configured with baker credentials.

Bootstrappers do no reveal any consensus information as they do not run the consensus protocol.

public Task<NodeInfo> GetNodeInfoAsync(CancellationToken token = default)

Parameters

token CancellationToken

Cancellation token

Returns

Task<NodeInfo>

Information about the node.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.

GetPassiveDelegationInfoAsync(IBlockHashInput, CancellationToken)

State of the passive delegation pool at block hash. Changes to delegation, e.g., an account deciding to delegate are reflected in this structure at first.

public Task<QueryResponse<PassiveDelegationStatus>> GetPassiveDelegationInfoAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block hash from where passive delegation status will be returned.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<PassiveDelegationStatus>>

State of the passive delegation pool

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetPoolInfoAsync(BakerId, IBlockHashInput, CancellationToken)

Get information about a given pool at the end of a given block. If the block does not exist or is prior to protocol version 4 then exception is thrown.

public Task<QueryResponse<BakerPoolStatus>> GetPoolInfoAsync(BakerId bakerId, IBlockHashInput blockHash, CancellationToken token = default)

Parameters

bakerId BakerId

Id of baker

blockHash IBlockHashInput

Block hash from where information will be fetched

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<BakerPoolStatus>>

The state of the baker currently registered on the account.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

GetTokenomicsInfoAsync(IBlockHashInput, CancellationToken)

Get information about tokenomics at the end of a given block.

public Task<QueryResponse<RewardOverviewBase>> GetTokenomicsInfoAsync(IBlockHashInput blockHash, CancellationToken token = default)

Parameters

blockHash IBlockHashInput

Block from where state of tokenomics are returned.

token CancellationToken

Cancellation token

Returns

Task<QueryResponse<RewardOverviewBase>>

Tokenomics

Exceptions

RpcException

RPC error occurred, access StatusCode for more information. NotFound indicates block was not found.

SendAccountTransaction(SignedAccountTransaction, CancellationToken)

Send an account transaction to the node.

public TransactionHash SendAccountTransaction(SignedAccountTransaction transaction, CancellationToken token = default)

Parameters

transaction SignedAccountTransaction

The account transaction to send.

token CancellationToken

Cancellation token

Returns

TransactionHash

Hash of the transaction if it was accepted by the node.

Exceptions

RpcException

The call failed, e.g. due to the node not accepting the transaction.

FormatException

The returned transaction hash has an invalid number of bytes.

SendAccountTransactionAsync(SignedAccountTransaction, CancellationToken)

Spawn a task which sends an account transaction to the node.

Note that the task may throw a FormatException if the transaction hash it returns has an invalid number of bytes.

public Task<TransactionHash> SendAccountTransactionAsync(SignedAccountTransaction transaction, CancellationToken token = default)

Parameters

transaction SignedAccountTransaction

The account transaction to send.

token CancellationToken

Cancellation token

Returns

Task<TransactionHash>

Task which returns the hash of the transaction if it was accepted by the node.

Exceptions

RpcException

The call failed, e.g. due to the node not accepting the transaction.

WaitUntilFinalized(TransactionHash, CancellationToken)

Wait until the transaction is finalized.

For production it is recommended to provide a CancellationToken with a timeout, since a faulty/misbehaving node could otherwise make this wait indefinitely.

The RpcException with StatusCode of NotFound is thrown if the transaction is not known by the node. Sending a transaction right before calling this method, might produce this exception, due to the node still processing the transaction.

public Task<(BlockHash BlockHash, BlockItemSummary Summary)> WaitUntilFinalized(TransactionHash transactionHash, CancellationToken token = default)

Parameters

transactionHash TransactionHash

Transaction Hash which is included in blocks returned.

token CancellationToken

Cancellation token

Returns

Task<(BlockHash BlockHash, BlockItemSummary Summary)>

Hash of the block finalizing the transaction and the block summary of the transaction.

Exceptions

RpcException

RPC error occurred, access StatusCode for more information.