Merge pull request #3629 from input-output-hk/aniketd/rule-transition…

…-diagrams Add rule-transition diagrams in dot syntax
IntersectMBO · Sep 11, 2023 · 8e8b0f8 · 8e8b0f8
2 parents cf05d70 + 9e82208
commit 8e8b0f8
Show file tree

Hide file tree

Showing 4 changed files with 918 additions and 0 deletions.
diff --git a/docs/graphviz-diagrams/conway_transitions.gv b/docs/graphviz-diagrams/conway_transitions.gv
@@ -0,0 +1,99 @@
+digraph conway_transitions {
+    label="NOTE 
+    A straight arrow form one node to another represents a sub-rule relationship.
+    A dotted arrow from one node to another represents a dependency:
+      that the output of the target rule in an input to the source rule,
+      either as part of the source state, the evironment or the signal.
+    In most cases these dependencies are between sub-rules of a rule.
+    In the case of a recursive rule, the sub-rule can also have a dependency on the super rule.
+    Those recursively call themselves while traversing the input signal sequence,
+      until reaching the base case with an empty input sequence.
+    A blue colored box indicates a trigger in consensus that triggers the rule in ledger.
+
+    NOTE
+    In the Shelley ledger, the @CHAIN@ rule is used to apply a whole block.
+    In consensus, we split up the application of a block to the ledger into 
+    separate steps that are performed together by 'applyExtLedgerState':
+    
+    1. 'applyChainTickLedgerResult': executes the @TICK@ transition
+    2. 'validateHeader':
+       2.1. 'validateEnvelope': executes the @chainChecks@
+       2.2. 'updateChainDepState': executes the @PRTCL@ transition
+    3. 'applyBlockLedgerResult': executes the @BBODY@ transition";
+
+    # Externals
+
+    applyTickOpts  [shape=box, label="ApplyBlock.applyTickOpts (API.Validation)" , color=blue];
+    applyBlockOpts [shape=box, label="ApplyBlock.applyBlockOpts (API.Validation)", color=blue];
+    applyTx        [shape=box, label="ApplyTx (API.Mempool)"                     , color=blue];
+    futureLedger   [shape=box, label="FutureLedgerView"                          , color=blue];
+
+    # Internals
+
+    BBODY    [shape=box, label="BBODY (alonzo)     \nenv:BbodyEnv,state:ShelleyBbodyState,signal:Block(BHeaderView)."];
+    UTXO     [shape=box, label="UTXO (babbage)     \nenv:UtxoEnv,state:UTxOState,signal:Tx."];
+    CERT     [shape=box, label="CERT (conway)      \nenv:CertEnv,state:CertState,signal:TxCert."];
+    CERTS    [shape=box, label="CERTS (conway)     \nenv:CertsEnv,state:CertState,signal:Seq(TxCert)."];
+    DELEG    [shape=box, label="DELEG (conway)     \nenv:PParams,state:DState,signal:ConwayDelegCert."];
+    ENACT    [shape=box, label="ENACT (conway)     \nenv:(),state:EnactState,signal:GovAction."];
+    EPOCH    [shape=box, label="EPOCH (conway)     \nenv:PoolDistr,state:EpochState,signal:EpochNo."];
+    GOV      [shape=box, label="GOV (conway)       \nenv:GovEnv,state:GovActionState,signal:GovProcedures."];
+    GOVCERT  [shape=box, label="GOVCERT (conway)   \nenv:ConwayGovCertEnv,state:VState,signal:ConwayGovCert."];
+    LEDGER   [shape=box, label="LEDGER (conway)    \nenv:LedgerEnv,state:LedgerState,signal:Tx."];
+    NEWEPOCH [shape=box, label="NEWEPOCH (conway)  \nenv:(),state:NewEpochState,signal:EpochNo."];
+    POOL     [shape=box, label="POOL (conway)      \nenv:PoolEnv,state:PState,signal:PoolCert."];
+    RATIFY   [shape=box, label="RATIFY (conway)    \nenv:RatifyEnv,state:RatifyState,signal:RatifySignal."];
+    TICKF    [shape=box, label="TICKF (conway)     \nenv:(),state:NewEpochState,signal:SlotNo."];
+    UTXOS    [shape=box, label="UTXOS (conway)     \nenv:UtxoEnv,state:UTxOState,signal:AlonzoTx."];
+    UTXOW    [shape=box, label="UTXOW (conway)     \nenv:UtxoEnv,state:UTxOState,signal:Tx."];
+    LEDGERS  [shape=box, label="LEDGERS (shelley)  \nenv:ShelleyLedgersEnv,state:LedgerState,signal:Seq(Tx)."];
+    POOLREAP [shape=box, label="POOLREAP (shelley) \nenv:ShelleyPoolreapEnv,state:ShelleyPoolreapState,signal:EpochNo."];
+    RUPD     [shape=box, label="RUPD (shelley)     \nenv:RupdEnv,state:StrictMaybe(PulsingRewUpdate),signal:SlotNo."];
+    SNAP     [shape=box, label="SNAP (shelley)     \nenv:SnapEnv,state:SnapShots,signal:()."];
+    TICK     [shape=box, label="TICK (shelley)     \nenv:(),state:NewEpochState,signal:SlotNo."];
+
+    # Graph
+
+    applyTickOpts -> TICK;
+    applyBlockOpts -> BBODY;
+    applyTx -> LEDGER;
+    futureLedger -> TICKF;
+
+    BBODY -> LEDGERS;
+
+    TICK -> RUPD;
+    TICK -> NEWEPOCH;
+
+    RUPD -> NEWEPOCH[style=dotted];
+
+    NEWEPOCH -> EPOCH;
+
+    EPOCH -> SNAP;
+    EPOCH -> RATIFY;
+    EPOCH -> POOLREAP;
+
+    RATIFY -> SNAP[style=dotted];
+    RATIFY -> POOLREAP[style=dotted];
+    RATIFY -> ENACT;
+
+    LEDGERS -> LEDGERS;
+    LEDGERS -> LEDGER;
+
+    LEDGER -> LEDGERS[style=dotted];
+    LEDGER -> UTXOW;
+    LEDGER -> CERTS;
+    LEDGER -> GOV;
+
+    UTXOW -> UTXO;
+    UTXOW -> CERTS[style=dotted];
+
+    UTXO -> UTXOS;
+
+    CERTS -> CERTS;
+    CERTS -> CERT;
+
+    CERT -> CERTS[style=dotted];
+    CERT -> DELEG;
+    CERT -> POOL;
+    CERT -> GOVCERT;
+}