Struct RequestPrepareProposal 

pub struct RequestPrepareProposal {

    pub max_tx_bytes: i64,
    pub txs: Vec<Vec<u8>>,
    pub local_last_commit: Option<CommitInfo>,
    pub misbehavior: Vec<Misbehavior>,
    pub height: i64,
    pub time: Option<Timestamp>,
    pub next_validators_hash: Vec<u8>,
    pub round: i32,
    pub core_chain_locked_height: u32,
    pub proposer_pro_tx_hash: Vec<u8>,
    pub proposed_app_version: u64,
    pub version: Option<Consensus>,
    pub quorum_hash: Vec<u8>,
}

Prepare new block proposal, potentially altering list of transactions.

Usage

• The first six parameters of RequestPrepareProposal are the same as RequestProcessProposal and RequestFinalizeBlock.

• The height and time values match the values from the header of the proposed block.

• RequestPrepareProposal contains a preliminary set of transactions txs that Tenderdash considers to be a good block proposal, called raw proposal. The Application can modify this set via ResponsePrepareProposal.tx_records (see TxRecord).

  • The Application can reorder, remove or add transactions to the raw proposal. Let tx be a transaction in txs:
    • If the Application considers that tx should not be proposed in this block, e.g., there are other transactions with higher priority, then it should not include it in tx_records. In this case, Tenderdash won’t remove tx from the mempool. The Application should be extra-careful, as abusing this feature may cause transactions to stay forever in the mempool.
    • If the Application considers that a tx should not be included in the proposal and removed from the mempool, then the Application should include it in tx_records and mark it as REMOVED. In this case, Tenderdash will remove tx from the mempool.
    • If the Application wants to add a new transaction, then the Application should include it in tx_records and mark it as ADD. In this case, Tenderdash will add it to the mempool.
  • The Application should be aware that removing and adding transactions may compromise traceability.

    Consider the following example: the Application transforms a client-submitted transaction t1 into a second transaction t2, i.e., the Application asks Tenderdash to remove t1 and add t2 to the mempool. If a client wants to eventually check what happened to t1, it will discover that t_1 is not in the mempool or in a committed block, getting the wrong idea that t_1 did not make it into a block. Note that t_2 will be in a committed block, but unless the Application tracks this information, no component will be aware of it. Thus, if the Application wants traceability, it is its responsability to support it. For instance, the Application could attach to a transformed transaction a list with the hashes of the transactions it derives from.

• Tenderdash MAY include a list of transactions in RequestPrepareProposal.txs whose total size in bytes exceeds RequestPrepareProposal.max_tx_bytes. Therefore, if the size of RequestPrepareProposal.txs is greater than RequestPrepareProposal.max_tx_bytes, the Application MUST make sure that the RequestPrepareProposal.max_tx_bytes limit is respected by those transaction records returned in ResponsePrepareProposal.tx_records that are marked as UNMODIFIED or ADDED.

• In same-block execution mode, the Application must provide values for ResponsePrepareProposal.app_hash, ResponsePrepareProposal.tx_results, ResponsePrepareProposal.validator_updates, ResponsePrepareProposal.core_chain_lock_update and ResponsePrepareProposal.consensus_param_updates, as a result of fully executing the block.

  • The values for ResponsePrepareProposal.validator_updates, ResponsePrepareProposal.core_chain_lock_update or ResponsePrepareProposal.consensus_param_updates may be empty. In this case, Tenderdash will keep the current values.
  • ResponsePrepareProposal.validator_updates, triggered by block H, affect validation for blocks H+1, and H+2. Heights following a validator update are affected in the following way:
    • H: NextValidatorsHash includes the new validator_updates value.
    • H+1: The validator set change takes effect and ValidatorsHash is updated.
    • H+2: local_last_commit now includes the altered validator set.
  • ResponseFinalizeBlock.consensus_param_updates returned for block H apply to the consensus params for block H+1 even if the change is agreed in block H. For more information on the consensus parameters, see the application spec entry on consensus parameters.
  • It is the responsibility of the Application to set the right value for TimeoutPropose so that the (synchronous) execution of the block does not cause other processes to prevote nil because their propose timeout goes off.

• As a result of executing the prepared proposal, the Application may produce header events or transaction events. The Application must keep those events until a block is decided and then pass them on to Tenderdash via ResponsePrepareProposal.

