Skip to main content
⚠️ This is the beta version of the Sui GraphQL schema. The beta schema will replace the alpha GraphQL schema upon its official release.

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 {
  epochId: UInt53!
  coinDenyList: Object
  protocolConfigs: ProtocolConfigs
  referenceGasPrice: BigInt
  startTimestamp: DateTime
  transactions(
    first: Int
    after: String
    last: Int
    before: String
    filter: TransactionFilter
  ): TransactionConnection
  systemPackages(
    first: Int
    after: String
    last: Int
    before: String
  ): MovePackageConnection
  endTimestamp: DateTime
  validatorSet: ValidatorSet
  totalCheckpoints: UInt53
  totalTransactions: UInt53
  totalGasFees: BigInt
  totalStakeRewards: BigInt
  totalStakeSubsidies: BigInt
  fundSize: BigInt
  netInflow: BigInt
  fundInflow: BigInt
  fundOutflow: BigInt
  storageFund: StorageFund
  safeMode: SafeMode
  systemStateVersion: UInt53
  systemParameters: SystemParameters
  systemStakeSubsidy: StakeSubsidy
  liveObjectSetDigest: String
}

Fields​

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.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.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.startTimestamp ● DateTime scalar​

The timestamp associated with the first checkpoint in the epoch.

Epoch.transactions ● TransactionConnection object​

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

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.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.endTimestamp ● DateTime scalar​

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

Epoch.validatorSet ● ValidatorSet object​

Validator-related properties, including the active validators.

Epoch.totalCheckpoints ● UInt53 scalar​

The total number of checkpoints in this epoch.

Epoch.totalTransactions ● UInt53 scalar​

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

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.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.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.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.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.safeMode ● SafeMode object​

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

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.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.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.

Returned By​

epoch query ● multiGetEpochs query

Member Of​

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