LightClientV2

LightClient V2: with stake table snapshot update during epoch change.

State Variables

blocksPerEpoch

number of blocks per epoch

uint64 public blocksPerEpoch

epochStartBlock

the block height when Epoch-related logic gets activated

uint64 public epochStartBlock

firstEpoch

the first epoch where dynamic stake table is activated, not the numerical value epoch=1

uint64 private firstEpoch

votingStakeTableState

stake table commitments for the current voting stakers

StakeTableState public votingStakeTableState

Functions

initializeV2

Initialize V2

function initializeV2(uint64 _blocksPerEpoch, uint64 _epochStartBlock)
    public
    onlyOwner
    reinitializer(2);

getVersion

function getVersion()
    public
    pure
    virtual
    override
    returns (uint8 majorVersion, uint8 minorVersion, uint8 patchVersion);

newFinalizedState

override the V1’s to disable calling it

function newFinalizedState(LightClientState memory, IPlonkVerifier.PlonkProof memory)
    external
    pure
    override;

setStateHistoryRetentionPeriod

identical as LightClientV1’s setstateHistoryRetentionPeriod() but this function name has the correct camelCase

function setStateHistoryRetentionPeriod(uint32 historySeconds) public virtual onlyOwner;

updateEpochStartBlock

function updateEpochStartBlock(uint64 newEpochStartBlock) public virtual onlyOwner;

newFinalizedState

See detailed doc in LightClient.sol

function newFinalizedState(
    LightClientState memory newState,
    StakeTableState memory nextStakeTable,
    IPlonkVerifier.PlonkProof memory proof
) external virtual;

Parameters

Name	Type	Description
`newState`	`LightClientState`
`nextStakeTable`	`StakeTableState`	the stake table to use in the next block (same as the current except
`proof`	`IPlonkVerifier.PlonkProof`

_getVk

function _getVk() public pure virtual override returns (IPlonkVerifier.VerifyingKey memory vk);

verifyProof

compare to V1, we extend public input length from 7 to 11, use a newly generated VK, and enforce correct usage of the nextStakeTable outside the epoch change period.

function verifyProof(
    LightClientState memory state,
    StakeTableState memory nextStakeTable,
    IPlonkVerifier.PlonkProof memory proof
) internal virtual;

currentEpoch

Returns the current epoch according the latest update on finalizedState

function currentEpoch() public view virtual returns (uint64);

Returns

Name	Type	Description
`<none>`	`uint64`	current epoch (computed from the last known hotshot block number)

epochFromBlockNumber

Calculate the epoch number from the hotshot block number

same logic as hotshot_types::utils::epoch_from_block_number()

function epochFromBlockNumber(uint64 _blockNum, uint64 _blocksPerEpoch)
    public
    pure
    virtual
    returns (uint64);

isEpochRoot

Decide if a block height is the an “epoch root” (defined as last block in epoch - 5)

see https://github.com/EspressoSystems/espresso-network/blob/2a904fa17838961cef130d0e87d7b371acaaea42/hotshot-types/src/utils.rs#L475

function isEpochRoot(uint64 blockHeight) public view virtual returns (bool);

isGtEpochRoot

Returns true if the given block number is greater than the epoch root block

function isGtEpochRoot(uint64 blockHeight) public view virtual returns (bool);

Events

NewEpoch

When entering a new epoch and a new stake table snapshot.

event NewEpoch(uint64 epoch);

Errors

MissingEpochRootUpdate

The finalized state for the epoch root of every epoch should NOT be skipped

error MissingEpochRootUpdate();

DeprecatedApi

Invocation on outdated APIs on V1

error DeprecatedApi();

Keyboard shortcuts