Add how to consolidate to documentation

bindings/python/examples/how_tos/accounts_and_addresses/consolidate_outputs.py

@@ -0,0 +1,73 @@
+from iota_sdk import Wallet, Utils
+from dotenv import load_dotenv
+import os
+
+# In this example we will consolidate basic outputs from an account with only an AddressUnlockCondition by sending
+# them to the same address again.
+
+# This example uses secrets in environment variables for simplicity which should not be done in production.
+load_dotenv()
+
+if 'STRONGHOLD_PASSWORD' not in os.environ:
+    raise Exception('.env STRONGHOLD_PASSWORD is undefined, see .env.example')
+
+wallet = Wallet('./alice-database')
+wallet.set_stronghold_password(os.environ['STRONGHOLD_PASSWORD'])
+
+account = wallet.get_account('Alice')
+
+# Sync account to make sure account is updated with outputs from previous examples
+account.sync()
+print('Account synced')
+
+# List unspent outputs before consolidation.
+# The output we created with example `request_funds` and the basic output from `mint` have only one
+# unlock condition and it is an `AddressUnlockCondition`, and so they are valid for consolidation. They have the
+# same `AddressUnlockCondition`(the first address of the account), so they will be consolidated into one
+# output.
+outputs = account.unspent_outputs()
+print('Outputs BEFORE consolidation:')
+
+for i, output_data in enumerate(outputs):
+    print(f'OUTPUT #{i}')
+    print(
+        '- address: {}\n- amount: {}\n- native tokens: {}'.format(
+            Utils.hex_to_bech32(output_data['address']['pubKeyHash'], 'rms'),
+            output_data['output']['amount'],
+            output_data['output'].get('nativeTokens'),
+        )
+    )
+
+print('Sending consolidation transaction...')
+
+# Consolidate unspent outputs and print the consolidation transaction IDs
+# Set `force` to true to force the consolidation even though the `output_consolidation_threshold` isn't reached
+transaction = account.prepare_consolidate_outputs(True, None).send()
+print('Transaction sent: {}'.format(transaction['transactionId']))
+
+# Wait for the consolidation transaction to get confirmed
+block_id = account.retry_transaction_until_included(transaction['transactionId'])
+
+print(
+    'Transaction included: {}/block/{}'.format(
+        os.environ['EXPLORER_URL'],
+        block_id
+    )
+)
+
+# Sync account
+account.sync()
+print('Account synced')
+
+# Outputs after consolidation
+outputs = account.unspent_outputs()
+print('Outputs AFTER consolidation:')
+for i, output_data in enumerate(outputs):
+    print(f'OUTPUT #{i}')
+    print(
+        '- address: {}\n- amount: {}\n- native tokens: {}'.format(
+            Utils.hex_to_bech32(output_data['address']['pubKeyHash'], 'rms'),
+            output_data['output']['amount'],
+            output_data['output'].get('nativeTokens'),
+        )
+    )

documentation/sdk/docs/how-tos/accounts-and-addresses/consolidate-outputs.mdx