• As a sanity check, Tenderdash will check the returned parameters for validity if the Application modified them. In particular, ResponsePrepareProposal.tx_records will be deemed invalid if

  • There is a duplicate transaction in the list.
  • A new or modified transaction is marked as UNMODIFIED or REMOVED.
  • An unmodified transaction is marked as ADDED.
  • A transaction is marked as UNKNOWN.

• ResponsePrepareProposal.tx_results contains only results of UNMODIFIED and ADDED transactions. REMOVED transactions are omitted. The length of tx_results can be different than the length of tx_records.

• If Tenderdash fails to validate the ResponsePrepareProposal, Tenderdash will assume the application is faulty and crash.

  • The implementation of PrepareProposal can be non-deterministic.

When does Tenderdash call it?

When a validator p enters Tenderdash consensus round r, height h, in which p is the proposer, and p’s validValue is nil:

1. p’s Tenderdash collects outstanding transactions from the mempool
   • The transactions will be collected in order of priority
   • Let $C$ the list of currently collected transactions
   • The collection stops when any of the following conditions are met
     • the mempool is empty
     • the total size of transactions $\in C$ is greater than or equal to consensusParams.block.max_bytes
     • the sum of GasWanted field of transactions $\in C$ is greater than or equal to consensusParams.block.max_gas
   • p’s Tenderdash creates a block header.
2. p’s Tenderdash calls RequestPrepareProposal with the newly generated block. The call is synchronous: Tenderdash’s execution will block until the Application returns from the call.
3. The Application checks the block (hashes, transactions, commit info, misbehavior). Besides,
   • in same-block execution mode, the Application can (and should) provide ResponsePrepareProposal.app_hash, ResponsePrepareProposal.validator_updates, or ResponsePrepareProposal.consensus_param_updates.
   • the Application can manipulate transactions
     • leave transactions untouched - TxAction = UNMODIFIED
     • add new transactions directly to the proposal - TxAction = ADDED
     • remove transactions (invalid) from the proposal and from the mempool - TxAction = REMOVED
     • remove transactions from the proposal but not from the mempool (effectively delaying them) - the Application removes the transaction from the list
     • modify transactions (e.g. aggregate them) - TxAction = ADDED followed by TxAction = REMOVED. As explained above, this compromises client traceability, unless it is implemented at the Application level.
     • reorder transactions - the Application reorders transactions in the list
4. If the block is modified, the Application includes the modified block in the return parameters (see the rules in section Usage). The Application returns from the call.
5. p’s Tenderdash uses the (possibly) modified block as p’s proposal in round r, height h.

Note that, if p has a non-nil validValue, Tenderdash will use it as proposal and will not call RequestPrepareProposal.

Fields

max_tx_bytes: i64

Currently configured maximum size in bytes taken by the modified transactions. The modified transactions cannot exceed this size.

txs: Vec<Vec<u8>>

Preliminary list of transactions that have been picked as part of the block to propose. Sent to the app for possible modifications.

local_last_commit: Option<CommitInfo>

Info about the last commit, obtained locally from Tenderdash’s data structures.

misbehavior: Vec<Misbehavior>

List of information about validators that acted incorrectly.

height: i64

The height of the block that will be proposed.

time: Option<Timestamp>

Timestamp of the block that that will be proposed.

next_validators_hash: Vec<u8>

Merkle root of the next validator set.

round: i32

Round number for the block.

core_chain_locked_height: u32

Core chain lock height to be used when signing this block.

proposer_pro_tx_hash: Vec<u8>

ProTxHash of the original proposer of the block.

proposed_app_version: u64

Proposer’s latest available app protocol version.

version: Option<Consensus>

App and block version used to generate the block. App version included in the block can be modified by setting ResponsePrepareProposal.app_version.

quorum_hash: Vec<u8>

quorum_hash contains hash of validator quorum that will sign the block

Trait Implementations

impl Clone for RequestPrepareProposal

fn clone(&self) -> RequestPrepareProposal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequestPrepareProposal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RequestPrepareProposal

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RequestPrepareProposal

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<RequestPrepareProposal> for Value

fn from(value: RequestPrepareProposal) -> Self

Converts to this type from the input type.

impl Message for RequestPrepareProposal

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode(&self, buf: &mut impl BufMut) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited( &self, buf: &mut impl BufMut, ) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl PartialEq for RequestPrepareProposal

fn eq(&self, other: &RequestPrepareProposal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for RequestPrepareProposal

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RequestPrepareProposal