Merge pull request #6 from DeAccountSystems/docs

docs: improve documents
dotbitHQ · Aug 5, 2021 · 81375d7 · 81375d7
2 parents 3f0048a + 7e2a3bd
commit 81375d7
Show file tree

Hide file tree

Showing 20 changed files with 1,406 additions and 282 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,21 @@
 # das-contracts
 
+![Version](https://img.shields.io/github/release/DeAccountSystems/das-contracts.svg)
+![License](https://img.shields.io/github/license/DeAccountSystems/das-contracts.svg)
+[![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/DASystemsNews)
+[![Discord](https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/WVunwT2hju)
+[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/realDASystems)
+
+This repository is open source for DAS contracts which also called "type script" in CKB. They can only execute in 
+[ckb-vm](https://github.com/nervosnetwork/ckb-vm) environment which a pure software implementation of the RISC-V 
+instruction set.
+
+
+## About DAS
+
+DAS is a blockchain-based, open source, censorship-resistant decentralized account system that provides a globally unique naming system with a .bit suffix that can be used for cryptocurrency transfers, domain name resolution, authentication, and other scenarios.
+
+Now DAS has been deployed on CKB mainnet which named **Lina** and launched from **2021-07-22** 🎉 .
 
 ## Development
 
@@ -40,18 +56,28 @@ All tests are divided into three categories:
 The prefix is design for running different categories of tests separately: 
 
 ``` sh
-cargo test -p tests test_ -- --nocapture --test-threads=1
-cargo test -p tests challenge_ -- --nocapture --test-threads=1
+cargo test -p tests gen_
+cargo test -p tests test_
+cargo test -p tests challenge_
 ```
 
-> Do not use `capsule build` and `capsule test` for performance reasons.
+> DO NOT use `capsule build` and `capsule test` for performance reasons.
 
 ### BE CAREFUL!
 
 - DO NOT use `ckb_types::bytes`, IDE may treat it as `bytes-v0.5.6`, but it is `molecule::bytes` indeed, that is just a simple wrapper for `Vec<u8>`.
 - DO NOT use `bytes-v0.5.6`, it will cause `VM Internal Error: InvalidInstruction(335951151)` for some reasons.
 
+### Documents
+
+- For details about price, preserved accounts and so on, please see: https://docs.da.systems/docs/v/English/
+- To learn more about data structures, protocols and other technical details, please see documents in [docs/](docs) directory of this repository.
+- It's a good idea to start with their RFCs to learn more about all aspects of CKB: https://github.com/nervosnetwork/rfcs
+- Other things may helps you a lot when develop contracts:
+  - CKB VM Error Codes: https://github.com/nervosnetwork/ckb-system-scripts/wiki/Error-codes
+  - CKB JSON-RPC Protocols: https://github.com/nervosnetwork/ckb/tree/develop/rpc
+
 
-## Documents
+## License
 
-- CKB VM Error Codes: https://github.com/nervosnetwork/ckb-system-scripts/wiki/Error-codes
+This repository is released under the terms of the MIT license. See [LICENSE](LICENSE) for more information or see https://choosealicense.com/licenses/mit/.
diff --git a/docs/en/DAS-account-lifecycle.png b/docs/en/DAS-account-lifecycle.png
diff --git a/docs/en/DAS-account-structure.png b/docs/en/DAS-account-structure.png
diff --git a/docs/en/DAS-big-picture.png b/docs/en/DAS-big-picture.png
diff --git a/docs/en/DAS-register-process.png b/docs/en/DAS-register-process.png
diff --git a/docs/en/Data-Structure-and-Protocol/Formulas.md b/docs/en/Data-Structure-and-Protocol/Formulas.md
@@ -0,0 +1,68 @@
+# Formulas
+
+
+## Total Amount of PreRegister Transaction
+
+Users are required to pay both **storage fee** and **registration fee** when executing a [PreRegister](./Transaction-Structure.md#PreRegister) transaction. Whatever crypto currency the user is paying, it must be exchanged to CKB before this transaction. The detail formula is:
+
+```
+// All numbers in the following pseudo-code are of type uint64
+storage_fee = (AccountCell_basic_capacity + bytes_of_account + 4) * 100_000_000 + prepared_fee
+amount = storage_fee + registration_fee
+
+// Among them, the registration_fee must meet the following conditions
+if annual_price_in_USD < exchange_rate_of_CKB {
+  annual_price_in_CKB = annual_price_in_USD * 100_000_000 / exchange_rate_of_CKB
+} else {
+  annual_price_in_CKB = annual_price_in_USD / exchange_rate_of_CKB * 100_000_000
+}
+annual_price_in_CKB = annual_price_in_CKB - (annual_price_in_CKB * invited_discount_rate / 10000)
+
+assert(registration_fee >= annual_price_in_CKB)
+```
+
+- **AccountCell_basic_capacity** can be retrieved from `ConfigCellAccount.basic_capacity`.
+- **prepared_fee** can be retrieved from `ConfigCellAccount.prepared_fee_capacity`.
+- **annual_price_in_USD** can be retrieved from `ConfigCellPrice.prices` , its unit is **USDT**.
+- **exchange_rate_of_CKB** can be retrieved from [QuoteCell](./Cell-Structure.md#QuoteCell) , its unit is **USDT/CKB**.
+- **invited_discount_rate** can be retrieved from `ConfigCellAccount.discount`.
+- The total amount is stored in `PreAccountCell.capacity` during the entire registration process.
+- The registration fee must be greater than or equal to the annual fee for one year, i.e. a minimum of one year must be registered.
+
+
+## Duration Calculation After Registerd/Renewed
+
+After a successful registration or renewal of an account, the duration which the account finally received will be calculated according to the following formula:
+
+```
+// All numbers in the following pseudo-code are of type uint64
+if annual_price_in_USD < exchange_rate_of_CKB {
+  annual_price_in_CKB = annual_price_in_USD * 100_000_000 / exchange_rate_of_CKB
+} else {
+  annual_price_in_CKB = annual_price_in_USD / exchange_rate_of_CKB * 100_000_000
+}
+annual_price_in_CKB = annual_price_in_CKB - (annual_price_in_CKB * discount_rate / 10000)
+
+duration_received = registration_fee * 365 / annual_price_in_CKB * 86400
+```
+
+
+## Profit Distribution upon Successful Registration
+
+When an account is successfully registered, the registration fees carried in the PreAccountCell will be distributed to the various participants in a specific percentage, and the percentage of profit for each role can be found in ConfigCellProfitRate：
+
+```
+// All numbers in the following pseudo-code are of type uint64
+profit = registration_fee
+
+if is_inviter_exist {
+  profit_of_inviter = profit * inviter_profit_rate
+}
+if is_channel_exist {
+  profit_of_channel = profit * channel_profit_rate
+}
+profit_of_proposal_creator = profit * proposal_creator_profit_rate
+profit_of_proposal_confirmer = profit * proposal_confirmer_profit_rate
+
+profit_of_DAS = profit - profit_of_inviter - profit_of_channel - profit_of_proposal_creator - profit_of_proposal_confirmer
+```