diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f6b6248 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.obsidian/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..48e647c --- /dev/null +++ b/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/ \ No newline at end of file diff --git a/architecture/1. Elements.md b/architecture/1. Elements.md new file mode 100644 index 0000000..fb595e6 --- /dev/null +++ b/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, + +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]] \ No newline at end of file diff --git a/crypto sysarch.md b/architecture/2. Cryptographic Activities.md similarity index 91% rename from crypto sysarch.md rename to architecture/2. Cryptographic Activities.md index be389da..4052582 100644 --- a/crypto sysarch.md +++ b/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, 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 \ No newline at end of file diff --git a/diagrams/zkl enterprise module legend dark.png b/diagrams/zkl enterprise module legend dark.png new file mode 100644 index 0000000..71b0cb0 Binary files /dev/null and b/diagrams/zkl enterprise module legend dark.png differ diff --git a/diagrams/zkl enterprise module legend light.png b/diagrams/zkl enterprise module legend light.png new file mode 100644 index 0000000..7838bca Binary files /dev/null and b/diagrams/zkl enterprise module legend light.png differ diff --git a/diagrams/zkl module legend dark.png b/diagrams/zkl module legend dark.png index 6b20318..0678448 100644 Binary files a/diagrams/zkl module legend dark.png and b/diagrams/zkl module legend dark.png differ diff --git a/diagrams/zkl module legend light.png b/diagrams/zkl module legend light.png index 5f4b777..7f50810 100644 Binary files a/diagrams/zkl module legend light.png and b/diagrams/zkl module legend light.png differ diff --git a/pdfs/1. Elements.pdf b/pdfs/1. Elements.pdf new file mode 100644 index 0000000..8bacfd0 Binary files /dev/null and b/pdfs/1. Elements.pdf differ diff --git a/pdfs/2. Cryptographic Activities.pdf b/pdfs/2. Cryptographic Activities.pdf new file mode 100644 index 0000000..cddd0b3 Binary files /dev/null and b/pdfs/2. Cryptographic Activities.pdf differ diff --git a/pdfs/crypto sysarch.pdf b/pdfs/crypto sysarch.pdf deleted file mode 100644 index 487bb3b..0000000 Binary files a/pdfs/crypto sysarch.pdf and /dev/null differ