epoch.rs

Overview

This file is responsible for handling the encoding, decoding, and message creation related to epoch and preepoch data structures within the system managed by the BlockKeeper module. It primarily interacts with blockchain account data to decode stored epoch-related information and provides utilities to create specific messages used in the epoch lifecycle.

The key functionalities include:

• Decoding epoch and preepoch data from blockchain account storage using ABI specifications.

• Constructing outbound messages for epoch interaction (e.g., "touch" message to update epoch status).

• Managing and interpreting various tokens related to epoch state such as BLS public keys, stakes, addresses, and signer indices.

The file relies on ABI definitions (EPOCH_ABI and PREEPOCH_ABI) and various blockchain-related types and traits for parsing and encoding data.

Constants

Functions

get_epoch_abi() -> tvm_client::abi::Abi

Returns the ABI object for the epoch smart contract interface by wrapping the EPOCH_ABI JSON string.

Usage

let epoch_abi = get_epoch_abi();

get_preepoch_abi() -> tvm_client::abi::Abi

Returns the ABI object for the preepoch smart contract interface by wrapping the PREEPOCH_ABI JSON string.

Usage

let preepoch_abi = get_preepoch_abi();

decode_epoch_data(account: &Account) -> anyhow::Result<Option<(SignerIndex, BlockKeeperData)>>

Decodes epoch data from a blockchain Account object.

• Parameters:

  • account: Reference to the blockchain Account containing epoch data.

• Returns:

  • Ok(Some((SignerIndex, BlockKeeperData))) if decoding succeeds and all required tokens are found.

  • Ok(None) if the account has no epoch data or required tokens are missing.

  • Err if any failure occurs during ABI loading or decoding.

Behavior

• Uses the epoch ABI to decode the account's storage fields.

• Extracts tokens such as BLS public key, epoch finish sequence number, wait step, stake, owner address, signer index, and owner public key.

• Converts and maps these tokens into a BlockKeeperData struct and returns it along with the signer index.

• The epoch finish token is used to determine if the epoch is finished or ongoing.

Example

let epoch_data = decode_epoch_data(&account)?;
if let Some((signer_idx, block_keeper_data)) = epoch_data {
    // Use block_keeper_data and signer_idx
}

decode_preepoch_data(account: &Account) -> anyhow::Result<Option<(SignerIndex, BlockKeeperData)>>

Decodes preepoch data from a blockchain Account object.

• Parameters:

  • account: Reference to the blockchain Account containing preepoch data.

• Returns:

  • Ok(Some((SignerIndex, BlockKeeperData))) if decoding succeeds with all required tokens.

  • Ok(None) if data is missing or incomplete.

  • Err if ABI loading or decoding fails.

Behavior

• Uses preepoch ABI to decode storage fields from the account.

• Extracts tokens for BLS public key, stake, wait step, wallet address, signer index, and owner public key.

• Constructs a BlockKeeperData object reflecting preepoch status.

• The epoch_finish_seq_no is set to None as it does not apply to preepoch.

Example

let preepoch_data = decode_preepoch_data(&account)?;
if let Some((signer_idx, block_keeper_data)) = preepoch_data {
    // Use block_keeper_data and signer_idx for preepoch logic
}

create_epoch_touch_message(data: &BlockKeeperData, time: u32) -> anyhow::Result<Message>

Creates an external inbound message to "touch" (update) an epoch contract.

• Parameters:

  • data: A reference to BlockKeeperData containing epoch contract information.

  • time: The current time as a 32-bit integer, used to calculate message expiration.

• Returns:

  • A Message object ready for dispatch.

  • Err if message creation fails at any step.

Behavior

• Sets an expiration time 5 units after the provided time.

• Encodes the "touch" function call using the epoch ABI with an expiration parameter.

• Constructs an ExternalInboundMessageHeader targeting the epoch contract address.

• Wraps the message body into a SliceData format.

• Returns the constructed message for sending to the blockchain.

Example

let touch_msg = create_epoch_touch_message(&block_keeper_data, current_time)?;

Implementation Details and Algorithms

• ABI Decoding: Uses the ABI JSON definitions to parse on-chain contract storage fields. The decoding relies on the tvm_client::abi module's capability to translate raw cell data into structured tokens.

• Token Mapping: The decoded tokens are iterated, and values are extracted based on their names matching predefined keys. Conversion from token types (TokenValue::Bytes, TokenValue::Uint, TokenValue::Address) to corresponding Rust types is performed carefully with zero-value checks.

• BigUint Handling: Stake values are represented as BigUint to support arbitrarily large numbers.

• Address Extraction: Wallet addresses are extracted from MsgAddress::AddrStd variants, ignoring other address types.

• Signer Index: Stored as a 32-bit SignerIndex type and converted from Uint token values.

• Error Propagation: The anyhow crate is used to propagate errors with descriptive messages.

• Tracing: Uses the tracing crate to log detailed debug information during decoding for troubleshooting.

Interaction with Other Modules

• BlockKeeperData and BlockKeeperStatus (in block_keeper_system): This file creates and returns instances of BlockKeeperData with associated status (Active or PreEpoch).

• BLS Public Key (gosh_bls::PubKey): Parses BLS public keys from token bytes for cryptographic identity.

• tvm_block and tvm_types: Utilizes blockchain data types such as Account, Message, MsgAddress, and UInt256 for interaction with the underlying blockchain data structures.

• tvm_client::abi: For ABI parsing and encoding function calls.

• SignerIndex (from node module): Represents the index of the signer for the epoch or preepoch.

• Encoding utilities: Uses tvm_abi::encode_function_call to create message bodies for blockchain interactions.

Data Structures

BlockKeeperData

A struct representing the state of an epoch or preepoch keeper. It contains:

• pubkey: BLS public key (PubKey)

• epoch_finish_seq_no: Optional sequence number of epoch finish (Option<u64>)

• wait_step: A wait step indicator (u64)

• status: Status of the block keeper (BlockKeeperStatus)

• address: Contract address as a string

• stake: Stake amount (BigUint)

• owner_address: Owner account identifier (AccountId)

• signer_index: Signer index (SignerIndex)

• owner_pubkey: Owner public key (UInt256)

Visual Diagram: File Structure and Function Relationships

flowchart TD
A[Account] -->|get_data()| B[decode_epoch_data]
A -->|get_data()| C[decode_preepoch_data]
B --> D[BlockKeeperData + SignerIndex]
C --> D
D --> E[create_epoch_touch_message]
E --> F[Message]
subgraph ABI
G["get_epoch_abi()"]
H["get_preepoch_abi()"]
end
B -.-> G
C -.-> H
E -.-> G

• decode_epoch_data and decode_preepoch_data both operate on Account data, decode via respective ABIs, and produce BlockKeeperData.

• create_epoch_touch_message consumes BlockKeeperData and constructs a Message.

• ABI retrieval functions provide the necessary ABI for encoding/decoding.

Usage Notes

• These decoding functions are typically used when processing account states to monitor or manage epoch-related blockchain contracts.

• The message creation function is used when constructing outbound messages to interact with epoch contracts, e.g., to update or "touch" the epoch state.

• Error handling is critical; all decoding steps return detailed errors on failure.

• The file assumes that the ABI JSON strings EPOCH_ABI and PREEPOCH_ABI are correctly defined and available via imports.

For more on blockchain data types, ABI encoding/decoding, and message handling, see Blockchain Account Management and ABI Encoding and Decoding. For details on BLS cryptography, refer to BLS Cryptography.