Build a Basic Output

You can build a simple output using the Client.buildBasicOutput(options) function.

The following code example will:

1. Create a Client which will connect to the Shimmer Testnet.
2. Create a SecretManager from a mnemonic.
3. Generate a public address.
4. Build a simple output.

Code Example

Rust

Dotenv

This example uses dotenv, which is not safe to use in production environments.

// Copyright 2023 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

//! cargo run --example build_basic_output --release

use iota_client::{
    block::{
        address::Address,
        output::{
            feature::MetadataFeature,
            unlock_condition::{
                AddressUnlockCondition, ExpirationUnlockCondition, StorageDepositReturnUnlockCondition,
                TimelockUnlockCondition, UnlockCondition,
            },
            BasicOutputBuilder, Feature,
        },
    },
    Client, Result,
};

/// In this example we will send basic outputs with different feature blocks

#[tokio::main]
async fn main() -> Result<()> {
    // This example uses dotenv, which is not safe for use in production!
    dotenv::dotenv().ok();

    let node_url = std::env::var("NODE_URL").unwrap();

    // Create a client instance.
    let client = Client::builder().with_node(&node_url)?.finish()?;

    let token_supply = client.get_token_supply().await?;

    let address = Address::try_from_bech32("rms1qpllaj0pyveqfkwxmnngz2c488hfdtmfrj3wfkgxtk4gtyrax0jaxzt70zy")?.1;

    let basic_output_builder = BasicOutputBuilder::new_with_amount(1_000_000)?
        .add_unlock_condition(UnlockCondition::Address(AddressUnlockCondition::new(address)));

    let outputs = vec![
        // most simple output
        basic_output_builder.clone().finish_output(token_supply)?,
        // with metadata feature block
        basic_output_builder
            .clone()
            .add_feature(Feature::Metadata(MetadataFeature::new(
                "Hello, World!".as_bytes().to_owned(),
            )?))
            .finish_output(token_supply)?,
        // with storage deposit return
        basic_output_builder
            .clone()
            .add_unlock_condition(UnlockCondition::StorageDepositReturn(
                StorageDepositReturnUnlockCondition::new(address, 1000000, token_supply)?,
            ))
            .finish_output(token_supply)?,
        // with expiration
        basic_output_builder
            .clone()
            .add_unlock_condition(UnlockCondition::Expiration(ExpirationUnlockCondition::new(address, 1)?))
            .finish_output(token_supply)?,
        // with timelock
        basic_output_builder
            .add_unlock_condition(UnlockCondition::Timelock(TimelockUnlockCondition::new(1)?))
            .finish_output(token_supply)?,
    ];

    println!("{outputs:#?}");

    Ok(())
}

Run the Example

Run the example by running the following command:

cargo run --example build_basic_output --release

Nodejs

Dotenv

This example uses dotenv, which is not safe to use in production environments.

// Copyright 2021-2022 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

import { Client, initLogger } from '@iota/client';
import type { UnlockConditionTypes } from '@iota/types';
require('dotenv').config({ path: '../.env' });

// Run with command:
// node ./dist/11_build_output.js

