Build a Basic Output
You can build a simple output using the Client.buildBasicOutput(options)
function.
The following code example will:
- Create a
Client
which will connect to the Shimmer Testnet. - Create a
SecretManager
from a mnemonic. - Generate a public address.
- Build a simple output.
Code Example
- Rust
- Nodejs
- Python
- Java
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
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
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
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
- Nodejs
- Python
- Java
[
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([]),
),
},
),
]
{
"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
}
]
}
{
"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
}
]
}
{
"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
}
]
}