@concordium/common-sdk - npm Package Compare versions

Comparing version 9.4.0 to 9.5.0

lib/GRPCClient.d.ts

@@ -167,3 +167,3 @@ /**
      * @param signature the signatures on the signing digest of the transaction
-     * @returns The transaction hash as a byte array
+     * @returns The transaction hash as a hex-encoded string
      */
@@ -683,2 +683,81 @@ sendAccountTransaction(transaction: v1.AccountTransaction, signature: v1.AccountTransactionSignature): Promise<HexString>;
     findFirstFinalizedBlockNoLaterThan(time: Date, from?: v1.AbsoluteBlocksAtHeightRequest, to?: v1.AbsoluteBlocksAtHeightRequest): Promise<v1.BlockInfo | undefined>;
+    /**
+     * 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.
+     *
+     * @throws an `UNAVAILABLE` RPC error if the current consensus version is 0 (prior to protocol version 6), as the endpoint is only supported from consensus version 1 (from protocol version 6).
+     *
+     * @param {v1.BakerId} baker - The baker that should be queried for.
+     *
+     * @returns {v1.Timestamp} The projected earliest time at which a particular baker will be required to bake a block, as a unix timestamp in milliseconds.
+     */
+    getBakerEarliestWinTime(baker: v1.BakerId): Promise<v1.Timestamp>;
+    /**
+     * For a non-genesis block, this returns the quorum certificate, a timeout
+     * certificate (if present) and epoch finalization entry (if present).
+     *
+     * @throws an `UNIMPLEMENTED` RPC error if the endpoint is not enabled by the node.
+     * @throws an `INVALID_ARGUMENT` if the block being pointed to is not a product of ConcordiumBFT
+     *
+     * @param blockHash optional block hash to get the cryptographic parameters at, otherwise retrieves from last finalized block.
+     *
+     * @returns the requested block certificates.
+     */
+    getBlockCertificates(blockHash?: HexString): Promise<v1.BlockCertificates>;
+    /**
+     * Get all bakers in the reward period of a block.
+     * This endpoint is only supported for protocol version 6 and onwards.
+     *
+     * @throws an `IllegalArgument` RPC error if the protocol does not support the endpoint.
+     *
+     * @param blockHash optional block hash to get the cryptographic parameters at, otherwise retrieves from last finalized block.
+     *
+     * @returns All bakers in the reward period of a block
+     */
+    getBakersRewardPeriod(blockHash?: HexString): AsyncIterable<v1.BakerRewardPeriodInfo>;
+    /**
+     * 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:
+     * @throws a `NOT_FOUND` RPC error if the query specifies an unknown block.
+     * @throws an `UNAVAILABLE` RPC error if the query is for an epoch that is not finalized in the current genesis index, or is for a future genesis index.
+     * @throws an `INVALID_ARGUMENT` RPC error if the query is for an epoch that is not finalized for a past genesis index.
+     * @throws an `INVALID_ARGUMENT` RPC error if the query is for a genesis index at consensus version 0.
+     * @throws an `INVALID_ARGUMENT` RPC error if the input `EpochRequest` is malformed.
+     * @throws an `UNAVAILABLE` RPC error if the endpoint is disabled on the node.
+     *
+     * @param {HexString | v1.RelativeEpochRequest } epochRequest - Consists of either a hex-encoded block hash or a relative epoch request consisting of a genesis index and an epoch. If none is passed, it queries the last finalized block.
+     *
+     * @returns {v1.WinningBaker} A stream of winning bakers for a given epoch.
+     */
+    getWinningBakersEpoch(epochRequest?: HexString | v1.RelativeEpochRequest): AsyncIterable<v1.WinningBaker>;
+    /**
+     * Get the block hash of the first finalized block in a specified epoch.
+     *
+     * The following error cases are possible:
+     * @throws - a `NOT_FOUND` RPC error if the query specifies an unknown block.
+     * @throws - an `UNAVAILABLE` RPC error if the query is for an epoch that is not finalized in the current genesis index, or is for a future genesis index.
+     * @throws - an `INVALID_ARGUMENT` RPC error if the query is for an epoch with no finalized blocks for a past genesis index.
+     * @throws - an `INVALID_ARGUMENT` RPC error if the input `EpochRequest` is malformed.
+     * @throws - an `UNAVAILABLE` RPC error if the endpoint is disabled on the node.
+     *
+     * @param {HexString | v1.RelativeEpochRequest } epochRequest - Consists of either a hex-encoded block hash or a relative epoch request consisting of a genesis index and an epoch. If none is passed, it queries the last finalized block.
+     *
+     * @returns {HexString} The block hash as a hex encoded string.
+     */
+    getFirstBlockEpoch(epochRequest?: HexString | v1.RelativeEpochRequest): Promise<HexString>;
     private getConsensusHeight;
