Skip to main content

Transaction Plugins

warning

The Transaction plugin API is experimental and may change rapidly as it is being developed.

This document describes the plugin API for the Transaction builder. It covers internal details intended for developers interested in extending the Transaction builder. Developers using the Transaction builder to build transactions do not need this level of detail. The Transaction builder includes a plugin system designed to extend how transactions are built. The two primary goals are:

  1. Allow developers to customize how data is resolved when building transactions.
  2. Provide a way for developers to extend the core commands that can be added to transactions.

The Plugin API consists of three main components: serialization plugins, build plugins, and Transaction Intents. Serialization and build plugins act like middleware, allowing developers to modify the data and commands added to a transaction before it is serialized to JSON or built into BCS bytes. Transaction Intents are custom representations of user intents for a transaction, eventually resolved to one or more commands in the transaction.

Contents of a Transaction​

When a Transaction is created (e.g., new Transaction()), it is initialized with an empty TransactionDataBuilder instance which stores the state of the partially built transaction.

As commands are added to the Transaction, they are stored in the TransactionDataBuilder. The TransactionData contains a list of commands and their arguments. The exact arguments a command takes depend on the command, but they will be one of a few different types:

  • GasCoin: A reference to the coin used to pay for gas.
  • Input: An input to the transaction (described below).
  • Result: The result of a previous command.
  • NestedResult: If a previous command returns a tuple (e.g., SplitCoin), a NestedResult is used to refer to a specific value in that tuple.

Transactions also store a list of Inputs, which refer to user-provided values. Inputs can either be objects or Pure values and can be represented in several different ways:

  • Pure: An input value serialized to BCS. Pure values are generally scalar values or simple wrappers like options or vectors and cannot represent object types.
  • Object: A fully resolved object reference, which will be one of the following types:
    • ImmOrOwnedObject: A reference to an object, including the object's id, version, and digest.
    • SharedObject: A reference to a shared object, including the object's id, initialSharedVersion, and whether the shared object is used mutably.
    • Receiving: A reference to a receiving object, including the object's id, version, and digest.
  • UnresolvedPure: A placeholder for a pure value that has not been serialized to BCS.
  • UnresolvedObject: A partial reference to an object, often containing just the object's id, but may also include a version, digest, or initialSharedVersion.

Lifecycle of a Transaction​

Because transactions can contain UnresolvedPure and UnresolvedObject inputs, these values need to be resolved before the transaction can be serialized to BCS. However, these unresolved inputs can be represented in JSON. What may not be able to be represented in JSON are Transaction Intents. Transaction Intents represent custom concepts added by plugins or third-party SDKs. To account for this, the build process of a transaction is split into two phases: serialization and building. Serialization prepares the transaction to be serialized to JSON by running serialization plugins, and resolving any unsupported intents. The Build phase then runs, which runs build plugins and resolves any UnresolvedPure and UnresolvedObject inputs, before the transaction is serialized to BCS.

Serialization Plugins​

Serialization plugins can be added to a Transaction by calling the addSerializationPlugin method on a Transaction instance. Serialization plugins are called in the order they are added and are passed the TransactionDataBuilder instance of the transaction.

const transaction = new Transaction();

transaction.addSerializationPlugin(async (transactionData, buildOptions, next) => {
    // Modify the data before running other serialization steps
    await next();
    // Modify the data after running other serialization steps
});

Build Plugins​

The build phase is responsible for taking unresolved objects and unresolved pure values and converting them to their resolved versions by querying the RPC API to fetch the missing data. Build plugins can hook into this phase to resolve some of this data from a cache instead, avoiding extra API calls.

Build plugins work just like serialization plugins and can be added to a Transaction by calling the addBuildPlugin method on a Transaction instance. Build plugins are called in the order they are added and are passed the TransactionDataBuilder instance of the transaction.

The following example demonstrates a simplified version of the caching plugin used by the SerialTransactionExecutor and ParallelTransactionExecutor classes. This example works by adding missing object versions and digest from a cache. Updating the cache (which could be done by looking at transaction effects of previous transactions) is not covered in this example.

import {
    BuildTransactionOptions,
    Transaction,
    TransactionDataBuilder,
} from '@iota/iota-sdk/transactions';

const objectCache = new Map<string, { objectId: string; version: string; digest: string }>();

