chore: add more documents

Author: zensh

Makefile

@@ -9,6 +9,9 @@ lint:
 fix:
 	@cargo clippy --fix --workspace --tests
 
+test:
+	@cargo test --workspace -- --nocapture
+
 # cargo install twiggy
 twiggy:
 	twiggy top -n 12 target/wasm32-unknown-unknown/release/ic_panda_luckypool.wasm

README.md

@@ -1,5 +1,11 @@
 # ICPanda DAO
-🐼 A decentralized Panda meme brand built on the Internet Computer.
+🐼 A decentralized Panda meme platform featuring E2E encrypted messaging, lucky draws, airdrops.
+
+## dMsg (ICPanda Message)
+
+[dMsg System Overview](./docs/dMsg_system_overview.md)
+
+[dMsg Design Choices](./docs/dMsg_design_choices.md)
 
 ## Whitepaper
 
@@ -26,7 +32,6 @@
 |                  | -- **10%** | -- 100,000,000 | CEX Incentive                                                                                                                                           |
 |                  | -- **10%** | -- 100,000,000 | DEX Liquidity                                                                                                                                           |
 
-
 ### Token utility
 
 PANDA is the only token issued by ICPanda DAO. By holding PANDA tokens, users can participate in:
@@ -44,87 +49,5 @@ PANDA is the only token issued by ICPanda DAO. By holding PANDA tokens, users ca
 - Twitter: [https://twitter.com/ICPandaDAO](https://twitter.com/ICPandaDAO)
 - GitHub: [https://github.com/ldclabs/ic-panda](https://github.com/ldclabs/ic-panda)
 
-## Running the project locally
-
-If you want to test your project locally, you can use the following commands:
-
-```bash
-# Starts the replica
-dfx start
-
-# Creates the canisters with the specified IDs
-dfx canister create --specified-id rdmx6-jaaaa-aaaaa-aaadq-cai internet_identity
-dfx canister create --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister
-dfx canister create --specified-id c63a7-6yaaa-aaaap-ab3gq-cai ic_panda_frontend
-dfx canister create --specified-id f75us-gyaaa-aaaap-ab3wq-cai ic_panda_infra
-dfx canister create --specified-id a7cug-2qaaa-aaaap-ab3la-cai ic_panda_luckypool
-dfx canister create --specified-id q5mxo-eyaaa-aaaap-ahfoq-cai ic_panda_ai
-
-# Deploys the ICP Ledger canister with the specified initial values
-dfx identity use default
-export MINTER_ACCOUNT_ID=$(dfx ledger account-id)
-export DEFAULT_ACCOUNT_ID=$(dfx ledger account-id)
-dfx deploy --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister --argument "
-  (variant {
-    Init = record {
-      minting_account = \"$MINTER_ACCOUNT_ID\";
-      initial_values = vec {
-        record {
-          \"$DEFAULT_ACCOUNT_ID\";
-          record {
-            e8s = 21_000_000_000_000_000 : nat64;
-          };
-        };
-      };
-      send_whitelist = vec {};
-      transfer_fee = opt record {
-        e8s = 10_000 : nat64;
-      };
-      token_symbol = opt \"LICP\";
-      token_name = opt \"Local ICP\";
-    }
-  })
-"
-
-# Deploys the ICRC-1 token Ledger canister with the specified initial values
-dfx identity use default
-export MINTER=$(dfx identity get-principal)
-export DEFAULT=$(dfx identity get-principal)
-export ARCHIVE_CONTROLLER=$(dfx identity get-principal)
-export TOKEN_NAME="ICPanda"
-export TOKEN_SYMBOL="PANDA"
-export PRE_MINTED_TOKENS=100_000_000_000_000_000
-export TRANSFER_FEE=10_000
-export TRIGGER_THRESHOLD=2000
-export NUM_OF_BLOCK_TO_ARCHIVE=1000
-export CYCLE_FOR_ARCHIVE_CREATION=10000000000000
-export FEATURE_FLAGS=true
-
-dfx deploy icrc1_ledger_canister --specified-id druyg-tyaaa-aaaaq-aactq-cai --argument "(variant {Init =
-record {
-     token_symbol = \"${TOKEN_SYMBOL}\";
-     token_name = \"${TOKEN_NAME}\";
-     minting_account = record { owner = principal \"${MINTER}\" };
-     transfer_fee = ${TRANSFER_FEE};
-     metadata = vec {};
-     feature_flags = opt record{icrc2 = ${FEATURE_FLAGS}};
-     initial_balances = vec { record { record { owner = principal \"${DEFAULT}\"; }; ${PRE_MINTED_TOKENS}; }; };
-     archive_options = record {
-         num_blocks_to_archive = ${NUM_OF_BLOCK_TO_ARCHIVE};
-         trigger_threshold = ${TRIGGER_THRESHOLD};
-         controller_id = principal \"${ARCHIVE_CONTROLLER}\";
-         cycles_for_archive_creation = opt ${CYCLE_FOR_ARCHIVE_CREATION};
-     };
- }
-})"
-
-# Deploys other canisters
-dfx deploy
-```
-
-Open the frontend in your default browser
-
-http://c63a7-6yaaa-aaaap-ab3gq-cai.localhost:4943/
-
 ## License
 Copyright © 2024 [LDC Labs](https://github.com/ldclabs).

diagrams/dMsg_channels_data_flow.png

@@ -0,0 +1,25 @@
+# dMsg (ICPanda Message) Design Choices
+
+## CBOR
+
+The Concise Binary Object Representation ([CBOR, RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949)) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.
+
+The Internet Computer source code also makes extensive use of CBOR. All dMsg smart contracts and the client use CBOR as the primary data serialization format.
+
+## COSE
+
+COSE ([RFC 9052](https://datatracker.ietf.org/doc/html/rfc9052), [RFC 9053](https://datatracker.ietf.org/doc/html/rfc9053)) is a standard for signing and encrypting data in the CBOR data format. It is designed to be simple and efficient, and to be usable in constrained environments. It is intended to be used in a variety of applications, including the Internet of Things, and is designed to be extensible to support new algorithms and applications.
+
+dMsg uses COSE as the standard for message encryption and key exchange.
+
+## IC-COSE
+
+[IC-COSE](https://github.com/ldclabs/ic-cose) is a decentralized COnfiguration service with Signing and Encryption on the Internet Computer.
+
+After registering a username, dMsg users gain a dedicated namespace on the COSE service for key derivation, key storage, and other confidential information.
+
+## IC-OSS
+
+[IC-OSS](https://github.com/ldclabs/ic-oss) is a decentralized Object Storage Service on the Internet Computer.
+
+dMsg uses IC-OSS to store user avatars, channel logos, and channel files. Each channel has a dedicated folder on the OSS service for file storage.

diagrams/dMsg_component_interaction.png

@@ -0,0 +1,65 @@
+# dMsg (ICPanda Message) System Overview
+
+![dMsg System Overview](../diagrams/dMsg_component_interaction.png)
+
+## dMsg On-Chain Side
+
+### Backend Smart Contracts
+
+- Management canister:
+  - Source code: [ic_message](../src/ic_message)
+  - Description: The management canister that handles users management, canisters management, price management and channels management.
+  - `ic_message` canister: [nscli-qiaaa-aaaaj-qa4pa-cai](https://dashboard.internetcomputer.org/canister/nscli-qiaaa-aaaaj-qa4pa-cai)
+- User public profile canister:
+  - Source code: [ic_message_profile](../src/ic_message_profile)
+  - Description: The profile canister that handles user public profiles management. The number of profile canisters can be increased based on user scale.
+  - `ic_message_profile` Canister: [ijyxz-wyaaa-aaaaj-qa4qa-cai](https://dashboard.internetcomputer.org/canister/ijyxz-wyaaa-aaaaj-qa4qa-cai)
+- Channel canister:
+  - Source code: [ic_message_channel](../src/ic_message_channel)
+  - Description: The channel canister that handles channels management and messages management. The number of channel canisters can be increased based on user scale.
+  - `ic_message_channel` canister: [nvdn4-5qaaa-aaaaj-qa4pq-cai](https://dashboard.internetcomputer.org/canister/nvdn4-5qaaa-aaaaj-qa4pq-cai)
+  - `ic_message_channel_02` canister: [zof5a-5yaaa-aaaai-acr2q-cai](https://dashboard.internetcomputer.org/canister/zof5a-5yaaa-aaaai-acr2q-cai)
+  - `ic_message_channel_03` canister: [4jxyd-pqaaa-aaaah-qdqtq-cai](https://dashboard.internetcomputer.org/canister/4jxyd-pqaaa-aaaah-qdqtq-cai)
+- COSE canister:
+  - Source code: [ic-cose](https://github.com/ldclabs/ic-cose)
+  - Description: IC-COSE is a decentralized COnfiguration service with Signing and Encryption on the Internet Computer. Users who register a username gain a dedicated namespace on the COSE service for key derivation, key storage, and other confidential information. The number of COSE canisters can be increased based on user scale.
+  - `ic_cose_canister` canister: [n3bau-gaaaa-aaaaj-qa4oq-cai](https://dashboard.internetcomputer.org/canister/n3bau-gaaaa-aaaaj-qa4oq-cai)
+- OSS canister:
+  - Source code: [ic-oss](https://github.com/ldclabs/ic-oss)
+  - Description: IC-OSS is a decentralized Object Storage Service on the Internet Computer. Channels have a dedicated folder on the OSS service to store files. The number of IC-OSS bucket canisters can be increased based on user scale.
+  - `ic_oss_cluster` canister: [5szpn-tiaaa-aaaaj-qncoq-cai](https://dashboard.internetcomputer.org/canister/5szpn-tiaaa-aaaaj-qncoq-cai)
+  - `ic_oss_bucket` canister: [532er-faaaa-aaaaj-qncpa-cai](https://dashboard.internetcomputer.org/canister/532er-faaaa-aaaaj-qncpa-cai)
+  - `ic_oss_bucket_02` canister: [sb6zj-3aaaa-aaaaj-qndla-cai](https://dashboard.internetcomputer.org/canister/sb6zj-3aaaa-aaaaj-qndla-cai)
+
+### Channels Management and Access Control
+
+![Channels](../diagrams/dMsg_channels_data_flow.png)
+
+- No public channels.
+- After creating a channel, multiple managers and regular members can be invited.
+- Managers can remove regular members but cannot remove other managers.
+- Users can read channel info and all (encrypted) messages only after joining.
+- After joining, users use ECDH to obtain the KEK from managers for encrypting and decrypting the DEK.
+- Users encrypt and decrypt messages and files with the DEK on the client side.
+- The channel and its data are deleted when the last manager leaves.
+- Sending messages and uploading files consume Gas.
+
+## dMsg Client Side
+
+### Master Key Derivation
+
+![Master key](../diagrams/dMsg_mk_data_flow.png)
+
+The client supports three types of master keys:
+- **Free users**: The master key (I) is generated using an on-chain derived IV and the user’s password. `MK = HKDF-SHA-256(argon2id(password, ID), IV)`
+- **Paid users**: The master key (II) is generated using an on-chain derived PK and the user’s password. `MK = HKDF-SHA-256(argon2id(password, ID), PK)`
+- **Paid users (with vetkey)**: Once the vetkey feature is live, the master key (III) will be generated using an on-chain derived vetkey and an optional user password. `MK = HKDF-SHA-256(argon2id(password, ID), Vetkey)`
+
+### Key Encryption Key (KEK) Exchanging
+
+![KEK Exchanging](../diagrams/dMsg_kek_exchanging_data_flow.png)
+
+- The MK encrypts and decrypts the KEK.
+- The KEK is used to encrypt and decrypt the DEK for message channels, with a 1:1 mapping.
+- The encryption scheme follows AES-256-GCM as defined in RFC 9053 (COSE).
+- The exchanging scheme follows ECDH-ES + X25519 as defined in RFC 9053 (COSE).

diagrams/dMsg_kek_exchanging_data_flow.png

@@ -0,0 +1,90 @@
+# Deployment Guide
+
+## Running the project locally
+
+If you want to test your project locally, you can use the following commands:
+
+```bash
+# Starts the replica
+dfx start
+
+# Creates the canisters with the specified IDs
+dfx canister create --specified-id rdmx6-jaaaa-aaaaa-aaadq-cai internet_identity
+dfx canister create --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister
+dfx canister create --specified-id c63a7-6yaaa-aaaap-ab3gq-cai ic_panda_frontend
+dfx canister create --specified-id a7cug-2qaaa-aaaap-ab3la-cai ic_panda_luckypool
+dfx canister create --specified-id nscli-qiaaa-aaaaj-qa4pa-cai ic_message
+dfx canister create --specified-id nvdn4-5qaaa-aaaaj-qa4pq-cai ic_message_channel
+dfx canister create --specified-id ijyxz-wyaaa-aaaaj-qa4qa-cai ic_message_profile
+dfx canister create --specified-id 2fvu6-tqaaa-aaaap-akksa-cai ic_message_frontend
+dfx canister create --specified-id n3bau-gaaaa-aaaaj-qa4oq-cai ic_cose_canister
+dfx canister create --specified-id 5szpn-tiaaa-aaaaj-qncoq-cai ic_oss_cluster
+dfx canister create --specified-id 532er-faaaa-aaaaj-qncpa-cai ic_oss_bucket
+
+# Deploys the ICP Ledger canister with the specified initial values
+dfx identity use default
+export MINTER_ACCOUNT_ID=$(dfx ledger account-id)
+export DEFAULT_ACCOUNT_ID=$(dfx ledger account-id)
+dfx deploy --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister --argument "
+  (variant {
+    Init = record {
+      minting_account = \"$MINTER_ACCOUNT_ID\";
+      initial_values = vec {
+        record {
+          \"$DEFAULT_ACCOUNT_ID\";
+          record {
+            e8s = 21_000_000_000_000_000 : nat64;
+          };
+        };
+      };
+      send_whitelist = vec {};
+      transfer_fee = opt record {
+        e8s = 10_000 : nat64;
+      };
+      token_symbol = opt \"LICP\";
+      token_name = opt \"Local ICP\";
+    }
+  })
+"
+
+# Deploys the ICRC-1 token Ledger canister with the specified initial values
+dfx identity use default
+export MINTER=$(dfx identity get-principal)
+export DEFAULT=$(dfx identity get-principal)
+export ARCHIVE_CONTROLLER=$(dfx identity get-principal)
+export TOKEN_NAME="ICPanda"
+export TOKEN_SYMBOL="PANDA"
+export PRE_MINTED_TOKENS=100_000_000_000_000_000
+export TRANSFER_FEE=10_000
+export TRIGGER_THRESHOLD=2000
+export NUM_OF_BLOCK_TO_ARCHIVE=1000
+export CYCLE_FOR_ARCHIVE_CREATION=10000000000000
+export FEATURE_FLAGS=true
+
+dfx deploy icrc1_ledger_canister --specified-id druyg-tyaaa-aaaaq-aactq-cai --argument "(variant {Init =
+record {
+     token_symbol = \"${TOKEN_SYMBOL}\";
+     token_name = \"${TOKEN_NAME}\";
+     minting_account = record { owner = principal \"${MINTER}\" };
+     transfer_fee = ${TRANSFER_FEE};
+     metadata = vec {};
+     feature_flags = opt record{icrc2 = ${FEATURE_FLAGS}};
+     initial_balances = vec { record { record { owner = principal \"${DEFAULT}\"; }; ${PRE_MINTED_TOKENS}; }; };
+     archive_options = record {
+         num_blocks_to_archive = ${NUM_OF_BLOCK_TO_ARCHIVE};
+         trigger_threshold = ${TRIGGER_THRESHOLD};
+         controller_id = principal \"${ARCHIVE_CONTROLLER}\";
+         cycles_for_archive_creation = opt ${CYCLE_FOR_ARCHIVE_CREATION};
+     };
+ }
+})"
+
+# Deploys other canisters
+dfx deploy
+
+# TODO: Add the following command to configure the dMsg canisters
+```
+
+Open the frontend in your default browser
+
+http://2fvu6-tqaaa-aaaap-akksa-cai.localhost:4943/