From 0736cddbafeea73ec5332f60294acbe26623ed99 Mon Sep 17 00:00:00 2001
From: Ammar Arif <evergreenkary@gmail.com>
Date: Thu, 25 Jan 2024 23:42:38 +0800
Subject: [PATCH] doc(katana): db table layout (#1442)

Initial effort in improving documentations for katana. This adds an ER diagram loosely representing the logical model of katana's DB table schema using mermaid diagram so it can be easily embedded in markdown.
---
 crates/katana/docs/database.md | 153 +++++++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 crates/katana/docs/database.md

diff --git a/crates/katana/docs/database.md b/crates/katana/docs/database.md
new file mode 100644
index 0000000000..fde4c692c1
--- /dev/null
+++ b/crates/katana/docs/database.md
@@ -0,0 +1,153 @@
+# Database
+
+## Table layout
+
+```mermaid
+erDiagram
+
+Headers {
+    KEY BlockNumber
+    VALUE Header 
+}
+
+BlockHashes {
+    KEY BlockNumber
+    VALUE BlockHash
+}
+
+BlockNumbers {
+    KEY BlockHash
+    VALUE BlockNumber
+}
+
+BlockStatusses {
+    KEY BlockNumber
+    VALUE FinalityStatus
+}
+
+BlockBodyIndices {
+    KEY BlockNumber
+    VALUE StoredBlockBodyIndices
+}
+
+TxNumbers {
+    KEY TxHash
+    VALUE TxNumber
+}
+
+TxHashes {
+    KEY TxNumber
+    VALUE TxHash
+}
+
+Transactions {
+    KEY TxNumber
+    VALUE Tx
+}
+
+TxBlocks {
+    KEY TxNumber
+    VALUE BlockNumber
+}
+
+Receipts {
+    KEY TxNumber
+    VALUE Receipt
+}
+
+CompiledClassHashes {
+    KEY ClassHash
+    VALUE CompiledClassHash
+}
+
+CompiledContractClasses {
+    KEY ClassHash
+    VALUE StoredContractClass
+}
+
+SierraClasses {
+    KEY ClassHash
+    VALUE FlattenedSierraClass
+}
+
+ContractInfo {
+    KEY ContractAddress
+    VALUE GenericContractInfo
+}
+
+ContractStorage {
+    KEY ContractAddress
+    DUP_KEY StorageKey
+    VALUE StorageEntry
+}
+
+ClassDeclarationBlock {
+    KEY ClassHash
+    VALUE BlockNumber
+}
+
+ClassDeclarations {
+    KEY BlockNumber
+    DUP_KEY ClassHash
+    VALUE ClassHash
+}
+
+ContractInfoChangeSet {
+    KEY ContractAddress
+    VALUE ContractInfoChangeList
+}
+
+NonceChanges {
+    KEY BlockNumber
+    DUP_KEY ContractAddress
+    VALUE ContractNonceChange
+}
+
+ContractClassChanges {
+    KEY BlockNumber
+    DUP_KEY ContractAddress
+    VALUE ContractClassChange
+}
+
+StorageChangeSet {
+    KEY ContractAddress
+    DUP_KEY StorageKey
+    VALUE StorageEntryChangeList
+}
+
+StorageChanges {
+    KEY BlockNumber
+    DUP_KEY ContractStorageKey
+    VALUE ContractStorageEntry
+}
+
+
+BlockHashes ||--|| BlockNumbers : "block id"
+BlockNumbers ||--|| BlockBodyIndices : "has"
+BlockNumbers ||--|| Headers : "has"
+BlockNumbers ||--|| BlockStatusses : "has"
+
+BlockBodyIndices ||--o{ Transactions : "block txs"
+
+TxHashes ||--|| TxNumbers : "tx id"
+TxNumbers ||--|| Transactions : "has"
+TxBlocks ||--|{ Transactions : "tx block"
+Transactions ||--|| Receipts : "each tx must have a receipt"
+
+CompiledClassHashes ||--|| CompiledContractClasses : "has"
+CompiledClassHashes ||--|| SierraClasses : "has"
+SierraClasses |o--|| CompiledContractClasses : "has"
+
+ContractInfo ||--o{ ContractStorage : "a contract storage slots"
+ContractInfo ||--|| CompiledClassHashes : "has"
+
+ContractInfo }|--|{ ContractInfoChangeSet : "has"
+ContractStorage }|--|{ StorageChangeSet : "has"
+ContractInfoChangeSet }|--|{ NonceChanges : "has"
+ContractInfoChangeSet }|--|{ ContractClassChanges : "has"
+CompiledClassHashes ||--|| ClassDeclarationBlock : "has"
+ClassDeclarationBlock ||--|| ClassDeclarations : "has"
+BlockNumbers ||--|| ClassDeclarations : ""
+StorageChangeSet }|--|{ StorageChanges : "has"
+
+```
\ No newline at end of file