@@ -685,0 +764,0 @@ /**

lib/GRPCTypeTranslation.d.ts

@@ -35,3 +35,11 @@ import * as v1 from './types';
 export declare function blockFinalizationSummary(finalizationSummary: v2.BlockFinalizationSummary): v1.BlockFinalizationSummary;
+export declare function blockCertificates(certs: v2.BlockCertificates): v1.BlockCertificates;
+export declare function quorumCertificate(cert: v2.QuorumCertificate): v1.QuorumCertificate;
+export declare function timeoutCertificate(cert: v2.TimeoutCertificate): v1.TimeoutCertificate;
+export declare function epochFinalizationEntry(cert: v2.EpochFinalizationEntry): v1.EpochFinalizationEntry;
+export declare function finalizerRound(round: v2.FinalizerRound): v1.FinalizerRound;
+export declare function bakerRewardPeriodInfo(bakerRewardPeriod: v2.BakerRewardPeriodInfo): v1.BakerRewardPeriodInfo;
+export declare function bakerInfo(bakerInfo: v2.BakerInfo): v1.BakerInfo;
+export declare function winningBaker(winningBaker: v2.WinningBaker): v1.WinningBaker;
 export declare function accountTransactionSignatureToV2(signature: v1.AccountTransactionSignature): v2.AccountTransactionSignature;
 export declare function BlocksAtHeightRequestToV2(request: v1.BlocksAtHeightRequest): v2.BlocksAtHeightRequest;

lib/types.d.ts

@@ -28,3 +28,26 @@ /**
 export declare type JsonString = string;
+/** A smart contract module reference. This is always 32 bytes long. */
 export declare type ModuleRef = HexString;
+/** The signature of a 'QuorumCertificate'. the bytes have a fixed length of 48 bytes. */
+export declare type QuorumSignature = HexString;
+/** The signature of a 'TimeoutCertificate'. the bytes have a fixed length of 48 bytes. */
+export declare type TimeoutSignature = HexString;
+/**
+ * A proof that establishes that the successor block of
+ * a 'EpochFinalizationEntry' is the immediate successor of
+ * the finalized block.
+ *
+ * The bytes have a fixed length of 32 bytes.
+ */
+export declare type SuccessorProof = HexString;
+/** Baker's public key used to check whether they won the lottery or not. */
+export declare type BakerElectionVerifyKey = HexString;
+/** Baker's public key used to check that they are indeed the ones who produced the block. */
+export declare type BakerSignatureVerifyKey = HexString;
+/**
+ * Baker's public key used to check signatures on finalization records.
+ * This is only used if the baker has sufficient stake to participate in
+ * finalization.
+ */
+export declare type BakerAggregationVerifyKey = HexString;
 /** A number of milliseconds */
@@ -39,2 +62,9 @@ export declare type Duration = bigint;
 /**
+ * The number of chain restarts via a protocol update. An effected
+ * protocol update instruction might not change the protocol version
+ * specified in the previous field, but it always increments the genesis
+ * index.
+ */
+export declare type GenesisIndex = number;
+/**
  * Makes keys of type optional
@@ -639,3 +669,3 @@ *
      */
-    genesisIndex: number;
+    genesisIndex: GenesisIndex;
     /** The height of this block relative to the (re)genesis block of its era */
@@ -668,3 +698,3 @@ eraBlockHeight: number;
 export interface RelativeBlocksAtHeightRequest {
-    genesisIndex: number;
+    genesisIndex: GenesisIndex;
     height: bigint;
@@ -736,3 +766,3 @@ restrict: boolean;
      */
-    genesisIndex: number;
+    genesisIndex: GenesisIndex;
     /** Currently active protocol version. */
@@ -933,2 +963,3 @@ protocolVersion: bigint;
     delegatedCapital: Amount;
+    commissionRates: CommissionRates;
 }
@@ -1550,2 +1581,211 @@ export declare enum BakerPoolPendingChangeType {
 } | SmartContractTypeValues[] | number | string | boolean;
