Added examples and docs for nft mint, send, burn

.gitignore

@@ -3,6 +3,7 @@
 **/target
 *.pyc
 **/*.rs.bk
+yarn.lock
 
 # IDE files
 .vscode
@@ -20,6 +21,7 @@ online_walletdb
 /pingdb
 /pongdb
 backup
+example-walletdb
 
 # JSON files
 address.json

bindings/nodejs/examples/how_tos/nfts/burn_nft.ts

@@ -0,0 +1,68 @@
+// Copyright 2023 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { Wallet } from '@iota/sdk';
+
+// In this example we will burn an existing nft output.
+//
+// Make sure that `example.stronghold` and `example.walletdb` already exist by
+// running the `how_tos/accounts-and-addresses/create-wallet` example!
+//
+// Rename `.env.example` to `.env` first, then run
+// yarn run-example ./how_tos/nfts/burn_nft.ts
+async function run() {
+    try {
+        if (!process.env.STRONGHOLD_PASSWORD) {
+            throw new Error(
+                '.env STRONGHOLD_PASSWORD is undefined, see .env.example',
+            );
+        }
+
+        // Create the wallet
+        const wallet = new Wallet({
+            storagePath: process.env.WALLET_DB_PATH,
+        });
+
+        // Get the account we generated with `01-create-wallet`
+        const account = await wallet.getAccount(
+            `${process.env.ACCOUNT_ALIAS_1}`,
+        );
+
+        // May want to ensure the account is synced before sending a transaction.
+        let balance = await account.sync();
+
+        if (balance.nfts.length == 0) {
+            throw new Error(
+                `No NFT available in account '${process.env.ACCOUNT_ALIAS_1}'`,
+            );
+        }
+        // Get the first nft
+        const nftId = balance.nfts[0];
+
+        console.log(`Balance BEFORE burning:\n`, balance);
+
+        // Burn an NFT
+        const transaction = await account
+            .prepareBurnNft(nftId)
+            .then((prepared) => prepared.send());
+
+        console.log(`Transaction sent: ${transaction.transactionId}`);
+
+        // Wait for transaction to get included
+        const blockId = await account.retryTransactionUntilIncluded(
+            transaction.transactionId,
+        );
+        console.log(
+            `Block included: ${process.env.EXPLORER_URL}/block/${blockId}`,
+        );
+        console.log(`Burned NFT ${nftId}`);
+
+        balance = await account.sync();
+        console.log(`Balance AFTER burning:\n`, balance);
+    } catch (error) {
+        console.log('Error: ', error);
+    }
+    process.exit(0);
+}
+
+run();

bindings/nodejs/examples/how_tos/nfts/mint_nft.ts

@@ -0,0 +1,117 @@
+// Copyright 2023 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    AddressUnlockCondition,
+    Ed25519Address,
+    IssuerFeature,
+    MintNftParams,
+    SenderFeature,
+    utf8ToHex,
+    Utils,
+    Wallet
+} from '@iota/sdk';
+
+// The owner address of the first NFT we'll mint
+const NFT1_OWNER_ADDRESS =
+    'rms1qpszqzadsym6wpppd6z037dvlejmjuke7s24hm95s9fg9vpua7vluaw60xu';
+// The metadata of the first minted NFT
+const NFT1_METADATA = utf8ToHex('some NFT metadata');
+// The immutable metadata of the first minted NFT
+const NFT1_IMMUTABLE_METADATA = utf8ToHex('some NFT immutable metadata');
+// The tag of the first minted NFT
+const NFT1_TAG = utf8ToHex('some NFT tag');
+// The base coin amount we sent with the second NFT
+const NFT2_AMOUNT = '1000000';
+
+// In this example we will mint a new nft.
+//
+// Make sure that `example.stronghold` and `example.walletdb` already exist by
+// running the `how_tos/accounts-and-addresses/create-wallet` example!
+//
+// Rename `.env.example` to `.env` first, then run
+// yarn run-example ./how_tos/nfts/mint_nft.ts
+async function run() {
+    try {
+        if (!process.env.STRONGHOLD_PASSWORD) {
+            throw new Error(
+                '.env STRONGHOLD_PASSWORD is undefined, see .env.example',
+            );
+        }
+
+        const wallet = new Wallet({
+            storagePath: process.env.WALLET_DB_PATH,
+        });
+
+        const account = await wallet.getAccount(
+            `${process.env.ACCOUNT_ALIAS_1}`,
+        );
+
+        // May want to ensure the account is synced before sending a transaction.
+        let balance = await account.sync();
+        const nftsBefore = balance.nfts;
+
+        // We send from the first address in the account.
+        const senderAddress = (await account.addresses())[0].address;
+
+        const params: MintNftParams = {
+            address: NFT1_OWNER_ADDRESS, // Remove or change to senderAddress to send to self
+            sender: senderAddress,
+            metadata: NFT1_METADATA,
+            tag: NFT1_TAG,
+            issuer: senderAddress,
+            immutableMetadata: NFT1_IMMUTABLE_METADATA,
+        };
+        const prepared = await account.prepareMintNfts([params]);
+
+        let transaction = await prepared.send();
+        console.log(`Transaction sent: ${transaction.transactionId}`);
+
+        // Wait for transaction to get included
+        let blockId = await account.retryTransactionUntilIncluded(
+            transaction.transactionId,
+        );
+
+        console.log(
+            `Block included: ${process.env.EXPLORER_URL}/block/${blockId}`,
+        );
+        console.log('Minted NFT 1');
+
+        // Build an NFT manually by using the `NftOutputBuilder`
+        const client = await wallet.getClient();
+
+        const hexAddress = Utils.bech32ToHex(senderAddress);
+        const output = await client.buildNftOutput({
+            amount: NFT2_AMOUNT,
+            nftId: '0x0000000000000000000000000000000000000000000000000000000000000000',
+            unlockConditions: [
+                new AddressUnlockCondition(new Ed25519Address(Utils.bech32ToHex(NFT1_OWNER_ADDRESS))),
+            ],
+            immutableFeatures: [
+                new IssuerFeature(new Ed25519Address(hexAddress)),
+            ],
+            features: [new SenderFeature(new Ed25519Address(hexAddress))],
+        });
+
+        transaction = await account.sendOutputs([output]);
+        console.log(`Transaction sent: ${transaction.transactionId}`);
+
+        // Wait for transaction to get included
+        blockId = await account.retryTransactionUntilIncluded(
+            transaction.transactionId,
+        );
+
+        console.log(
+            `Block included: ${process.env.EXPLORER_URL}/block/${blockId}`,
+        );
+
+        console.log('Minted NFT 2');
+
+        // Ensure the account is synced after minting.
+        await account.sync();
+    } catch (error) {
+        console.error('Error: ', error);
+    }
+}
+
+run().then(() => process.exit());

bindings/nodejs/examples/how_tos/nfts/send_nft.ts

@@ -0,0 +1,86 @@
+// Copyright 2023 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { SendNftParams, Wallet } from '@iota/sdk';
+
+// The address to send the NFT to
+const RECV_ADDRESS =
+    'rms1qpszqzadsym6wpppd6z037dvlejmjuke7s24hm95s9fg9vpua7vluaw60xu';
+
+// In this example we will send an NFT (Non-fungible token).
+//
+// Make sure that `example.stronghold` and `example.walletdb` already exist by
+// running the `how_tos/accounts-and-addresses/create-wallet` example!
+//
+// Rename `.env.example` to `.env` first, then run
+// yarn run-example ./how_tos/nfts/send_nft.ts
+async function run() {
+    try {
+        if (!process.env.STRONGHOLD_PASSWORD) {
+            throw new Error(
+                '.env STRONGHOLD_PASSWORD is undefined, see .env.example',
+            );
+        }
+
+        const wallet = new Wallet({
+            storagePath: process.env.WALLET_DB_PATH,
+        });
+
+        // Get the account we generated with `01-create-wallet`
+        const account = await wallet.getAccount(
+            `${process.env.ACCOUNT_ALIAS_1}`,
+        );
+
+        // May want to ensure the account is synced before sending a transaction.
+        const balance = await account.sync();
+
+        if (balance.nfts.length == 0) {
+            throw new Error('No available NFTs');
+        }
+
+        const nftId = balance.nfts[0];
+
+        const outputs: SendNftParams[] = [
+            {
+                address: RECV_ADDRESS,
+                nftId,
+            },
+        ];
+
+        // Send the full NFT output to the specified address
+        const transaction = await account
+            .prepareSendNft(outputs)
+            .then((prepared) => prepared.send());
+
+        console.log(`Transaction sent: ${transaction.transactionId}`);
+
+        // Wait for transaction to get included
+        const blockId = await account.retryTransactionUntilIncluded(
+            transaction.transactionId,
+        );
+
+        console.log(
+            `Block included: ${process.env.EXPLORER_URL}/block/${blockId}`,
+        );
+
+        // To send an NFT with expiration unlock condition prepareOutput() can be used like this:
+        // const output = await account.prepareOutput({
+        //     recipientAddress: 'rms1qz6aj69rumk3qu0ra5ag6p6kk8ga3j8rfjlaym3wefugs3mmxgzfwa6kw3l',
+        //     amount: "47000",
+        //     unlocks: {
+        //         expirationUnixTime: 1677065933
+        //     },
+        //     assets: {
+        //         nftId: '0x447b20b81e2311a6c16a32eaeda2f2f2472c4b43ed4ffc80a0c0f850130fc4bb',
+        //     },
+        //     storageDeposit: { returnStrategy: 'Gift' }
+        // });
+
+        // const transaction = await account.sendOutputs([output]);
+    } catch (error) {
+        console.log('Error: ', error);
+    }
+    process.exit(0);
+}
+
+run();

bindings/python/examples/how_tos/nfts/burn_nft.py

@@ -0,0 +1,26 @@
+from iota_sdk import Wallet
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+# In this example we will burn an NFT
+wallet = Wallet('./alice-database')
+
+if 'STRONGHOLD_PASSWORD' not in os.environ:
+    raise Exception(".env STRONGHOLD_PASSWORD is undefined, see .env.example")
+
+wallet.set_stronghold_password(os.environ["STRONGHOLD_PASSWORD"])
+
+account = wallet.get_account('Alice')
+
+# Sync account with the node
+response = account.sync()
+
+# TODO: replace with your own values.
+nftId = "0xf95f4d5344217a2ba19a6c19a47f97d267edf8c4d76a7b8c08072ad35acbebbe"
+
+# Send transaction.
+transaction = account.prepare_burn_nft(nftId).send()
+print(f'Block sent: {os.environ["EXPLORER_URL"]}/block/{transaction["blockId"]}')
+

bindings/python/examples/how_tos/nfts/mint_nft.py

@@ -0,0 +1,26 @@
+from iota_sdk import Wallet, utf8_to_hex
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+# In this example we will mint an nft
+
+wallet = Wallet('./alice-database')
+
+if 'STRONGHOLD_PASSWORD' not in os.environ:
+    raise Exception(".env STRONGHOLD_PASSWORD is undefined, see .env.example")
+
+wallet.set_stronghold_password(os.environ["STRONGHOLD_PASSWORD"])
+
+account = wallet.get_account('Alice')
+
+# Sync account with the node
+response = account.sync()
+
+outputs = [{
+    "immutableMetadata": utf8_to_hex("some immutable nft metadata"),
+}]
+
+transaction = account.prepare_mint_nfts(outputs).send()
+print(f'Block sent: {os.environ["EXPLORER_URL"]}/block/{transaction["blockId"]}')

bindings/python/examples/how_tos/nfts/send_nft.py

@@ -0,0 +1,27 @@
+from iota_sdk import Wallet
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+# In this example we will send an nft
+
+wallet = Wallet('./alice-database')
+
+if 'STRONGHOLD_PASSWORD' not in os.environ:
+    raise Exception(".env STRONGHOLD_PASSWORD is undefined, see .env.example")
+
+wallet.set_stronghold_password(os.environ["STRONGHOLD_PASSWORD"])
+
+account = wallet.get_account('Alice')
+
+# Sync account with the node
+response = account.sync()
+
+outputs = [{
+    "address": "rms1qpszqzadsym6wpppd6z037dvlejmjuke7s24hm95s9fg9vpua7vluaw60xu",
+    "nftId": "0x17f97185f80fa56eab974de6b7bbb80fa812d4e8e37090d166a0a41da129cebc",
+}]
+
+transaction = account.prepare_send_nft(outputs).send()
+print(f'Block sent: {os.environ["EXPLORER_URL"]}/block/{transaction["blockId"]}')