Skip to content

Validator Interface

Jump to bottom
Junha Yang(양준하) edited this page Jul 20, 2020 · 1 revision

The Coordinator provides interfaces for the Foundry host to communicate with the application state and run Tendermint engine.

Interface

initialize_chain'

WIP

execute_block

  • Signature

    fn execute_block(&mut self, header: &Header, transactions: &[Transaction], evidences: &[Evidence]) -> BlockOutcome

  • Usage

execute_block executes a block of transactions. It changes the application state and returns a BlockOutcome.

Note that the application does not write this state change to the persistent storage until Commit is called, and the state change can be reverted with a Revert call. One of Commit or Revert will be called after execute_block method.

Commit

  • Signature

    fn commit(&mut self)

  • Usage

commit is called in order to write the state changed by execute_block to the persistent storage. commit informs the application that the state transition (i.e. the corresponding block) is accepted by the consensus engine.

Revert

  • Signature

    fn revert(&mut self)

  • Usage

revert reverts state changed by execute_block into the previous state. revert informs the application that the state transition (i.e. the corresponding block) is rejected by the consensus engine. revert can be called as long as commit is not yet called.

check_transaction

  • Signature

    fn check_transaction(&mut self, transaction: &Transaction) -> bool

  • Usage

    check_transaction serves as a guard to the mempool. It is called when a transaction is entering into the mempool. The mempool will reject the transaction if check_transation returns false.

    Note that check_transaction should be lightweight enough, because all messages incoming to the mempool will be handled by the method. There is another guard method, fetch_transactions_for_block to prevent invalid transactions from being included in newly created blocks.

fetch_transactions_for_block

  • Signature

    fn fetch_transactions_for_block(&self, transactions: Vec<TransactionWithMetadata>) -> Vec<TransactionWithGas>

  • Usage

    • fetch_transactions_for_block should return transactions ordered by priority and dependency
    • A proposer uses fetch_transactions_for_block to create a block to be proposed.
    • fetch_transactions_for_block returns Vec<TransactionWithGas>. The Foundry host will create a block with the returned transactions, enforcing the gas and the size limit.

remove_transactions

  • Signature

    fn remove_transactions(&mut self, transactions: &[TransactionWithMetadata], memory_limit: Option<usize>, count_limit: Option<usize>) -> (Vec<&TransactionWithMetadata>, Vec<&TransactionWithMetadata>)

  • Input

    • transactions is the list of all transactions in the mempool
    • size is an option parameter indicating the size of the mempool
      • If this is not none, the application should suggest transactions of low priorities so that the host can remove them from the mempool
      • The size of all transactions after removing

  • Output

    • The first list is the list of invalid transactions, which should be removed from the mempool
    • The second list is the list of low priority transactions, which might be removed if the mempool is full

  • Usage

    • The Foundry host calls remove_transactions in order to discard transactions from mempool
      • When the mempool is full, it calls remove_transactions to select transactions to be evicted.
      • When the application state is changed, the host calls remove_transactions in order to find transactions that became invalid or obsolete.

Types

VoteWeight

alias of u64

Public

actual public key type used by the host

Event

  • Fields
    • key: &'static str,
    • value: Bytes

Transactions and blocks can emit events while they are being executed. Note that this field is reserved for deterministic events only, and application developers should

ValidatorInfo

  • Fields
    • weight: VoteWeight
    • pubkey: Public

ConsensusParams

WIP

Header

TxOrigin

Enum which can be Local or External. TxOrigin indicates the origin of each transaction.

Transaction

  • Fields

    • tx_type: &str,
    • body: &dyn Any

    Coordinator needs to know about the tx_type of each transaction in order to route the transaction to the appropriate module.

TransactionWithMetadata

  • Fields

    • tx: Transaction
    • origin: TxOrigin
    • inserted_block_number: u64
    • inserted_timestamp: u64
    • insertion_id: u64
      • ID assigned upon insertion to the mempool. Each transaction should have a unique insertion_id

    TransactionWithMetadata type is used as inputs of fetch_transactions_for_block method. The application uses the metadata (origin, inserted_block_number, etc) to order transactions.

TransactionWithGas

  • Fields
    • tx: Transaction
    • gas: usize

fetch_transactions_for_block returns a list of TransactionWithGas. The application will be responsible for ordering transactions, but it will be the Foundry host's responsibility to create blocks with the ordered transactions and to ensure the gas and the size limits are not exceeded.

Evidence

WIP

TransactionExecutionOutcome

  • Fields
    • is_success: bool
    • events: Vec

BlockOutcome

  • Fields

    • block_hash: BlockHash
    • updated_consensus_params: ConsensusParams
    • transaction_results: Vec
    • events: Vec

    BlockOutcome is a result returned from the application after executing a block.

Clone this wiki locally