function simpleObjectCachePlugin(
    transactionData: TransactionDataBuilder,
    _options: BuildTransactionOptions,
    next: () => Promise<void>,
) {
    for (const input of transactionData.inputs) {
        if (!input.UnresolvedObject) continue;

        const cached = objectCache.get(input.UnresolvedObject.objectId);

        if (!cached) continue;

        if (cached.version && !input.UnresolvedObject.version) {
            input.UnresolvedObject.version = cached.version;
        }

        if (cached.digest && !input.UnresolvedObject.digest) {
            input.UnresolvedObject.digest = cached.digest;
        }
    }

    return next();
}

// Example usage of the build plugin
const transaction = new Transaction();
transaction.addBuildPlugin(simpleObjectCachePlugin);

Transaction Intents​

Transaction Intents consist of two parts: adding the intent to the transaction and resolving the intent to standard commands.

Adding an intent is similar to adding any other command to a transaction:

import { Commands, Transaction } from '@iota/iota-sdk/transactions';

const transaction = new Transaction();

transaction.add(
    Commands.Intent({
        name: 'TransferToSender',
        inputs: {
            objects: [transaction.object(someId)],
        },
    }),
);

To make our custom TransferToSender intent easier to use, we can write a helper function that wraps things up a bit. The add method on transactions accepts a function that will be passed the current transaction instance. This allows us to create a helper that automatically adds the intent:

import { Commands, Transaction, TransactionObjectInput } from '@iota/iota-sdk/transactions';

function transferToSender(objects: TransactionObjectInput[]) {
    return (tx: Transaction) => {
        tx.add(
            Commands.Intent({
                name: 'TransferToSender',
                inputs: {
                    objects: objects.map((obj) => tx.object(obj)),
                },
            }),
        );
    };
}

const transaction = new Transaction();

transaction.add(transferToSender(['0x1234']));

Now that we've added the intent to the transaction, we need to resolve the intent to standard commands. To do this, we'll use the addIntentResolver method on the Transaction instance. The addIntentResolver method works like serialization and build plugins but will only be called if the intent is present in the transaction.

import { Transaction } from '@iota/iota-sdk/transactions';

const transaction = new Transaction();

transaction.addIntentResolver('TransferToSender', resolveTransferToSender);

async function resolveTransferToSender(
    transactionData: TransactionDataBuilder,
    buildOptions: BuildTransactionOptions,
    next: () => Promise<void>,
) {
    if (!transactionData.sender) {
        throw new Error('Sender must be set to resolve TransferToSender');
    }

    // Add an input that references the sender's address
    const addressInput = Inputs.Pure(bcs.Address.serialize(transactionData.sender));
    transactionData.inputs.push(addressInput);
    // Get the index of the input to use when adding the TransferObjects command
    const addressIndex = transactionData.inputs.length - 1;

    for (const [index, transaction] of transactionData.commands.entries()) {
        if (transaction.$kind !== '$Intent' || transaction.$Intent.name !== 'TransferToSender') {
            continue;
        }

        // This will replace the intent command with the correct TransferObjects command
        transactionData.replaceCommand(index, [
            Commands.TransferObjects(
                // The inputs for intents are not currently typed, so we need to cast to the correct type here
                transaction.$Intent.inputs.objects as Extract<
                    TransactionObjectArgument,
                    { $kind: 'Input' }
                >,
                // This is a CallArg referencing the addressInput we added above
                {
                    Input: addressIndex,
                },
            ),
        ]);
    }

    // Plugins always need to call next() to continue the build process
    return next();
}

Manually adding intent resolvers to a transaction can be cumbersome, so we can add the resolver automatically when our transferToSender helper is called:

import { Commands, Transaction, TransactionObjectInput } from '@iota/iota-sdk/transactions';

function transferToSender(objects: TransactionObjectInput[]) {
    return (tx: Transaction) => {
        // As long as we are adding the same function reference, it will only be added once
        tx.addIntentResolver('TransferToSender', resolveTransferToSender);
        tx.add(
            Commands.Intent({
                name: 'TransferToSender',
                inputs: {
                    objects: objects.map((obj) => tx.object(obj)),
                },
            }),
        );
    };
}

const transaction = new Transaction();
transaction.add(transferToSender(['0x1234']));