rev.3 complete & more details

.gitignore

@@ -0,0 +1 @@
+.obsidian/

README.md

@@ -0,0 +1,20 @@
+# zkl-docs
+
+This repository is a homepage for zk-Lokomotive's
+- cryptographic system architecture
+- infrastructure architecture
+- notes from brainstorming sessions
+
+Take everything with a grain of salt.
+
+## contents
+
+| Document                        | Description                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| [[1. Elements]]                 | Overview of modules, submodules and their functionalities                   |
+| [[2. Cryptographic Activities]] | A detailed explanation of cryptographic activities and their implementation |
+
+## credits
+
+2024 © zk-Lokomotive team
+https://zk-lokomotive.xyz/

architecture/1. Elements.md

@@ -0,0 +1,79 @@
+# ZKL Architecture
+
+This file describes modules and submodules present in zk-Lokomotive's platform and web applications.
+
+Yigid BALABAN, <fyb@fybx.dev>
+
+Revision 1
+20/09/2024
+
+## 1. Elements
+
+Our architecture consists of 3 layers, middle one being the platform and the edges being the users.
+
+Figure: zk-Lokomotive Module Legend
+![[zkl module legend light.png]]
+
+### Difference between installations
+
+We offer enterprise-level solutions where the platform is full on-chain for an unmatched privacy potential. With the use of a decentralised "CCIR", we provide identity proving and account management in blockchain, removing any centralised layers where data can be tampered with.
+
+See "Appendix A" for the enterprise module legend.
+
+### Modules
+
+The infrastructure consists of 3 modules, with the JavaScript/Svelte web application consisting of 4 submodules. Here's the breakdown of each module:
+
+#### JavaScript/Svelte web application (client)
+
+The client is the user-facing module of zk-Lokomotive, allowing people to send and receive files using the accounts they "create" through linking their wallet accounts.
+
+##### Submodule: aus
+
+This submodule provides the functionality of communicating with distributed file chains and/or decentralised networks like IPFS. In our current implementation (see "crypto sysarch", revision 3) we are utilising Arweave.
+
+##### Submodule: roadhog
+
+This submodule interfaces with the several blockchain networks utilised in our platform to perform specific objectives by calling or querying smart contracts, Solana programs, etc.
+
+##### Submodule: crypto
+
+This submodule performs cryptographic applications. In our current implementation we support elliptic curve integrated encryption scheme through [ecies/rs-wasm](https://github.com/ecies/rs-wasm) package which consumes the Rust crate [eciesrs](https://docs.rs/crate/ecies/0.1.2).
+
+##### Submodule: kds
+
+This submodule generates pseudo-random mnemonics using [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) that are then derived to elliptic curve keypairs.
+
+#### Platform-level: CCIR
+
+Cross-Chain Identity Registry, or CCIR for short is the address book of zk-Lokomotive users, linking their wallet addresses to their elliptic public keys. On CCIR, the wallet user can only add or modify information about themselves after proving that they own the private key to that wallet account (simply, authenticating), but everyone is allowed to do queries from a public EC key to the wallet address, or from a wallet address to the public EC key.
+
+The CCIR holds the following information:
+```json
+{
+	"wallet_addresses": [
+		{ "address": "0x123...", "network": "ethereum" }
+	],
+	"userPublicKey": "0x123...",
+	"main_wallet_address": "0x123..."
+}
+```
+
+#### Platform-level: Arweave
+
+Following our current (rev.3) architecture, we are using Arweave for a decentralised file storage solution.
+
+#### Platform-level: Inbox
+
+Inboxes are on-chain and network-specific implementations which the client calls using the submodule roadhog when querying for incoming files, or sending a file.
+
+The inbox can be logically defined as:
+```ocaml
+type message = { q_e: string; e_plink: string; uPK: string; }
+let inbox : message StringMap.t ref = ref StringMap.empty
+```
+
+### Appendix A
+
+Figure: zk-Lokomotive Enterprise Deployment Module Legend
+![[zkl enterprise module legend light.png]]

architecture/2. Cryptographic Activities.md

@@ -1,10 +1,14 @@
-# zk-Lokomotive Cryptographic System Architecture
+# ZKL Architecture
+
+This file describes the cryptographic activities that take place in zk-Lokomotive's platform and web applications.
 
 Yigid BALABAN, <fyb@fybx.dev>
 
 Revision 3
 20/09/2024
 
+## 2. Cryptographic Activities
+
 ## System Elements
 
 The system elements are/will be described and discussed in the ZKL System Architecture document. This section is to provide a reminder/reference.
@@ -29,9 +33,7 @@ The client (the sender) generates the encrypted payload to be sent to the reciev
 
 ## Workflows
 
-### Sending a file
-
-#### Definitions
+### Definitions
 $Q_{r}:\text{Recipient's public key on curve secp256k1}$
 $G:\text{The generator point on curve secp256k1}$
 $Z:\text{A symmetric key derived for the file to be sent, the shared secret}$
@@ -49,7 +51,7 @@ The $F$, intermediate file format is as follows:
 | **Content**         | Length of $F_m$ | $F_m$                | $F_c$                     |
 | **Length in bytes** | 4 bytes         | 1020 (255 * 4 bytes) | variable                  |
 
-#### Workflow
+### Workflow: Sending a file
 
 1. The $Q_{r}$ is retrieved from the CCIR.
 2. An ephemeral keypair is generated, $Q_{e}$ and $d_{e}$.
@@ -60,3 +62,7 @@ The $F$, intermediate file format is as follows:
 
 > [!info] Reminder
 > The MAC in the payload $P$ at step 7 is a result of using AES-GCM-256, which is selected in ECIES implementation in the Rust crate we consume through ecies/rs-wasm package.
+
+### Workflow: Receiving a file
+
+TBE