@polymeshassociation/polymesh-sdk 31.0.0 → 31.1.0-beta.10

package/api/client/Staking.d.ts

@@ -1,5 +1,6 @@
-import { Context } from '../../internal';
-import { BondPolyxParams, NoArgsProcedureMethod, NominateValidatorsParams, PaginationOptions, ProcedureMethod, ResultSet, SetStakingPayeeParams, StakingCommission, StakingEraInfo, SubCallback, UnsubCallback, UpdatePolyxBondParams } from '../../types';
+import BigNumber from 'bignumber.js';
+import { Account, Context } from '../../internal';
+import { BondPolyxParams, ElectionPhase, ElectionSchedule, EraExposure, EraNominators, EraProgress, EraRewardPoints, NoArgsProcedureMethod, NominateValidatorsParams, PaginationOptions, ProcedureMethod, ResultSet, SetStakingPayeeParams, StakingCommission, StakingConstants, StakingEraInfo, SubCallback, UnsubCallback, UpdatePolyxBondParams } from '../../types';
 /**
  * Handles Staking related functionality
  */
@@ -12,7 +13,9 @@ export declare class Staking {
     /**
      * Bond POLYX for staking
      *
-     * @note the signing account cannot be a stash
+     * @note the signing Account cannot already be a stash — use
+     *   {@link api/client/Staking!Staking.bondExtra | bondExtra} to add to a bond it already has —
+     *   nor a controller for another stash, since one Account cannot be both
      */
     bond: ProcedureMethod<BondPolyxParams, void>;
     /**
@@ -23,8 +26,28 @@ export declare class Staking {
     bondExtra: ProcedureMethod<UpdatePolyxBondParams, void>;
     /**
      * Unbond POLYX for staking. The unbonded amount can be withdrawn after the lockup period
+     *
+     * @note the chain chills a stash that unbonds its whole ledger. Since this refuses an amount
+     *   larger than the active bond, that is the case where nothing is already unlocking and the
+     *   whole of it is unbonded — the stash stops nominating or validating as well
      */
     unbond: ProcedureMethod<UpdatePolyxBondParams, void>;
+    /**
+     * Rebond POLYX that is currently unbonding, without waiting for the lockup period to elapse
+     *
+     * @note this transaction must be signed by a controller
+     *
+     * @note the chain takes the amount from the most recently unbonded POLYX first, so a partial
+     *   rebond leaves the lots closest to maturing where they are
+     */
+    rebond: ProcedureMethod<UpdatePolyxBondParams, void>;
+    /**
+     * Stop nominating validators, without unbonding any POLYX
+     *
+     * @note the bonded POLYX stays bonded. Use `unbond` to begin withdrawing it
+     * @note this transaction must be signed by a controller
+     */
+    chill: NoArgsProcedureMethod<void>;
     /**
      * Withdraw unbonded POLYX to free it for the stash account
      *
@@ -56,9 +79,37 @@ export declare class Staking {
      */
     getValidators(paginationOpts?: PaginationOptions): Promise<ResultSet<StakingCommission>>;
     /**
-     * Retrieve the current staking era information
+     * Retrieve the validators whose set is actually in force for the active era
+     *
+     * @returns the elected validators, in the chain's own order
      *
-     * @returns Promise that resolves to the current era information
+     * @note this is a different question from
+     *   {@link api/client/Staking!Staking.getValidators | getValidators}, which lists every Account
+     *   *declaring intent* to validate. Those declaring intent but not elected are the waiting set —
+     *   subtract this result from `getValidators` to get it
+     * @note bounded by {@link api/client/Staking!Staking.getValidatorCount | getValidatorCount}, so
+     *   unlike the intent list this needs no pagination
+     */
+    getActiveValidators(): Promise<Account[]>;
+    /**
+     * Retrieve how many validators the chain aims to elect each era
+     *
+     * @note this is the target the election is run against, not how many are currently in force —
+     *   read {@link api/client/Staking!Staking.getActiveValidators | getActiveValidators} for that.
+     *   The two differ when fewer Accounts declare intent than there are slots
+     */
+    getValidatorCount(): Promise<BigNumber>;
+    /**
+     * Retrieve information about the staking eras the chain is tracking
+     *
+     * @returns Promise that resolves to the era information
+     *
+     * @note the chain tracks **two** era numbers and they are not interchangeable. `currentEra` is
+     *   the latest era the chain has *planned* — a validator set has been elected for it, but the
+     *   Session pallet may not have brought it into force. `activeEra` is the era whose validator set
+     *   is in force and whose rewards and slashes are being processed. `currentEra` runs ahead of
+     *   `activeEra` between an election and the session rotation that follows it, and the two are
+     *   equal the rest of the time. Anything describing what the chain is doing now wants `activeEra`
      */
     eraInfo(): Promise<StakingEraInfo>;
     /**
@@ -71,5 +122,155 @@ export declare class Staking {
      * @note can be subscribed to, if connected to node using a web socket
      */
     eraInfo(callback: SubCallback<StakingEraInfo>): Promise<UnsubCallback>;
+    /**
+     * Retrieve the chain constants that govern staking
+     *
+     * @note these come from the chain's metadata, so this makes no query
+     */
+    getConstants(): StakingConstants;
+    /**
+     * Retrieve how far through the staking cycle the chain is — which era and session are in force,
+     *   and how far through each of them the chain has got
+     *
+     * @throws if there is no active era
+     *
+     * @note progress is counted in **slots**, which is how the chain measures a period, so
+     *   `progress` is exact. The `remaining` and `end` projections come from `expectedBlockTime` and
+     *   move as block production drifts
+     */
+    eraProgress(): Promise<EraProgress>;
+    /**
+     * Retrieve how far through the staking cycle the chain is, and subscribe to its advance
+     *
+     * @param callback - called on every block, since the slot the progress is counted in advances
+     *   with each one. This is what drives a progress bar without polling
+     *
+     * @returns Promise that resolves to an unsubscribe function
+     *
+     * @note can be subscribed to, if connected to node using a web socket
+     */
+    eraProgress(callback: SubCallback<EraProgress>): Promise<UnsubCallback>;
+    /**
+     * Retrieve the reward points earned by each validator in an era
+     *
+     * @param era - defaults to the active era
+     *
+     * @note points are how the era's reward is split between validators. A validator that authored no
+     *   blocks in the era is absent rather than present with zero
+     */
+    getEraRewardPoints(era?: BigNumber): Promise<EraRewardPoints>;
+    /**
+     * Retrieve the reward points earned by each validator in an era, and subscribe to them
+     *
+     * @param callback - called as points are credited. Points accrue block by block as validators
+     *   author, so for the active era this is a live leaderboard
+     *
+     * @returns Promise that resolves to an unsubscribe function
+     *
+     * @note only the active era changes. Subscribing to a past era is allowed and simply calls back
+     *   once, since the chain has finished writing it
+     * @note can be subscribed to, if connected to node using a web socket
+     */
+    getEraRewardPoints(callback: SubCallback<EraRewardPoints>): Promise<UnsubCallback>;
+    /**
+     * Retrieve the reward points earned by each validator in a specific era, and subscribe to them
+     *
+     * @returns Promise that resolves to an unsubscribe function
+     *
+     * @note can be subscribed to, if connected to node using a web socket
+     */
+    getEraRewardPoints(era: BigNumber, callback: SubCallback<EraRewardPoints>): Promise<UnsubCallback>;
+    /**
+     * Retrieve the total POLYX paid out to validators and their nominators for an era
+     *
+     * @param era - defaults to the active era
+     *
+     * @returns `null` for an era the chain has not paid out, i.e. one still running or older than the
+     *   history depth
+     */
+    getEraValidatorReward(era?: BigNumber): Promise<BigNumber | null>;
+    /**
+     * Retrieve the session an era started at
+     *
+     * @param era - defaults to the active era
+     *
+     * @returns `null` for an era outside the chain's history depth
+     */
+    getEraStartSession(era?: BigNumber): Promise<BigNumber | null>;
+    /**
+     * Retrieve how much POLYX was backing a validator in an era, and how it was split
+     *
+     * @param args.validator - the validator's Account or address
+     * @param args.era - defaults to the active era
+     *
+     * @returns `null` if the Account was not in the era's validator set
+     */
+    getEraExposure(args: {
+        validator: Account | string;
+        era?: BigNumber;
+    }): Promise<EraExposure | null>;
+    /**
+     * Retrieve one page of the nominators backing a validator in an era
+     *
+     * @param args.validator - the validator's Account or address
+     * @param args.page - defaults to the first page. Read `pageCount` from
+     *   {@link api/client/Staking!Staking.getEraExposure | getEraExposure} for how many there are
+     * @param args.era - defaults to the active era
+     *
+     * @returns `null` if the page does not exist
+     *
+     * @note nominators are paged by the chain so that a payout fits in a block, which is why this is
+     *   not returned as part of the exposure
+     */
+    getEraNominators(args: {
+        validator: Account | string;
+        page?: BigNumber;
+        era?: BigNumber;
+    }): Promise<EraNominators | null>;
+    /**
+     * Retrieve when the next validator election opens and closes
+     *
+     * @throws if there is no active era
+     *
+     * @note this is the figure that says whether a nomination made now takes effect this era or the
+     *   next. It is not the era's own countdown: the election closes a session before the era ends,
+     *   so it can be minutes away while the era still has hours left
+     */
+    getElectionSchedule(): Promise<ElectionSchedule>;
+    /**
+     * Retrieve when the next validator election opens and closes, and subscribe to it
+     *
+     * @param callback - called on every block, since the projections advance with each one
+     *
+     * @returns Promise that resolves to an unsubscribe function
+     *
+     * @note can be subscribed to, if connected to node using a web socket
+     */
+    getElectionSchedule(callback: SubCallback<ElectionSchedule>): Promise<UnsubCallback>;
+    /**
+     * Retrieve the current phase of the validator election
+     *
+     * @note staking transactions behave differently while an election is open, so a UI should say
+     *   when the phase is anything other than `Off`
+     */
+    getElectionPhase(): Promise<ElectionPhase>;
+    /**
+     * Retrieve the current phase of the validator election, and subscribe to it
+     *
+     * @param callback - called whenever the phase changes, which happens several times an era
+     *
+     * @returns Promise that resolves to an unsubscribe function
+     *
+     * @note this is the read that most benefits from a subscription — a warning that only appears on
+     *   the next poll appears after the user has already acted
+     * @note can be subscribed to, if connected to node using a web socket
+     */
+    getElectionPhase(callback: SubCallback<ElectionPhase>): Promise<UnsubCallback>;
+    /**
+     * @hidden
+     *
+     * Resolve an optional era argument to the era to query, defaulting to the active one
+     */
+    private asRawEra;
 }
 //# sourceMappingURL=Staking.d.ts.map

package/api/client/Staking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Staking.d.ts","sourceRoot":"","sources":["../../../src/api/client/Staking.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,OAAO,EAMR,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,aAAa,EACb,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAUjB;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;OAEG;gBACS,OAAO,EAAE,OAAO;IAuD5B;;;;OAIG;IACI,IAAI,EAAE,eAAe,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAEpD;;;;OAIG;IACI,SAAS,EAAE,eAAe,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;IAE/D;;OAEG;IACI,MAAM,EAAE,eAAe,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;IAE5D;;;;OAIG;IACI,QAAQ,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAE7C;;;;OAIG;IACI,QAAQ,EAAE,eAAe,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAEjE;;;;OAIG;IACI,aAAa,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAElD;;;;OAIG;IACI,QAAQ,EAAE,eAAe,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;IAE9D;;;;OAIG;IACU,aAAa,CACxB,cAAc,CAAC,EAAE,iBAAiB,GACjC,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAyCxC;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAE/C;;;;;;;;OAQG;IACU,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;CAkHpF"}
+{"version":3,"file":"Staking.d.ts","sourceRoot":"","sources":["../../../src/api/client/Staking.ts"],"names":[],"mappings":"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"}