// Build a basic output
async function run() {
    initLogger();
    if (!process.env.NODE_URL) {
        throw new Error('.env NODE_URL is undefined, see .env.example');
    }

    const client = new Client({
        nodes: [process.env.NODE_URL],
    });

    try {
        const hexAddress = await client.bech32ToHex(
            'rms1qpllaj0pyveqfkwxmnngz2c488hfdtmfrj3wfkgxtk4gtyrax0jaxzt70zy',
        );

        const addressUnlockCondition: UnlockConditionTypes = {
            type: 0,
            address: {
                type: 0,
                pubKeyHash: hexAddress,
            },
        };

        // Build most basic output with amound and a single address unlock condition
        const basicOutput = await client.buildBasicOutput({
            amount: '1000000',
            unlockConditions: [addressUnlockCondition],
        });

        console.log(JSON.stringify(basicOutput, null, 2));

        // Output with metadata feature block
        const basicOutputWithMetadata = await client.buildBasicOutput({
            amount: '1000000',
            unlockConditions: [addressUnlockCondition],
            features: [
                {
                    type: 2,
                    // "Hello, World!" hex encoded
                    data: '0x48656c6c6f2c20576f726c6421',
                },
            ],
        });

        console.log(JSON.stringify(basicOutputWithMetadata, null, 2));

        // Output with storage deposit return
        const basicOutputWithStorageReturn = await client.buildBasicOutput({
            amount: '1000000',
            unlockConditions: [
                addressUnlockCondition,
                {
                    type: 1,
                    returnAddress: {
                        type: 0,
                        pubKeyHash: hexAddress,
                    },
                    amount: '1000000',
                },
            ],
        });

        console.log(JSON.stringify(basicOutputWithStorageReturn, null, 2));

        // Output with expiration
        const basicOutputWithExpiration = await client.buildBasicOutput({
            amount: '1000000',
            unlockConditions: [
                addressUnlockCondition,
                {
                    type: 3,
                    returnAddress: {
                        type: 0,
                        pubKeyHash: hexAddress,
                    },
                    unixTime: 1,
                },
            ],
        });

        console.log(JSON.stringify(basicOutputWithExpiration, null, 2));

        // Output with timelock
        const basicOutputWithTimelock = await client.buildBasicOutput({
            amount: '1000000',
            unlockConditions: [
                addressUnlockCondition,
                {
                    type: 2,
                    unixTime: 1,
                },
            ],
        });

        console.log(JSON.stringify(basicOutputWithTimelock, null, 2));
    } catch (error) {
        console.error('Error: ', error);
    }
}

run().then(() => process.exit());

You can run the example by running the following command from the bindings/node/examples/ folder:

node dist/11_build_output.js

Python

from iota_client import IotaClient
import json

# Create an IotaClient instance
client = IotaClient({'nodes': ['https://api.testnet.shimmer.network']})

hex_address = client.bech32_to_hex("rms1qpllaj0pyveqfkwxmnngz2c488hfdtmfrj3wfkgxtk4gtyrax0jaxzt70zy")

address_unlock_condition = {
    "type": 0,
    "address": {
        "type": 0,
        "pubKeyHash": hex_address,
    },
}

# Build most basic output with amound and a single address unlock condition
basic_output = client.build_basic_output(
    unlock_conditions=[
        address_unlock_condition
    ],
    amount='1000000',
)
print(json.dumps(basic_output, indent=2))

# Output with metadata feature block
basic_output = client.build_basic_output(
    unlock_conditions=[
        address_unlock_condition,
    ],
    features=[
        {
            "type": 2,
            # "Hello, World!" hex encoded
            "data": "0x48656c6c6f2c20576f726c6421",
        },
    ],
    amount='1000000',
)
print(json.dumps(basic_output, indent=2))

# Output with storage deposit return
basic_output = client.build_basic_output(
    unlock_conditions=[
        address_unlock_condition,
        {
            "type": 1,
            "returnAddress": {
                "type": 0,
                "pubKeyHash": hex_address,
            },
            "amount": "1000000",
        },
    ],
    amount='1000000',
)
print(json.dumps(basic_output, indent=2))

# Output with expiration
basic_output = client.build_basic_output(
    unlock_conditions=[
        address_unlock_condition,
        {
            "type": 3,
            "returnAddress": {
                "type": 0,
                "pubKeyHash": hex_address,
            },
            "unixTime": 1
        },
    ],
    amount='1000000',
)
print(json.dumps(basic_output, indent=2))

# Output with timelock
basic_output = client.build_basic_output(
    unlock_conditions=[
        address_unlock_condition,
        {
            "type": 2,
            "unixTime": 1
        },
    ],
    amount='1000000',
)
print(json.dumps(basic_output, indent=2))

You can run the example by running the following command from the binding/python/examples folder:

python3 11_build_output.py

Java

How To Build A Basic Output

