v2.concordium.service.proto Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of concordium-sdk Show documentation
Show all versions of concordium-sdk Show documentation
An SDK for interacting with the Concordium blockchain
The newest version!
syntax = "proto3";
import "v2/concordium/types.proto";
package concordium.v2;
// This specifies the package we want to use for our generated Go code.
// Has no effect on code generated on other languages.
option go_package = "./pb";
// This specifies the package we want to use for our generated Java classes.
// Has no effect on code generated on other languages.
option java_package = "com.concordium.grpc.v2";
// This specifies the package we want to use for our generated C# classes.
// Has no effect on code generated on other languages.
option csharp_namespace = "Concordium.Grpc.V2";
// This specifies that separate .java files will be generated for each of the Java classes/enums/etc. generated for the top-level messages, services, and enumerations,
// and the wrapper Java class generated for this .proto file won't contain any nested classes/enums/etc.
// If not generating Java code, this option has no effect.
option java_multiple_files = true;
service Queries {
// Return a stream of blocks that arrive from the time the query is made onward.
// This can be used to listen for incoming blocks.
rpc GetBlocks (Empty) returns (stream ArrivedBlockInfo);
// 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.
rpc GetFinalizedBlocks (Empty) returns (stream FinalizedBlockInfo);
// Retrieve the information about the given account in the given block.
rpc GetAccountInfo (AccountInfoRequest) returns (AccountInfo);
// Retrieve the list of accounts that exist at the end of the given block.
rpc GetAccountList (BlockHashInput) returns (stream AccountAddress);
// Get a list of all smart contract modules. The stream will end
// when all modules that exist in the state at the end of the given
// block have been returned.
rpc GetModuleList (BlockHashInput) returns (stream ModuleRef);
// 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.
rpc GetAncestors (AncestorsRequest) returns (stream BlockHash);
// Get the source of a smart contract module.
rpc GetModuleSource (ModuleSourceRequest) returns (VersionedModuleSource);
// Get a list of addresses for all smart contract instances. The stream
// will end when all instances that exist in the state at the end of the
// given block has been returned.
rpc GetInstanceList (BlockHashInput) returns (stream ContractAddress);
// Get info about a smart contract instance as it appears at the end of the
// given block.
rpc GetInstanceInfo (InstanceInfoRequest) returns (InstanceInfo);
// 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.
rpc GetInstanceState (InstanceInfoRequest) returns (stream InstanceStateKVPair);
// Get the value at a specific key of a contract state. In contrast to
// `GetInstanceState` this is more efficient, but requires the user to know
// the specific key to look for.
rpc InstanceStateLookup(InstanceStateLookupRequest) returns (InstanceStateValueAtKey);
// Get the best guess as to what the next account sequence number should be.
// 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.
rpc GetNextAccountSequenceNumber (AccountAddress) returns (NextAccountSequenceNumber);
// Get information about the current state of consensus.
rpc GetConsensusInfo (Empty) returns (ConsensusInfo);
// Get the status of and information about a specific block item (transaction).
rpc GetBlockItemStatus (TransactionHash) returns (BlockItemStatus);
// Get the cryptographic parameters in a given block.
rpc GetCryptographicParameters (BlockHashInput) returns (CryptographicParameters);
// Get information, such as height, timings, and transaction counts for the given block.
rpc GetBlockInfo (BlockHashInput) returns (BlockInfo);
// Get all the bakers at the end of the given block.
rpc GetBakerList (BlockHashInput) returns (stream BakerId);
// Get information about a given pool at the end of a given block.
rpc GetPoolInfo (PoolInfoRequest) returns (PoolInfoResponse);
// Get information about the passive delegators at the end of a given block.
rpc GetPassiveDelegationInfo (BlockHashInput) returns (PassiveDelegationInfo);
// Get a list of live blocks at a given height.
rpc GetBlocksAtHeight (BlocksAtHeightRequest) returns (BlocksAtHeightResponse);
// Get information about tokenomics at the end of a given block.
rpc GetTokenomicsInfo (BlockHashInput) returns (TokenomicsInfo);
// Run the smart contract entrypoint in a given context and in the state at
// the end of the given block.
rpc InvokeInstance (InvokeInstanceRequest) returns (InvokeInstanceResponse);
// Get the registered delegators of a given pool at the end of a given block.
// In contrast to the `GetPoolDelegatorsRewardPeriod` which returns delegators
// that are fixed for the reward period of the block, this endpoint returns the
// list of delegators that are registered in the block. Any changes to delegators
// are immediately visible in this list.
// The stream will end when all the delegators has been returned.
rpc GetPoolDelegators (GetPoolDelegatorsRequest) returns (stream DelegatorInfo);
// 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.
rpc GetPoolDelegatorsRewardPeriod (GetPoolDelegatorsRequest) returns (stream DelegatorRewardPeriodInfo);
// Get the registered passive delegators at the end of a given block.
// In contrast to the `GetPassiveDelegatorsRewardPeriod` which returns delegators
// that are fixed for the reward period of the block, this endpoint returns the
// list of delegators that are registered in the block. Any changes to delegators
// are immediately visible in this list.
// The stream will end when all the delegators has been returned.
rpc GetPassiveDelegators (BlockHashInput) returns (stream DelegatorInfo);
// 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.
rpc GetPassiveDelegatorsRewardPeriod (BlockHashInput) returns (stream DelegatorRewardPeriodInfo);
// Get the current branches of blocks starting from and including the last finalized block.
rpc GetBranches (Empty) returns (Branch);
// Get information related to the baker election for a particular block.
rpc GetElectionInfo (BlockHashInput) returns (ElectionInfo);
// 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.
rpc GetIdentityProviders (BlockHashInput) returns (stream IpInfo);
// Get the anonymity revokers registered as of the end of a given block.
// The stream will end when all the anonymity revokers have been returned.
rpc GetAnonymityRevokers (BlockHashInput) returns (stream ArInfo);
// Get a list of non-finalized transaction hashes for a given account. This
// endpoint is not expected to return a large amount of data in most cases,
// but in bad network condtions it might. The stream will end when all the
// non-finalized transaction hashes have been returned.
rpc GetAccountNonFinalizedTransactions (AccountAddress) returns (stream TransactionHash);
// Get a list of transaction events in a given block.
// The stream will end when all the transaction events for a given block have been returned.
rpc GetBlockTransactionEvents (BlockHashInput) returns (stream BlockItemSummary);
// Get a list of special events in a given block. These are events generated
// by the protocol, such as minting and reward payouts. They are not directly
// generated by any transaction. The stream will end when all the special
// events for a given block have been returned.
rpc GetBlockSpecialEvents (BlockHashInput) returns (stream BlockSpecialEvent);
// 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.
rpc GetBlockPendingUpdates (BlockHashInput) returns (stream PendingUpdate);
// Get next available sequence numbers for updating chain parameters after a given block.
rpc GetNextUpdateSequenceNumbers (BlockHashInput) returns (NextUpdateSequenceNumbers);
// Get the projected earliest time at which a particular baker will be required to bake a block.
// If the current consensus version is 0, this returns the status 'Unavailable', as the endpoint
// is only supported by consensus version 1.
//
// 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.
rpc GetBakerEarliestWinTime(BakerId) returns (Timestamp);
// Shut down the node.
// Return a GRPC error if the shutdown failed.
rpc Shutdown(Empty) returns (Empty);
// Suggest to a peer to connect to the submitted peer details.
// This, if successful, adds the peer to the list of given addresses.
// Otherwise return a GRPC error.
// Note. The peer might not be connected to instantly, in that case
// the node will try to establish the connection in near future. This
// function returns a GRPC status 'Ok' in this case.
rpc PeerConnect (IpSocketAddress) returns (Empty);
// Disconnect from the peer and remove them from the given addresses list
// if they are on it. Return if the request was processed successfully.
// Otherwise return a GRPC error.
rpc PeerDisconnect (IpSocketAddress) returns (Empty);
// Get a list of banned peers.
rpc GetBannedPeers(Empty) returns (BannedPeers);
// Ban the given peer.
// Returns a GRPC error if the action failed.
rpc BanPeer(PeerToBan) returns (Empty);
// Unban the banned peer.
// Returns a GRPC error if the action failed.
rpc UnbanPeer(BannedPeer) returns (Empty);
// Start dumping packages into the specified file.
// Only enabled if the node was built with the `network_dump` feature.
// Returns a GRPC error if the network dump failed to start.
rpc DumpStart(DumpRequest) returns (Empty);
// Stop dumping packages.
// Only enabled if the node was built with the `network_dump` feature.
// Returns a GRPC error if the network dump failed to be stopped.
rpc DumpStop(Empty) returns (Empty);
// Get a list of the peers that the node is connected to
// and assoicated network related information for each peer.
rpc GetPeersInfo(Empty) returns (PeersInfo);
// Get information about the node.
// The `NodeInfo` includes information of
// * Meta information such as the, version of the node, type of the node, uptime and the local time of the node.
// * NetworkInfo which yields data such as the node id, packets sent/received,
// average bytes per second sent/received.
// * ConsensusInfo. The `ConsensusInfo` returned depends on if the node supports
// the protocol on chain and whether the node is configured as a baker or not.
rpc GetNodeInfo(Empty) returns (NodeInfo);
// Send a block item. A block item is either an `AccountTransaction`, which is
// a transaction signed and paid for by an account, a `CredentialDeployment`,
// which creates a new account, or `UpdateInstruction`, which is an
// instruction to change some parameters of the chain. Update instructions can
// only be sent by the governance committee.
//
// Returns a hash of the block item, which can be used with
// `GetBlockItemStatus`.
rpc SendBlockItem (SendBlockItemRequest) returns (TransactionHash);
// Get the hash to be signed for an account transaction. The hash returned
// should be signed and the signatures included as an
// AccountTransactionSignature when calling `SendBlockItem`. This is provided as
// a convenience to support cases where the right SDK is not available for
// interacting with the node. If an SDK is available then it is strongly
// recommended to compute this hash off-line using it. That reduces the trust
// in the node, removes networking failure modes, and will perform better.
rpc GetAccountTransactionSignHash (PreAccountTransaction) returns (AccountTransactionSignHash);
// Get the values of chain parameters in effect in the given block.
rpc GetBlockChainParameters(BlockHashInput) returns (ChainParameters);
// Get the summary of the finalization data in a given block.
rpc GetBlockFinalizationSummary(BlockHashInput) returns (BlockFinalizationSummary);
// Get the items of a block.
rpc GetBlockItems(BlockHashInput) returns (stream BlockItem);
// Get all bakers in the reward period of a block.
// This endpoint is only supported for protocol version 6 and onwards.
// If the protocol does not support the endpoint then an 'IllegalArgument' error is returned.
rpc GetBakersRewardPeriod(BlockHashInput) returns (stream BakerRewardPeriodInfo);
// For a non-genesis block, this returns the quorum certificate, a timeout
// certificate (if present) and epoch finalization entry (if present).
// Note that, if the block being pointed to is not a product of ConcordiumBFT,
// then the response will be a grpc error (invalid argument).
// If the endpoint is not enabled by the node, then an 'unimplemented' error
// will be returned.
rpc GetBlockCertificates(BlockHashInput) returns (BlockCertificates);
// 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.
//
// The following error cases are possible:
// * `NOT_FOUND` if the query specifies an unknown block.
// * `UNAVAILABLE` if the query is for an epoch that is not finalized in the current genesis
// index, or is for a future genesis index.
// * `INVALID_ARGUMENT` if the query is for an epoch that is not finalized for a past genesis
// index.
// * `INVALID_ARGUMENT` if the query is for a genesis index at consensus version 0.
// * `INVALID_ARGUMENT` if the input `EpochRequest` is malformed.
// * `UNIMPLEMENTED` if the endpoint is disabled on the node.
rpc GetWinningBakersEpoch (EpochRequest) returns (stream WinningBaker);
// Get the block hash of the first finalized block in a specified epoch.
//
// The following error cases are possible:
// * `NOT_FOUND` if the query specifies an unknown block.
// * `UNAVAILABLE` if the query is for an epoch that is not finalized in the current genesis
// index, or is for a future genesis index.
// * `INVALID_ARGUMENT` if the query is for an epoch with no finalized blocks for a past genesis
// index.
// * `INVALID_ARGUMENT` if the input `EpochRequest` is malformed.
// * `UNIMPLEMENTED` if the endpoint is disabled on the node.
rpc GetFirstBlockEpoch (EpochRequest) returns (BlockHash);
// Dry run a series of transactions and operations on a state derived from a specified block.
// The server should send a single `DryRunResponse` for each `DryRunRequest` received, unless
// the call fails with an error status code. If a request produces a `DryRunErrorResponse`, then
// the server will still process subsequent requests, just as if the request causing the error
// did not happen.
//
// The first request should be `load_block_at_state` to determine the block state that will be
// used for the dry run.
//
// The server associates each request with an energy cost, and limits the total energy that may
// be expended in a single invocation of `DryRun`. This limit is reported as `quota` in the
// initial metadata returned by the server. If executing an operation exceeds the limit,
// the server terminates the session with `RESOURCE_EXHAUSTED`.
//
// The server also imposes a timeout for a dry-run session to complete. The server reports
// the timeout duration in milliseconds in the initial metadata field `timeout`. If the session
// is not completed before the timeout elapses, the server terminates the session with
// `DEADLINE_EXCEEDED`.
//
// The following error cases are possible:
// * `INVALID_ARGUMENT` if any `DryRunRequest` is malformed.
// * `RESOURCE_EXHAUSTED` if the energy quota is exceeded.
// * `DEADLINE_EXCEEDED` if the session does not complete before the server-imposed timeout.
// * `RESOURCE_EXHAUSTED` if the server is not currently accepting new `DryRun` sessions.
// (The server may impose a limit on the number of concurrent sessions.)
// * `INTERNAL` if an interal server error occurs. This should not happen, and likely indicates
// a bug.
// * `UNIMPLEMENTED` if the endpoint is disabled on the node.
rpc DryRun (stream DryRunRequest) returns (stream DryRunResponse);
}