From 320022dd552f9ca0721c820cbd2031b862701d28 Mon Sep 17 00:00:00 2001
From: Liu Zhicong <waterflier@gmail.com>
Date: Mon, 15 Jul 2024 23:22:21 -0700
Subject: [PATCH] add doc comment for DMCBridge.sol

---
 contracts/dmc_bridge.sol | 28 ++++++++++++++++++++++++----
 doc/gwt_mine.py          | 11 +++++++++++
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/contracts/dmc_bridge.sol b/contracts/dmc_bridge.sol
index f40e4bc..03f5237 100644
--- a/contracts/dmc_bridge.sol
+++ b/contracts/dmc_bridge.sol
@@ -7,25 +7,42 @@ import "@openzeppelin/contracts/access/Ownable.sol";
 contract DMCBridge is Ownable {
     DMC public dmc2;
 
-    // DMC1到2的兑换
     mapping(bytes32 => uint256) public dmc1_to_dmc2;
 
     constructor(address _dmc2) Ownable(msg.sender) {
         dmc2 = DMC(_dmc2);
     }
 
+    /**
+     * @dev Retrieves the amount of claimable DMC2 tokens for a given cookie.
+     * @param cookie The cookie associated with the claimable DMC2 tokens.
+     * @return The amount of claimable DMC2 tokens.
+     */
     function getClaimableDMC2(string calldata cookie) public view returns (uint256) {
         return dmc1_to_dmc2[keccak256(abi.encodePacked(msg.sender, cookie))];
     }
 
+    /**
+     * @dev Registers DMC1 transfor request for claimDMC2
+     * @param recvAddress The array of recipient addresses.
+     * @param cookie The array of cookie values associated with each recipient.
+     * @param dmc1Amount The array of DMC1 token amounts to be registered for each recipient.
+     * @notice recvAddress, cookie and dmc1Amount must have the same length
+     */
     function registerDMC1(address[] calldata recvAddress, string[] calldata cookie, uint256[] calldata dmc1Amount) onlyOwner public {
         for (uint i = 0; i < recvAddress.length; i++) {
             dmc1_to_dmc2[keccak256(abi.encodePacked(recvAddress[i], cookie[i]))] = dmc1Amount[i];
-        }
-        
+        }   
     }
 
+    /**
+     * @dev Allows a user to claim DMC2 tokens.
+     * @param cookie The cookie string for authentication.
+     * @notice cookie must same as the one used in registerDMC1
+     */
     function claimDMC2(string calldata cookie) public {
+        // function implementation goes here
+    }
         bytes32 key = keccak256(abi.encodePacked(msg.sender, cookie));
         require(dmc1_to_dmc2[key] > 0, "no dmc1 amount");
         uint256 dmc2Amount = dmc1_to_dmc2[key];
@@ -33,7 +50,10 @@ contract DMCBridge is Ownable {
         
         dmc2.transfer(msg.sender, dmc2Amount);
     }
-
+    
+    /**
+     * @dev Allows the owner to claim remaining DMC2 tokens.
+     */
     function claimRemainDMC2() public onlyOwner {
         dmc2.transfer(msg.sender, dmc2.balanceOf(address(this)));
     }
diff --git a/doc/gwt_mine.py b/doc/gwt_mine.py
index 670d4ed..beed5c9 100644
--- a/doc/gwt_mine.py
+++ b/doc/gwt_mine.py
@@ -1,3 +1,14 @@
+# 算力奖励的核心思路，是资本回报逻辑
+# 矿工出售空间，质押了7500个 GWT，按质押率 3倍来算，在结束时可以得到2500个GWT的收入，那么通过算力奖励，要得到多少附加的GWT》
+# 用户花了2500个GWT购买空间，那么通过算力奖励，其实际开销相当于打了几折呢？
+
+# 因为我们不使用自动匹配机制，所以存在矿工左手倒右手的问题，一共是锁定了10000个GWT，那么其算力奖励的收入在2000GWT到 250GWT之间。
+# 因为不使用自动匹配机制，无存储空间的矿工会Cancel不是自己左手的订单。系统通过增加Cancel时间提高了矿工的资金成本
+# 用户一般不承担Cancel的手续费（因为锁定的资金比矿工少）
+# Fake用户攻击，准备一些GWT，然后不断的去买空间，单不传数据等取消。这样的行为会导致整个DMC网络的实际GWT利用率低下。这样的用户行为是损人不直接利己的，比较适合GWT的大户来提高挖矿难度。
+
+# 算力奖励与price无关，只和质押率有关。也就是说，站在提高算力的角度，系统鼓励高质押率，低价格的存储空间。
+
 # x的含义是当前的增长率
 def mine_gwt(x):
     return 0.2 + (1.8*x) / (x + 1)