[WIP] first bits for header validation

Author: larskuhtz

src/Chainweb/BlockHeader/Validation.hs

@@ -315,6 +315,8 @@ instance Show ValidationFailure where
             InvalidFeatureFlags -> "The block has an invalid feature flag value"
             InvalidBraiding -> "The block is not braided correctly into the chainweb"
             InvalidAdjacentVersion -> "An adjancent parent has a chainweb version that does not match the version of the validated header"
+            IncorrectForkNumber -> "The block has an incorrect fork number"
+            InvalidForkVotes -> "The block has an invalid fork vote count"
 
 -- | An enumeration of possible validation failures for a block header.
 --
@@ -374,13 +376,29 @@ data ValidationFailureType
     | InvalidAdjacentVersion
         -- ^ An adjacent parent has chainweb version that does not match the
         -- version of the validated header.
+    | IncorrectForkNumber
+        -- ^ The block has an incorrect fork number. At the beginning of a fork
+        -- epoch the fork number is the fork number of the parent plus one if
+        -- the fork vote count of the parent is at least 2/3 of the total number
+        -- of blocks in a fork epoch. Otherwise the number must be equal to the
+        -- fork number of the parent. Note, that the fork number is determined
+        -- deterministically from the parent block. It increases monotonically
+        -- at most once per fork epoch.
+    | InvalidForkVotes
+        -- ^ The block has an invalid fork vote count. At the beginning of an
+        -- fork epoch the fork vote count must be zero. Otherwise, the fork vote
+        -- count must be equal to the fork vote of the parent block or one more
+        -- than that. The fork vote count increases monotonically within an fork
+        -- epoch in steps of zero or one. The step size at each block is
+        -- non-deterministic. It is reset to zero at the beginning of a new fork
+        -- epoch.
   deriving (Show, Eq, Ord)
 
 instance Exception ValidationFailure
 
 -- | The list of validation failures that are definite and independent of any
 -- external context. A block for which validation fails with one of these
--- failures must be dicarded.
+-- failures must be discarded.
 --
 -- No node on the chainweb-web network should propgate blocks with these
 -- failures. If a block is received that causes a definite validation failures
@@ -401,6 +419,8 @@ definiteValidationFailures =
     , IncorrectGenesisParent
     , IncorrectGenesisTarget
     , IncorrectPayloadHash
+    , IncorrectForkNumber
+    , InvalidForkVotes
     ]
 
 -- | Predicate that checks whether a validation failure is definite.
@@ -631,6 +651,7 @@ validateIntrinsic t b = concat
     , [ BlockInTheFuture | not (prop_block_current t b)]
     , [ InvalidFeatureFlags | not (prop_block_featureFlags b)]
     , [ AdjacentChainMismatch | not (prop_block_adjacent_chainIds b) ]
+    , [ InvalidForkVotes | not (prop_block_forkVotesReset b) ]
     ]
 
 -- | Validate properties of a block with respect to a given parent.
@@ -653,6 +674,8 @@ validateInductiveChainStep s = concat
     , [ VersionMismatch | not (prop_block_chainwebVersion s) ]
     , [ IncorrectWeight | not (prop_block_weight s) ]
     , [ ChainMismatch | not (prop_block_chainId s) ]
+    , [ InvalidForkVotes | not (prop_block_forkVotesIncrement s) ]
+    , [ IncorrectForkNumber | not (prop_block_forkNumber s)
     ]
 
 validateInductiveWebStep
@@ -718,6 +741,11 @@ prop_block_adjacent_chainIds b
         | isGenesisBlockHeader b = _chainGraph b
         | otherwise = chainGraphAt (_chainwebVersion b) (view blockHeight b - 1)
 
+prop_block_forkVotesReset :: BlockHeader -> Bool
+prop_block_forkVotesReset b
+    | isForkEpochStartBlockHeader b = view blockForkVotes b == 0
+    | otherwise = True
+
 -- -------------------------------------------------------------------------- --
 -- Inductive BlockHeader Properties
 -- -------------------------------------------------------------------------- --
@@ -745,6 +773,14 @@ prop_block_chainId :: ChainStep -> Bool
 prop_block_chainId (ChainStep (ParentHeader p) b)
     = view blockChainId p == view blockChainId b
 
+prop_block_forkVotesIncrement :: ChainStep -> Bool
+prop_block_forkVotesIncrement (ChainStep (ParentHeader p) b)
+    | isForkEpochStartBlockHeader b = votes == 0
+    | otherwise = fv == parentVotes || votes == parentVotes + 1
+  where
+    votes = view blockForkVotes b
+    parentVotes = view blockForkVotes p
+
 -- -------------------------------------------------------------------------- --
 -- Multi chain inductive properties
 

src/Chainweb/ForkState.hs

@@ -1,7 +1,7 @@
 {-# LANGUAGE ImportQualifiedPost #-}
 
 -- |
--- Module: Chainweb.ForkNumber
+-- Module: Chainweb.ForkState
 -- Copyright: Copyright © 2025 Kadena LLC.
 -- License: MIT
 -- Maintainer: Lars Kuhtz <lars@kadena.io>
@@ -46,9 +46,12 @@ module Chainweb.ForkState
 -- epochs between the activation of two successive forks.
 --
 -- Starting with chainweb-node version 2.33, a node must accept blocks that have
--- either the fork number of the block height of the block or the respetive fork
--- number plus one. It must reject all other blocks. The fork number at the time
--- that chainweb node version 2.33 is released is zero.
+-- a fork number equal to the current fork number and a fork vote count that is
+-- either the fork vote count of the previous block or that number plus one. It
+-- must reject all other blocks. The fork number at the time that chainweb node
+-- version 2.33 is released is zero. That version does not increase the vote
+-- count, so the vote count will be zero as long as no other version is
+-- released that proposes a fork.
 --
 newtype ForkState = ForkState { _forkState :: Word64 }
     deriving (Eq, Ord, Generic)
@@ -87,6 +90,7 @@ forkVotes = forkState . forkVotes'
 
 forkEpochLength :: Natural
 forkEpochLength = 120 * 120 -- 5 days
+forkEpochLength = 120 * 120
 
 isForkEpoch :: BlockHeader -> Bool
 isForkEpoch hdr = mod (view blockHeight hdr) forkEpochLength == 0
@@ -100,7 +104,7 @@ getForkNumberVotes = view signaledNumber . view forkState
 validateForkNumber :: Parent BlockHeader -> BlockHeader -> Bool
 validateForkNumber (Parent parent) hdr
     | isForkEpoch hdr =
-        if view getForkNumberVotes parent >= (forkEpochLength * 2 `div 3)
+        if view getForkNumberVotes parent >= ((forkEpochLength * 2) `div` 3)
           then
             view getForkNumber hdr == view getForkNumber parent + 1
             && view getForkNumberVotes hdr <= 1
@@ -111,3 +115,17 @@ validateForkNumber (Parent parent) hdr
         view getForkNumber hdr == view getForkNumber (parent hdr)
         && view getForkNumberVotes hdr <= view getForkNumberVotes (parent hdr) + 1
 
+-- -------------------------------------------------------------------------- --
+-- Details
+--
+-- Votes:
+--
+-- * Voting is done per chain over a fork epoch mines a DA epoch.
+-- * The last epoch in a fork epoch no voting is done. Instead the votes are
+--   aggregated over all chains, by computing the global average:
+--
+--   * Use a quantized average consensus algorithm to compute the average vote.
+--   * Use 1000 quantization levels.
+--   * In each step use integer division with biased rounding.
+--   * At the end roude to nearest integer using bankers rounding.
+--