Merge pull request #501 from hashgraph/sr/examples

Author: mehcode

examples/account_alias.rs

@@ -0,0 +1,125 @@
+/*
+ * ‌
+ * Hedera Rust SDK
+ * ​
+ * Copyright (C) 2022 - 2023 Hedera Hashgraph, LLC
+ * ​
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ‍
+ */
+
+use clap::Parser;
+use hedera::{
+    AccountBalanceQuery, AccountId, AccountInfoQuery, Client, Hbar, PrivateKey, TransferTransaction
+};
+
+#[derive(Parser, Debug)]
+struct Args {
+    #[clap(long, env)]
+    operator_account_id: AccountId,
+
+    #[clap(long, env)]
+    operator_key: PrivateKey,
+
+    #[clap(long, env, default_value = "testnet")]
+    hedera_network: String,
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let _ = dotenvy::dotenv();
+    let args = Args::parse();
+
+    let client = Client::for_name(&args.hedera_network)?;
+
+    client.set_operator(args.operator_account_id, args.operator_key.clone());
+
+    // Hedera supports a form of auto account creation.
+    //
+    // You can "create" an account by generating a private key, and then deriving the public key,
+    // without any need to interact with the Hedera network.  The public key more or less acts as the user's
+    // account ID.  This public key is an account's alias_key: a public key that aliases (or will eventually alias)
+    // to a Hedera account.
+    //
+    // An AccountId takes one of two forms: a normal `AccountId` with no `alias_key` takes the form 0.0.123,
+    // while an account ID with an `alias_key` takes the form
+    // 0.0.302a300506032b6570032100114e6abc371b82dab5c15ea149f02d34a012087b163516dd70f44acafabf7777
+    // Note the prefix of "0.0." indicating the shard and realm.  Also note that the aliasKey is stringified
+    // as a hex-encoded ASN1 DER representation of the key.
+    //
+    // An AccountId with an aliasKey can be used just like a normal AccountId for the purposes of queries and
+    // transactions, however most queries and transactions involving such an AccountId won't work until Hbar has
+    // been transferred to the alias_key account.
+    //
+    // There is no record in the Hedera network of an account associated with a given `alias_key`
+    // until an amount of Hbar is transferred to the account.  The moment that Hbar is transferred to that `alias_key`
+    // AccountId is the moment that that account actually begins to exist in the Hedera ledger.
+
+    println!(r#""Creating" a new account"#);
+
+    let private_key = PrivateKey::generate_ed25519();
+    let public_key = private_key.public_key();
+
+    // Assuming that the target shard and realm are known.
+    // For now they are virtually always 0 and 0.
+    let alias_account_id = public_key.to_account_id(0, 0);
+
+    println!("New account ID: {alias_account_id}");
+    println!("Just the aliasKey: {:?}", &alias_account_id.alias);
+
+    // Note that no queries or transactions have taken place yet.
+    // This account "creation" process is entirely local.
+    //
+    // AccountId::from_str can construct an AccountId with an alias_key.
+    // It expects a string of the form 0.0.123 in the case of a normal AccountId, or of the form
+    // 0.0.302a300506032b6570032100114e6abc371b82dab5c15ea149f02d34a012087b163516dd70f44acafabf7777
+    // in the case of an AccountId with an alias.  Note the prefix of "0.0." to indicate the shard and realm.
+    //
+    // If the shard and realm are known, you may use PublicKey::from_str().to_account_id() to construct the
+    // alias_key AccountId.
+
+    println!("Transferring some Hbar to the new account");
+    let _ = TransferTransaction::new()
+        .hbar_transfer(args.operator_account_id, Hbar::new(-10))
+        .hbar_transfer(alias_account_id, Hbar::new(10))
+        .execute(&client)
+        .await?
+        .get_receipt(&client)
+        .await?;
+
+    let balance = AccountBalanceQuery::new()
+        .account_id(alias_account_id)
+        .execute(&client)
+        .await?;
+
+    println!("Balances of the new account: {balance:?}");
+
+    let info = AccountInfoQuery::new()
+        .account_id(alias_account_id)
+        .execute(&client)
+        .await?;
+
+    println!("Info about the new account: {info:?}");
+
+    // Note that once an account exists in the ledger, it is assigned a normal AccountId, which can be retrieved
+    // via an AccountInfoQuery.
+    //
+    // Users may continue to refer to the account by its alias_key AccountId, but they may also
+    // now refer to it by its normal AccountId.
+
+    println!("the normal account ID: {}", info.account_id);
+    println!("the alias key: {:?}", info.alias_key);
+    println!("Example complete!");
+
+    Ok(())
+}

examples/account_allowance.rs

@@ -0,0 +1,270 @@
+/*
+ * ‌
+ * Hedera Rust SDK
+ * ​
+ * Copyright (C) 2022 - 2023 Hedera Hashgraph, LLC
+ * ​
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ‍
+ */
+
+use clap::Parser;
+use hedera::{
+    AccountAllowanceApproveTransaction, AccountBalanceQuery, AccountCreateTransaction, AccountDeleteTransaction, AccountId, Client, Hbar, PrivateKey, TransactionId, TransferTransaction
+};
+
+#[derive(Parser, Debug)]
+struct Args {
+    #[clap(long, env)]
+    operator_account_id: AccountId,
+
+    #[clap(long, env)]
+    operator_key: PrivateKey,
+
+    #[clap(long, env, default_value = "testnet")]
+    hedera_network: String,
+}
+
+#[derive(Clone, Debug)]
+struct Account {
+    key: PrivateKey,
+    id: AccountId,
+    name: &'static str,
+}
+
+async fn create_account(client: &Client, name: &'static str) -> hedera::Result<Account> {
+    let key = PrivateKey::generate_ed25519();
+
+    let reciept = AccountCreateTransaction::new()
+        .key(key.public_key())
+        .initial_balance(Hbar::new(5))
+        .account_memo(format!("[sdk::rust::account_allowance_example::{name}]"))
+        .execute(client)
+        .await?
+        .get_receipt(client)
+        .await?;
+
+    let account_id = reciept
+        .account_id
+        .expect("Created account but no account ID in receipt");
+
+    Ok(Account {
+        key,
+        id: account_id,
+        name,
+    })
+}
+
+async fn create_accounts(client: &Client) -> anyhow::Result<[Account; 3]> {
+    println!("Creating accounts");
+
+    let (alice, bob, charlie) = tokio::try_join!(
+        create_account(client, "Alice"),
+        create_account(client, "Bob"),
+        create_account(client, "Charlie"),
+    )?;
+
+    let accounts = [alice, bob, charlie];
+
+    for account in &accounts {
+        println!("{}'s ID: {}", account.name, account.id);
+    }
+
+    Ok(accounts)
+}
+
+// this needs to be a function because rust doesn't have try blocks.
+/// Transfer from `alice` (0) to `charlie` (2) via `bob`'s allowance (1).
+async fn transfer(client: &Client, accounts: &[Account; 3], value: Hbar) -> hedera::Result<()> {
+    let [alice, bob, charlie] = accounts;
+    // `approved_{hbar,token}_transfer()` means that the transfer has been approved by an allowance
+    // The allowance spender must be pay the fee for the transaction.
+    // use `transaction_id()` to set the account ID that will pay the fee for the transaction.
+    let _ = TransferTransaction::new()
+        .approved_hbar_transfer(alice.id, -value)
+        .hbar_transfer(charlie.id, value)
+        .transaction_id(TransactionId::generate(bob.id))
+        .freeze_with(client)?
+        .sign(bob.key.clone())
+        .execute(client)
+        .await?
+        .get_receipt(client)
+        .await?;
+
+    Ok(())
+}
+
+async fn demonstrate_allowances(client: &Client, accounts: &[Account; 3]) -> anyhow::Result<()> {
+    const FIRST_ALLOWANCE_VALUE: Hbar = Hbar::new(2);
+    const FIRST_TRANSFER_VALUE: Hbar = Hbar::new(1);
+    const SECOND_ALLOWANCE_VALUE: Hbar = Hbar::new(3);
+    const SECOND_TRANSFER_VALUE: Hbar = Hbar::new(2);
+
+    let [alice, bob, charlie] = accounts;
+
+    println!(
+        "Approving an allowance of {FIRST_ALLOWANCE_VALUE} with owner {} and spender {}",
+        alice.name, bob.name
+    );
+
+    let _ = AccountAllowanceApproveTransaction::new()
+        .approve_hbar_allowance(alice.id, bob.id, FIRST_ALLOWANCE_VALUE)
+        .freeze_with(client)?
+        .sign(alice.key.clone())
+        .execute(client)
+        .await?
+        .get_receipt(client)
+        .await?;
+
+    print_balances(client, accounts).await?;
+
+    println!(
+        "Transferring {FIRST_TRANSFER_VALUE} from {alice} to {charlie}, but the transaction is signed only by {bob} ({bob} is dipping into their allowance from {alice})",
+        alice=alice.name,
+        bob=bob.name,
+        charlie=charlie.name
+    );
+
+    transfer(client, accounts, FIRST_TRANSFER_VALUE).await?;
+
+    let current_balance = FIRST_ALLOWANCE_VALUE - FIRST_TRANSFER_VALUE;
+
+    println!(
+        "Transfer succeeded. {bob} should now have {current_balance} left in their allowance.",
+        bob = bob.name,
+    );
+
+    print_balances(client, accounts).await?;
+
+    println!(
+        "Attempting to transfer {SECOND_TRANSFER_VALUE} from {alice} to {charlie} using {bob}'s allowance.",
+        alice=alice.name,
+        bob=bob.name,
+        charlie=charlie.name
+    );
+    println!(
+        "This should fail, because there is only {current_balance} left in {bob}'s allowance.",
+        bob = bob.name
+    );
+
+    match transfer(client, accounts, SECOND_TRANSFER_VALUE).await {
+        Ok(()) => {
+            println!("The transfer succeeded. This should not happen.");
+        }
+
+        Err(e) => {
+            println!("The transfer failed as expected: {e:?}")
+        }
+    }
+
+    println!(
+        "Adjusting {bob}'s allowance to {SECOND_ALLOWANCE_VALUE}.",
+        bob = bob.name
+    );
+
+    let _ = AccountAllowanceApproveTransaction::new()
+        .approve_hbar_allowance(alice.id, bob.id, SECOND_ALLOWANCE_VALUE)
+        .freeze_with(client)?
+        .sign(alice.key.clone())
+        .execute(client)
+        .await?
+        .get_receipt(client)
+        .await?;
+
+    println!(
+        "Attempting to transfer {SECOND_TRANSFER_VALUE} from {alice} to {charlie} using {bob}'s allowance again.",
+        alice=alice.name,
+        bob=bob.name,
+        charlie=charlie.name
+    );
+    println!("This time it should succeed.");
+
+    transfer(client, accounts, SECOND_TRANSFER_VALUE).await?;
+
+    println!("Transfer succeeded.");
+
+    print_balances(client, accounts).await?;
+
+    println!("Deleting {bob}'s allowance", bob = bob.name);
+
+    let _ = AccountAllowanceApproveTransaction::new()
+        .approve_hbar_allowance(alice.id, bob.id, Hbar::ZERO)
+        .freeze_with(client)?
+        .sign(alice.key.clone())
+        .execute(client)
+        .await?
+        .get_receipt(client)
+        .await?;
+
+    Ok(())
+}
+
+async fn clean_up(
+    client: &Client,
+    operator_id: AccountId,
+    accounts: [Account; 3],
+) -> anyhow::Result<()> {
+    println!("Cleaning up...");
+
+    for account in accounts {
+        let _ = AccountDeleteTransaction::new()
+            .account_id(account.id)
+            .transfer_account_id(operator_id)
+            .freeze_with(client)?
+            .sign(account.key)
+            .execute(client)
+            .await?
+            .get_receipt(client)
+            .await?;
+
+        println!("Deleted `{}` ({})", account.name, account.id);
+    }
+
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let _ = dotenvy::dotenv();
+
+    let args = Args::parse();
+
+    let client = Client::for_name(&args.hedera_network)?;
+
+    client.set_operator(args.operator_account_id, args.operator_key);
+
+    let accounts = create_accounts(&client).await?;
+
+    print_balances(&client, &accounts).await?;
+
+    demonstrate_allowances(&client, &accounts).await?;
+    clean_up(&client, args.operator_account_id, accounts).await?;
+
+    println!("End of example");
+
+    Ok(())
+}
+
+async fn print_balances(client: &Client, accounts: &[Account; 3]) -> hedera::Result<()> {
+    for account in accounts {
+        let balance = AccountBalanceQuery::new()
+            .account_id(account.id)
+            .execute(&client)
+            .await?
+            .hbars;
+
+        println!("{name}'s balance: {balance}", name = account.name);
+    }
+
+    Ok(())
+}