Rust SDK 快速入门

注意

完整的示例代码可在页面底部的完整快速入门代码中找到。

1. 创建新项目

   使用 Cargo 创建一个新的 Rust 项目：

   cargo new aptos-quickstart && cd aptos-quickstart

2. 添加依赖

   打开 Cargo.toml，添加 Aptos SDK 以及用于异步运行时的 tokio 和用于错误处理的 anyhow：

   [dependencies]
   aptos-sdk = { git = "https://github.com/aptos-labs/aptos-rust-sdk", package = "aptos-sdk" }
   tokio = { version = "1", features = ["full"] }
   anyhow = "1"

3. 设置 Aptos 客户端

   Aptos 客户端负责处理与 Aptos 网络的所有通信。通过传入指定连接网络的 AptosConfig 来创建客户端。

   use aptos_sdk::{Aptos, AptosConfig};
   use aptos_sdk::account::Ed25519Account;
   
   #[tokio::main]
   async fn main() -> anyhow::Result<()> {
       println!("This example will create two accounts (Alice and Bob), fund them, and transfer APT between them.");
   
       // Connect to testnet
       let aptos = Aptos::new(AptosConfig::testnet())?;
   
       Ok(())
   }

   注意

   您可以使用 AptosConfig::devnet()、AptosConfig::mainnet() 或 AptosConfig::local() 代替 AptosConfig::testnet() 来连接不同的网络。

4. 创建并充值账户

   生成两个新的 Ed25519 账户。在测试网和开发网上，您可以使用水龙头以编程方式为账户充值，水龙头会向您的新账户发送测试 APT。为账户充值的同时也会在链上创建该账户。

   // Generate two new accounts
   let alice = Ed25519Account::generate();
   let bob = Ed25519Account::generate();
   
   println!("\n=== Addresses ===\n");
   println!("Alice's address is: {}", alice.address());
   println!("Bob's address is: {}", bob.address());
   
   // Fund the accounts using the testnet faucet
   println!("\n=== Funding accounts ===\n");
   aptos.fund_account(alice.address(), 100_000_000).await?;
   aptos.fund_account(bob.address(), 100_000_000).await?;
   println!("Alice and Bob's accounts have been funded!");

   注意

   上述金额以 octas 为单位，octas 是 APT 的最小单位。1 APT = 100,000,000 octas（10^8）。因此 100_000_000 octas 等于 1 APT。

5. 从链上获取数据

   使用 Aptos 客户端查询账户余额。get_balance 方法返回以 octas 为单位的 APT 余额。

   println!("\n=== Initial Balances ===\n");
   let alice_balance = aptos.get_balance(alice.address()).await?;
   let bob_balance = aptos.get_balance(bob.address()).await?;
   println!("Alice's balance: {} octas", alice_balance);
   println!("Bob's balance: {} octas", bob_balance);

6. 转账 APT

   使用 transfer_apt 便捷方法将 APT 从一个账户发送到另一个账户。此方法在一次调用中完成交易的构建、签名、提交和等待。

   // Transfer 0.1 APT (10_000_000 octas) from Alice to Bob
   println!("\n=== Transfer transaction ===\n");
   let result = aptos.transfer_apt(&alice, bob.address(), 10_000_000).await?;
   
   // Verify the transaction succeeded
   let success = result.data.get("success").and_then(|v| v.as_bool()).unwrap_or(false);
   println!("Transaction success: {}", success);

   注意

   转账金额以 octas 为单位。这里 10_000_000 octas 等于 0.1 APT。

7. 验证转账

   获取更新后的余额以确认转账已完成。由于交易需要支付 gas 费用，Alice 的余额会比预期更低。

   println!("\n=== Balances after transfer ===\n");
   let new_alice_balance = aptos.get_balance(alice.address()).await?;
   let new_bob_balance = aptos.get_balance(bob.address()).await?;
   println!("Alice's balance: {} octas", new_alice_balance);
   println!("Bob's balance: {} octas", new_bob_balance);

完整快速入门代码

运行快速入门

cargo run

/// This example shows how to use the Aptos Rust SDK to create accounts,
/// fund them, and transfer APT between them on testnet.
use aptos_sdk::{Aptos, AptosConfig};
use aptos_sdk::account::Ed25519Account;

const ALICE_INITIAL_BALANCE: u64 = 100_000_000;
const BOB_INITIAL_BALANCE: u64 = 100_000_000;
const TRANSFER_AMOUNT: u64 = 10_000_000;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    println!(
        "This example will create two accounts (Alice and Bob), fund them, \
         and transfer APT between them."
    );

    // Setup the client
    let aptos = Aptos::new(AptosConfig::testnet())?;

    // Generate two new accounts
    let alice = Ed25519Account::generate();
    let bob = Ed25519Account::generate();

    println!("\n=== Addresses ===\n");
    println!("Alice's address is: {}", alice.address());
    println!("Bob's address is: {}", bob.address());

    // Fund the accounts using the testnet faucet.
    // Funding an account creates it on-chain.
    println!("\n=== Funding accounts ===\n");
    aptos.fund_account(alice.address(), ALICE_INITIAL_BALANCE).await?;
    aptos.fund_account(bob.address(), BOB_INITIAL_BALANCE).await?;
    println!("Alice and Bob's accounts have been funded!");

    // Look up the newly funded account balances
    println!("\n=== Initial Balances ===\n");
    let alice_balance = aptos.get_balance(alice.address()).await?;
    let bob_balance = aptos.get_balance(bob.address()).await?;
    println!("Alice's balance: {} octas", alice_balance);
    println!("Bob's balance: {} octas", bob_balance);

    // Transfer APT from Alice to Bob
    println!("\n=== Transfer transaction ===\n");
    let result = aptos.transfer_apt(&alice, bob.address(), TRANSFER_AMOUNT).await?;

    // Verify the transaction succeeded
    let success = result
        .data
        .get("success")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    println!("Transaction success: {}", success);

    // Check updated balances
    println!("\n=== Balances after transfer ===\n");
    let new_alice_balance = aptos.get_balance(alice.address()).await?;
    let new_bob_balance = aptos.get_balance(bob.address()).await?;
    println!("Alice's balance: {} octas", new_alice_balance);
    println!("Bob's balance: {} octas", new_bob_balance);

    // Bob should have received the transfer amount
    assert_eq!(
        new_bob_balance,
        BOB_INITIAL_BALANCE + TRANSFER_AMOUNT,
        "Bob's balance after transfer is incorrect"
    );

    // Alice should have less than her initial balance minus the transfer,
    // because gas fees are also deducted
    assert!(
        new_alice_balance < ALICE_INITIAL_BALANCE - TRANSFER_AMOUNT,
        "Alice's balance after transfer is incorrect"
    );

    println!("\nQuickstart complete!");

    Ok(())
}

总结

在本快速入门中，您学习了如何：

1. 使用 Aptos SDK 搭建 Rust 项目。
2. 使用 Aptos 客户端连接到 Aptos 测试网。
3. 生成新的 Ed25519 账户。
4. 使用测试网水龙头为账户充值。
5. 从链上查询账户余额。
6. 使用 transfer_apt 便捷方法在账户之间转账 APT。
7. 验证交易结果和更新后的余额。

注意

完整的 API 文档请参阅 docs.rs 参考。Aptos 结构体是大多数操作的主要入口点。