Ваша первая транзакция

В этом руководстве описывается, как генерировать и отправлять транзакции в блокчейн Aptos, а также проверять эти отправленные транзакции. Пример transfer-coin, используемый в этом руководстве, создан с помощью Aptos SDKs.

Шаг 1: Выберите SDK

Установите предпочтительный SDK из приведенного ниже списка:

Шаг 2: Запустите пример

Клонируйте репозиторий aptos-core:

git clone https://github.com/aptos-labs/aptos-core.git

Перейдите в каталог примеров Typescript SDK:

cd ~/aptos-core/ecosystem/typescript/sdk/examples/typescriptр

Установите необходимые зависимости:

yarn install

Запустите пример transfer_coin:

yarn run transfer_coin

Перейдите в каталог Python SDK:

cd ~/aptos-core/ecosystem/python/sdk

Установите необходимые зависимости:

curl -sSL https://install.python-poetry.org | python3
poetry update

Запустите пример transfer_coin:

poetry run python -m examples.transfer-coin

Перейдите в каталог Rust SDK:

cd ~/aptos-core/sdk

Запустите пример transfer_coin:

cargo run --example transfer-coin

Шаг 3: Понимание вывода

После выполнения приведенной выше команды появится результат, очень похожий на следующий:

=== Addresses ===
Alice: 0x0baec07bfc42f8018ea304ddc307a359c1c6ab20fbce598065b6cb19acff7043
Bob: 0xc98ceafadaa32e50d06d181842406dbbf518b6586ab67cfa2b736aaddeb7c74f

=== Initial Balances ===
Alice: 20000
Bob: 0

=== Intermediate Balances ===
Alice: 18996
Bob: 1000

=== Final Balances ===
Alice: 17992
Bob: 2000

Приведенный выше вывод демонстрирует, что пример transfer-coin выполняет следующие шаги:

Инициализация клиентов REST и faucet.
Создание двух учетных записей: Alice и Bob.
- Финансирование и создание учетной записи Alice из faucet.
- Создание учетной записи Bob из faucet.
Передача 1000 coins от Alice к Bob.
4 coins газа, оплаченные Alice для осуществления этого перевода.
Еще один перевод 1000 coins от Alice к Bob.
Дополнительные 4 coins газа, заплаченные Alice за этот перевод.

Далее ниже приведено описание функций SDK, которые используются для выполнения описанных выше действий.

Шаг 4: SDK в деталях

Код примера transfer-coin использует вспомогательные функции для взаимодействия с REST API. В этом разделе рассматривается каждый из вызовов и дается представление о функциональности.

СМОТРИТЕ ПОЛНЫЙ КОД Полный код см. в Typescript transfer-coin, следуя приведенным ниже шагам.

СМОТРИТЕ ПОЛНЫЙ КОД Полный код смотрите в Python transfer-coin, выполнив следующие шаги.

СМОТРИТЕ ПОЛНЫЙ КОД Смотрите полный код на Rust transfer-coin, выполнив следующие действия.

Шаг 4.1: Инициализация клиентов

На первом этапе пример transfer-coin инициализирует REST и faucet-клиенты.

Клиент REST взаимодействует с API REST, и
Клиент faucet взаимодействует с сервисом devnet Faucet для создания и пополнения учетных записей.

const client = new AptosClient(NODE_URL);
const faucetClient = new FaucetClient(NODE_URL, FAUCET_URL);

Используя клиент API, мы можем создать CoinClient, который мы используем для обычных операций с coin, таких как перевод coin и проверка баланса.

const coinClient = new CoinClient(client);

common.ts инициализирует значения URL таким образом:

export const NODE_URL = process.env.APTOS_NODE_URL || "https://fullnode.devnet.aptoslabs.com";
export const FAUCET_URL = process.env.APTOS_FAUCET_URL || "https://faucet.devnet.aptoslabs.com";

СОВЕТ По умолчанию URL-адреса обеих служб указывают на службы Aptos devnet. Однако их можно настроить с помощью следующих переменных среды:
APTOS_NODE_URL
APTOS_FAUCET_URL

rest_client = RestClient(NODE_URL)
faucet_client = FaucetClient(FAUCET_URL, rest_client)

В файле common.py эти значения инициализируются следующим образом:

NODE_URL = os.getenv("APTOS_NODE_URL", "https://fullnode.devnet.aptoslabs.com/v1")
FAUCET_URL = os.getenv(
    "APTOS_FAUCET_URL", "https://faucet.devnet.aptoslabs.com"
)

СОВЕТ По умолчанию URL-адреса обеих служб указывают на службы Aptos devnet. Однако их можно настроить с помощью следующих переменных среды:
APTOS_NODE_URL
APTOS_FAUCET_URL

let rest_client = Client::new(NODE_URL.clone());
let faucet_client = FaucetClient::new(FAUCET_URL.clone(), NODE_URL.clone());

Используя клиент API, мы можем создать CoinClient, который мы используем для обычных операций с coin, таких как перевод coin и проверка баланса.

