From 2fed6773ea2bbf6a211c997b1520fc661f9a1e9f Mon Sep 17 00:00:00 2001
From: Igor Konnov <igor@konnov.phd>
Date: Thu, 16 May 2024 14:31:10 +0200
Subject: [PATCH 1/3] add ADR002 to document the storage

---
 doc/adr002-storage.md | 58 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 doc/adr002-storage.md

diff --git a/doc/adr002-storage.md b/doc/adr002-storage.md
new file mode 100644
index 00000000..7de39af8
--- /dev/null
+++ b/doc/adr002-storage.md
@@ -0,0 +1,58 @@
+# ADR002: Storage Layout
+
+**Author:** Igor Konnov, 2024
+
+This ADR discusses the simple layout of the Soroban transactions that are
+fetched from a Stellar network.
+
+Our goals are:
+
+ - Store contract calls retrieved from the Horizon API, see [storage.ts][].
+ - Access calls indendently for verification.
+ - Tag calls as `stored`, `verified`, `failed`, etc.
+
+To keep things simple in the activation stage, we are simply using the
+filesystem instead of a fully-featured database. This is sufficient to
+demonstrate our idea.  When the users expect a storage that its durable,
+consistent, fail-free, etc., we would have to implement the storage with a solid
+database library.
+
+In the rest of this document, we refer to the root of the storage directory as
+`${STOR}$`. We expect the user to provide the Solarkraft commands with the
+root directory. By default, `${STOR}` would point to
+`$HOME/.solarkraft/.stor`.
+
+## 1. Storing extracted calls
+
+We have the following requirements to the storage:
+
+ - It should support contract calls (from transactions) that are extracted for
+   different contracts.
+ 
+ - It should be relatively easy to order these transactions, e.g., by ledger height.
+
+ - Transactions that happen in the same block should not collide.
+
+
+Given all these requirements, we store every contract call in its own file called:
+
+```
+${STOR}/${contractId}/${height}/entry-${txHash}.json
+```
+
+The values `${contractId}`, `${height}`, `${txHash}` are the values of the
+fields that are defined in [storage.ts][].
+
+## 2. Storing verification results
+
+The verification results are to be stored in a file called:
+
+```
+${STOR}/${contractId}/${height}/verification-${txHash}.json
+```
+
+The exact format of this file is to be defined later.
+
+
+
+[storage.ts]: https://github.com/freespek/solarkraft/blob/main/solarkraft/src/fetcher/storage.ts
\ No newline at end of file

From a37780292099835c471e39009c980f46445d8c29 Mon Sep 17 00:00:00 2001
From: Igor Konnov <igor@konnov.phd>
Date: Thu, 16 May 2024 14:41:23 +0200
Subject: [PATCH 2/3] Update doc/adr002-storage.md

Co-authored-by: Kukovec <jure.kukovec@gmail.com>
---
 doc/adr002-storage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/adr002-storage.md b/doc/adr002-storage.md
index 7de39af8..bb745fe2 100644
--- a/doc/adr002-storage.md
+++ b/doc/adr002-storage.md
@@ -18,7 +18,7 @@ consistent, fail-free, etc., we would have to implement the storage with a solid
 database library.
 
 In the rest of this document, we refer to the root of the storage directory as
-`${STOR}$`. We expect the user to provide the Solarkraft commands with the
+`${STOR}`. We expect the user to provide the Solarkraft commands with the
 root directory. By default, `${STOR}` would point to
 `$HOME/.solarkraft/.stor`.
 

From 52ea2e90819826fb9375cd3b0be7c660154dabb7 Mon Sep 17 00:00:00 2001
From: Igor Konnov <igor@konnov.phd>
Date: Thu, 16 May 2024 15:40:28 +0200
Subject: [PATCH 3/3] add a comment about JSON serialization

---
 doc/adr002-storage.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/adr002-storage.md b/doc/adr002-storage.md
index bb745fe2..d59b676d 100644
--- a/doc/adr002-storage.md
+++ b/doc/adr002-storage.md
@@ -43,6 +43,10 @@ ${STOR}/${contractId}/${height}/entry-${txHash}.json
 The values `${contractId}`, `${height}`, `${txHash}` are the values of the
 fields that are defined in [storage.ts][].
 
+The file is a JSON serialization of [ContractCallEntry][]. Some care is required
+to serialize big integers, we use [json-bigint][]. Additionally, we serialized
+`OrderedMap` as an array.
+
 ## 2. Storing verification results
 
 The verification results are to be stored in a file called:
@@ -55,4 +59,6 @@ The exact format of this file is to be defined later.
 
 
 
-[storage.ts]: https://github.com/freespek/solarkraft/blob/main/solarkraft/src/fetcher/storage.ts
\ No newline at end of file
+[storage.ts]: https://github.com/freespek/solarkraft/blob/main/solarkraft/src/fetcher/storage.ts
+[ContractCallEntry]: https://github.com/freespek/solarkraft/blob/38d57fd51082feab9215a77c555bdccdc961aa26/solarkraft/src/fetcher/storage.ts#L23
+[json-bigint]: https://www.npmjs.com/package/@types/json-bigint
\ No newline at end of file