The commitment metric aims to give clients a measure of the network confirmation and stake levels on a particular block. Clients can then use this information to derive their own measures of commitment.
Clients can request commitment metrics from a validator for a signature
get_block_commitment(s: Signature) -> BlockCommitment over RPC. The
BlockCommitment struct contains an array of u64
[u64, MAX_CONFIRMATIONS]. This
array represents the commitment metric for the particular block
contains the signature
s as of the last block
M that the validator voted on.
s at index
i in the
BlockCommitment array implies that the
s total stake in the cluster reaching
i confirmations on
N as observed in some block
M. There will be
MAX_CONFIRMATIONS elements in
this array, representing all the possible number of confirmations from 1 to
BlockCommitment struct leverages the computations already being
performed for building consensus. The
collect_vote_lockouts function in
consensus.rs builds a HashMap, where each entry is of the form
s is the amount of stake on a bank
This computation is performed on a votable candidate bank
b as follows.
f is some accumulation function that modifies the
a with some data derivable from vote
(stake, lockout, etc.). Note here that the
ancestors here only includes
slots that are present in the current status cache. Signatures for banks earlier
than those present in the status cache would not be queryable anyway, so those
banks are not included in the commitment calculations here.
Now we can naturally augment the above computation to also build a
BlockCommitment array for every bank
- Adding a
ForkCommitmentCacheto collect the
f'such that the above computation also builds this
BlockCommitmentfor every bank
We will proceed with the details of 2) as 1) is trivial.
Before continuing, it is noteworthy that for some validator's vote account
the number of local confirmations for that validator on slot
v is the smallest vote in the stack of votes
a.votes such that
v.slot >= s (i.e. there is no need to look at any
votes > v as the number of confirmations will be lower).
Now more specifically, we augment the above computation to:
f' is defined as: