Application Requirements
This section specifies what Tenderdash expects from the Application. It is structured as a set of formal requirement that can be used for testing and verification of the Application's logic.
Let $p$ and $q$ be two different correct proposers in rounds $r_p$ and $r_q$ respectively, in height $h$.
Let $s_{p,h-1}$ be $p$'s Application's state committed for height $h-1$.
Let $v_p$ (resp. $v_q$) be the block that $p$'s (resp. $q$'s) Tenderdash passes on to the Application
via RequestPrepareProposal as proposer of round $r_p$ (resp $r_q$), height $h$, also known as the
raw proposal.
Let $v'_p$ (resp. $v'_q$) the possibly modified block $p$'s (resp. $q$'s) Application returns via
ResponsePrepareProposal to Tenderdash, also known as the prepared proposal.
Process $p$'s prepared proposal can differ in two different rounds where $p$ is the proposer.
- Requirement 1 [
PrepareProposal, header-changes] When the blockchain is in same-block execution mode, $p$'s Application provides values for the following parameters inResponsePrepareProposal: AppHash, TxResults, ConsensusParams, ValidatorSetUpdate. Provided values for ConsensusParams and ValidatorSetUpdate MAY be empty to denote that the Application wishes to keep the current values.
Parameters AppHash, TxResults, ConsensusParams, and ValidatorSetUpdate are used by Tenderdash to compute various hashes in the block header that will finally be part of the proposal.
In practical terms, Requirement 1 imply that Tenderdash will panic if the Application is in same-block execution mode and does not provide values for AppHash, TxResults, ConsensusParams, and ValidatorSetUpdate.
- Requirement 2 [
PrepareProposal, timeliness] If $p$'s Application fully executes prepared blocks inPrepareProposaland the network is in a synchronous period while processes $p$ and $q$ are in $r_p$, then the value of TimeoutPropose at $q$ must be such that $q$'s propose timer does not time out (which would result in $q$ prevoting nil in $r_p$).
Full execution of blocks at PrepareProposal time stands on Tenderdash's critical path. Thus,
Requirement 2 ensures the Application will set a value for TimeoutPropose such that the time it takes
to fully execute blocks in PrepareProposal does not interfere with Tenderdash's propose timer.
- Requirement 3 [
PrepareProposal, tx-size] When $p$'s Application callsResponsePrepareProposal, the total size in bytes of the transactions returned does not exceedRequestPrepareProposal.max_tx_bytes.
Busy blockchains might seek to maximize the amount of transactions included in each block. Under those conditions,
Tenderdash might choose to increase the transactions passed to the Application via RequestPrepareProposal.txs
beyond the RequestPrepareProposal.max_tx_bytes limit. The idea is that, if the Application drops some of
those transactions, it can still return a transaction list whose byte size is as close to
RequestPrepareProposal.max_tx_bytes as possible. Thus, Requirement 3 ensures that the size in bytes of the
transaction list returned by the application will never cause the resulting block to go beyond its byte limit.
- Requirement 4 [
PrepareProposal,ProcessProposal, coherence]: For any two correct processes $p$ and $q$, if $q$'s Tenderdash callsRequestProcessProposalon $v'_p$, $q$'s Application returns Accept inResponseProcessProposal.
Requirement 4 makes sure that blocks proposed by correct processes always pass the correct receiving process's
ProcessProposal check.
On the other hand, if there is a deterministic bug in PrepareProposal or ProcessProposal (or in both),
strictly speaking, this makes all processes that hit the bug byzantine. This is a problem in practice,
as very often validators are running the Application from the same codebase, so potentially all would
likely hit the bug at the same time. This would result in most (or all) processes prevoting nil, with the
serious consequences on Tenderdash's liveness that this entails. Due to its criticality, Requirement 4 is a
target for extensive testing and automated verification.
-
Requirement 5 [
ProcessProposal, determinism-1]:ProcessProposalis a (deterministic) function of the current state and the block that is about to be applied. In other words, for any correct process $p$, and any arbitrary block $v'$, if $p$'s Tenderdash callsRequestProcessProposalon $v'$ at height $h$, then $p$'s Application's acceptance or rejection exclusively depends on $v'$ and $s_{p,h-1}$. -
Requirement 6 [
ProcessProposal, determinism-2]: For any two correct processes $p$ and $q$, and any arbitrary block $v'$, if $p$'s (resp. $q$'s) Tenderdash callsRequestProcessProposalon $v'$ at height $h$, then $p$'s Application accepts $v'$ if and only if $q$'s Application accepts $v'$. Note that this requirement follows from Requirement 5 and the Agreement property of consensus.
Requirements 5 and 6 ensure that all correct processes will react in the same way to a proposed block, even
if the proposer is Byzantine. However, ProcessProposal may contain a bug that renders the
acceptance or rejection of the block non-deterministic, and therefore prevents processes hitting
the bug from fulfilling Requirements 5 or 6 (effectively making those processes Byzantine).
In such a scenario, Tenderdash's liveness cannot be guaranteed.
Again, this is a problem in practice if most validators are running the same software, as they are likely
to hit the bug at the same point. There is currently no clear solution to help with this situation, so
the Application designers/implementors must proceed very carefully with the logic/implementation
of ProcessProposal. As a general rule ProcessProposal should always accept the block.
A correct validator broadcasts at most one precommit per height and round.
ExtendVote can also run after a rejected commit to discover the expected vector,
including on an observer. Applications must support repeated calls and return the
same threshold-recoverable subset for the same block, round and committed state.
See expected call sequences.
Let $e^r_p$ be the set of vote extensions that the Application of a correct process $p$ returns via ResponseExtendVote in round $r$, height $h$.
Let $w^r_p$ be the proposed block that $p$'s Tenderdash passes to the Application via RequestExtendVote in round $r$, height $h$.
- Requirement 7 [
ExtendVote,VerifyVoteExtension, coherence]: For any two correct processes $p$ and $q$, if $q$ receives $e^r_p$ from $p$ in height $h$, $q$'s Application returns Accept inResponseVerifyVoteExtension.
Requirement 7 constrains the creation and handling of vote extensions in a similar way as Requirement 4
contrains the creation and handling of proposed blocks.
Requirement 7 ensures that extensions created by correct processes always pass the VerifyVoteExtension
checks performed by correct processes receiving those extensions.
However, if there is a (deterministic) bug in ExtendVote or VerifyVoteExtension (or in both),
we will face the same liveness issues as described for Requirement 4, as Precommit messages with invalid vote
extensions will be discarded.
-
Requirement 8 [
VerifyVoteExtension, determinism-1]:VerifyVoteExtensionis a (deterministic) function of the current state, the vote extensions received, and the prepared proposal that the extensions refers to. In other words, for any correct process $p$, and any arbitrary vote extension $e$, and any arbitrary block $w$, if $p$'s (resp. $q$'s) Tenderdash callsRequestVerifyVoteExtensionon $e$ and $w$ at height $h$, then $p$'s Application's acceptance or rejection exclusively depends on $e$, $w$ and $s_{p,h-1}$. -
Requirement 9 [
VerifyVoteExtension, determinism-2]: For any two correct processes $p$ and $q$, and any arbitrary vote extensions $e$, and any arbitrary block $w$, if $p$'s (resp. $q$'s) Tenderdash callsRequestVerifyVoteExtensionon $e$ and $w$ at height $h$, then $p$'s Application accepts $e$ if and only if $q$'s Application accepts $e$. Note that this requirement follows from Requirement 8 and the Agreement property of consensus.
Requirements 8 and 9 ensure that the validation of vote extensions will be deterministic at all
correct processes.
Requirements 8 and 9 protect against arbitrary vote extensions data from Byzantine processes
similarly to Requirements 5 and 6 and proposed blocks.
Requirements 8 and 9 can be violated by a bug inducing non-determinism in
VerifyVoteExtension. In this case liveness can be compromised.
Extra care should be put in the implementation of ExtendVote and VerifyVoteExtension and,
as a general rule, VerifyVoteExtension should always accept the vote extensions of a precommit.
Commit verification, a call with an empty validator_pro_tx_hash, is the exception: the Application
must reject a commit whose extension vector differs from the threshold-recoverable subset of the
extensions it expects for the block, or an altered vector reaches FinalizeBlock. Threshold recovery
requires the contributing validators to sign identical extension content, so a valid recovered extension
from correct processes matches that expected vector. Rejecting an altered vector therefore costs no
liveness; a deterministic bug in the check, however, halts the chain, because no commit
for the block can pass it. See VerifyVoteExtension for what
Tenderdash does on each path when a commit is rejected.
-
Requirement 10 [all, no-side-effects]: $p$'s calls to
RequestPrepareProposal,RequestProcessProposal,RequestExtendVote, andRequestVerifyVoteExtensionat height $h$ do not modify $s_{p,h-1}$. -
Requirement 11 [
ExtendVote,FinalizeBlock, non-dependency]: for any correct process $p$, and any vote extensions $e$ that $p$ received at height $h$, the computation of $s_{p,h}$ does not depend on $e$.
The call to correct process $p$'s RequestFinalizeBlock at height $h$, with block $v_{p,h}$
passed as parameter, creates state $s_{p,h}$.
PrepareProposal and ProcessProposal compute the transaction results $T_{p,h}$
for the current block before consensus decides it. FinalizeBlock persists the
selected candidate and returns no transaction results.
-
Requirement 12 [
FinalizeBlock, determinism-1]: For any correct process $p$, $s_{p,h}$ exclusively depends on $s_{p,h-1}$ and $v_{p,h}$. -
Requirement 13 [
FinalizeBlock, determinism-2]: For any correct process $p$, the contents of $T_{p,h}$ exclusively depend on $s_{p,h-1}$ and $v_{p,h}$.
Note that Requirements 12 and 13, combined with Agreement property of consensus ensure the Application state evolves consistently at all correct processes.
Finally, notice that neither PrepareProposal nor ExtendVote have determinism-related
requirements associated.
Indeed, PrepareProposal is not required to be deterministic:
- $v'p$ may depend on $v_p$ and $s{p,h-1}$, but may also depend on other values or operations.
- $v_p = v_q \nRightarrow v'_p = v'_q$.
Likewise, ExtendVote can also be non-deterministic:
- $e^r_p$ may depend on $w^r_p$ and $s_{p,h-1}$, but may also depend on other values or operations.
- $w^r_p = w^r_q \nRightarrow e^r_p = e^r_q$
In Tenderdash this freedom holds for extensions that are not threshold-recoverable, and does not
extend to threshold-recoverable ones (THRESHOLD_RECOVER and THRESHOLD_RECOVER_RAW): they are
recovered into the commit, so every validator must produce the same ones. ExtendVote must also be
free of side effects, and the threshold-recoverable subset of its response must be exactly the vector
the Application accepts in a commit-level VerifyVoteExtension for the same block, height and round:
after such a VerifyVoteExtension rejects a commit, following ProcessProposal of that block and
round, Tenderdash calls ExtendVote on any node to learn that vector (see
VerifyVoteExtension).
Connections
Tenderdash uses one application client for consensus, mempool, query and state-sync calls. Its transport determines concurrency: the reference socket server processes one connection sequentially, while gRPC can execute calls concurrently over one connection. Explicitly configured routed clients may use multiple underlying connections. Local clients call the application directly.
Applications MUST synchronize state shared by concurrent calls, including calls on different methods or connections. Waiting for one response does not block other callers. Queries must read committed state. See Client and Server for transport ordering and gRPC concurrency settings.