Skip to content

Commit 0d7a122

Browse files
yHSJch1bo
yHSJ
authored and
ch1bo
committed
ledger: scaffold block validation and introduce conway diagram
1 parent 95042fc commit 0d7a122

File tree

8 files changed

+364
-0
lines changed

8 files changed

+364
-0
lines changed

‎src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
- [Mempool](mempool/README.md)
2121
- [TxSubmission2](mempool/txsubmission2.md)
2222
- [Ledger](ledger/README.md)
23+
- [Block Validation](ledger/block-validation.md)
2324

2425
---
2526

‎src/ledger/block-validation.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Ledger: Block Validation
2+
3+
Block validation is the process of applying a set of ledger rules to a candidate block before adding it to the blockchain and updating the state of the ledger.
4+
Each [era](../consensus/README.md#multi-era-considerations) has it's own set of rules for block validation.
5+
6+
7+
8+
> [!NOTE]
9+
> TODO: Write a full introduction here with relevant terminology and concepts defined.
10+
11+
While different node implementations may implement these rules in different ways, it's vital that they all agree on the outcome of the validation process to prevent forks in the blockchain.
12+
13+
14+
## Conway Block Validation
15+
16+
In this section, we will walk through the [cardano-ledger](https://github.com/IntersectMBO/cardano-ledger) implementation of Conway era block validation.
17+
We will break up the validation process into smaller sections to make it easier to visualize and understand. All diagrams should be read from left to right and top to bottom in terms of order of execution.
18+
19+
20+
The [cardano-ledger](https://github.com/IntersectMBO/cardano-ledger) has the concept of an _EraRule_, which is a set of validations that are applied to a block in a specific era. Often, a newer era may call a previous era's EraRule instead of reimplementing the same logic.
21+
### EraRule BBODY
22+
This is the "entrypoint" for block validation, responsible for validating the body of a block.
23+
```mermaid
24+
{{#include diagrams/conway-bbody.mermaid}}
25+
```
26+
27+
### EraRule LEDGERS
28+
This EraRule is responsible for validating and updating the ledger state, namely UTxO state, governance state, and certificate state.
29+
```mermaid
30+
{{#include diagrams/conway-ledgers.mermaid}}
31+
```
32+
33+
### EraRule CERTS
34+
This EraRule is responsible for validating and updating the certificate state.
35+
```mermaid
36+
{{#include diagrams/conway-certs.mermaid}}
37+
```
38+
39+
40+
### EraRule GOV
41+
This EraRule is responsible for validating and updating the governance state.
42+
```mermaid
43+
{{#include diagrams/conway-gov.mermaid}}
44+
```
45+
46+
47+
### EraRule UTXOW
48+
This EraRule is responsible for validating and updating the UTxO state.
49+
```mermaid
50+
{{#include diagrams/conway-utxos.mermaid}}
51+
```
52+
53+
54+
### Full Diagram
55+
Here is the full diagram, with all EraRules combined.
56+
```mermaid
57+
{{#include diagrams/conway-block-validation.mermaid}}
58+
```

‎src/ledger/diagrams/conway-bbody.mermaid

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
flowchart LR
2+
EBBC[EraRule BBODY Conway]
3+
EBBC --> CBBT[conwayBbodyTransition]
4+
CBBT --> totalScriptRefSize(totalScriptRefSize <= maxRefScriptSizePerBlock)
5+
CBBT --> S[(state)]
6+
7+
EBBC --> ABBT[alonzoBbodyTransition]
8+
ABBT --> ELC[EraRule LEDGERS Conway]
9+
ABBT --> txTotalExUnits(txTotal <= ppMax ExUnits)
10+
ABBT --> BBodyState[(BbodyState @era ls')]

‎src/ledger/diagrams/conway-block-validation.mermaid

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
flowchart LR
2+
EBBC[EraRule BBODY Conway]
3+
EBBC --> CBBT[conwayBbodyTransition]
4+
CBBT --> totalScriptRefSize(totalScriptRefSize <= maxRefScriptSizePerBlock)
5+
CBBT --> S[(state)]
6+
7+
EBBC --> ABBT[alonzoBbodyTransition]
8+
ABBT --> ELC[EraRule LEDGERS Conway]
9+
ELC --> ELS[EraRule LEDGERS Shelley]
10+
ELS --> ledgersTransition
11+
ledgersTransition --> |repeat| ledgerTransition
12+
ledgerTransition --> |when mempool| EMC[EraRule Mempool Conway]
13+
EMC --> mempoolTransition
14+
mempoolTransition --> unelectedCommitteeMembers(failOnNonEmpty unelectedCommitteeMembers)
15+
ledgerTransition --> isValid{isValid}
16+
isValid --> |True| ltDoBlock[do]
17+
ltDoBlock --> |currentTreasuryValueTxBodyL| submittedTreasuryValue(submittedTreasuryValue == actualTreasuryValue)
18+
ltDoBlock --> totalRefScriptSize(totalRefScriptSize <= maxRefScriptSizePerTx)
19+
ltDoBlock --> nonExistentDelegations(failOnNonEmpty nonExistentDelegations)
20+
21+
ltDoBlock --> ECSC[EraRule CERTS Conway]
22+
ECSC --> conwayCertsTransition
23+
conwayCertsTransition --> certificates{isEmpty certificates}
24+
25+
certificates --> |True| cctDoBlock[do]
26+
cctDoBlock --> validateZeroRewards(validateZeroRewards)
27+
cctDoBlock --> certStateWithDrepExiryUpdated[(certStateWithDrepExiryUpdated)]
28+
29+
certificates --> |False| sizeCheck{size > 1}
30+
sizeCheck --> |True| conwayCertsTransition
31+
sizeCheck --> |False| ECC[EraRule CERT Conway]
32+
ECC --> certTransition
33+
certTransition --> |ConwayTxCertDeleg| EDC[EraRule DELEG Conway]
34+
EDC --> conwayDelegTransition
35+
conwayDelegTransition --> |ConwayRegCert| crcDoBlock[do]
36+
crcDoBlock --> crcCheckDepositAgaintPParams(checkDespoitAgainstPParams)
37+
crcDoBlock --> crcCheckStakeKeyNotRegistered(checkStakeKeyNotRegistered)
38+
conwayDelegTransition --> |ConwayUnregCert| cucDoBlock[do]
39+
cucDoBlock --> checkInvalidRefund(checkInvalidRefund)
40+
cucDoBlock --> mUMElem(isJust mUMElem)
41+
cucDoBlock --> cucCheckStakeKeyHasZeroRewardBalance(checkStakeKeyHasZeroRewardBalance)
42+
conwayDelegTransition --> |ConwayDelegCert| cdcDoBlock[do]
43+
cdcDoBlock --> checkStakeKeyIsRegistered(checkStakeKeyIsRegistered)
44+
cdcDoBlock --> checkStakeDelegateeRegistered(checkStakeDelegateeRegistered)
45+
conwayDelegTransition --> |ConwayRegDelegCert| crdcDoBlock[do]
46+
crdcDoBlock --> checkDepositAgainstPParams(checkDepositAgainstPParams)
47+
crdcDoBlock --> checkStakeKeyNotRegistered(checkStakeKeyNotRegistered)
48+
crdcDoBlock --> checkStakeKeyZeroRewardBalance(checkStakeKeyHasZeroRewardBalance)
49+
certTransition --> EPC[EraRule POOL Conway]
50+
EPC --> EPS[EraRule POOL Shelley]
51+
EPS --> poolDelegationTransition
52+
poolDelegationTransition --> |regPool| rpDoBlock[do]
53+
rpDoBlock --> actualNetId(actualNetId == suppliedNetId)
54+
rpDoBlock --> pmHash(length pmHash <= sizeHash)
55+
rpDoBlock --> ppCost(ppCost >= minPoolCost)
56+
rpDoBlock --> ppId{ppId ∉ dom psStakePoolParams}
57+
58+
ppId --> |True| payPoolDeposit --> psDeposits[(psDeposits)]
59+
ppId --> |False| psFutureStakePoolParams[(psFutureStakePoolParams, psRetiring)]
60+
61+
poolDelegationTransition --> |RetirePool| retirePoolDoBlock[do]
62+
retirePoolDoBlock --> hk(hk ∈ dom psStakePoolParams)
63+
retirePoolDoBlock --> cEpoch(cEpoch < e && e <= limitEpoch)
64+
retirePoolDoBlock --> psRetiring[(psRetiring)]
65+
66+
certTransition --> EGOVERTC[EraRule GOVERT Conway]
67+
EGOVERTC --> conwayGovCertTransition
68+
conwayGovCertTransition --> |ConwayRegDRep| crdrDoBlock[do]
69+
crdrDoBlock --> notMemberCredVsDReps(Map.notMember cred vsDReps)
70+
crdrDoBlock --> deposit(deposit == ppDRepDeposit)
71+
crdrDoBlock --> crdrDRepState[(dRepState)]
72+
conwayGovCertTransition --> |ConwayUnregDRep| curdrDoBlock[do]
73+
curdrDoBlock --> mDRepState(isJust mDRepState)
74+
curdrDoBlock --> drepRefundMismatch(failOnJust drepRefundMismatch)
75+
curdrDoBlock --> curdrDRepState[(dRepState)]
76+
conwayGovCertTransition -->|ConwayUpdateDRep| cudrDoBlock[do]
77+
cudrDoBlock --> memberCredVsDreps(Map.member cred vsDReps)
78+
cudrDoBlock --> cudrDRepState[(vsDReps)]
79+
conwayGovCertTransition --> |ConwayResignCommitteeColdKey| crcckDoBlock[do]
80+
conwayGovCertTransition --> |ConwayAuthCommitteeHotKey| cachkDoBlock[do]
81+
crcckDoBlock --> checkAndOverwriteCommitteMemberState
82+
cachkDoBlock --> checkAndOverwriteCommitteMemberState
83+
checkAndOverwriteCommitteMemberState --> coldCredResigned(failOnJust coldCredResigned)
84+
checkAndOverwriteCommitteMemberState --> isCurrentMember(isCurrentMember OR isPotentialFutureMember)
85+
checkAndOverwriteCommitteMemberState --> vsCommitteeState[(vsCommitteeState)]
86+
ltDoBlock --> EGC[EraRule GOV Conway]
87+
EGC --> govTransition
88+
govTransition --> badHardFork(failOnJust badHardFork)
89+
govTransition --> actionWellFormed(actionWellFormed)
90+
govTransition --> refundAddress(refundAddress)
91+
govTransition --> nonRegisteredAccounts(nonRegisteredAccounts)
92+
govTransition --> pProcDepost(pProcDeposit == expectedDeposit)
93+
govTransition --> pProcReturnAddr(pProcReturnAddr == expectedNetworkId)
94+
govTransition --> govAction{case pProcGovAction}
95+
govAction --> |TreasuryWithdrawals| twDoBlock[do]
96+
twDoBlock --> mismatchedAccounts(mismatchedAccounts)
97+
twDoBlock --> twCheckPolicy(checkPolicy)
98+
govAction --> |UpdateCommittee| ucDoBlock[do]
99+
ucDoBlock --> setNull(Set.null conflicting)
100+
ucDoBlock --> mapNull(Map.null invalidMembers)
101+
govAction --> |ParameterChange| pcDoBlock[do]
102+
pcDoBlock --> checkPolicy(checkPolicy)
103+
govTransition --> ancestryCheck(ancestryCheck)
104+
govTransition --> unknownVoters(failOnNonEmpty unknownVoters)
105+
govTransition --> unknwonGovActionIds(failOnNonEmpty unknownGovActionIds)
106+
govTransition --> checkBootstrapVotes(checkBootstrapVotes)
107+
govTransition --> checkVotesAreNotForExpiredActions(checkVotesAreNotForExpiredActions)
108+
govTransition --> checkVotersAreValid(checkVotersAreValid)
109+
govTransition --> updatedProposalStates[(updatedProposalStates)]
110+
ltDoBlock --> utxoState[(utxoState', certStateAfterCerts)]
111+
isValid --> |False| utxoStateCertState[(utxoState, certState)]
112+
ledgerTransition --> EUC[EraRule UTXOW Conway]
113+
EUC --> babbageUtxowTransition
114+
babbageUtxowTransition --> validateFailedBabbageScripts(validateFailedBabbageScripts)
115+
babbageUtxowTransition --> babbageMissingScripts(babbageMissingScripts)
116+
babbageUtxowTransition --> missingRequiredDatums(missingRequiredDatums)
117+
babbageUtxowTransition --> hasExactSetOfRedeemers(hasExactSetOfRedeemers)
118+
babbageUtxowTransition --> validateVerifiedWits(Shelley.validateVerifiedWits)
119+
babbageUtxowTransition --> validateNeededWitnesses(validateNeededWitnesses)
120+
babbageUtxowTransition --> validateMetdata(Shelley.validateMetadata)
121+
babbageUtxowTransition --> validateScriptsWellFormed(validateScriptsWellFormed)
122+
babbageUtxowTransition --> ppViewHashesMatch(ppViewHashesMatch)
123+
babbageUtxowTransition --> EUTXOC[EraRule UTXO Conway]
124+
EUTXOC --> utxoTransition
125+
utxoTransition --> disjointRefInputs(disjointRefInputs)
126+
utxoTransition --> validateOutsideValidityIntervalUtxo(Allegra.validateOutsideValidityIntervalUtxo)
127+
utxoTransition --> validateOutsideForecast(Alonzo.validateOutsideForecast)
128+
utxoTransition --> validateInputSetEmptyUTxO(Shelley.validateInputSetEmptyUTxO)
129+
utxoTransition --> feesOk(feesOk)
130+
utxoTransition --> validateBadInputsUTxO(Shelley.validateBadInputsUTxO)
131+
utxoTransition --> validateValueNotConservedUTxO(Shelley.validateValueNotConservedUTxO)
132+
utxoTransition --> validateOutputTooSmallUTxO(validateOutputTooSmallUTxO)
133+
utxoTransition --> validateOutputTooBigUTxO(Alonzo.validateOutputTooBigUTxO)
134+
utxoTransition --> validateOutputBootAddrAttrsTooBig(Shelley.validateOuputBootAddrAttrsTooBig)
135+
utxoTransition --> validateWrongNetwork(Shelley.validateWrongNetwork)
136+
utxoTransition --> validateWrongNetworkWithdrawal(Shelley.validateWrongNetworkWithdrawal)
137+
utxoTransition --> validateWrongNetworkInTxBody(Alonzo.validateWrongNetworkInTxBody)
138+
utxoTransition --> validateMaxTxSizeUTxO(Shelley.vallidateMaxTxSizeUTxO)
139+
utxoTransition --> validateExUnitsTooBigUTxO(Alonzo.validateExUnitsTooBigUTxO)
140+
utxoTransition --> EUTXOSC[EraRule UTXOS Conway]
141+
EUTXOSC --> utxosTransition
142+
utxosTransition --> isValidTxL{isValidTxL}
143+
isValidTxL --> |True| conwayEvalScriptsTxValid
144+
conwayEvalScriptsTxValid --> expectScriptsToPass(expactScriptsToPass)
145+
conwayEvalScriptsTxValid --> conwayEvalScriptsTxValidUtxosPrime[(utxos')]
146+
isValidTxL --> |False| babbageEvalScriptsTxInvalid
147+
babbageEvalScriptsTxInvalid --> evalPlutusScripts(evalPlutusScripts FAIL)
148+
babbageEvalScriptsTxInvalid --> babbageEvalScriptsTxInvalidUtxosPrime([utxos'])
149+
EUC --> LedgerState[(LedgerState utxoState'' certStateAfterCERTS)]
150+
ABBT --> txTotalExUnits(txTotal <= ppMax ExUnits)
151+
ABBT --> BBodyState[(BbodyState @era ls')]

0 commit comments

Comments
 (0)