let coin_client = CoinClient::new(&rest_client);

В примере мы инициализируем значения URL следующим образом:

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()
});

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

СОВЕТ По умолчанию URL-адреса обеих служб указывают на службы Aptos devnet. Однако их можно настроить с помощью следующих переменных среды:
APTOS_NODE_URL
APTOS_FAUCET_URL

Шаг 4.2: Создание локальных учетных записей

Следующим шагом будет создание двух учетных записей на локальном уровне. Учетные записи представляют собой состояние в сети и вне сети. Состояние вне сети состоит из адреса и пары открытого и закрытого ключей, используемых для аутентификации владельца. Этот шаг демонстрирует, как генерировать состояние вне сети.

const alice = new AptosAccount();
const bob = new AptosAccount();

alice = Account.generate()
bob = Account.generate()

let mut alice = LocalAccount::generate(&mut rand::rngs::OsRng);
let bob = LocalAccount::generate(&mut rand::rngs::OsRng);

Шаг 4.3: Создание учетных записей на блокчейне

В Aptos каждая учетная запись должна иметь представление в сети, чтобы поддерживать получение токенов и coins, а также взаимодействие в других dApp. Учетная запись представляет собой носитель для хранения активов, поэтому она должна быть явно создана. В данном примере используется Faucet для создания и пополнения учетной записи Alice и только для создания учетной записи Bob:

await faucetClient.fundAccount(alice.address(), 100_000_000);
await faucetClient.fundAccount(bob.address(), 0);

faucet_client.fund_account(alice.address(), 100_000_000)
faucet_client.fund_account(bob.address(), 0)

faucet_client
    .fund(alice.address(), 20_000)
    .await
    .context("Failed to fund Alice's account")?;
faucet_client
    .create_account(bob.address())
    .await
    .context("Failed to fund Bob's account")?;

Шаг 4.4: Чтение балансов

На этом этапе SDK преобразует один вызов в процесс запроса ресурса и чтения поля из этого ресурса.

console.log(`Alice: ${await coinClient.checkBalance(alice)}`);
console.log(`Bob: ${await coinClient.checkBalance(bob)}`);

За кулисами функция checkBalance в CoinClient в SDK запрашивает ресурс CoinStore для AptosCoin и считывает текущее значение:

async checkBalance(
  account: AptosAccount,
  extraArgs?: {
    // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin
    coinType?: string;
  },
): Promise<bigint> {
  const coinType = extraArgs?.coinType ?? APTOS_COIN;
  const typeTag = `0x1::coin::CoinStore<${coinType}>`;
  const resources = await this.aptosClient.getAccountResources(account.address());
  const accountResource = resources.find((r) => r.type === typeTag);
  return BigInt((accountResource!.data as any).coin.value);
}

print(f"Alice: {rest_client.account_balance(alice.address())}")
print(f"Bob: {rest_client.account_balance(bob.address())}")

За кулисами SDK запрашивает ресурс CoinStore для AptosCoin и считывает текущее хранимое значение:

def account_balance(self, account_address: str) -> int:
    """Returns the test coin balance associated with the account"""
    return self.account_resource(
        account_address, "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>"
    )["data"]["coin"]["value"]

println!(
    "Alice: {:?}",
    coin_client
        .get_account_balance(&alice.address())
        .await
        .context("Failed to get Alice's account balance the second time")?
);
println!(
    "Bob: {:?}",
    coin_client
        .get_account_balance(&bob.address())
        .await
        .context("Failed to get Bob's account balance the second time")?
);

За кулисами SDK запрашивает ресурс CoinStore для AptosCoin и считывает текущее хранимое значение:

let balance = self
    .get_account_resource(address, "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>")
    .await?;

Шаг 4.5: Передача

Как и предыдущий шаг, это еще один вспомогательный шаг, который создает транзакцию, передающую coins от Alice к Bob. Для правильно созданных транзакций API возвращает хэш транзакции, который можно использовать в последующих шагах для проверки статуса транзакции. Блокчейн Aptos выполняет несколько проверок при отправке, и если какая-либо из них не проходит, пользователю выдается сообщение об ошибке. Эти проверки включают подпись транзакции, неиспользованный порядковый номер и отправку транзакции в соответствующую сеть.

let txnHash = await coinClient.transfer(alice, bob, 1_000, { gasUnitPrice: BigInt(100) });

За кулисами функция transfer генерирует рабочую нагрузку транзакции и поручает клиенту подписать, отправить и дождаться ее:

async transfer(
  from: AptosAccount,
  to: AptosAccount,
  amount: number | bigint,
  extraArgs?: OptionalTransactionArgs & {
    // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin
    coinType?: string;
  },
): Promise<string> {
  const coinTypeToTransfer = extraArgs?.coinType ?? APTOS_COIN;
  const payload = this.transactionBuilder.buildTransactionPayload(
    "0x1::coin::transfer",
    [coinTypeToTransfer],
    [to.address(), amount],
  );
  return this.aptosClient.generateSignSubmitTransaction(from, payload, extraArgs);
}