import org.iota.Client;
import org.iota.types.ClientConfig;
import org.iota.types.expections.ClientException;
import org.iota.types.Output;
import org.iota.types.UnlockCondition;
import org.iota.types.Feature;
import org.iota.types.expections.InitializeClientException;
import org.iota.types.output_builder.BasicOutputBuilderParams;
import org.iota.types.secret.GenerateAddressesOptions;
import org.iota.types.secret.MnemonicSecretManager;
import org.iota.types.secret.Range;
import com.google.gson.*;

public class BuildBasicOutput {
    public static void main(String[] args) throws ClientException, InitializeClientException {
        // Build the client.
        Client client = new Client(new ClientConfig().withNodes(new String[]{"https://api.testnet.shimmer.network"}));

        String hexAddress = client.bech32ToHex("rms1qpllaj0pyveqfkwxmnngz2c488hfdtmfrj3wfkgxtk4gtyrax0jaxzt70zy");
        String amount = "1000000";
        UnlockCondition addressUnlockCondition = new UnlockCondition("{ type: 0, address: { type: 0, pubKeyHash: \"" + hexAddress + "\"} }");

        // Build most basic output with amound and a single address unlock condition
        BasicOutputBuilderParams basicParams = new BasicOutputBuilderParams()
            .withAmount(amount)
            .withUnlockConditions(new UnlockCondition[]{addressUnlockCondition});

        Output basicOutput = client.buildBasicOutput(basicParams);

        System.out.println(
            new GsonBuilder().setPrettyPrinting().create().toJson(JsonParser.parseString(basicOutput.toString()))
        );

        // Output with metadata feature block
        BasicOutputBuilderParams metadataParams = new BasicOutputBuilderParams()
            .withAmount(amount)
            .withUnlockConditions(new UnlockCondition[]{addressUnlockCondition})
            // "Hello, World!" hex encoded
            .withFeatures(new Feature[]{new Feature("{ type: 2, data: \"0x48656c6c6f2c20576f726c6421\" }")});

        Output metadataOutput = client.buildBasicOutput(metadataParams);

        System.out.println(
            new GsonBuilder().setPrettyPrinting().create().toJson(JsonParser.parseString(metadataOutput.toString()))
        );

        // Output with storage deposit return
        UnlockCondition storageReturnUnlock = new UnlockCondition(
            "{ type: 1, returnAddress: { type: 0, pubKeyHash: \"" + hexAddress + "\"}, amount: \"" + amount + "\"}"
        ); 
        BasicOutputBuilderParams storageParams = new BasicOutputBuilderParams()
            .withAmount(amount)
            .withUnlockConditions(new UnlockCondition[]{addressUnlockCondition, storageReturnUnlock});

        Output storageOutput = client.buildBasicOutput(storageParams);

        System.out.println(
            new GsonBuilder().setPrettyPrinting().create().toJson(JsonParser.parseString(storageOutput.toString()))
        );

        // Output with expiration
        UnlockCondition expirationUnlock = new UnlockCondition(
            "{ type: 3, returnAddress: { type: 0, pubKeyHash: \"" + hexAddress + "\"}, unixTime: 1 }"
        );
        BasicOutputBuilderParams expirationParams = new BasicOutputBuilderParams()
            .withAmount(amount)
            .withUnlockConditions(new UnlockCondition[]{addressUnlockCondition, expirationUnlock});

        Output expirationOutput = client.buildBasicOutput(expirationParams);

        System.out.println(
            new GsonBuilder().setPrettyPrinting().create().toJson(JsonParser.parseString(expirationOutput.toString()))
        );

        // Output with timelock
        UnlockCondition timeUnlock = new UnlockCondition(
            "{ type: 2, unixTime: 1 }"
        );
        BasicOutputBuilderParams timelockParams = new BasicOutputBuilderParams()
            .withAmount(amount)
            .withUnlockConditions(new UnlockCondition[]{addressUnlockCondition, timeUnlock});

        Output timelockOutput = client.buildBasicOutput(timelockParams);

        System.out.println(
            new GsonBuilder().setPrettyPrinting().create().toJson(JsonParser.parseString(timelockOutput.toString()))
        );
    }
}

