Merge pull request #19 from panyongxu1002/main

add market typescript guide

docs/.vitepress/config.mts

@@ -20,6 +20,14 @@ export default defineConfig({
       { text: '主页', link: '/' },
       { text: 'Awesome-Fuel', link: 'https://fuellabs.notion.site/Awesome-Fuel-7b4ca6b262d3414a9968f275cba43fc9' },
       // {
+      //   text: "示例",
+      //   items: [
+      //     { text: "构建市场dApp", link: "/sway-market" },
+      //     // { text: "v0.0.2", link: "" },
+      //     // { text: "v0.0.3", link: "" },
+      //   ],
+      // },
+      // {
       //   text: "版本",
       //   items: [
       //     { text: "v0.0.1", link: "" },
@@ -700,6 +708,26 @@ export default defineConfig({
 
 
       ],
+      "/sway-applications" : [
+        {
+          text: '构建市场dApp',
+          link: '/sway-applications/market/index',
+          collapsed: true,
+          items: [
+            { text: '基础条件', link: '/sway-applications/market/prerequisites' },
+            { text: '项目导入', link: '/sway-applications/market/imports' },
+            { text: '定义商品结构', link: '/sway-applications/market/structs' },
+            { text: '定义存储块', link: '/sway-applications/market/storage' },
+            { text: '定义错误处理', link: '/sway-applications/market/errors' },
+            { text: '定义合约函数', link: '/sway-applications/market/functions' },
+            { text: '合约检查站', link: '/sway-applications/market/checkpoint' },
+            { text: '合约测试', link: '/sway-applications/market/test' },
+            { text: '构建前端', link: '/sway-applications/market/typescript_frontend' },
+
+
+          ]
+        },
+      ]
     },
     socialLinks: [
       { icon: 'github', link: 'https://github.com/fuelchina/webdoc' },

docs/index.md

@@ -16,6 +16,9 @@ hero:
     - theme: alt
       text: Sway Example 中文教程
       link: /sway-example/index
+    - theme: alt
+      text: Sway applications 中文教程
+      link: /sway-applications/market/index
 
 features:
   - icon: 🎉

docs/sway-applications/index.md

@@ -0,0 +1 @@
+这是sway应用示例的首页。

docs/sway-applications/market/checkpoint.md

@@ -0,0 +1,218 @@
+# 合约检查站
+
+## Sway 合约检查点
+如果您已正确执行上述步骤，则您的main.sw市场合约应如下所示：
+
+```sway
+contract;
+ 
+use std::{
+    auth::msg_sender,
+    call_frames::msg_asset_id,
+    context::{
+        msg_amount,
+        this_balance,
+    },
+    asset::transfer,
+    hash::Hash,
+};
+ 
+struct Item {
+    id: u64,
+    price: u64,
+    owner: Identity,
+    metadata: str[20],
+    total_bought: u64,
+}
+ 
+abi SwayStore {
+    // a function to list an item for sale
+    // takes the price and metadata as args
+    #[storage(read, write)]
+    fn list_item(price: u64, metadata: str[20]);
+ 
+    // a function to buy an item
+    // takes the item id as the arg
+    #[storage(read, write), payable]
+    fn buy_item(item_id: u64);
+ 
+    // a function to get a certain item
+    #[storage(read)]
+    fn get_item(item_id: u64) -> Item;
+ 
+    // a function to set the contract owner
+    #[storage(read, write)]
+    fn initialize_owner() -> Identity;
+ 
+    // a function to withdraw contract funds
+    #[storage(read)]
+    fn withdraw_funds();
+ 
+    // return the number of items listed
+    #[storage(read)]
+    fn get_count() -> u64;
+}
+ 
+storage {
+    // counter for total items listed
+    item_counter: u64 = 0,
+ 
+    // map of item IDs to Items
+    item_map: StorageMap<u64, Item> = StorageMap {},
+ 
+    // owner of the contract
+    owner: Option<Identity> = Option::None,
+}
+ 
+enum InvalidError {
+    IncorrectAssetId: AssetId,
+    NotEnoughTokens: u64,
+    OnlyOwner: Identity,
+}
+ 
+impl SwayStore for Contract {
+    #[storage(read, write)]
+    fn list_item(price: u64, metadata: str[20]) {
+        
+        // increment the item counter
+        storage.item_counter.write(storage.item_counter.try_read().unwrap() + 1);
+        
+        // get the message sender
+        let sender = msg_sender().unwrap();
+        
+        // configure the item
+        let new_item: Item = Item {
+            id: storage.item_counter.try_read().unwrap(),
+            price: price,
+            owner: sender,
+            metadata: metadata,
+            total_bought: 0,
+        };
+ 
+        // save the new item to storage using the counter value
+        storage.item_map.insert(storage.item_counter.try_read().unwrap(), new_item);
+    }
+ 
+    #[storage(read, write), payable]
+    fn buy_item(item_id: u64) {
+        // get the asset id for the asset sent
+        let asset_id = msg_asset_id();
+ 
+        // require that the correct asset was sent
+        require(asset_id == AssetId::base(), InvalidError::IncorrectAssetId(asset_id));
+ 
+        // get the amount of coins sent
+        let amount = msg_amount();
+ 
+        // get the item to buy
+        let mut item = storage.item_map.get(item_id).try_read().unwrap();
+ 
+        // require that the amount is at least the price of the item
+        require(amount >= item.price, InvalidError::NotEnoughTokens(amount));
+ 
+        // update the total amount bought
+        item.total_bought += 1;
+ 
+        // update the item in the storage map
+        storage.item_map.insert(item_id, item);
+ 
+        // only charge commission if price is more than 0.1 ETH
+        if amount > 100_000_000 {
+            // keep a 5% commission
+            let commission = amount / 20;
+            let new_amount = amount - commission;
+            // send the payout minus commission to the seller
+            transfer(item.owner, asset_id, new_amount);
+        } else {
+            // send the full payout to the seller
+            transfer(item.owner, asset_id, amount);
+        }
+    }
+ 
+    #[storage(read)]
+    fn get_item(item_id: u64) -> Item {
+        // returns the item for the given item_id
+        return storage.item_map.get(item_id).try_read().unwrap();
+    }
+ 
+    #[storage(read, write)]
+    fn initialize_owner() -> Identity {
+        let owner = storage.owner.try_read().unwrap();
+        
+        // make sure the owner has NOT already been initialized
+        require(owner.is_none(), "owner already initialized");
+        
+        // get the identity of the sender        
+        let sender = msg_sender().unwrap(); 
+ 
+        // set the owner to the sender's identity
+        storage.owner.write(Option::Some(sender));
+        
+        // return the owner
+        return sender;
+    }
+ 
+    #[storage(read)]
+    fn withdraw_funds() {
+        let owner = storage.owner.try_read().unwrap();
+ 
+        // make sure the owner has been initialized
+        require(owner.is_some(), "owner not initialized");
+        
+        let sender = msg_sender().unwrap(); 
+ 
+        // require the sender to be the owner
+        require(sender == owner.unwrap(), InvalidError::OnlyOwner(sender));
+        
+        // get the current balance of this contract for the base asset
+        let amount = this_balance(AssetId::base());
+ 
+        // require the contract balance to be more than 0
+        require(amount > 0, InvalidError::NotEnoughTokens(amount));
+        
+        // send the amount to the owner
+        transfer(owner.unwrap(), AssetId::base(), amount);
+    }
+ 
+    #[storage(read)]
+    fn get_count() -> u64 {
+        return storage.item_counter.try_read().unwrap();
+    }
+}
+```
+
+## 建立合同
+以下是您的说明的精美版本：
+
+要格式化合同，请执行以下命令：
+
+```sway
+forc fmt
+```
+
+若要编译合约，请进入到合约文件夹并运行：
+
+```sway
+forc build
+```
+
+祝贺！您已在 Sway 中成功编写了完整的合同！
+
+编译后，系统会自动生成abi.json, storage_slots.json和contract.bin.您可以在以下目录中找到这些文件：
+
+```sway
+contract/out/debug/*
+```
+
+## 部署协定
+有关部署此合约的详细步骤，请参阅官方 Fuel 开发者计数器 dapp 指南： 
+部署合约
+
+要部署，如果您已经设置了 forc-wallet 并且您的账户中有测试网资金，请使用以下命令。
+
+```sway
+forc deploy --testnet
+```
+
+
+部署后，你将能够看到 contract/out/deployments 文件夹。前端集成的时候需要它。

docs/sway-applications/market/errors.md

@@ -0,0 +1,27 @@
+# 定义错误处理
+
+**enum**（通常称为枚举）是一种可以表示几种可能变体之一的类型。在我们的合约中，我们可以使用枚举来制作自定义错误消息，从而促进函数中更精确的错误处理。
+
+将自定义错误块复制到您的main.sw文件：
+
+```sway
+enum InvalidError {
+    IncorrectAssetId: AssetId,
+    NotEnoughTokens: u64,
+    OnlyOwner: Identity,
+}
+```
+
+在我们的合约中，我们可以预测各种情况，在这些情况下，我们想要抛出错误并停止交易：
+
+  1. 有人可能会尝试使用不正确的货币支付商品。
+  2. 个人可以在没有足够硬币的情况下尝试购买物品。
+  3. 所有者以外的其他人可能会尝试从合同中提取资金。
+
+
+对于每种情况，我们可以为错误定义特定的返回类型：
+
+  对于 IncorrectAssetId 错误，我们可以返回提交的资产 ID，其类型为 AssetId. <br>
+  在 NotEnoughTokenserror ，我们可以将返回类型定义为 u64 以表示涉及的硬币数量。<br>
+  对于 OnlyOwner 错误，我们可以利用 Identity 作为返回值的消息发送者。
+