@@ -0,0 +1,88 @@
+---
+title: Consolidate Outputs
+description: 'How to consolidate outputs'
+image: /img/logo/iota_mark_light.png
+keywords:
+- how to
+- consolidate outputs
+- nodejs
+- python
+- rust
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import RustCode from "!!raw-loader!../../../../../sdk/examples/how_tos/accounts_and_addresses/consolidate_outputs.rs";
+import NodejsCode from "!!raw-loader!../../../../../bindings/nodejs/examples/how_tos/accounts_and_addresses/consolidate-outputs.ts";
+import PythonCode from "!!raw-loader!../../../../../bindings/python/examples/how_tos/accounts_and_addresses/consolidate_outputs.py";
+
+This How-To will show you how to consolidate all outputs of an account.
+
+## Code Example
+
+<Tabs groupId="language">
+    <TabItem value="rust" label="Rust">
+        <CodeBlock className="language-rust">
+            {RustCode}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="nodejs" label="Nodejs">
+        <CodeBlock className="language-typescript">
+            {NodejsCode}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="python" label="Python">
+        <CodeBlock className="language-python">
+            {PythonCode}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+## Expected Output
+
+```plaintext
+Account synced
+Outputs BEFORE consolidation:
+OUTPUT #0
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 998947200
+- native tokens: Some(NativeTokens([NativeToken { token_id: TokenId(0x08bb8fe924f520a17acc1f55ae1b387e3d48e088423e136d7584aafcddb6c9f4de0200000000), amount: 100 }]))
+OUTPUT #1
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 50300
+- native tokens: Some(NativeTokens([]))
+OUTPUT #2
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 999895300
+- native tokens: Some(NativeTokens([NativeToken { token_id: TokenId(0x08bb8fe924f520a17acc1f55ae1b387e3d48e088423e136d7584aafcddb6c9f4de0100000000), amount: 100 }]))
+OUTPUT #3
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 54400
+- native tokens: Some(NativeTokens([]))
+OUTPUT #4
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 52800
+- native tokens: Some(NativeTokens([]))
+Sending consolidation transaction...
+Transaction sent: 0xff3498d1bfc22997a333d9ff57c007f342bc709d3e8d2978bcc7e339fe1f2f60
+Transaction included: https://explorer.shimmer.network/testnet/block/0x11d15f4cfb995352fd5e59dd35481743d9290b64f05da8558df2873b60314105
+Account synced
+Outputs AFTER consolidation:
+OUTPUT #0
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 50300
+- native tokens: Some(NativeTokens([]))
+OUTPUT #1
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 1998842500
+- native tokens: Some(NativeTokens([NativeToken { token_id: TokenId(0x08bb8fe924f520a17acc1f55ae1b387e3d48e088423e136d7584aafcddb6c9f4de0100000000), amount: 100 }, NativeToken { token_id: TokenId(0x08bb8fe924f520a17acc1f55ae1b387e3d48e088423e136d7584aafcddb6c9f4de0200000000), amount: 100 }]))
+OUTPUT #2
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 54400
+- native tokens: Some(NativeTokens([]))
+OUTPUT #3
+- address: Bech32Address(rms1qzqn6l47kcascxg2rpzwz6ahdv9qkjnpjulw5x05t34zfq3ngd0fwt6at3h)
+- amount: 52800
+- native tokens: Some(NativeTokens([]))
+```

documentation/sdk/sidebars.js

@@ -72,6 +72,7 @@ module.exports = {
             'how-tos/accounts-and-addresses/create-address',
             'how-tos/accounts-and-addresses/list-transactions',
             'how-tos/accounts-and-addresses/list-outputs',
+            'how-tos/accounts-and-addresses/consolidate-outputs',
           ]
         },
         {

sdk/Cargo.toml

@@ -151,6 +151,11 @@ name = "list_outputs"
 path = "examples/how_tos/accounts_and_addresses/list_outputs.rs"
 required-features = [ "rocksdb", "stronghold" ]
 
+[[example]]
+name = "consolidate_outputs"
+path = "examples/how_tos/accounts_and_addresses/consolidate_outputs.rs"
+required-features = [ "wallet", "stronghold" ]
+
 # Simple Transaction Examples
 
 [[example]]
@@ -656,11 +661,6 @@ name = "logger"
 path = "examples/wallet/logger.rs"
 required-features = [ "wallet" ]
 
-[[example]]
-name = "output_consolidation"
-path = "examples/wallet/output_consolidation.rs"
-required-features = [ "wallet", "stronghold" ]
-
 [[example]]
 name = "recover_accounts"
 path = "examples/wallet/recover_accounts.rs"

sdk/examples/wallet/output_consolidation.rs → sdk/examples/how_tos/accounts_and_addresses/consolidate_outputs.rs

@@ -9,7 +9,7 @@
 //!
 //! Rename `.env.example` to `.env` first, then run the command:
 //! ```sh
-//! cargo run --release --all-features --example output_consolidation
+//! cargo run --release --all-features --example consolidate_outputs
 //! ```
 
 use std::env::var;