com.concordium.sdk

Class ClientV2

java.lang.Object

com.concordium.sdk.ClientV2

public final class ClientV2
extends Object

The Client is responsible for sending requests to the node.

Method Summary

Modifier and Type	Method and Description
void	banPeer(InetAddress ipToBan) Ban a specific peer Note this will ban all peers located behind the specified IP even though they are using different ports
void	close() Closes the underlying grpc channel
void	dumpStart(DumpRequest dumpRequest) Start dumping packages into the specified File Only enabled if the node was built with the 'network_dump' feature enabled
void	dumpStop() Stop dumping packages Only enabled if the node was built with the 'network_dump' feature enabled
Optional<FindAccountResponse>	findAccountCreation(AccountAddress address) Find a block in which the AccountAddress was created, if it exists and is finalized.
Optional<FindAccountResponse>	findAccountCreation(Range<AbsoluteBlockHeight> range, AccountAddress address) Find a block in which the AccountAddress was created, if it exists and is finalized.
<T> Optional<T>	findAtLowestHeight(BiFunction<ClientV2,BlockQuery,Optional<T>> test) Find a finalized block with the lowest height that satisfies the given condition.
<T> Optional<T>	findAtLowestHeight(Range<AbsoluteBlockHeight> range, BiFunction<ClientV2,BlockQuery,Optional<T>> test) Find a finalized block with the lowest height that satisfies the given condition.
static ClientV2	from(Connection connection)
AccountInfo	getAccountInfo(BlockQuery input, AccountQuery accountIdentifier) Retrieve the information about the given account in the given block.
Iterator<AccountAddress>	getAccountList(BlockQuery input) Retrieve the list of accounts that exist at the end of the given block.
Iterator<Hash>	getAccountNonFinalizedTransactions(AccountAddress address) Get the list of transactions hashes for transactions from the given account, but which are not yet finalized.
Iterator<Hash>	getAncestors(BlockQuery blockQuery, long num) Gets Block Ancestor Blocks.
Iterator<AnonymityRevokerInfo>	getAnonymityRevokers(BlockQuery input) Gets all the Anonymity Revokers at the end of the block pointed by BlockQuery.
Timestamp	getBakerEarliestWinTime(BakerId bakerId) Get the projected earliest time at which a particular baker will be required to bake a block.
Iterator<BakerId>	getBakerList(BlockQuery blockQuery) Get the IDs of the bakers registered in the given block.
com.google.common.collect.ImmutableList<BakerRewardPeriodInfo>	getBakersRewardPeriod(BlockQuery input) Get all bakers in the reward period of a block.
com.google.common.collect.ImmutableList<InetAddress>	getBannedPeers() Get a list of banned peers
BlockCertificates	getBlockCertificates(BlockQuery block) Retrieves the BlockCertificates for a given block.
Optional<FinalizationData>	getBlockFinalizationSummary(BlockQuery blockQuery) Retrieves the FinalizationData of a given block BlockQuery Note.
BlockInfo	getBlockInfo(BlockQuery blockQuery) Retrieves a BlockInfo
Iterator<BlockItem>	getBlockItems(BlockQuery input) Gets the transactions of a Block.
BlockItemStatus	getBlockItemStatus(Hash transactionHash) Retrieves the BlockItemStatus for a given transaction Hash
Iterator<PendingUpdateV2>	getBlockPendingUpdates(BlockQuery input)
Iterator<BlockIdentifier>	getBlocks(int timeoutMillis) Gets an Iterator of Blocks Arriving at the node.
com.google.common.collect.ImmutableList<Hash>	getBlocksAtHeight(BlocksAtHeightRequest height) Get a ImmutableList of live blocks at a given height.
com.google.common.collect.ImmutableList<SpecialOutcome>	getBlockSpecialEvents(BlockQuery blockQuery) Retrieves a list of SpecialOutcomes in a given block BlockQuery These are events generated by the protocol, such as minting and reward payouts.
Iterator<Summary>	getBlockTransactionEvents(BlockQuery input) Retrieve a stream of transaction events in the specified block.
Branch	getBranches() Get the branches of the node's tree.
ChainParameters	getChainParameters(BlockQuery blockQuery) Get the blockchain parameters
ConsensusDetailedStatus	getConsensusDetailedStatus(ConsensusDetailedStatusQuery query) Get the detailed status of the consensus.
ConsensusStatus	getConsensusInfo() Retrieve the Consensus Info that contains the summary of the current state of the chain from the perspective of the node.
Iterator<AccountPending>	getCooldownAccounts(BlockQuery input) Get all accounts that have stake in cooldown, with the timestamp of the first pending cooldown expiry for each account.
CryptographicParameters	getCryptographicParameters(BlockQuery blockHash) Get the CryptographicParameters at a given block.
ElectionInfo	getElectionInfo(BlockQuery input) Get information related to the baker election for a particular block.
Iterator<BlockIdentifier>	getFinalizedBlocks() Gets an Iterator of Finalized Blocks from the time request is made and onwards.
Iterator<BlockIdentifier>	getFinalizedBlocks(int timeoutMillis) Gets an Iterator of Finalized Blocks with specified timeout from the time request is made and onwards.
FinalizedBlockItemIterator	getFinalizedBlocksFrom(AbsoluteBlockHeight startHeight) Get a FinalizedBlockItemIterator of BlockIdentifier of finalized blocks starting from a given height.
Hash	getFirstBlockEpoch(EpochQuery epochQuery) Get the block hash of the first finalized block in a specified epoch.
Iterator<IdentityProviderInfo>	getIdentityProviders(BlockQuery input) Gets all the Identity Providers at the end of the block pointed by BlockQuery.
InstanceInfo	getInstanceInfo(BlockQuery input, ContractAddress contractAddress) Get info about a smart contract instance as it appears at the end of the given block.
Iterator<ContractAddress>	getInstanceList(BlockQuery blockQuery) Get the list of contract addresses in the given block.
Iterator<KeyValurPair>	getInstanceState(BlockQuery input, ContractAddress contractAddress) Get the exact state of a specific contract instance, streamed as a list of key-value pairs.
Iterator<ModuleRef>	getModuleList(BlockQuery input) Get list of Smart Contract modules at the end of the given block.
WasmModule	getModuleSource(BlockQuery query, ModuleRef moduleRef) Get the source of a smart contract module from the perspective of the last finalized block.
Nonce	getNextAccountSequenceNumber(AccountAddress address) Retrieves the next Nonce for an account.
NextUpdateSequenceNumbers	getNextUpdateSequenceNumbers(BlockQuery input) Get next available sequence numbers for updating chain parameters after a given block.
NodeInfo	getNodeInfo() Retrieves valious information about the node
PassiveDelegationInfo	getPassiveDelegationInfo(BlockQuery input) Get information about the passive delegators at the end of a given block.
Iterator<DelegatorInfo>	getPassiveDelegators(BlockQuery input) Get information about the passive delegators at the end of a given block.
Iterator<DelegatorRewardPeriodInfo>	getPassiveDelegatorsRewardPeriod(BlockQuery input) Get the fixed passive delegators for the reward period of the given block.
com.google.common.collect.ImmutableList<PeerInfo>	getPeersInfo() Returns a ImmutableList of PeerInfo containing information about the nodes' peers
Iterator<DelegatorInfo>	getPoolDelegators(BlockQuery input, AccountIndex bakerId) Get the registered delegators of a given pool at the end of a given block.
Iterator<DelegatorRewardPeriodInfo>	getPoolDelegatorsRewardPeriod(BlockQuery input, BakerId bakerId) Get the fixed delegators of a given pool for the reward period of the given block.
BakerPoolStatus	getPoolInfo(BlockQuery input, BakerId bakerId) Get information about a given pool at the end of a given block.
Iterator<AccountIndex>	getPreCooldownAccounts(BlockQuery input) Get all accounts that have stake in pre-cooldown.
Iterator<AccountIndex>	getPrePreCooldownAccounts(BlockQuery input) Get all accounts that have stake in pre-pre-cooldown.
RewardsOverview	getRewardStatus(BlockQuery blockHash) Get the information about total amount of CCD and the state of valious special accounts in the provided block.
Iterator<AccountPending>	getScheduledReleaseAccounts(BlockQuery input) Get all accounts that have scheduled releases, with the timestamp of the first pending scheduled release for that account.
com.google.common.collect.ImmutableList<WinningBaker>	getWinningBakersEpoch(EpochQuery epochQuery) Get the list of bakers that won the lottery in a particular historical epoch (i.e.
byte[]	instanceStateLookup(BlockQuery input, ContractAddress contractAddress, byte[] key) Get the value at a specific key of a contract state.
InvokeInstanceResult	invokeInstance(InvokeInstanceRequest request) This function can be used to either 1.
void	peerConnect(InetSocketAddress socketAddress) Tries to connect to a peer with the submitted InetSocketAddress.
void	peerDisconnect(InetSocketAddress socketAddress) Disconnect from the peer with the submitted InetSocketAddress and remove them from the address list if they are on it.
Hash	sendCredentialDeploymentTransaction(CredentialDeploymentTransaction credentialDeploymentTransaction) Sends a credential deployment transaction to the Concordium Node.
Hash	sendTransaction(AccountTransaction accountTransaction) Sends an Account Transaction to the Concordium Node.
void	shutdown() Shut down the node.
void	unbanPeer(InetAddress ipToUnban) Unban a specific peer
Optional<FinalizedBlockItem>	waitUntilFinalized(Hash transactionHash, int timeoutMillis) Waits until a given transaction is finalized and returns the corresponding Optional.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

from

public static ClientV2 from(Connection connection)
                     throws ClientInitializationException

Throws:

ClientInitializationException

getAnonymityRevokers

public Iterator<AnonymityRevokerInfo> getAnonymityRevokers(BlockQuery input)

Gets all the Anonymity Revokers at the end of the block pointed by BlockQuery.

Parameters:

input - Pointer to the Block.

Returns:

Iterator of AnonymityRevokerInfo

getBlocks

public Iterator<BlockIdentifier> getBlocks(int timeoutMillis)

Gets an Iterator of Blocks Arriving at the node. With Specified Timeout. Form the time request is made and onwards. This can be used to listen for incoming blocks.

Parameters:

timeoutMillis - Timeout for the request in Milliseconds.

Returns:

Iterator

getFinalizedBlocks

public Iterator<BlockIdentifier> getFinalizedBlocks(int timeoutMillis)

Gets an Iterator of Finalized Blocks with specified timeout from the time request is made and onwards. This can be used to listen for blocks being Finalized.

Parameters:

timeoutMillis - Timeout for the request in Milliseconds.

Returns:

Iterator

getFinalizedBlocks

public Iterator<BlockIdentifier> getFinalizedBlocks()

Gets an Iterator of Finalized Blocks from the time request is made and onwards. This can be used to listen for blocks being Finalized.

Note, may block indefinitely. Use getFinalizedBlocks(int) to specify a timeout.

Returns:

Iterator

getAccountInfo

public AccountInfo getAccountInfo(BlockQuery input,
                                  AccountQuery accountIdentifier)

Retrieve the information about the given account in the given block.

Parameters:

input - Pointer to the Block.

accountIdentifier - Identifier of the Account.

Returns:

Account Information (AccountInfo)

getAccountList

public Iterator<AccountAddress> getAccountList(BlockQuery input)

Retrieve the list of accounts that exist at the end of the given block.

Parameters:

input - Pointer to the Block.

Returns:

Iterator.

getBlockTransactionEvents

public Iterator<Summary> getBlockTransactionEvents(BlockQuery input)

Retrieve a stream of transaction events in the specified block.

Parameters:

input - the block to query.

Returns:

the stream of transaction events

getBlockItems

public Iterator<BlockItem> getBlockItems(BlockQuery input)

Gets the transactions of a Block. Type of Block Items currently supported are
BlockItemType.ACCOUNT_TRANSACTION
BlockItemType.CREDENTIAL_DEPLOYMENT
BlockItemType.UPDATE_INSTRUCTION

Parameters:

input - Pointer to the Block.

Returns:

Iterator

getConsensusInfo

public ConsensusStatus getConsensusInfo()

Retrieve the Consensus Info that contains the summary of the current state of the chain from the perspective of the node.

Returns:

the Consensus Status (ConsensusStatus)

See Also:

getConsensusDetailedStatus(ConsensusDetailedStatusQuery)

getConsensusDetailedStatus

public ConsensusDetailedStatus getConsensusDetailedStatus(ConsensusDetailedStatusQuery query)

Get the detailed status of the consensus. This is only available for consensus version 1.

Parameters:

query - ConsensusDetailedStatusQuery representing the genesis index to get status for.

Returns:

the detailed status

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.NOT_FOUND if the query specifies an unknown genesis index
• Status.INVALID_ARGUMENT if the query specifies a genesis index at consensus version 0
• Status.UNIMPLEMENTED if the endpoint is disabled on the node

See Also:

getConsensusInfo()

getScheduledReleaseAccounts

public Iterator<AccountPending> getScheduledReleaseAccounts(BlockQuery input)

Get all accounts that have scheduled releases, with the timestamp of the first pending scheduled release for that account. (Note, this only identifies accounts by index, and only indicates the first pending release for each account.)

getCooldownAccounts

public Iterator<AccountPending> getCooldownAccounts(BlockQuery input)

Get all accounts that have stake in cooldown, with the timestamp of the first pending cooldown expiry for each account. (Note, this only identifies accounts by index, and only indicates the first pending cooldown for each account.) Prior to protocol version 7, the resulting stream will always be empty.

getPreCooldownAccounts

public Iterator<AccountIndex> getPreCooldownAccounts(BlockQuery input)

Get all accounts that have stake in pre-cooldown. (This only identifies accounts by index.) Prior to protocol version 7, the resulting stream will always be empty.

getPrePreCooldownAccounts

public Iterator<AccountIndex> getPrePreCooldownAccounts(BlockQuery input)

Get all accounts that have stake in pre-pre-cooldown. (This only identifies accounts by index.) Prior to protocol version 7, the resulting stream will always be empty.

sendTransaction

public Hash sendTransaction(AccountTransaction accountTransaction)

Sends an Account Transaction to the Concordium Node.

Parameters:

accountTransaction - Account Transaction to send.

Returns:

Transaction Hash.

sendCredentialDeploymentTransaction

public Hash sendCredentialDeploymentTransaction(CredentialDeploymentTransaction credentialDeploymentTransaction)

Sends a credential deployment transaction to the Concordium Node.

Parameters:

credentialDeploymentTransaction - the credential deployment to send.

Returns:

Transaction Hash.

getIdentityProviders

public Iterator<IdentityProviderInfo> getIdentityProviders(BlockQuery input)

Gets all the Identity Providers at the end of the block pointed by BlockQuery.

Parameters:

input - Pointer to the Block.

Returns:

Iterator of IdentityProviderInfo

getCryptographicParameters

public CryptographicParameters getCryptographicParameters(BlockQuery blockHash)

Get the CryptographicParameters at a given block.

Parameters:

blockHash - the hash of the block

Returns:

the cryptographic parameters at the given block.

getRewardStatus

public RewardsOverview getRewardStatus(BlockQuery blockHash)

Get the information about total amount of CCD and the state of valious special accounts in the provided block.

Parameters:

blockHash - Block at which the reward status is to be retrieved.

Returns:

Parsed RewardsOverview.

getBlockInfo

public BlockInfo getBlockInfo(BlockQuery blockQuery)

Retrieves a BlockInfo

Parameters:

blockQuery - the block BlockQuery to query.

Returns:

A BlockInfo for the block

getChainParameters

public ChainParameters getChainParameters(BlockQuery blockQuery)

Get the blockchain parameters

Parameters:

blockQuery - block to query.

Returns:

the ChainParameters

getNextAccountSequenceNumber

public Nonce getNextAccountSequenceNumber(AccountAddress address)

Retrieves the next Nonce for an account. This is the Nonce to use for future transactions E.g. when using sendTransaction(AccountTransaction) When this function is queried with a non-existent account it will report the next available account nonce to be 1 and all transactions as finalized.

Parameters:

address - The AccountAddress

Returns:

The next Nonce

getBlockItemStatus

public BlockItemStatus getBlockItemStatus(Hash transactionHash)

Retrieves the BlockItemStatus for a given transaction Hash

Parameters:

transactionHash - The transaction Hash

Returns:

The BlockItemStatus

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.NOT_FOUND if the transaction is not known to the node.

getAccountNonFinalizedTransactions

public Iterator<Hash> getAccountNonFinalizedTransactions(AccountAddress address)

Get the list of transactions hashes for transactions from the given account, but which are not yet finalized. They are either committed to a block or still pending. If the account does not exist an empty list will be returned.

Parameters:

address - AccountAddress

Returns:

Iterator of Transaction Hash

dumpStart

public void dumpStart(DumpRequest dumpRequest)

Start dumping packages into the specified File Only enabled if the node was built with the 'network_dump' feature enabled

Parameters:

dumpRequest - DumpRequest specifying the file and if raw packages should be dumped

Throws:

{@link - io.grpc.StatusRuntimeException} if the network dump failed to start or if the node was not built with the 'network_dump' feature

dumpStop

public void dumpStop()

Stop dumping packages Only enabled if the node was built with the 'network_dump' feature enabled

Throws:

io.grpc.StatusRuntimeException - if the network dump failed to be stopped or if the node was not built with the 'network_dump' feature

getBlockFinalizationSummary

public Optional<FinalizationData> getBlockFinalizationSummary(BlockQuery blockQuery)

Retrieves the FinalizationData of a given block BlockQuery Note. Returns NULL if there is no finalization data in the block

Parameters:

blockQuery - the block BlockQuery to query

Returns:

The FinalizationData of the block

getElectionInfo

public ElectionInfo getElectionInfo(BlockQuery input)

Get information related to the baker election for a particular block.

Parameters:

input - BlockQuery

Returns:

ElectionInfo

getBlockSpecialEvents

public com.google.common.collect.ImmutableList<SpecialOutcome> getBlockSpecialEvents(BlockQuery blockQuery)

Retrieves a list of SpecialOutcomes in a given block BlockQuery These are events generated by the protocol, such as minting and reward payouts. They are not directly generated by any transaction.

Parameters:

blockQuery - the block BlockQuery to query

Returns:

ImmutableList of SpecialOutcomes not directly caused by a transaction

getAncestors

public Iterator<Hash> getAncestors(BlockQuery blockQuery,
                                   long num)

Gets Block Ancestor Blocks.

Parameters:

blockQuery - BlockQuery of the block.

num - Total no of Ancestor blocks to get.

Returns:

Iterator of Hash

getBakerList

public Iterator<BakerId> getBakerList(BlockQuery blockQuery)

Get the IDs of the bakers registered in the given block.

Parameters:

blockQuery - BlockQuery of the block bakers are to be retrieved.

Returns:

Parsed Iterator of BakerId

getInstanceList

public Iterator<ContractAddress> getInstanceList(BlockQuery blockQuery)

Get the list of contract addresses in the given block.

Parameters:

blockQuery - BlockQuery of the block bakers are to be retrieved.

Returns:

Parsed Iterator of ContractAddress

getInstanceInfo

public InstanceInfo getInstanceInfo(BlockQuery input,
                                    ContractAddress contractAddress)

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

Parameters:

input - BlockQuery

contractAddress - ContractAddress of the contract instance.

Returns:

InstanceInfo Information about the contract instance.

getPoolDelegatorsRewardPeriod

public Iterator<DelegatorRewardPeriodInfo> getPoolDelegatorsRewardPeriod(BlockQuery input,
                                                                         BakerId bakerId)

Get the fixed delegators of a given pool for the reward period of the given block. In contracts to the `GetPoolDelegators` which returns delegators registered for the given block, this endpoint returns the fixed delegators contributing stake in the reward period containing the given block. The stream will end when all the delegators has been returned.

Parameters:

input - BlockQuery.

bakerId - BakerId.

Returns:

Iterator.

getPassiveDelegatorsRewardPeriod

public Iterator<DelegatorRewardPeriodInfo> getPassiveDelegatorsRewardPeriod(BlockQuery input)

Get the fixed passive delegators for the reward period of the given block. In contracts to the `GetPassiveDelegators` which returns delegators registered for the given block, this endpoint returns the fixed delegators contributing stake in the reward period containing the given block. The stream will end when all the delegators has been returned.

Parameters:

input - BlockQuery.

Returns:

Iterator.

getBranches

public Branch getBranches()

Get the branches of the node's tree. Branches are all live blocks that are successors of the last finalized block. In particular this means that blocks which do not have a parent are not included in this response

Returns:

Branch

getPassiveDelegators

public Iterator<DelegatorInfo> getPassiveDelegators(BlockQuery input)

Get information about the passive delegators at the end of a given block.

Parameters:

input - BlockQuery.

Returns:

Iterator of DelegatorInfo.

getPoolDelegators

public Iterator<DelegatorInfo> getPoolDelegators(BlockQuery input,
                                                 AccountIndex bakerId)

Get the registered delegators of a given pool at the end of a given block. Any changes to delegators are immediately visible in this list.

Parameters:

input - BlockQuery

bakerId - AccountIndex

Returns:

Iterator of DelegatorInfo. List of delegators that are registered in the block.

getPassiveDelegationInfo

public PassiveDelegationInfo getPassiveDelegationInfo(BlockQuery input)

Get information about the passive delegators at the end of a given block.

Parameters:

input - BlockQuery

getNextUpdateSequenceNumbers

public NextUpdateSequenceNumbers getNextUpdateSequenceNumbers(BlockQuery input)

Get next available sequence numbers for updating chain parameters after a given block.

Parameters:

input - BlockQuery.

Returns:

NextUpdateSequenceNumbers.

getBlockPendingUpdates

public Iterator<PendingUpdateV2> getBlockPendingUpdates(BlockQuery input)

getInstanceState

public Iterator<KeyValurPair> getInstanceState(BlockQuery input,
                                               ContractAddress contractAddress)

Get the exact state of a specific contract instance, streamed as a list of key-value pairs. The list is streamed in lexicographic order of keys.

Parameters:

input - BlockQuery.

contractAddress - ContractAddress.

Returns:

Iterator of KeyValurPair.

instanceStateLookup

public byte[] instanceStateLookup(BlockQuery input,
                                  ContractAddress contractAddress,
                                  byte[] key)

Get the value at a specific key of a contract state. In contrast to getInstanceState(BlockQuery, ContractAddress) this is more efficient, but requires the user to know the specific key to look for.

Parameters:

input - BlockQuery.

contractAddress - ContractAddress.

key - Instance State Key to Lookup.

Returns:

Instance State Value for the input `key`

close

public void close()

Closes the underlying grpc channel

This should only be done when the ClientV2 is of no more use as creating a new ClientV2 (and the associated) channel is rather expensive.

Subsequent calls following a closed channel will throw a StatusRuntimeException

getNodeInfo

public NodeInfo getNodeInfo()

Retrieves valious information about the node

Returns:

NodeInfo containing valious information about the node

getPeersInfo

public com.google.common.collect.ImmutableList<PeerInfo> getPeersInfo()
                                                               throws UnknownHostException

Returns a ImmutableList of PeerInfo containing information about the nodes' peers

Returns:

ImmutableList of PeerInfo

Throws:

UnknownHostException - When the returned IP address of Peer is Invalid

getPoolInfo

public BakerPoolStatus getPoolInfo(BlockQuery input,
                                   BakerId bakerId)

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

Parameters:

input - BlockQuery.

bakerId - BakerId.

Returns:

BakerPoolStatus.

getModuleList

public Iterator<ModuleRef> getModuleList(BlockQuery input)

Get list of Smart Contract modules at the end of the given block.

Parameters:

input - BlockQuery.

Returns:

Iterator.

shutdown

public void shutdown()

Shut down the node. Return a GRPC error if the shutdown failed.

peerConnect

public void peerConnect(InetSocketAddress socketAddress)

Tries to connect to a peer with the submitted InetSocketAddress. If successful, adds the peer to the list of given addresses. Note. The peer might not be connected instantly, in that case the node will try to establish the connection in near future. In this case Status.OK is returned

Parameters:

socketAddress - InetSocketAddress of the peer to connect to

Throws:

{@link - io.grpc.StatusRuntimeException} if unsuccessful

peerDisconnect

public void peerDisconnect(InetSocketAddress socketAddress)

Disconnect from the peer with the submitted InetSocketAddress and remove them from the address list if they are on it.

Parameters:

socketAddress - InetSocketAddress of the peer to disconnect from

Throws:

{@link - io.grpc.StatusRuntimeException} if unsuccessful

banPeer

public void banPeer(InetAddress ipToBan)

Ban a specific peer Note this will ban all peers located behind the specified IP even though they are using different ports

Parameters:

ipToBan - ip of the node to ban

Throws:

{@link - io.grpc.StatusRuntimeException} If the action failed

unbanPeer

public void unbanPeer(InetAddress ipToUnban)

Unban a specific peer

Parameters:

ipToUnban - ip of the node to unban

Throws:

{@link - io.grpc.StatusRuntimeException} If the action failed

getBannedPeers

public com.google.common.collect.ImmutableList<InetAddress> getBannedPeers()
                                                                    throws UnknownHostException

Get a list of banned peers

Returns:

ImmutableList of InetAddress of banned peers

Throws:

UnknownHostException - When the returned IP address of a peer is invalid

getModuleSource

public WasmModule getModuleSource(BlockQuery query,
                                  ModuleRef moduleRef)

Get the source of a smart contract module from the perspective of the last finalized block.

Parameters:

query - The query is at the end of the block specified.

moduleRef - the reference of the module.

Returns:

the parsed WasmModule.

Throws:

io.grpc.StatusRuntimeException - if the module could not be looked up on the chain.

invokeInstance

public InvokeInstanceResult invokeInstance(InvokeInstanceRequest request)

This function can be used to either 1. Dry-run the smart contract entrypoint with the provided context and in the state at the end of the given block. 2. Call a view function on a smart contract. View functions are a special kind of functions that smart contract writers write in order to be able to read the state of a smart contract instance.
Note that calling a smart contract instance with this function does not have any effect on the actual chain, it's solely a local operation on the node, hence it's "free" to call a smart contract instance with this function.

Parameters:

request - InvokeInstanceRequest

Returns:

InvokeInstanceResult

getBakersRewardPeriod

public com.google.common.collect.ImmutableList<BakerRewardPeriodInfo> getBakersRewardPeriod(BlockQuery input)

Get all bakers in the reward period of a block. This endpoint is only supported for protocol version 6 and onwards.

Parameters:

input - The block to query.

Returns:

ImmutableList with the BakerRewardPeriodInfo of all the bakers in the block.

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.Code.UNIMPLEMENTED if the protocol does not support the endpoint.

getBlockCertificates

public BlockCertificates getBlockCertificates(BlockQuery block)

Retrieves the BlockCertificates for a given block.

Parameters:

block - The block to query

Returns:

BlockCertificates of the block.

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.Code.UNIMPLEMENTED if the endpoint is not enabled by the node.
• Status.Code.INVALID_ARGUMENT if the block being pointed to is not a product of ConcordiumBFT, i.e. created before protocol version 6.

getBakerEarliestWinTime

public Timestamp getBakerEarliestWinTime(BakerId bakerId)

Get the projected earliest time at which a particular baker will be required to bake a block.

If the baker is not a baker for the current reward period, this returns a timestamp at the start of the next reward period.

If the baker is a baker for the current reward period, the earliest win time is projected from the current round forward, assuming that each round after the last finalized round will take the minimum block time. (If blocks take longer, or timeouts occur, the actual time may be later, and the reported time in subsequent queries may reflect this.)

At the end of an epoch (or if the baker is not projected to bake before the end of the epoch) the earliest win time for a (current) baker will be projected as the start of the next epoch. This is because the seed for the leader election is updated at the epoch boundary, and so the winners cannot be predicted beyond that.

Note that in some circumstances the returned timestamp can be in the past, especially at the end of an epoch.

Parameters:

bakerId - id of the baker to query.

Returns:

Timestamp as described in the method documentation.

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.Code.UNIMPLEMENTED if the current consensus version is 0, as the endpoint is only supported by consensus version 1.

getFirstBlockEpoch

public Hash getFirstBlockEpoch(EpochQuery epochQuery)

Get the block hash of the first finalized block in a specified epoch.

Parameters:

epochQuery - EpochQuery representing the specific epoch to query.

Returns:

Hash of the first finalized block in the epoch.

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.NOT_FOUND if the query specifies an unknown block.
• Status.UNAVAILABLE if the query is for an epoch that is not finalized in the current genesis index, or is for a future genesis index.
• Status.INVALID_ARGUMENT if the query is for an epoch with no finalized blocks for a past genesis index.
• Status.INVALID_ARGUMENT if the input EpochQuery is malformed.
• Status.UNIMPLEMENTED if the endpoint is disabled on the node.

getWinningBakersEpoch

public com.google.common.collect.ImmutableList<WinningBaker> getWinningBakersEpoch(EpochQuery epochQuery)

Get the list of bakers that won the lottery in a particular historical epoch (i.e. the last finalized block is in a later epoch).

This lists the winners for each round in the epoch, starting from the round after the last block in the previous epoch, running to the round before the first block in the next epoch.

It also indicates if a block in each round was included in the finalized chain.

Parameters:

epochQuery - EpochQuery representing the specific epoch to query.

Returns:

ImmutableList of bakers that won the lottery in the specified epoch.

Throws:

io.grpc.StatusRuntimeException - with Status.Code:

• Status.NOT_FOUND if the query specifies an unknown block.
• Status.UNAVAILABLE if the query is for an epoch that is not finalized in the current genesis index, or is for a future genesis index.
• Status.INVALID_ARGUMENT if the query is for an epoch that is not finalized for a past genesis index.
• Status.INVALID_ARGUMENT if the query is for a genesis index at consensus version 0.
• Status.INVALID_ARGUMENT if the input EpochQuery is malformed.
• Status.UNIMPLEMENTED if the endpoint is disabled on the node.

waitUntilFinalized

public Optional<FinalizedBlockItem> waitUntilFinalized(Hash transactionHash,
                                                       int timeoutMillis)

Waits until a given transaction is finalized and returns the corresponding Optional. If the transaction is unknown to the node or not finalized, the client starts listening for newly finalized blocks, and returns the corresponding Optional once the transaction is finalized.

Parameters:

transactionHash - the Hash of the transaction to wait for.

timeoutMillis - the number of milliseconds to listen for newly finalized blocks.

Returns:

Optional of the transaction if it was finalized before exceeding the timeout, Empty otherwise.

findAtLowestHeight

public <T> Optional<T> findAtLowestHeight(BiFunction<ClientV2,BlockQuery,Optional<T>> test)

Find a finalized block with the lowest height that satisfies the given condition. If a block is not found return Optional.empty().

The provided `test` method should, given a ClientV2 and a BlockQuery, return Optional#of(T) if the object is found in the block, and Optional.empty() otherwise. It can also throw exceptions which will terminate the search immediately and pass on the exception.

The precondition for this method is that the `test` method is monotone, i.e. if a block at height `h` satisfies the test then also a block at height `h+1` does. If this precondition does not hold then the return value from this method is unspecified.

Note, this searches the entire chain. Use findAtLowestHeight(Range, BiFunction) to only search a given range.

Type Parameters:

T - The type to be returned if the search is successful.

Parameters:

test - BiFunction satisfying the conditions described above.

Returns:

Optional#of(T) if the search was successful, Optional.empty() otherwise.

findAtLowestHeight

public <T> Optional<T> findAtLowestHeight(Range<AbsoluteBlockHeight> range,
                                          BiFunction<ClientV2,BlockQuery,Optional<T>> test)

Find a finalized block with the lowest height that satisfies the given condition. If a block is not found return Optional.empty().

The provided `test` method should, given a ClientV2 and a BlockQuery, return Optional#of(T) if the object is found in the block, and Optional.empty() otherwise. It can also throw exceptions which will terminate the search immediately and pass on the exception.

The precondition for this method is that the `test` method is monotone, i.e. if a block at height `h` satisfies the test then also a block at height `h+1` does. If this precondition does not hold then the return value from this method is unspecified.

The search is limited to at most the given range, the upper bound is always at most the last finalized block at the time of the call. If the lower bound is not provided it defaults to 0, if the upper bound is not provided it defaults to the last finalized block at the time of the call.

Type Parameters:

T - The type to be returned if the search is successful.

Parameters:

range - Range optionally specifying upper and lower bounds of the search.

test - BiFunction satisfying the conditions described above.

Returns:

Optional#of(T) if the search was successful, Optional.empty() otherwise.

findAccountCreation

public Optional<FindAccountResponse> findAccountCreation(Range<AbsoluteBlockHeight> range,
                                                         AccountAddress address)

Find a block in which the AccountAddress was created, if it exists and is finalized. The returned FindAccountResponse, if present, contains the absolute block height, corresponding Hash and the AccountInfo at the end of the block. The block is the first block in which the account appears.

Note that this is not necessarily the initial state of the account since there can be transactions updating it in the same block that it is created.

The search is limited to at most the given range, the upper bound is always at most the last finalized block at the time of the call. If the lower bound is not provided it defaults to 0, if the upper bound is not provided it defaults to the last finalized block at the time of the call.

If the account is not found, Optional.empty() is returned.

Parameters:

range - Range optionally specifying upper and lower bounds of the search.

address - The AccountAddress to search for.

Returns:

Optional containing FindAccountResponse if the search was successful, Optional.empty() otherwise.

findAccountCreation

public Optional<FindAccountResponse> findAccountCreation(AccountAddress address)

Find a block in which the AccountAddress was created, if it exists and is finalized. The returned FindAccountResponse, if present, contains the absolute block height, corresponding Hash and the AccountInfo at the end of the block. The block is the first block in which the account appears.

Note that this is not necessarily the initial state of the account since there can be transactions updating it in the same block that it is created.

If the account is not found, Optional.empty() is returned.

Note, this searches the entire chain. Use findAccountCreation(Range, AccountAddress) to only search a given range.

Parameters:

address - The AccountAddress to search for.

Returns:

Optional containing FindAccountResponse if the search was successful, Optional.empty() otherwise.

getBlocksAtHeight

public com.google.common.collect.ImmutableList<Hash> getBlocksAtHeight(BlocksAtHeightRequest height)

Get a ImmutableList of live blocks at a given height.

Parameters:

height - BlocksAtHeightRequest with the height to query at.

Returns:

ImmutableList of Hash of live blocks at the specified height.

getFinalizedBlocksFrom

public FinalizedBlockItemIterator getFinalizedBlocksFrom(AbsoluteBlockHeight startHeight)

Get a FinalizedBlockItemIterator of BlockIdentifier of finalized blocks starting from a given height. This function starts a Thread that listens for new finalized blocks. This Thread is killed when the FinalizedBlockItemIterator dropped with FinalizedBlockItemIterator.drop()

Parameters:

startHeight - AbsoluteBlockHeight to start at.

Returns:

FinalizedBlockItemIterator containing BlockIdentifiers of finalized blocks.