Document @solana/sysvars with TypeDoc

Author: steveluscher

packages/rpc-api/src/getEpochSchedule.ts

@@ -1,7 +1,12 @@
 type GetEpochScheduleApiResponse = Readonly<{
-    /** First normal-length epoch, log2(slotsPerEpoch) - log2(MINIMUM_SLOTS_PER_EPOCH) */
+    /**
+     * First normal-length epoch after the warmup period,
+     * log2(slotsPerEpoch) - log2(MINIMUM_SLOTS_PER_EPOCH)
+     */
     firstNormalEpoch: bigint;
-    /** MINIMUM_SLOTS_PER_EPOCH * (2^(firstNormalEpoch) - 1) */
+    /**
+     * The first slot after the warmup period, MINIMUM_SLOTS_PER_EPOCH * (2^(firstNormalEpoch) - 1)
+     */
     firstNormalSlot: bigint;
     /**
      * The number of slots before beginning of an epoch to calculate a leader schedule for that

packages/sysvars/src/clock.ts

@@ -20,18 +20,30 @@ import { fetchEncodedSysvarAccount, SYSVAR_CLOCK_ADDRESS } from './sysvar';
 type SysvarClockSize = 40;
 
 /**
- * The `Clock` sysvar.
- *
- * Information about the network’s clock, ticks, slots, etc.
+ * Contains data on cluster time, including the current slot, epoch, and estimated wall-clock Unix
+ * timestamp. It is updated every slot.
  */
 export type SysvarClock = Readonly<{
+    /** The current epoch */
     epoch: Epoch;
+    /**
+     * The Unix timestamp of the first slot in this epoch.
+     *
+     * In the first slot of an epoch, this timestamp is identical to the `unixTimestamp`.
+     */
     epochStartTimestamp: UnixTimestamp;
+    /** The most recent epoch for which the leader schedule has already been generated */
     leaderScheduleEpoch: Epoch;
+    /** The current slot */
     slot: Slot;
+    /** The Unix timestamp of this slot */
     unixTimestamp: UnixTimestamp;
 }>;
 
+/**
+ * Returns an encoder that you can use to encode a {@link SysvarClock} to a byte array representing
+ * the `Clock` sysvar's account data.
+ */
 export function getSysvarClockEncoder(): FixedSizeEncoder<SysvarClock, SysvarClockSize> {
     return getStructEncoder([
         ['slot', getU64Encoder()],
@@ -42,6 +54,10 @@ export function getSysvarClockEncoder(): FixedSizeEncoder<SysvarClock, SysvarClo
     ]) as FixedSizeEncoder<SysvarClock, SysvarClockSize>;
 }
 
+/**
+ * Returns a decoder that you can use to decode a byte array representing the `Clock` sysvar's
+ * account data to a {@link SysvarClock}.
+ */
 export function getSysvarClockDecoder(): FixedSizeDecoder<SysvarClock, SysvarClockSize> {
     return getStructDecoder([
         ['slot', getU64Decoder()],
@@ -52,14 +68,18 @@ export function getSysvarClockDecoder(): FixedSizeDecoder<SysvarClock, SysvarClo
     ]) as FixedSizeDecoder<SysvarClock, SysvarClockSize>;
 }
 
+/**
+ * Returns a codec that you can use to encode from or decode to {@link SysvarClock}
+ *
+ * @see {@link getSysvarClockDecoder}
+ * @see {@link getSysvarClockEncoder}
+ */
 export function getSysvarClockCodec(): FixedSizeCodec<SysvarClock, SysvarClock, SysvarClockSize> {
     return combineCodec(getSysvarClockEncoder(), getSysvarClockDecoder());
 }
 
 /**
- * Fetch the `Clock` sysvar.
- *
- * Information about the network’s clock, ticks, slots, etc.
+ * Fetches the `Clock` sysvar account using any RPC that supports the {@link GetAccountInfoApi}.
  */
 export async function fetchSysvarClock(rpc: Rpc<GetAccountInfoApi>, config?: FetchAccountConfig): Promise<SysvarClock> {
     const account = await fetchEncodedSysvarAccount(rpc, SYSVAR_CLOCK_ADDRESS, config);

packages/sysvars/src/epoch-rewards.ts

@@ -29,28 +29,43 @@ import { fetchEncodedSysvarAccount, SYSVAR_EPOCH_REWARDS_ADDRESS } from './sysva
 type SysvarEpochRewardsSize = 81;
 
 /**
- * The `EpochRewards` sysvar.
+ * Tracks whether the rewards period (including calculation and distribution) is in progress, as
+ * well as the details needed to resume distribution when starting from a snapshot during the
+ * rewards period.
  *
- * Tracks the progress of epoch rewards distribution. It includes:
- * - Total rewards for the current epoch, in lamports.
- * - Rewards for the current epoch distributed so far, in lamports.
- * - Distribution completed block height, i.e. distribution of all staking rewards for the current
- *   epoch will be completed at this block height.
- *
- * Note that `EpochRewards` only lasts for a handful of blocks at the start of
- * an epoch. When all rewards have been distributed, the sysvar is deleted.
- * See https://github.com/anza-xyz/agave/blob/e0203f22dc83cb792fa97f91dbe6e924cbd08af1/docs/src/runtime/sysvars.md?plain=1#L155-L168
+ * The sysvar is repopulated at the start of the first block of each epoch. Therefore, the sysvar
+ * contains data about the current epoch until a new epoch begins.
  */
 export type SysvarEpochRewards = Readonly<{
+    /** Whether the rewards period (including calculation and distribution) is active */
     active: boolean;
+    /** The rewards currently distributed for the current epoch, in {@link Lamports} */
     distributedRewards: Lamports;
+    /** The starting block height of the rewards distribution in the current epoch */
     distributionStartingBlockHeight: bigint;
+    /**
+     * Number of partitions in the rewards distribution in the current epoch, used to generate an
+     * `EpochRewardsHasher`
+     */
     numPartitions: bigint;
+    /**
+     * The {@link Blockhash} of the parent block of the first block in the epoch, used to seed an
+     * `EpochRewardsHasher`
+     */
     parentBlockhash: Blockhash;
+    /**
+     * The total rewards points calculated for the current epoch, where points equals the sum of
+     * (delegated stake * credits observed) for all  delegations
+     */
     totalPoints: bigint;
+    /** The total rewards for the current epoch, in {@link Lamports} */
     totalRewards: Lamports;
 }>;
 
+/**
+ * Returns an encoder that you can use to encode a {@link SysvarEpochRewards} to a byte array
+ * representing the `EpochRewards` sysvar's account data.
+ */
 export function getSysvarEpochRewardsEncoder(): FixedSizeEncoder<SysvarEpochRewards, SysvarEpochRewardsSize> {
     return getStructEncoder([
         ['distributionStartingBlockHeight', getU64Encoder()],
@@ -63,6 +78,10 @@ export function getSysvarEpochRewardsEncoder(): FixedSizeEncoder<SysvarEpochRewa
     ]) as FixedSizeEncoder<SysvarEpochRewards, SysvarEpochRewardsSize>;
 }
 
+/**
+ * Returns a decoder that you can use to decode a byte array representing the `EpochRewards`
+ * sysvar's account data to a {@link SysvarEpochRewards}.
+ */
 export function getSysvarEpochRewardsDecoder(): FixedSizeDecoder<SysvarEpochRewards, SysvarEpochRewardsSize> {
     return getStructDecoder([
         ['distributionStartingBlockHeight', getU64Decoder()],
@@ -75,6 +94,12 @@ export function getSysvarEpochRewardsDecoder(): FixedSizeDecoder<SysvarEpochRewa
     ]) as FixedSizeDecoder<SysvarEpochRewards, SysvarEpochRewardsSize>;
 }
 
+/**
+ * Returns a codec that you can use to encode from or decode to {@link SysvarEpochRewards}
+ *
+ * @see {@link getSysvarEpochRewardsDecoder}
+ * @see {@link getSysvarEpochRewardsEncoder}
+ */
 export function getSysvarEpochRewardsCodec(): FixedSizeCodec<
     SysvarEpochRewards,
     SysvarEpochRewards,
@@ -84,17 +109,8 @@ export function getSysvarEpochRewardsCodec(): FixedSizeCodec<
 }
 
 /**
- * Fetch the `EpochRewards` sysvar.
- *
- * Tracks the progress of epoch rewards distribution. It includes:
- * - Total rewards for the current epoch, in lamports.
- * - Rewards for the current epoch distributed so far, in lamports.
- * - Distribution completed block height, i.e. distribution of all staking rewards for the current
- *   epoch will be completed at this block height.
- *
- * Note that `EpochRewards` only lasts for a handful of blocks at the start of
- * an epoch. When all rewards have been distributed, the sysvar is deleted.
- * See https://github.com/anza-xyz/agave/blob/e0203f22dc83cb792fa97f91dbe6e924cbd08af1/docs/src/runtime/sysvars.md?plain=1#L155-L168
+ * Fetch the `EpochRewards` sysvar account using any RPC that supports the
+ * {@link GetAccountInfoApi}.
  */
 export async function fetchSysvarEpochRewards(
     rpc: Rpc<GetAccountInfoApi>,

packages/sysvars/src/epoch-schedule.ts

@@ -20,18 +20,34 @@ import { fetchEncodedSysvarAccount, SYSVAR_EPOCH_SCHEDULE_ADDRESS } from './sysv
 type SysvarEpochScheduleSize = 33;
 
 /**
- * The `EpochSchedule` sysvar.
- *
- * Information about epoch duration.
+ * Includes the number of slots per epoch, timing of leader schedule selection, and information
+ * about epoch warm-up time.
  */
 export type SysvarEpochSchedule = Readonly<{
+    /**
+     * First normal-length epoch after the warmup period,
+     * log2(slotsPerEpoch) - log2(MINIMUM_SLOTS_PER_EPOCH)
+     */
     firstNormalEpoch: Epoch;
+    /**
+     * The first slot after the warmup period, MINIMUM_SLOTS_PER_EPOCH * (2^(firstNormalEpoch) - 1)
+     */
     firstNormalSlot: Slot;
+    /**
+     * A number of slots before beginning of an epoch to calculate a leader schedule for that
+     * epoch.
+     */
     leaderScheduleSlotOffset: bigint;
+    /** The maximum number of slots in each epoch */
     slotsPerEpoch: bigint;
+    /** Whether epochs start short and grow */
     warmup: boolean;
 }>;
 
+/**
+ * Returns an encoder that you can use to encode a {@link SysvarEpochSchedule} to a byte array
+ * representing the `EpochSchedule` sysvar's account data.
+ */
 export function getSysvarEpochScheduleEncoder(): FixedSizeEncoder<SysvarEpochSchedule, SysvarEpochScheduleSize> {
     return getStructEncoder([
         ['slotsPerEpoch', getU64Encoder()],
@@ -42,6 +58,10 @@ export function getSysvarEpochScheduleEncoder(): FixedSizeEncoder<SysvarEpochSch
     ]) as FixedSizeEncoder<SysvarEpochSchedule, SysvarEpochScheduleSize>;
 }
 
+/**
+ * Returns a decoder that you can use to decode a byte array representing the `EpochSchedule`
+ * sysvar's account data to a {@link SysvarEpochSchedule}.
+ */
 export function getSysvarEpochScheduleDecoder(): FixedSizeDecoder<SysvarEpochSchedule, SysvarEpochScheduleSize> {
     return getStructDecoder([
         ['slotsPerEpoch', getU64Decoder()],
@@ -52,6 +72,12 @@ export function getSysvarEpochScheduleDecoder(): FixedSizeDecoder<SysvarEpochSch
     ]) as FixedSizeDecoder<SysvarEpochSchedule, SysvarEpochScheduleSize>;
 }
 
+/**
+ * Returns a codec that you can use to encode from or decode to {@link SysvarEpochSchedule}
+ *
+ * @see {@link getSysvarEpochScheduleDecoder}
+ * @see {@link getSysvarEpochScheduleEncoder}
+ */
 export function getSysvarEpochScheduleCodec(): FixedSizeCodec<
     SysvarEpochSchedule,
     SysvarEpochSchedule,
@@ -61,9 +87,8 @@ export function getSysvarEpochScheduleCodec(): FixedSizeCodec<
 }
 
 /**
- * Fetch the `EpochSchedule` sysvar.
- *
- * Information about epoch duration.
+ * Fetches the `EpochSchedule` sysvar account using any RPC that supports the
+ * {@link GetAccountInfoApi}.
  */
 export async function fetchSysvarEpochSchedule(
     rpc: Rpc<GetAccountInfoApi>,

packages/sysvars/src/index.ts

@@ -1,3 +1,57 @@
+/**
+ * This package contains types and helpers for fetching and decoding Solana sysvars.
+ * It can be used standalone, but it is also exported as part of Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * More information about the available sysvars on Solana can be found in the docs at
+ * https://docs.solanalabs.com/runtime/sysvars.
+ *
+ * All currently available sysvars can be retrieved and/or decoded using this library.
+ *
+ * - `Clock`
+ * - `EpochRewards`
+ * - `EpochSchedule`
+ * - `Fees`
+ * - `LastRestartSlot`
+ * - `RecentBlockhashes`
+ * - `Rent`
+ * - `SlotHashes`
+ * - `SlotHistory`
+ * - `StakeHistory`
+ *
+ * The `Instructions` sysvar is also supported but does not exist on-chain, therefore has no
+ * corresponding module or codec.
+ *
+ * @example Fetch and decode a sysvar account.
+ * ```ts
+ * const clock: SysvarClock = await fetchSysvarClock(rpc);
+ * ```
+ *
+ * @example Fetch and decode a sysvar account manually.
+ * ```ts
+ * // Fetch.
+ * const clock = await fetchEncodedSysvarAccount(rpc, SYSVAR_CLOCK_ADDRESS);
+ * clock satisfies MaybeEncodedAccount<'SysvarC1ock11111111111111111111111111111111'>;
+ *
+ * // Assert.
+ * assertAccountExists(clock);
+ * clock satisfies EncodedAccount<'SysvarC1ock11111111111111111111111111111111'>;
+ *
+ * // Decode.
+ * const decodedClock = decodeAccount(clock, getSysvarClockDecoder());
+ * decodedClock satisfies Account<SysvarClock, 'SysvarC1ock11111111111111111111111111111111'>;
+ * ```
+ *
+ * @example Fetch a JSON-parsed sysvar account.
+ * ```ts
+ * const maybeJsonParsedClock = await fetchJsonParsedSysvarAccount(rpc, SYSVAR_CLOCK_ADDRESS);
+ * maybeJsonParsedClock satisfies
+ *     | MaybeAccount<JsonParsedSysvarAccount, 'SysvarC1ock11111111111111111111111111111111'>
+ *     | MaybeEncodedAccount<'SysvarC1ock11111111111111111111111111111111'>;
+ * ```
+ *
+ * @packageDocumentation
+ */
 export * from './clock';
 export * from './epoch-rewards';
 export * from './epoch-schedule';

packages/sysvars/src/last-restart-slot.ts

@@ -18,32 +18,45 @@ import { fetchEncodedSysvarAccount, SYSVAR_LAST_RESTART_SLOT_ADDRESS } from './s
 type SysvarLastRestartSlotSize = 8;
 
 /**
- * The `LastRestartSlot` sysvar.
- *
  * Information about the last restart slot (hard fork).
  *
- * The `LastRestartSlot` sysvar provides access to the last restart slot kept in the
- * bank fork for the slot on the fork that executes the current transaction.
- * In case there was no fork it returns `0`.
+ * The `LastRestartSlot` sysvar provides access to the last restart slot kept in the bank fork for
+ * the slot on the fork that executes the current transaction. In case there was no fork it returns
+ * `0`.
  */
 export type SysvarLastRestartSlot = Readonly<{
+    /** The last restart {@link Slot} */
     lastRestartSlot: Slot;
 }>;
 
+/**
+ * Returns an encoder that you can use to encode a {@link SysvarLastRestartSlot} to a byte array
+ * representing the `LastRestartSlot` sysvar's account data.
+ */
 export function getSysvarLastRestartSlotEncoder(): FixedSizeEncoder<SysvarLastRestartSlot, SysvarLastRestartSlotSize> {
     return getStructEncoder([['lastRestartSlot', getU64Encoder()]]) as FixedSizeEncoder<
         SysvarLastRestartSlot,
         SysvarLastRestartSlotSize
     >;
 }
 
+/**
+ * Returns a decoder that you can use to decode a byte array representing the `LastRestartSlot`
+ * sysvar's account data to a {@link SysvarLastRestartSlot}.
+ */
 export function getSysvarLastRestartSlotDecoder(): FixedSizeDecoder<SysvarLastRestartSlot, SysvarLastRestartSlotSize> {
     return getStructDecoder([['lastRestartSlot', getU64Decoder()]]) as FixedSizeDecoder<
         SysvarLastRestartSlot,
         SysvarLastRestartSlotSize
     >;
 }
 
+/**
+ * Returns a codec that you can use to encode from or decode to {@link SysvarLastRestartSlot}
+ *
+ * @see {@link getSysvarLastRestartSlotDecoder}
+ * @see {@link getSysvarLastRestartSlotEncoder}
+ */
 export function getSysvarLastRestartSlotCodec(): FixedSizeCodec<
     SysvarLastRestartSlot,
     SysvarLastRestartSlot,
@@ -53,13 +66,8 @@ export function getSysvarLastRestartSlotCodec(): FixedSizeCodec<
 }
 
 /**
- * Fetch the `LastRestartSlot` sysvar.
- *
- * Information about the last restart slot (hard fork).
- *
- * The `LastRestartSlot` sysvar provides access to the last restart slot kept in the
- * bank fork for the slot on the fork that executes the current transaction.
- * In case there was no fork it returns `0`.
+ * Fetches the `LastRestartSlot` sysvar account using any RPC that supports the
+ * {@link GetAccountInfoApi}.
  */
 export async function fetchSysvarLastRestartSlot(
     rpc: Rpc<GetAccountInfoApi>,