Expected Output

Rust

[
    Basic(
        BasicOutput {
            amount: 1000000,
            native_tokens: NativeTokens(
                BoxedSlicePrefix([]),
            ),
            unlock_conditions: UnlockConditions(
                BoxedSlicePrefix([
                    Address(
                        AddressUnlockCondition(
                            Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                        ),
                    ),
                ]),
            ),
            features: Features(
                BoxedSlicePrefix([]),
            ),
        },
    ),
    Basic(
        BasicOutput {
            amount: 1000000,
            native_tokens: NativeTokens(
                BoxedSlicePrefix([]),
            ),
            unlock_conditions: UnlockConditions(
                BoxedSlicePrefix([
                    Address(
                        AddressUnlockCondition(
                            Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                        ),
                    ),
                ]),
            ),
            features: Features(
                BoxedSlicePrefix([
                    Metadata(
                        MetadataFeature(0x48656c6c6f2c20576f726c6421),
                    ),
                ]),
            ),
        },
    ),
    Basic(
        BasicOutput {
            amount: 1000000,
            native_tokens: NativeTokens(
                BoxedSlicePrefix([]),
            ),
            unlock_conditions: UnlockConditions(
                BoxedSlicePrefix([
                    Address(
                        AddressUnlockCondition(
                            Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                        ),
                    ),
                    StorageDepositReturn(
                        StorageDepositReturnUnlockCondition {
                            return_address: Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                            amount: 1000000,
                        },
                    ),
                ]),
            ),
            features: Features(
                BoxedSlicePrefix([]),
            ),
        },
    ),
    Basic(
        BasicOutput {
            amount: 1000000,
            native_tokens: NativeTokens(
                BoxedSlicePrefix([]),
            ),
            unlock_conditions: UnlockConditions(
                BoxedSlicePrefix([
                    Address(
                        AddressUnlockCondition(
                            Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                        ),
                    ),
                    Expiration(
                        ExpirationUnlockCondition {
                            return_address: Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                            timestamp: 1,
                        },
                    ),
                ]),
            ),
            features: Features(
                BoxedSlicePrefix([]),
            ),
        },
    ),
    Basic(
        BasicOutput {
            amount: 1000000,
            native_tokens: NativeTokens(
                BoxedSlicePrefix([]),
            ),
            unlock_conditions: UnlockConditions(
                BoxedSlicePrefix([
                    Address(
                        AddressUnlockCondition(
                            Ed25519(
                                Ed25519Address(0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3),
                            ),
                        ),
                    ),
                    Timelock(
                        TimelockUnlockCondition(
                            1,
                        ),
                    ),
                ]),
            ),
            features: Features(
                BoxedSlicePrefix([]),
            ),
        },
    ),
]

Nodejs

{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ],
  "features": [
    {
      "type": 2,
      "data": "0x48656c6c6f2c20576f726c6421"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 1,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "amount": "1000000"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 3,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "unixTime": 1
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 2,
      "unixTime": 1
    }
  ]
}

Python

{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ],
  "features": [
    {
      "type": 2,
      "data": "0x48656c6c6f2c20576f726c6421"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 1,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "amount": "1000000"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 3,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "unixTime": 1
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 2,
      "unixTime": 1
    }
  ]
}

Java

{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    }
  ],
  "features": [
    {
      "type": 2,
      "data": "0x48656c6c6f2c20576f726c6421"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 1,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "amount": "1000000"
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 3,
      "returnAddress": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      },
      "unixTime": 1
    }
  ]
}
{
  "type": 3,
  "amount": "1000000",
  "unlockConditions": [
    {
      "type": 0,
      "address": {
        "type": 0,
        "pubKeyHash": "0x7ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3"
      }
    },
    {
      "type": 2,
      "unixTime": 1
    }
  ]
}