Epoch

Activity on Sui is partitioned in time, into epochs.

Epoch changes are opportunities for the network to reconfigure itself (perform protocol or system package upgrades, or change the committee) and distribute staking rewards. The network aims to keep epochs roughly the same duration as each other.

During a particular epoch the following data is fixed:

• protocol version,
• reference gas price,
• system package versions,
• validators in the committee.

type Epoch {
  checkpoints(
    first: Int
    after: String
    last: Int
    before: String
    filter: CheckpointFilter
  ): CheckpointConnection
  coinDenyList: Object
  endTimestamp: DateTime
  epochId: UInt53!
  fundInflow: BigInt
  fundOutflow: BigInt
  fundSize: BigInt
  liveObjectSetDigest: String
  netInflow: BigInt
  protocolConfigs: ProtocolConfigs
  referenceGasPrice: BigInt
  safeMode: SafeMode
  startTimestamp: DateTime
  storageFund: StorageFund
  systemPackages(
    first: Int
    after: String
    last: Int
    before: String
  ): MovePackageConnection
  systemParameters: SystemParameters
  systemStakeSubsidy: StakeSubsidy
  systemStateVersion: UInt53
  totalCheckpoints: UInt53
  totalGasFees: BigInt
  totalStakeRewards: BigInt
  totalStakeSubsidies: BigInt
  totalTransactions: UInt53
  transactions(
    first: Int
    after: String
    last: Int
    before: String
    filter: TransactionFilter
  ): TransactionConnection
  validatorSet: ValidatorSet
}

Fields

Epoch.checkpoints ● CheckpointConnection object

The epoch's corresponding checkpoints.

Epoch.checkpoints.first ● Int scalar

Epoch.checkpoints.after ● String scalar

Epoch.checkpoints.last ● Int scalar

Epoch.checkpoints.before ● String scalar

Epoch.checkpoints.filter ● CheckpointFilter input

Epoch.coinDenyList ● Object object

State of the Coin DenyList object (0x403) at the start of this epoch.

The DenyList controls access to Regulated Coins. Writes to the DenyList are accumulated and only take effect on the next epoch boundary. Consequently, it's possible to determine the state of the DenyList for a transaction by reading it at the start of the epoch the transaction is in.

Epoch.endTimestamp ● DateTime scalar

The timestamp associated with the last checkpoint in the epoch (or null if the epoch has not finished yet).

Epoch.epochId ● UInt53! non-null scalar

The epoch's id as a sequence number that starts at 0 and is incremented by one at every epoch change.

Epoch.fundInflow ● BigInt scalar

The storage fees paid for transactions executed during the epoch (or null if the epoch has not finished yet).

Epoch.fundOutflow ● BigInt scalar

The storage fee rebates paid to users who deleted the data associated with past transactions (or null if the epoch has not finished yet).

Epoch.fundSize ● BigInt scalar

The storage fund available in this epoch (or null if the epoch has not finished yet). This fund is used to redistribute storage fees from past transactions to future validators.

Epoch.liveObjectSetDigest ● String scalar

A commitment by the committee at the end of epoch on the contents of the live object set at that time. This can be used to verify state snapshots.

Epoch.netInflow ● BigInt scalar

The difference between the fund inflow and outflow, representing the net amount of storage fees accumulated in this epoch (or null if the epoch has not finished yet).

Epoch.protocolConfigs ● ProtocolConfigs object

The epoch's corresponding protocol configuration, including the feature flags and the configuration options.

Epoch.referenceGasPrice ● BigInt scalar

The minimum gas price that a quorum of validators are guaranteed to sign a transaction for in this epoch.

Epoch.safeMode ● SafeMode object

Information about whether this epoch was started in safe mode, which happens if the full epoch change logic fails.

Epoch.startTimestamp ● DateTime scalar

The timestamp associated with the first checkpoint in the epoch.

Epoch.storageFund ● StorageFund object

SUI set aside to account for objects stored on-chain, at the start of the epoch. This is also used for storage rebates.

Epoch.systemPackages ● MovePackageConnection object

The system packages used by all transactions in this epoch.

Epoch.systemPackages.first ● Int scalar

Epoch.systemPackages.after ● String scalar

Epoch.systemPackages.last ● Int scalar

Epoch.systemPackages.before ● String scalar

Epoch.systemParameters ● SystemParameters object

Details of the system that are decided during genesis.

Epoch.systemStakeSubsidy ● StakeSubsidy object

Parameters related to the subsidy that supplements staking rewards

Epoch.systemStateVersion ● UInt53 scalar

The value of the version field of 0x5, the 0x3::sui::SuiSystemState object. This version changes whenever the fields contained in the system state object (held in a dynamic field attached to 0x5) change.

Epoch.totalCheckpoints ● UInt53 scalar

The total number of checkpoints in this epoch.

Returns None when no checkpoint is set in scope (e.g. execution scope).

Epoch.totalGasFees ● BigInt scalar

The total amount of gas fees (in MIST) that were paid in this epoch (or null if the epoch has not finished yet).

Epoch.totalStakeRewards ● BigInt scalar

The total MIST rewarded as stake (or null if the epoch has not finished yet).

Epoch.totalStakeSubsidies ● BigInt scalar

The amount added to total gas fees to make up the total stake rewards (or null if the epoch has not finished yet).

Epoch.totalTransactions ● UInt53 scalar

The total number of transaction blocks in this epoch (or null if the epoch has not finished yet).

Epoch.transactions ● TransactionConnection object

The transactions in this epoch, optionally filtered by transaction filters.

Returns None when no checkpoint is set in scope (e.g. execution scope).

Epoch.transactions.first ● Int scalar

Epoch.transactions.after ● String scalar

Epoch.transactions.last ● Int scalar

Epoch.transactions.before ● String scalar

Epoch.transactions.filter ● TransactionFilter input

Epoch.validatorSet ● ValidatorSet object

Validator-related properties, including the active validators.

Returned By

epoch query ● multiGetEpochs query

Member Of

ActiveJwk object ● AuthenticatorStateExpireTransaction object ● AuthenticatorStateUpdateTransaction object ● ChangeEpochTransaction object ● Checkpoint object ● ConsensusCommitPrologueTransaction object ● EpochConnection object ● EpochEdge object ● Transaction object ● TransactionEffects object ● ValidatorAggregatedSignature object