開箱 Aptos 第一個範例程式

作者:師大科技系 PecuLab 蔡芸琤 (Pecu)

前情提要,請參考【成為 Aptos 公鏈開發者的第一步】

從官方文件中,可找到原始碼路徑為 https://github.com/aptos-labs/aptos-core/blob/main/sdk/examples/transfer-coin.rs

本文將以此範例程式來帶各位讀者理解 Rust 語言的思維。

Rust 語言的官方文件 https://doc.rust-lang.org/book/ 裡面有更詳盡的語法使用說明,本文不以單一語法逐步介紹 Rust,而是以 Aptos 第一個範例中要達成的執行目標,來說明 Rust 如何實現的。

回顧一下前情提要中的執行結果:

  1. 初始化 Representational State Transfer (REST) 和 Aptos 水龍頭。
  2. 創建兩個帳戶,Alice 和 Bob。
  3. 從水龍頭為 Alice 的帳戶提供 100000000 個 Token。
  4. Alice 轉移 1000 個 Token 給 Bob,此次轉帳由 Alice 支付 54100 個 Token 做為手續費,所以,Alice 的帳戶剩下 99944900 個 Token。
  5. 再重複一次,Alice 轉移 1000 個 Token 給 Bob,此次轉帳由 Alice 支付 54100 個 Token 做為手續費,最終,Alice 的帳戶剩下 99889800 個 Token。

為了達成上述的五項描述,Aptos 公鏈上已經幫各位開發者建立好【連上鏈】和到【水龍頭】領測試幣的工具包,我們只需要知道如何調用即可。

額外補充,所有 Aptos 提供的 Typescript SDK 工具包 (Rust SDK 還沒看到,若之後有發現,再補上來),都可在此找到定義及使用方式 https://aptos-labs.github.io/ts-sdk-doc/modules.html

這份範例程式測試鏈使用的 Aptos REST API,可在此 https://fullnode.devnet.aptoslabs.com/v1/spec#/ 找到所有細節與說明。

範例程式中的第 4 到第 10 行,是這份範例程式中所使用到的工具包。

Rust 調用工具包的語法為【use】,更詳細的官方文件請參考,https://doc.rust-lang.org/book/ch07-04-bringing-paths-into-scope-with-the-use-keyword.html?highlight=%22The%20use%20keyword%22#bringing-paths-into-scope-with-the-use-keyword

use anyhow::{Context, Result};
use aptos_sdk::coin_client::CoinClient;                             use aptos_sdk::rest_client::{Client, FaucetClient};                             use aptos_sdk::types::LocalAccount;
use once_cell::sync::Lazy;
use std::str::FromStr;
use url::Url;

範例程式中的第 13 到 21 行,是定義【如何連結哪個鏈上】。

static NODE_URL: Lazy<Url> = Lazy::new(|| {
    Url::from_str(
        std::env::var("APTOS_NODE_URL")
            .as_ref()
            .map(|s| s.as_str())
            .unwrap_or("https://fullnode.devnet.aptoslabs.com"),
    )
    .unwrap()
});

以上的所有語法,都可以直接在 https://doc.rust-lang.org/std/all.html 查閱。例如,不清楚甚麼是 std::env::var,就直接搜尋,畫面如下:

在 Rust 找到了 std::env::var 的定義與使用方式,就知道這是個可以回報環境錯誤訊息的變數宣告。

範例程式會使用這個宣告來和 Aptos 公鏈透過 REST API https://fullnode.devnet.aptoslabs.com 互動,是為了要知道,如果這個公鏈背後有甚麼狀況,可以回傳錯誤訊息到調用這個範例程式中,開發者才能知道錯誤是在自己的程式本身,還是發生在連結的公鏈上。

若是 Aptos 公鏈所建立的 REST API,定義及使用方式請參閱https://fullnode.devnet.aptoslabs.com/v1/spec#/

Aptos 目前的開法者測試鏈可在 https://github.com/aptos-labs/aptos-networks 找到官方說明。

範例程式中的第 23 到 21 行,是定義【如何拿水龍頭的測試幣】。

為了不要讓文章太冗長,接下來就不再貼程式碼到文章中,請自行參照 https://github.com/aptos-labs/aptos-core/blob/main/sdk/examples/transfer-coin.rs 範例程式的行數來對應本文的說明。

水龍頭位置 https://faucet.devnet.aptoslabs.com,但這還沒有 web 畫面可以互動直接取得測試幣,要透過 Aptos SDK 撰寫對應的程式來獲得。

範例程式中的第 35 到 139 行,是主程式區,所有的步驟都在這裡面完成。

第 37 行和 38 行先分別初始化連上的 Aptos 公鏈和 Aptos 水龍頭。

第 41 行是初始化 coin_client 這個物件,之後要使用 CoinClient 這個 Class 來查閱錢包的內容,可參考 https://aptos-labs.github.io/ts-sdk-doc/classes/CoinClient.html

一點點物件導向的觀念建立,等於的右邊是調用哪個 Class (屬於定義),透過 new 來將 Class 實體化,放到等於的左邊,就變成之後可以使用的物件。

例如:一隻猴子的特徵定義,就是 Class,但真的把一隻猴子生出來,就是物件。

第 45 行和第 46 行,分別創建兩個帳戶,Alice 和 Bob。

第 49 行到第 51 行,分別印出這兩個帳戶的錢包地址。

第 55 行到第 62 行,分別將這兩個帳戶放上範例程式所連上的公鏈,並從水龍頭中拿 100000000 個 Token 給 Alice,Bob 沒有放入任何 Token。

第 65 行到第 79 行,分別印出目前這兩個帳戶的錢包餘額。

第 82 行到第 89 行,Alice 轉移 1000 個 Token 給 Bob,此次轉帳由 Alice 支付 54100 個 Token 做為手續費。

第 92 行到第 107 行,印出目前兩個錢包餘額,因為進行過一次轉帳,所以,Alice 的帳戶剩下 99944900 個 Token。

第 111 行到第 119 行,再重複一次,Alice 轉移 1000 個 Token 給 Bob,此次轉帳由 Alice 支付 54100 個 Token 做為手續費。

第 122 行到第 136 行,分別再印出目前這兩個帳戶的錢包餘額。

第 138 行,完成這份範例,Rust 回傳程式正常執行完畢,細節可參考 https://doc.rust-lang.org/std/result/

 

複習上述提過的,重要語法參考區,初學者容易搞混,請參照上述的段落提示,感受一下哪些語法是要去哪裡查。

1. Rust 原生語法:https://doc.rust-lang.org/std/all.html
2. Aptos REST API:https://fullnode.devnet.aptoslabs.com/v1/spec#/
3. Aptos Typescript SDK:https://aptos-labs.github.io/ts-sdk-doc/modules.html

下篇文章,PecuLab 預計開箱 Move Module,開始帶著新手了解 Aptos 上的智能合約如何寫,下個周末再見囉!