В клиенте это делает generateSignSubmitTransaction:

const rawTransaction = await this.generateRawTransaction(sender.address(), payload, extraArgs);
const bcsTxn = AptosClient.generateBCSTransaction(sender, rawTransaction);
const pendingTransaction = await this.submitSignedBCSTransaction(bcsTxn);
return pendingTransaction.hash;

Разбиваем вышесказанное на части:

transfer внутренне является EntryFunction в модуле Coin Move, т.е. функцией входа в Move, которую можно вызвать напрямую.
Функция Move хранится на модуле coin: 0x1::coin.
Поскольку модуль Coin может использоваться другими coins, при передаче необходимо явно указать, какой тип coins передавать. Если coinType не указан, то по умолчанию используется 0x1::aptos_coin::AptosCoin.

txn_hash = rest_client.transfer(alice, bob.address(), 1_000)

За кулисами Python SDK генерирует, подписывает и отправляет транзакцию:

def bcs_transfer(
    self, sender: Account, recipient: AccountAddress, amount: int
) -> str:
    transaction_arguments = [
        TransactionArgument(recipient, Serializer.struct),
        TransactionArgument(amount, Serializer.u64),
    ]

    payload = EntryFunction.natural(
        "0x1::coin",
        "transfer",
        [TypeTag(StructTag.from_str("0x1::aptos_coin::AptosCoin"))],
        transaction_arguments,
    )

    signed_transaction = self.create_single_signer_bcs_transaction(
        sender, TransactionPayload(payload)
    )
    return self.submit_bcs_transaction(signed_transaction)

Разбиваем вышесказанное на части:

transfer внутренне является EntryFunction в модуле Coin Move, т.е. функцией входа в Move, которую можно вызвать напрямую.
Функция Move хранится на модуле coin:0x1::coin.
Поскольку модуль Coin может использоваться другими coins, при передаче необходимо явно использовать TypeTag, чтобы определить, какой coin передавать.
Аргументы транзакции должны быть помещены в TransactionArguments со спецификаторами типа (Serializer.{type}), которые будут сериализовать значение в соответствующий тип во время генерации транзакции.

let txn_hash = coin_client
    .transfer(&mut alice, bob.address(), 1_000, None)
    .await
    .context("Failed to submit transaction to transfer coins")?;

За кулисами Rust SDK генерирует, подписывает и отправляет транзакцию:

let chain_id = self
    .api_client
    .get_index()
    .await
    .context("Failed to get chain ID")?
    .inner()
    .chain_id;
let transaction_builder = TransactionBuilder::new(
    TransactionPayload::EntryFunction(EntryFunction::new(
        ModuleId::new(AccountAddress::ONE, Identifier::new("coin").unwrap()),
        Identifier::new("transfer").unwrap(),
        vec![TypeTag::from_str(options.coin_type).unwrap()],
        vec![
            bcs::to_bytes(&to_account).unwrap(),
            bcs::to_bytes(&amount).unwrap(),
        ],
    )),
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs()
        + options.timeout_secs,
    ChainId::new(chain_id),
)
.sender(from_account.address())
.sequence_number(from_account.sequence_number())
.max_gas_amount(options.max_gas_amount)
.gas_unit_price(options.gas_unit_price);
let signed_txn = from_account.sign_with_transaction_builder(transaction_builder);
Ok(self
    .api_client
    .submit(&signed_txn)
    .await
    .context("Failed to submit transfer transaction")?
    .into_inner())

Разбиваем вышесказанное на части:

Сначала мы получаем ID сети, необходимый для создания рабочей нагрузки транзакции.
transfer внутренне является EntryFunction в модуле Coin Move, т.е. функцией входа в Move, которую можно вызвать напрямую.
Функция Move хранится на модуле coin: 0x1::coin.
Поскольку модуль Coin может использоваться другими coins, при передаче необходимо явно использовать TypeTag, чтобы определить, какой coin передавать.
Аргументы транзакции, такие как to_account и amount, должны быть закодированы как BCS для использования с TransactionBuilder.

Шаг 4.6: Ожидание разрешения транзакции

В Typescript достаточно просто вызвать coinClient.transfer, чтобы дождаться завершения транзакции. Функция вернет Transaction, возвращенную API, как только она будет обработана (успешно или неуспешно), или выдаст ошибку, если время обработки превысит таймаут.

Вы можете установить checkSuccess в true при вызове transfer, если хотите, чтобы он выбрасывал сообщение, если транзакция не была успешно зафиксирована:

await client.waitForTransaction(txnHash);

Хэш транзакции можно использовать для запроса статуса транзакции:

rest_client.wait_for_transaction(txn_hash)

Хэш транзакции можно использовать для запроса статуса транзакции:

rest_client
    .wait_for_transaction(&txn_hash)
    .await
    .context("Failed when waiting for the transfer transaction")?;

PreviousРуководства для разработчиков NextВаше первое NFT

Last updated 1 year ago