github.com/MetalBlockchain/metalgo@v1.11.9/vms/platformvm/docs/block_formation_logic.md

github.com/MetalBlockchain/metalgo@v1.11.9/vms/platformvm/docs/block_formation_logic.md (about)

1 # Block Composition and Formation Logic
2
3 AvalancheGo v1.9.0 (Banff) slightly changes the way the P-chain selects transactions to be included in next block and deals with block timestamps. In this brief document we detail the process and the changes.
4
5 ## Apricot
6
7 ### Apricot Block Content
8
9 Apricot allows the following block types with the following content:
10
11 - _Standard Blocks_ may contain multiple transactions of the following types:
12 - CreateChainTx
13 - CreateSubnetTx
14 - ImportTx
15 - ExportTx
16 - _Proposal Blocks_ may contain a single transaction of the following types:
17 - AddValidatorTx
18 - AddDelegatorTx
19 - AddSubnetValidatorTx
20 - RewardValidatorTx
21 - AdvanceTimeTx
22 - _Options Blocks_, i.e. _Commit Block_ and _Abort Block_ do not contain any transactions.
23
24 Note that _Atomic Blocks_ were disallowed in the Apricot phase 5 upgrade. They used to contain ImportTx and ExportTx which are now included into Standard Blocks.
25
26 Each block has a header containing:
27
28 - ParentID
29 - Height
30
31 Note that Apricot block headers do not contain any block timestamp.
32
33 ### Apricot Block Formation Logic
34
35 Transactions included in an Apricot block can originate from the mempool or can be created just in time to duly update the staker set. Block formation logic in the Apricot upgrade can be broken up into two high-level steps:
36
37 - First, we try selecting any candidate decision or proposal transactions which could be included in a block _without advancing the current chain time_;
38 - If no such transactions are found, we evaluate candidate transactions which _may require advancing chain time_. If a chain time advancement is required to include these transactions in a block, a proposal block with an advance time transaction is built first; selected transactions may be included in a subsequent block.
39
40 In more detail, blocks which do not change chain time are built as follows:
41
42 1. If mempool contains any decision transactions, a Standard Block is issued with all of the transactions the default block size can accommodate. Note that Apricot Standard Blocks do not change the current chain time.
43 2. If the current chain time matches any staker's staking ending time, a reward transaction is issued into a Proposal Block to initiate network voting on whether the specified staker should be rewarded. Note that there could be multiple stakers ending their staking period at the same chain time, hence a Proposal Block must be issued for all of them before the chain time is moved ahead. Any attempt to move chain time ahead before rewarding all stakers would fail block verification.
44
45 While the above steps could be executed in any order, we pick decisions transactions first to maximize throughput.
46
47 Once all possibilities of create a block not advancing chain time are exhausted, we attempt to build a block which _may_ advance chain time as follows:
48
49 1. If the local clock's time is greater than or equal to the earliest change-event timestamp of the staker set, an advance time transaction is issued into a Proposal Block to move current chain time to the earliest change timestamp of the staker set. Upon this Proposal Block's acceptance, chain time will be moved ahead and all scheduled changes (e.g. promoting a staker from pending to current) will be carried out.
50 2. If the mempool contains any proposal transactions, the mempool proposal transaction with the earliest start time is selected and included into a Proposal Block[^1]. A mempool proposal transaction as is won't change the current chain time[^2]. However there is an edge case to consider: on low activity chains (e.g. Fuji P-chain) chain time may fall significantly behind the local clock. If a proposal transaction is finally issued, its start time is likely to be quite far in the future relative to the current chain time. This would cause the proposal transaction to be considered invalid and rejected, since a staker added by a proposal transaction's start time must be at most 366 hours (two weeks) after current chain time. To avoid this edge case on low-activity chains, an advance time transaction is issued first to move chain time to the local clock's time. As soon as chain time is advanced, the mempool proposal transaction will be issued and accepted.
51
52 Note that the order in which these steps are executed matters. A block updating chain time would be deemed invalid if it would advance time beyond the staker set's next change event, skipping the associated changes. The order above ensures this never happens because it checks first if chain time should be moved to the time of the next staker set change. It can also be verified by inspection that the timestamp selected for the advance time transactions always respect the synchrony bound.
53
54 Block formation terminates as soon as any of the steps executed manage to select transactions to be included into a block. Otherwise, an error is raised to signal that there are no transactions to be issued. Finally a timer is kicked off to schedule the next block formation attempt.
55
56 ## Banff
57
58 ### Banff Block Content
59
60 Banff allows the following block types with the following content:
61
62 - _Standard Blocks_ may contain multiple transactions of the following types:
63 - CreateChainTx
64 - CreateSubnetTx
65 - ImportTx
66 - ExportTx
67 - AddValidatorTx
68 - AddDelegatorTx
69 - AddSubnetValidatorTx
70 - RemoveSubnetValidatorTx
71 - TransformSubnetTx
72 - AddPermissionlessValidatorTx
73 - AddPermissionlessDelegatorTx
74 - _Proposal Blocks_ may contain a single transaction of the following types:
75 - RewardValidatorTx
76 - _Options blocks_, i.e. _Commit Block_ and _Abort Block_ do not contain any transactions.
77
78 Note that each block has a header containing:
79
80 - ParentID
81 - Height
82 - Time
83
84 So the main differences with respect to Apricot are:
85
86 - _AddValidatorTx_, _AddDelegatorTx_, _AddSubnetValidatorTx_ are included into Standard Blocks rather than Proposal Blocks so that they don't need to be voted on (i.e. followed by a Commit/Abort Block).
87 - New Transaction types: _RemoveSubnetValidatorTx_, _TransformSubnetTx_, _AddPermissionlessValidatorTx_, _AddPermissionlessDelegatorTx_ have been added into Standard Blocks.
88 - Block timestamp is explicitly serialized into block header, to allow chain time update.
89
90 ### Banff Block Formation Logic
91
92 The activation of the Banff upgrade only makes minor changes to the way the P-chain selects transactions to be included in next block, such as block timestamp calculation. Below are the details of changes.
93
94 Operations are carried out in the following order:
95
96 - We try to move chain time ahead to the current local time or the earliest staker set change event. Unlike Apricot, here we issue either a Standard Block or a Proposal Block to advance the time.
97 - We check if any staker needs to be rewarded, issuing as many Proposal Blocks as needed, as above.
98 - We try to fill a Standard Block with mempool decision transactions.
99
100 [^1]: Proposal transactions whose start time is too close to local time are dropped first and won't be included in any block.
101 [^2]: Advance time transactions are proposal transactions and they do change chain time. But advance time transactions are generated just in time and never stored in the mempool. Here mempool proposal transactions refer to AddValidator, AddDelegator and AddSubnetValidator transactions. Reward validator transactions are proposal transactions which do not change chain time but which never in mempool (they are generated just in time).