+/**
+ * Certificates for a block for protocols supporting
+ * ConcordiumBFT.
+ */
+export interface BlockCertificates {
+    /**
+     * The quorum certificate. Is present if and only if the block is
+     * not a genesis block.
+     */
+    quorumCertificate?: QuorumCertificate;
+    /**
+     * The timeout certificate. Is present only if the round prior to the
+     * round of the block timed out.
+     */
+    timeoutCertificate?: TimeoutCertificate;
+    /**
+     * The epoch finalization entry. Is present only if the block initiates
+     * a new epoch.
+     */
+    epochFinalizationEntry?: EpochFinalizationEntry;
+}
+/**
+ * A quorum certificate is the certificate that the
+ * finalization comittee issues in order to certify a block.
+ * A block must be certified before it will be part of the
+ * authorative part of the chain.
+ */
+export interface QuorumCertificate {
+    /**
+     * The hash of the block that the quorum certificate refers to.
+     */
+    blockHash: HexString;
+    /**
+     * The round of the block.
+     */
+    round: Round;
+    /**
+     * The epoch of the block.
+     */
+    epoch: Epoch;
+    /**
+     * The aggregated signature by the finalization committee on the block.
+     */
+    aggregateSignature: QuorumSignature;
+    /**
+     * A list of the finalizers that formed the quorum certificate
+     * i.e., the ones who have contributed to the 'aggregateSignature'.
+     * The finalizers are identified by their baker id as this is stable
+     * across protocols and epochs.
+     */
+    signatories: BakerId[];
+}
+/**
+ * A timeout certificate is the certificate that the
+ * finalization committee issues when a round times out,
+ * thus making it possible for the protocol to proceed to the
+ * next round.
+ */
+export interface TimeoutCertificate {
+    /**
+     * The round that timed out.
+     */
+    round: Round;
+    /**
+     * The minimum epoch of which signatures are included
+     * in the 'aggregate_signature'.
+     */
+    minEpoch: Epoch;
+    /**
+     * The rounds of which finalizers have their best
+     * quorum certificates in the 'minEpoch'.
+     */
+    qcRoundsFirstEpoch: FinalizerRound[];
+    /**
+     * The rounds of which finalizers have their best
+     * quorum certificates in the epoch 'minEpoch' + 1.
+     */
+    qcRoundsSecondEpoch: FinalizerRound[];
+    /**
+     * The aggregated signature by the finalization committee that witnessed
+     * the 'round' timed out.
+     */
+    aggregateSignature: TimeoutSignature;
+}
+/**
+ * The finalizer round is a map from a 'Round'
+ * to the list of finalizers (identified by their 'BakerId') that signed
+ * off the round.
+ */
+export interface FinalizerRound {
+    /**
+     * The round that was signed off.
+     */
+    round: Round;
+    /**
+     * The finalizers (identified by their 'BakerId' that
+     * signed off the in 'round'.
+     */
+    finalizers: BakerId[];
+}
+/**
+ * The epoch finalization entry is the proof that
+ * makes the protocol able to advance to a new epoch.
+ * I.e. the 'EpochFinalizationEntry' is present if and only if
+ * the block is the first block of a new 'Epoch'.
+ */
+export interface EpochFinalizationEntry {
+    /**
+     * The quorum certificate for the finalized block.
+     */
+    finalizedQc: QuorumCertificate;
+    /**
+     * The quorum certificate for the block that finalizes
+     * the block that 'finalizedQc' points to.
+     */
+    successorQc: QuorumCertificate;
+    /**
+     * A proof that the successor block is an immediate
+     * successor of the finalized block.
+     */
+    successorProof: SuccessorProof;
+}
+/**
+ * Information about a particular baker with respect to
+ * the current reward period.
+ */
+export interface BakerRewardPeriodInfo {
+    /**
+     * The baker id and public keys for the baker.
+     */
+    baker: BakerInfo;
+    /**
+     * The effective stake of the baker for the consensus protocol.
+     * The returned amount accounts for delegation, capital bounds and leverage bounds.
+     */
+    effectiveStake: Amount;
+    /**
+     * The effective commission rate for the baker that applies for the reward period.
+     */
+    commissionRates: CommissionRates;
+    /**
+     * The amount staked by the baker itself.
+     */
+    equityCapital: Amount;
+    /**
+     * The total amount of capital delegated to this baker pool.
+     */
+    delegatedCapital: Amount;
+    /**
+     * Whether the baker is a finalizer or not.
+     */
+    isFinalizer: boolean;
+}
+/**
+ * Information about a baker.
+ */
+export interface BakerInfo {
+    /**
+     * Identity of the baker. This is actually the account index of
+     * the account controlling the baker.
+     */
+    bakerId: BakerId;
+    /**
+     * Baker's public key used to check whether they won the lottery or not.
+     */
+    electionKey: BakerElectionVerifyKey;
+    /**
+     * Baker's public key used to check that they are indeed the ones who
+     * produced the block.
+     */
+    signatureKey: BakerSignatureVerifyKey;
+    /**
+     * Baker's public key used to check signatures on finalization records.
+     * This is only used if the baker has sufficient stake to participate in
+     * finalization.
+     */
+    aggregationKey: BakerAggregationVerifyKey;
+}
+/**
+ * Request an epoch by number at a given genesis index.
+ */
+export interface RelativeEpochRequest {
+    /**
+     * The genesis index to query at. The query is restricted to this genesis index, and
+     * will not return results for other indices even if the epoch number is out of bounds.
+     */
+    genesisIndex: GenesisIndex;
+    /**
+     * The epoch number to query at.
+     */
+    epoch: Epoch;
+}
+/**
+ * Details of which baker won the lottery in a given round in consensus version 1.
+ */
+export interface WinningBaker {
+    /**
+     * The round number.
+     */
+    round: Round;
+    /**
+     * The baker that won the round.
+     */
+    winner: BakerId;
+    /**
+     * True if the baker produced a block in this round on the finalized chain, and False otherwise.
+     */
+    present: boolean;
+}
 export declare type HealthCheckResponse = {
@@ -1552,0 +1792,0 @@ isHealthy: true;

package.json

 {
     "name": "@concordium/common-sdk",
-    "version": "9.4.0",
+    "version": "9.5.0",
     "license": "Apache-2.0",
@@ -5,0 +5,0 @@ "engines": {

No alert changes

Improved metrics

Lines of code

34797

0.98%

Worsened metrics

Total package byte prevSize

1521795

-3.24%

Number of package files

132

-2.22%

No dependency changes