Skip to content

Creating a Complete Aggregate Transaction⚓︎

ADVANCED

This tutorial shows how to create an asset swap using complete aggregate transactions.

In this example, Account A sends 10 XYM to Account B, while Account B simultaneously sends 1 custom mosaic back to Account A:

clusterAggregateComplete Aggregate TransactionclusterT2Embedded Transfer 2clusterT1Embedded Transfer 1A1Account AB1Account BA1->B11 Custom MosaicA2Account AB2Account BA2->B210 XYM

Both parties coordinate off-chain to collect signatures before announcement, ensuring the swap executes as a single atomic transaction.

Two types of aggregate transactions

Aggregate transactions group multiple transactions in a single operation, and require signatures from all involved accounts.

A complete aggregate transaction collects all signatures before being announced. This procedure works well, for example, in the following scenarios:

  • Multi-party coordination: When parties can communicate off-chain to exchange transaction payloads and cosignatures.
  • Single-account batching: When one account wants to execute multiple transactions atomically. No cosignatures are needed in this case.

If off-chain coordination is impractical, use bonded aggregate transactions instead, which allow cosignatures to be collected on the network.

Prerequisites⚓︎

Before you start, make sure to set up your development environment. See Setting Up a Development Environment.

You also need two accounts with XYM and one custom mosaic to complete the swap. Although pre-funded accounts are provided for convenience, they are not maintained and may run out of funds.

To use your own accounts, complete the following steps:

Additionally, review the Transfer transaction tutorial to understand how transactions are announced and confirmed.

Full Code⚓︎

The following is the complete code listing for this tutorial. A detailed, step-by-step explanation follows in the next section.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
import json
import os
import time
import urllib.request

from symbolchain.CryptoTypes import PrivateKey
from symbolchain.facade.SymbolFacade import SymbolFacade
from symbolchain.symbol.IdGenerator import generate_mosaic_alias_id

NODE_URL = os.getenv('NODE_URL', 'https://reference.symboltest.net:3001')
print(f'Using node {NODE_URL}')


# Helper function to announce a transaction
def announce_transaction(payload, label):
    print(f'Announcing {label} to /transactions')
    request = urllib.request.Request(
        f'{NODE_URL}/transactions',
        data=payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='PUT'
    )
    with urllib.request.urlopen(request) as announce_response:
        print(f'  Response: {announce_response.read().decode()}')


# Helper function to wait for transaction confirmation
def wait_for_confirmation(tx_hash, label):
    print(f'Waiting for {label} confirmation...')
    for attempt in range(60):
        time.sleep(1)
        try:
            url = f'{NODE_URL}/transactionStatus/{tx_hash}'
            with urllib.request.urlopen(url) as confirm_response:
                status = json.loads(confirm_response.read().decode())
                print(f'  Transaction status: {status["group"]}')
                if status['group'] == 'confirmed':
                    print(f'{label} confirmed in {attempt} seconds')
                    return
                if status['group'] == 'failed':
                    raise RuntimeError(
                        f'{label} failed: {status["code"]}')
        except urllib.error.HTTPError:
            print('  Transaction status: unknown')
    raise TimeoutError(f'{label} not confirmed after 60 seconds')


# Account A (initiates the aggregate tx and sends XYM to Account B)
ACCOUNT_A_PRIVATE_KEY = os.getenv(
    'ACCOUNT_A_PRIVATE_KEY',
    '0000000000000000000000000000000000000000000000000000000000000000')
account_a_key_pair = SymbolFacade.KeyPair(
    PrivateKey(ACCOUNT_A_PRIVATE_KEY))

# Account B (sends custom mosaic to Account A)
ACCOUNT_B_PRIVATE_KEY = os.getenv(
    'ACCOUNT_B_PRIVATE_KEY',
    '1111111111111111111111111111111111111111111111111111111111111111')
account_b_key_pair = SymbolFacade.KeyPair(
    PrivateKey(ACCOUNT_B_PRIVATE_KEY))

facade = SymbolFacade('testnet')
account_a_address = facade.network.public_key_to_address(
    account_a_key_pair.public_key)
account_b_address = facade.network.public_key_to_address(
    account_b_key_pair.public_key)
print(f'Account A: {account_a_address}')
print(f'Account B: {account_b_address}')

try:
    # Fetch recommended fees
    fee_path = '/network/fees/transaction'
    print(f'Fetching recommended fees from {fee_path}')
    with urllib.request.urlopen(f'{NODE_URL}{fee_path}') as response:
        response_json = json.loads(response.read().decode())
        median_multiplier = response_json['medianFeeMultiplier']
        minimum_multiplier = response_json['minFeeMultiplier']
        fee_multiplier = max(median_multiplier, minimum_multiplier)
        print(f'  Fee multiplier: {fee_multiplier}')

    # Embedded tx 1: Account A transfers 10 XYM to Account B
    embedded_transaction_1 = (
        facade.create_embedded_transaction_from_descriptor(
            {
                'type': 'transfer_transaction_v1',
                'recipient_address': account_b_address,
                'mosaics': [{
                    'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
                    'amount': 10_000_000  # 10 XYM
                }]
            },
            account_a_key_pair.public_key))

    # Embedded tx 2: Account B transfers 1 custom mosaic to Account A
    custom_mosaic_id = 0x6D1314BE751B62C2
    embedded_transaction_2 = (
        facade.create_embedded_transaction_from_descriptor(
            {
                'type': 'transfer_transaction_v1',
                'recipient_address': account_a_address,
                'mosaics': [{
                    'mosaic_id': custom_mosaic_id,
                    'amount': 1  # 1 custom mosaic
                }]
            },
            account_b_key_pair.public_key))

    # Build the aggregate transaction
    embedded_transactions = [
        embedded_transaction_1, embedded_transaction_2]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        account_a_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60,
        1)
    print('Built aggregate transaction without signatures:')
    print(json.dumps(transaction.to_json(), indent=2))

    # --- ACCOUNT A (Initiator) ---
    print('[Account A] Signing the aggregate...')
    signature_a = facade.sign_transaction(
        account_a_key_pair, transaction)
    transaction_payload = facade.transaction_factory.attach_signature(
        transaction, signature_a)
    payload_formatted = json.dumps(
        json.loads(transaction_payload), indent=2)
    print(f'[Account A] Payload ready to share:\n{payload_formatted}')

    # --- OFF-CHAIN COORDINATION ---
    # Account A sends the payload to Account B
    shared_payload = transaction_payload
    print('[Account A] ==> Payload sent to Account B (offchain)')

    # --- ACCOUNT B (Cosignatory) ---
    received_transaction = facade.transaction_factory.deserialize(
        bytes.fromhex(json.loads(shared_payload)['payload']))

    print('[Account B] Cosigning...')
    cosignature_b = facade.cosign_transaction(
        account_b_key_pair, received_transaction)
    cosignature_formatted = json.dumps(cosignature_b.to_json(), indent=2)
    print(f'[Account B] Cosignature created: {cosignature_formatted}')

    # --- OFF-CHAIN COORDINATION ---
    # Account B sends the cosignature back to Account A
    shared_cosignature = cosignature_b
    print(
        '[Account B] <== Cosignature sent back to Account A (offchain)')

    # --- ACCOUNT A (Initiator) ---
    # Add cosignature to the transaction and rebuild payload
    transaction.cosignatures.append(shared_cosignature)
    transaction_payload = facade.transaction_factory.to_json(transaction)
    json_payload = transaction_payload
    print('[Account A] Ready to announce')

    # Announce the transaction
    transaction_hash = facade.hash_transaction(transaction)
    print(f'Transaction hash: {transaction_hash}')
    announce_transaction(json_payload, 'transaction')

    # Wait for confirmation
    wait_for_confirmation(transaction_hash, 'transaction')

except Exception as e:
    print(e)

Download source

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
import { PrivateKey } from 'symbol-sdk';
import {
    SymbolFacade,
    descriptors,
    generateMosaicAliasId,
    models
} from 'symbol-sdk/symbol';

const NODE_URL = process.env.NODE_URL ||
    'https://reference.symboltest.net:3001';
console.log('Using node', NODE_URL);

// Helper function to announce a transaction
async function announceTransaction(payload, label) {
    console.log(`Announcing ${label} to /transactions`);
    const response = await fetch(`${NODE_URL}/transactions`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: payload
    });
    console.log('  Response:', await response.text());
}

// Helper function to wait for transaction confirmation
async function waitForConfirmation(transactionHash, label) {
    console.log(`Waiting for ${label} confirmation...`);
    for (let attempt = 0; 60 > attempt; attempt++) {
        await new Promise(resolve => { setTimeout(resolve, 1000); });
        const response = await fetch(
            `${NODE_URL}/transactionStatus/${transactionHash}`);
        if (!response.ok) {
            if (404 === response.status) {
                console.log('  Transaction status: unknown');
                continue;
            }
            throw new Error(`HTTP ${response.status}`);
        }
        const status = await response.json();
        console.log('  Transaction status:', status.group);
        if ('confirmed' === status.group) {
            console.log(`${label} confirmed in`, attempt, 'seconds');
            return;
        }
        if ('failed' === status.group)
            throw new Error(`${label} failed: ${status.code}`);
    }
    throw new Error(`${label} not confirmed after 60 seconds`);
}


// Account A (initiates the aggregate tx and sends XYM to Account B)
const ACCOUNT_A_PRIVATE_KEY = process.env.ACCOUNT_A_PRIVATE_KEY || (
    '0000000000000000000000000000000000000000000000000000000000000000');
const accountAKeyPair = new SymbolFacade.KeyPair(
    new PrivateKey(ACCOUNT_A_PRIVATE_KEY));

// Account B (sends custom mosaic to Account A)
const ACCOUNT_B_PRIVATE_KEY = process.env.ACCOUNT_B_PRIVATE_KEY || (
    '1111111111111111111111111111111111111111111111111111111111111111');
const accountBKeyPair = new SymbolFacade.KeyPair(
    new PrivateKey(ACCOUNT_B_PRIVATE_KEY));

const facade = new SymbolFacade('testnet');
const accountAAddress = facade.network.publicKeyToAddress(
    accountAKeyPair.publicKey);
const accountBAddress = facade.network.publicKeyToAddress(
    accountBKeyPair.publicKey);
console.log('Account A:', accountAAddress.toString());
console.log('Account B:', accountBAddress.toString());

try {
    // Fetch recommended fees
    const feePath = '/network/fees/transaction';
    console.log('Fetching recommended fees from', feePath);
    const feeResponse = await fetch(`${NODE_URL}${feePath}`);
    const feeJSON = await feeResponse.json();
    const medianMultiplier = feeJSON.medianFeeMultiplier;
    const minimumMultiplier = feeJSON.minFeeMultiplier;
    const feeMultiplier = Math.max(medianMultiplier, minimumMultiplier);
    console.log('  Fee multiplier:', feeMultiplier);

    // Embedded tx 1: Account A transfers 10 XYM to Account B
    const embeddedTransaction1 =
        facade.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.TransferTransactionV1Descriptor(
                accountBAddress,
                [
                    new descriptors.UnresolvedMosaicDescriptor(
                        generateMosaicAliasId('symbol.xym'),
                        new models.Amount(10_000_000n)) // 10 XYM
                ],
                undefined),
            accountAKeyPair.publicKey);

    // Embedded tx 2: Account B transfers 1 custom mosaic to Account A
    const customMosaicId = 0x6D1314BE751B62C2n;
    const embeddedTransaction2 =
        facade.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.TransferTransactionV1Descriptor(
                accountAAddress,
                [
                    new descriptors.UnresolvedMosaicDescriptor(
                        customMosaicId,
                        new models.Amount(1n)) // 1 custom mosaic
                ],
                undefined),
            accountBKeyPair.publicKey);

    // Build the aggregate transaction
    const embeddedTransactions = [
        embeddedTransaction1, embeddedTransaction2];
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60,
        1);
    console.log('Built aggregate transaction without signatures:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

    // --- ACCOUNT A (Initiator) ---
    console.log('[Account A] Signing the aggregate...');
    const signatureA = facade.signTransaction(
        accountAKeyPair, transaction);
    const transactionPayload = facade.transactionFactory.static
        .attachSignature(transaction, signatureA);
    const payloadFormatted = JSON.stringify(
        JSON.parse(transactionPayload), null, 2);
    console.log('[Account A] Payload ready to share:\n',
        payloadFormatted);

    // --- OFF-CHAIN COORDINATION ---
    // Account A sends the payload to Account B
    const sharedPayload = transactionPayload;
    console.log('[Account A] ==> Payload sent to Account B (offchain)');

    // --- ACCOUNT B (Cosignatory) ---
    const payloadHex = JSON.parse(sharedPayload).payload;
    const receivedTransaction = facade.transactionFactory.static
        .deserialize(Buffer.from(payloadHex, 'hex'));

    console.log('[Account B] Cosigning...');
    const cosignatureB = facade.cosignTransaction(
        accountBKeyPair, receivedTransaction);
    const cosignatureFormatted = JSON.stringify(
        cosignatureB.toJson(), null, 2);
    console.log('[Account B] Cosignature created:',
        cosignatureFormatted);

    // --- OFF-CHAIN COORDINATION ---
    // Account B sends the cosignature back to Account A
    const sharedCosignature = cosignatureB;
    console.log('[Account B] <== Cosignature sent back to Account A',
        '(offchain)');

    // --- ACCOUNT A (Initiator) ---
    // Add cosignature to the transaction and rebuild payload
    transaction.cosignatures.push(sharedCosignature);
    const transactionPayloadFinal = facade.transactionFactory.static
        .toJson(transaction);
    const jsonPayload = transactionPayloadFinal;
    console.log('[Account A] Ready to announce');

    // Announce the transaction
    const transactionHash =
        facade.hashTransaction(transaction).toString();
    console.log('Transaction hash:', transactionHash);
    await announceTransaction(jsonPayload, 'transaction');

    // Wait for confirmation
    await waitForConfirmation(transactionHash, 'transaction');

} catch (e) {
    console.error(e.message, '| Cause:', e.cause?.code ?? 'unknown');
}

Download source

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
//JAVA 21+
//DEPS org.symbol:symbol-sdk:3.3.1

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.HexFormat;
import java.util.List;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import org.symbol.sdk.CryptoTypes;
import org.symbol.sdk.facade.SymbolFacade;
import org.symbol.sdk.symbol.Address;
import org.symbol.sdk.symbol.IdGenerator;
import org.symbol.sdk.symbol.KeyPair;
import org.symbol.sdk.symbol.SymbolTransactionFactory;
import org.symbol.sdk.symbol.descriptors.*;
import org.symbol.sdk.symbol.models.*;

public final class CompleteAggregate {
    private static final ObjectMapper JSON_MAPPER = new ObjectMapper();

    private static final HttpClient HTTP_CLIENT =
        HttpClient.newHttpClient();

    private final String nodeUrl = System.getenv().getOrDefault(
        "NODE_URL", "https://reference.symboltest.net:3001");

    private final SymbolFacade facade = new SymbolFacade("testnet");

    private void announceTransaction(
        final String payload,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf("Announcing %s to /transactions%n", label);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + "/transactions"))
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        final HttpResponse<String> response = HTTP_CLIENT.send(
            request, BodyHandlers.ofString());
        System.out.printf("  Response: %s%n", response.body());
    }

    private void waitForConfirmation(
        final String transactionHash,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf("Waiting for %s confirmation...%n", label);
        for (int attempt = 0; 60 > attempt; ++attempt) {
            Thread.sleep(1000);
            final String statusPath =
                "/transactionStatus/" + transactionHash;
            final HttpRequest statusRequest = HttpRequest.newBuilder(
                URI.create(nodeUrl + statusPath)).GET().build();
            final HttpResponse<String> statusResponse = HTTP_CLIENT
                .send(statusRequest, BodyHandlers.ofString());
            if (404 == statusResponse.statusCode()) {
                System.out.println("  Transaction status: unknown");
                continue;
            }
            if (2 != statusResponse.statusCode() / 100)
                throw new IOException(
                    "HTTP " + statusResponse.statusCode());

            final JsonNode status =
                JSON_MAPPER.readTree(statusResponse.body());
            final String group = status.get("group").asText();
            System.out.printf("  Transaction status: %s%n", group);
            if ("confirmed".equals(group)) {
                System.out.printf("%s confirmed in %d seconds%n",
                    label, attempt);
                return;
            }
            if ("failed".equals(group))
                throw new IOException(String.format("%s failed: %s",
                    label, status.get("code").asText()));
        }
        throw new IOException(String.format(
            "%s not confirmed after 60 seconds", label));
    }

    public static void main(final String[] args) {
        try {
            new CompleteAggregate().run();
        } catch (final Exception ex) {
            System.out.println(null == ex.getMessage()
                ? ex.toString()
                : ex.getMessage());
        }
    }

    private void run() throws IOException, InterruptedException {
        System.out.printf("Using node %s%n", nodeUrl);

        // Account A (initiates the aggregate tx and sends XYM to
        // Account B)
        final String accountAPrivateKey = System.getenv().getOrDefault(
            "ACCOUNT_A_PRIVATE_KEY", "0".repeat(64));
        final KeyPair accountAKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountAPrivateKey));

        // Account B (sends custom mosaic to Account A)
        final String accountBPrivateKey = System.getenv().getOrDefault(
            "ACCOUNT_B_PRIVATE_KEY", "1".repeat(64));
        final KeyPair accountBKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountBPrivateKey));

        final Address accountAAddress = facade.network.publicKeyToAddress(
            accountAKeyPair.getPublicKey());
        final Address accountBAddress = facade.network.publicKeyToAddress(
            accountBKeyPair.getPublicKey());
        System.out.printf("Account A: %s%n", accountAAddress);
        System.out.printf("Account B: %s%n", accountBAddress);

        // Fetch recommended fees
        final String feePath = "/network/fees/transaction";
        System.out.printf(
            "Fetching recommended fees from %s%n", feePath);
        final HttpRequest feeRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + feePath)).GET().build();
        final HttpResponse<String> feeResponse = HTTP_CLIENT.send(
            feeRequest, BodyHandlers.ofString());
        final JsonNode feeJSON = JSON_MAPPER.readTree(
            feeResponse.body());
        final long medianMultiplier =
            feeJSON.get("medianFeeMultiplier").asLong();
        final long minimumMultiplier =
            feeJSON.get("minFeeMultiplier").asLong();
        final long feeMultiplier = Math.max(
            medianMultiplier, minimumMultiplier);
        System.out.printf("  Fee multiplier: %d%n", feeMultiplier);

        // Embedded tx 1: Account A transfers 10 XYM to Account B
        final EmbeddedTransaction embeddedTransaction1 =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new TransferTransactionV1Descriptor(
                    accountBAddress,
                    List.of(new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(
                            IdGenerator.generateMosaicAliasId(
                                "symbol.xym")),
                        new Amount(10_000_000))), // 10 XYM
                    null),
                accountAKeyPair.getPublicKey());

        // Embedded tx 2: Account B transfers 1 custom mosaic to Account A
        final long customMosaicId = 0x6D1314BE751B62C2L;
        final EmbeddedTransaction embeddedTransaction2 =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new TransferTransactionV1Descriptor(
                    accountAAddress,
                    List.of(new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(customMosaicId),
                        new Amount(1))), // 1 custom mosaic
                    null),
                accountBKeyPair.getPublicKey());

        // Build the aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction1, embeddedTransaction2);
        final AggregateCompleteTransactionV3 transaction =
            (AggregateCompleteTransactionV3) facade
                .createTransactionFromTypedDescriptor(
                    new AggregateCompleteTransactionV3Descriptor(
                        SymbolFacade.hashEmbeddedTransactions(
                            embeddedTransactions),
                        embeddedTransactions,
                        null),
                    accountAKeyPair.getPublicKey(),
                    feeMultiplier,
                    2 * 60 * 60,
                    1);
        System.out.println(
            "Built aggregate transaction without signatures:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

        // --- ACCOUNT A (Initiator) ---
        System.out.println("[Account A] Signing the aggregate...");
        final CryptoTypes.Signature signatureA = facade.signTransaction(
            accountAKeyPair, transaction);
        final String transactionPayload = SymbolTransactionFactory
            .attachSignature(transaction, signatureA);
        final String payloadFormatted = JSON_MAPPER
            .writerWithDefaultPrettyPrinter()
            .writeValueAsString(JSON_MAPPER.readTree(transactionPayload));
        System.out.printf("[Account A] Payload ready to share:%n %s%n",
            payloadFormatted);

        // --- OFF-CHAIN COORDINATION ---
        // Account A sends the payload to Account B
        final String sharedPayload = transactionPayload;
        System.out.println(
            "[Account A] ==> Payload sent to Account B (offchain)");

        // --- ACCOUNT B (Cosignatory) ---
        final String payloadHex = JSON_MAPPER.readTree(sharedPayload)
            .get("payload").asText();
        final Transaction receivedTransaction =
            SymbolTransactionFactory.deserialize(
                HexFormat.of().parseHex(payloadHex));

        System.out.println("[Account B] Cosigning...");
        final Cosignature cosignatureB = facade.cosignTransaction(
            accountBKeyPair, receivedTransaction);
        final String cosignatureFormatted = JSON_MAPPER
            .writerWithDefaultPrettyPrinter()
            .writeValueAsString(cosignatureB.toJson());
        System.out.printf("[Account B] Cosignature created: %s%n",
            cosignatureFormatted);

        // --- OFF-CHAIN COORDINATION ---
        // Account B sends the cosignature back to Account A
        final Cosignature sharedCosignature = cosignatureB;
        System.out.println("[Account B] <== Cosignature sent back "
            + "to Account A (offchain)");

        // --- ACCOUNT A (Initiator) ---
        // Add cosignature to the transaction and rebuild payload
        transaction.getCosignatures().add(sharedCosignature);
        final String transactionPayloadFinal =
            SymbolTransactionFactory.toJson(transaction);
        final String jsonPayload = transactionPayloadFinal;
        System.out.println("[Account A] Ready to announce");

        // Announce the transaction
        final String transactionHash =
            facade.hashTransaction(transaction).toString();
        System.out.printf("Transaction hash: %s%n", transactionHash);
        announceTransaction(jsonPayload, "transaction");

        // Wait for confirmation
        waitForConfirmation(transactionHash, "transaction");

    }
}

Download source

The whole code is wrapped in a single try block to provide simple error handling, but applications will probably want to use more fine-grained control.

A complete aggregate transaction may involve two distinct roles: an initiator (Account A) that builds and announces the aggregate, and one or more cosigners (Account B, and any additional cosigners) that receive the transaction payload off-chain and add their signatures after verifying the transaction. When only one account is involved, no cosignatures are needed.

In practice, each role runs as a separate program on a separate machine. This tutorial demonstrates the multi-party case but combines both roles in a single script for simplicity.

Account A: Initiator Workflow⚓︎

Setting Up Accounts⚓︎

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# Account A (initiates the aggregate tx and sends XYM to Account B)
ACCOUNT_A_PRIVATE_KEY = os.getenv(
    'ACCOUNT_A_PRIVATE_KEY',
    '0000000000000000000000000000000000000000000000000000000000000000')
account_a_key_pair = SymbolFacade.KeyPair(
    PrivateKey(ACCOUNT_A_PRIVATE_KEY))

# Account B (sends custom mosaic to Account A)
ACCOUNT_B_PRIVATE_KEY = os.getenv(
    'ACCOUNT_B_PRIVATE_KEY',
    '1111111111111111111111111111111111111111111111111111111111111111')
account_b_key_pair = SymbolFacade.KeyPair(
    PrivateKey(ACCOUNT_B_PRIVATE_KEY))

facade = SymbolFacade('testnet')
account_a_address = facade.network.public_key_to_address(
    account_a_key_pair.public_key)
account_b_address = facade.network.public_key_to_address(
    account_b_key_pair.public_key)
print(f'Account A: {account_a_address}')
print(f'Account B: {account_b_address}')

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
// Account A (initiates the aggregate tx and sends XYM to Account B)
const ACCOUNT_A_PRIVATE_KEY = process.env.ACCOUNT_A_PRIVATE_KEY || (
    '0000000000000000000000000000000000000000000000000000000000000000');
const accountAKeyPair = new SymbolFacade.KeyPair(
    new PrivateKey(ACCOUNT_A_PRIVATE_KEY));

// Account B (sends custom mosaic to Account A)
const ACCOUNT_B_PRIVATE_KEY = process.env.ACCOUNT_B_PRIVATE_KEY || (
    '1111111111111111111111111111111111111111111111111111111111111111');
const accountBKeyPair = new SymbolFacade.KeyPair(
    new PrivateKey(ACCOUNT_B_PRIVATE_KEY));

const facade = new SymbolFacade('testnet');
const accountAAddress = facade.network.publicKeyToAddress(
    accountAKeyPair.publicKey);
const accountBAddress = facade.network.publicKeyToAddress(
    accountBKeyPair.publicKey);
console.log('Account A:', accountAAddress.toString());
console.log('Account B:', accountBAddress.toString());

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
        // Account A (initiates the aggregate tx and sends XYM to
        // Account B)
        final String accountAPrivateKey = System.getenv().getOrDefault(
            "ACCOUNT_A_PRIVATE_KEY", "0".repeat(64));
        final KeyPair accountAKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountAPrivateKey));

        // Account B (sends custom mosaic to Account A)
        final String accountBPrivateKey = System.getenv().getOrDefault(
            "ACCOUNT_B_PRIVATE_KEY", "1".repeat(64));
        final KeyPair accountBKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountBPrivateKey));

        final Address accountAAddress = facade.network.publicKeyToAddress(
            accountAKeyPair.getPublicKey());
        final Address accountBAddress = facade.network.publicKeyToAddress(
            accountBKeyPair.getPublicKey());
        System.out.printf("Account A: %s%n", accountAAddress);
        System.out.printf("Account B: %s%n", accountBAddress);

This example includes both private keys in one script for simplicity. In practice, each party signs on their own machine. Account A only needs Account B's public key to build the aggregate, because B's public key is required to set B as the signer of an embedded transaction and to derive B's address.

The ACCOUNT_A_PRIVATE_KEY and ACCOUNT_B_PRIVATE_KEY environment variables set the keys for each account. If not provided, test keys are used as defaults. If using your own keys, ensure Account A has XYM and Account B holds a custom mosaic for the swap.

The addresses for both accounts are derived from their public keys using the facade's network configuration.

71
72
73
74
75
76
77
78
79
    # Fetch recommended fees
    fee_path = '/network/fees/transaction'
    print(f'Fetching recommended fees from {fee_path}')
    with urllib.request.urlopen(f'{NODE_URL}{fee_path}') as response:
        response_json = json.loads(response.read().decode())
        median_multiplier = response_json['medianFeeMultiplier']
        minimum_multiplier = response_json['minFeeMultiplier']
        fee_multiplier = max(median_multiplier, minimum_multiplier)
        print(f'  Fee multiplier: {fee_multiplier}')

72
73
74
75
76
77
78
79
80
    // Fetch recommended fees
    const feePath = '/network/fees/transaction';
    console.log('Fetching recommended fees from', feePath);
    const feeResponse = await fetch(`${NODE_URL}${feePath}`);
    const feeJSON = await feeResponse.json();
    const medianMultiplier = feeJSON.medianFeeMultiplier;
    const minimumMultiplier = feeJSON.minFeeMultiplier;
    const feeMultiplier = Math.max(medianMultiplier, minimumMultiplier);
    console.log('  Fee multiplier:', feeMultiplier);

122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
        // Fetch recommended fees
        final String feePath = "/network/fees/transaction";
        System.out.printf(
            "Fetching recommended fees from %s%n", feePath);
        final HttpRequest feeRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + feePath)).GET().build();
        final HttpResponse<String> feeResponse = HTTP_CLIENT.send(
            feeRequest, BodyHandlers.ofString());
        final JsonNode feeJSON = JSON_MAPPER.readTree(
            feeResponse.body());
        final long medianMultiplier =
            feeJSON.get("medianFeeMultiplier").asLong();
        final long minimumMultiplier =
            feeJSON.get("minFeeMultiplier").asLong();
        final long feeMultiplier = Math.max(
            medianMultiplier, minimumMultiplier);
        System.out.printf("  Fee multiplier: %d%n", feeMultiplier);

Recommended fees are fetched from /network/fees/transaction GET, following the process described in the Transfer Transaction tutorial.

Creating Embedded Transactions⚓︎

 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
    # Embedded tx 1: Account A transfers 10 XYM to Account B
    embedded_transaction_1 = (
        facade.create_embedded_transaction_from_descriptor(
            {
                'type': 'transfer_transaction_v1',
                'recipient_address': account_b_address,
                'mosaics': [{
                    'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
                    'amount': 10_000_000  # 10 XYM
                }]
            },
            account_a_key_pair.public_key))

    # Embedded tx 2: Account B transfers 1 custom mosaic to Account A
    custom_mosaic_id = 0x6D1314BE751B62C2
    embedded_transaction_2 = (
        facade.create_embedded_transaction_from_descriptor(
            {
                'type': 'transfer_transaction_v1',
                'recipient_address': account_a_address,
                'mosaics': [{
                    'mosaic_id': custom_mosaic_id,
                    'amount': 1  # 1 custom mosaic
                }]
            },
            account_b_key_pair.public_key))

 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
    // Embedded tx 1: Account A transfers 10 XYM to Account B
    const embeddedTransaction1 =
        facade.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.TransferTransactionV1Descriptor(
                accountBAddress,
                [
                    new descriptors.UnresolvedMosaicDescriptor(
                        generateMosaicAliasId('symbol.xym'),
                        new models.Amount(10_000_000n)) // 10 XYM
                ],
                undefined),
            accountAKeyPair.publicKey);

    // Embedded tx 2: Account B transfers 1 custom mosaic to Account A
    const customMosaicId = 0x6D1314BE751B62C2n;
    const embeddedTransaction2 =
        facade.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.TransferTransactionV1Descriptor(
                accountAAddress,
                [
                    new descriptors.UnresolvedMosaicDescriptor(
                        customMosaicId,
                        new models.Amount(1n)) // 1 custom mosaic
                ],
                undefined),
            accountBKeyPair.publicKey);

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
        // Embedded tx 1: Account A transfers 10 XYM to Account B
        final EmbeddedTransaction embeddedTransaction1 =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new TransferTransactionV1Descriptor(
                    accountBAddress,
                    List.of(new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(
                            IdGenerator.generateMosaicAliasId(
                                "symbol.xym")),
                        new Amount(10_000_000))), // 10 XYM
                    null),
                accountAKeyPair.getPublicKey());

        // Embedded tx 2: Account B transfers 1 custom mosaic to Account A
        final long customMosaicId = 0x6D1314BE751B62C2L;
        final EmbeddedTransaction embeddedTransaction2 =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new TransferTransactionV1Descriptor(
                    accountAAddress,
                    List.of(new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(customMosaicId),
                        new Amount(1))), // 1 custom mosaic
                    null),
                accountBKeyPair.getPublicKey());

The embedded transactions define the operations to execute atomically. Each embedded transaction specifies:

  • Type: All transaction types can be embedded within aggregates (except other aggregates). For embedded transfers, use TransferTransactionV1, the same as for basic transfer transactions.

  • Signer public key: The account that would sign this transaction if it were announced independently.

  • Transaction-specific fields: All fields specific to the transaction type must be provided. For transfers, this includes the recipient address and the mosaics to send.

Note that embedded transactions do not include fee or deadline fields. These are inherited from the enclosing aggregate transaction.

The example creates two transfer transactions for the swap:

  • The first transfer sends 10 XYM from Account A to Account B.
  • The second transfer sends 1 custom mosaic from Account B to Account A.

About the custom mosaic

The custom mosaic with ID 0x6D1314BE751B62C2 was created for this tutorial. The default Account B has been seeded with this mosaic so the swap can execute successfully.

If using your own accounts, ensure Account B holds a custom mosaic and update the mosaic ID in the code.

Building the Aggregate Transaction⚓︎

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
    # Build the aggregate transaction
    embedded_transactions = [
        embedded_transaction_1, embedded_transaction_2]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        account_a_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60,
        1)
    print('Built aggregate transaction without signatures:')
    print(json.dumps(transaction.to_json(), indent=2))

109
110
111
112
113
114
115
116
117
118
119
120
121
122
    // Build the aggregate transaction
    const embeddedTransactions = [
        embeddedTransaction1, embeddedTransaction2];
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60,
        1);
    console.log('Built aggregate transaction without signatures:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
        // Build the aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction1, embeddedTransaction2);
        final AggregateCompleteTransactionV3 transaction =
            (AggregateCompleteTransactionV3) facade
                .createTransactionFromTypedDescriptor(
                    new AggregateCompleteTransactionV3Descriptor(
                        SymbolFacade.hashEmbeddedTransactions(
                            embeddedTransactions),
                        embeddedTransactions,
                        null),
                    accountAKeyPair.getPublicKey(),
                    feeMultiplier,
                    2 * 60 * 60,
                    1);
        System.out.println(
            "Built aggregate transaction without signatures:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

Once the embedded transactions are prepared, create the complete aggregate transaction from the transaction's descriptor. The descriptor contains:

also receives the signer public key, fee multiplier, deadline duration, and reserved cosignature count. The signer initiates the aggregate, announces the transaction, and pays the transaction fee.

Sharing transaction fees

While the signer pays the entire fee upfront, other participants can contribute to the cost within the aggregate. For more details, see the Paying Transaction Fees on Behalf of Another Account tutorial.

calculates the fee based on the aggregate's total size, which includes all embedded transactions plus space reserved for one cosignature. The reserved cosignature count is provided as the final argument, set to 1 here.

Signing the Transaction⚓︎

125
126
127
128
129
130
131
132
133
134
135
136
137
138
    # --- ACCOUNT A (Initiator) ---
    print('[Account A] Signing the aggregate...')
    signature_a = facade.sign_transaction(
        account_a_key_pair, transaction)
    transaction_payload = facade.transaction_factory.attach_signature(
        transaction, signature_a)
    payload_formatted = json.dumps(
        json.loads(transaction_payload), indent=2)
    print(f'[Account A] Payload ready to share:\n{payload_formatted}')

    # --- OFF-CHAIN COORDINATION ---
    # Account A sends the payload to Account B
    shared_payload = transaction_payload
    print('[Account A] ==> Payload sent to Account B (offchain)')

124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
    // --- ACCOUNT A (Initiator) ---
    console.log('[Account A] Signing the aggregate...');
    const signatureA = facade.signTransaction(
        accountAKeyPair, transaction);
    const transactionPayload = facade.transactionFactory.static
        .attachSignature(transaction, signatureA);
    const payloadFormatted = JSON.stringify(
        JSON.parse(transactionPayload), null, 2);
    console.log('[Account A] Payload ready to share:\n',
        payloadFormatted);

    // --- OFF-CHAIN COORDINATION ---
    // Account A sends the payload to Account B
    const sharedPayload = transactionPayload;
    console.log('[Account A] ==> Payload sent to Account B (offchain)');

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
        // --- ACCOUNT A (Initiator) ---
        System.out.println("[Account A] Signing the aggregate...");
        final CryptoTypes.Signature signatureA = facade.signTransaction(
            accountAKeyPair, transaction);
        final String transactionPayload = SymbolTransactionFactory
            .attachSignature(transaction, signatureA);
        final String payloadFormatted = JSON_MAPPER
            .writerWithDefaultPrettyPrinter()
            .writeValueAsString(JSON_MAPPER.readTree(transactionPayload));
        System.out.printf("[Account A] Payload ready to share:%n %s%n",
            payloadFormatted);

        // --- OFF-CHAIN COORDINATION ---
        // Account A sends the payload to Account B
        final String sharedPayload = transactionPayload;
        System.out.println(
            "[Account A] ==> Payload sent to Account B (offchain)");

Account A signs the transaction using and produces an intermediate payload using . This payload is not yet ready to announce because it is missing Account B's cosignature. Account A sends this intermediate payload to Account B through an off-chain channel.

Signatures in aggregate transactions

An account only signs once, even if it appears as the signer in multiple embedded transactions. In this tutorial, Account A signs the aggregate transaction, which covers both the aggregate itself and the first embedded transaction where Account A is the signer.

When all embedded transactions share the same signer (batching multiple operations from one account), cosignatures are not required. The aggregate can be announced immediately after signing, and the fee calculation does not need to reserve space for cosignatures.

Account B: Cosigner Workflow⚓︎

Verifying and Cosigning⚓︎

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
    # --- ACCOUNT B (Cosignatory) ---
    received_transaction = facade.transaction_factory.deserialize(
        bytes.fromhex(json.loads(shared_payload)['payload']))

    print('[Account B] Cosigning...')
    cosignature_b = facade.cosign_transaction(
        account_b_key_pair, received_transaction)
    cosignature_formatted = json.dumps(cosignature_b.to_json(), indent=2)
    print(f'[Account B] Cosignature created: {cosignature_formatted}')

    # --- OFF-CHAIN COORDINATION ---
    # Account B sends the cosignature back to Account A
    shared_cosignature = cosignature_b
    print(
        '[Account B] <== Cosignature sent back to Account A (offchain)')

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
    // --- ACCOUNT B (Cosignatory) ---
    const payloadHex = JSON.parse(sharedPayload).payload;
    const receivedTransaction = facade.transactionFactory.static
        .deserialize(Buffer.from(payloadHex, 'hex'));

    console.log('[Account B] Cosigning...');
    const cosignatureB = facade.cosignTransaction(
        accountBKeyPair, receivedTransaction);
    const cosignatureFormatted = JSON.stringify(
        cosignatureB.toJson(), null, 2);
    console.log('[Account B] Cosignature created:',
        cosignatureFormatted);

    // --- OFF-CHAIN COORDINATION ---
    // Account B sends the cosignature back to Account A
    const sharedCosignature = cosignatureB;
    console.log('[Account B] <== Cosignature sent back to Account A',
        '(offchain)');

203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
        // --- ACCOUNT B (Cosignatory) ---
        final String payloadHex = JSON_MAPPER.readTree(sharedPayload)
            .get("payload").asText();
        final Transaction receivedTransaction =
            SymbolTransactionFactory.deserialize(
                HexFormat.of().parseHex(payloadHex));

        System.out.println("[Account B] Cosigning...");
        final Cosignature cosignatureB = facade.cosignTransaction(
            accountBKeyPair, receivedTransaction);
        final String cosignatureFormatted = JSON_MAPPER
            .writerWithDefaultPrettyPrinter()
            .writeValueAsString(cosignatureB.toJson());
        System.out.printf("[Account B] Cosignature created: %s%n",
            cosignatureFormatted);

        // --- OFF-CHAIN COORDINATION ---
        // Account B sends the cosignature back to Account A
        final Cosignature sharedCosignature = cosignatureB;
        System.out.println("[Account B] <== Cosignature sent back "
            + "to Account A (offchain)");

Account B receives the payload and deserializes it using to reconstruct the transaction object. Account B should verify that the embedded transactions match what it expects to sign.

It then cosigns using , which computes the transaction hash and produces a cosignature object. Only this cosignature is sent back to Account A.

Verify before cosigning

Always inspect transaction content before cosigning. Cosignatures are binding and cannot be undone.

Account A: Announcing and Confirming⚓︎

Collecting the Cosignature⚓︎

156
157
158
159
160
161
    # --- ACCOUNT A (Initiator) ---
    # Add cosignature to the transaction and rebuild payload
    transaction.cosignatures.append(shared_cosignature)
    transaction_payload = facade.transaction_factory.to_json(transaction)
    json_payload = transaction_payload
    print('[Account A] Ready to announce')

159
160
161
162
163
164
165
    // --- ACCOUNT A (Initiator) ---
    // Add cosignature to the transaction and rebuild payload
    transaction.cosignatures.push(sharedCosignature);
    const transactionPayloadFinal = facade.transactionFactory.static
        .toJson(transaction);
    const jsonPayload = transactionPayloadFinal;
    console.log('[Account A] Ready to announce');

225
226
227
228
229
230
231
        // --- ACCOUNT A (Initiator) ---
        // Add cosignature to the transaction and rebuild payload
        transaction.getCosignatures().add(sharedCosignature);
        final String transactionPayloadFinal =
            SymbolTransactionFactory.toJson(transaction);
        final String jsonPayload = transactionPayloadFinal;
        System.out.println("[Account A] Ready to announce");

Account A receives Account B's cosignature, adds it to the transaction object's cosignatures array, and rebuilds the payload for announcement.

Announcing the Transaction⚓︎

Now that the transaction is ready to be announced, it follows the same process as regular, non-aggregate transactions, as shown in the Transfer Transaction tutorial.

163
164
165
166
    # Announce the transaction
    transaction_hash = facade.hash_transaction(transaction)
    print(f'Transaction hash: {transaction_hash}')
    announce_transaction(json_payload, 'transaction')

167
168
169
170
171
    // Announce the transaction
    const transactionHash =
        facade.hashTransaction(transaction).toString();
    console.log('Transaction hash:', transactionHash);
    await announceTransaction(jsonPayload, 'transaction');

233
234
235
236
237
        // Announce the transaction
        final String transactionHash =
            facade.hashTransaction(transaction).toString();
        System.out.printf("Transaction hash: %s%n", transactionHash);
        announceTransaction(jsonPayload, "transaction");

Once all signatures are collected, the transaction is announced to a node using the /transactions PUT endpoint.

The node validates that all required signatures are present and valid before accepting the transaction. If validation passes, the transaction is added to the unconfirmed pool and broadcast to other nodes.

Waiting for Confirmation⚓︎

168
169
    # Wait for confirmation
    wait_for_confirmation(transaction_hash, 'transaction')

173
174
    // Wait for confirmation
    await waitForConfirmation(transactionHash, 'transaction');

239
240
        // Wait for confirmation
        waitForConfirmation(transactionHash, "transaction");

After announcement, the transaction status is monitored using /transactionStatus/{hash} GET.

The polling loop checks the status every second until the transaction is confirmed or fails. Once confirmed, the swap is complete and both transfers have executed.

Output⚓︎

The output shown below corresponds to a typical run of the program.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
Using node https://reference.symboltest.net:3001
Account A: TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I
Account B: TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI
Fetching recommended fees from /network/fees/transaction
  Fee multiplier: 100
Built aggregate transaction without signatures:
{
  "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 3,
  "network": 152,
  "type": 16705,
  "fee": "46400",
  "deadline": "96608924742",
  "transactions_hash": "C2F8137E86FA6CD2B5A6E0CBBEA5485DCC427C5F1C9AC98F7A35E84CF0A28877",
  "transactions": [
    {
      "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
      "version": 1,
      "network": 152,
      "type": 16724,
      "recipient_address": "98AD8BAAB80B1DC684542EC175259711AB2C41D2FE4DA9AD",
      "mosaics": [
        {
          "mosaic_id": "16666583871264174062",
          "amount": "10000000"
        }
      ],
      "message": ""
    },
    {
      "signer_public_key": "D04AB232742BB4AB3A1368BD4615E4E6D0224AB71A016BAF8520A332C9778737",
      "version": 1,
      "network": 152,
      "type": 16724,
      "recipient_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
      "mosaics": [
        {
          "mosaic_id": "7859648582932718274",
          "amount": "1"
        }
      ],
      "message": ""
    }
  ],
  "cosignatures": []
}
[Account A] Signing the aggregate...
[Account A] Payload ready to share:
{
  "payload": "680100000000000068EB60FF9F330E4F86DE7FB30F4E6A398519C23C0AE2EC465524CD03C79382489EB0048EA67FA73E6C68B290BA0BE8A4DDC8DD1911F181C688E10B7EB7625B043B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29000000000398414140B50000000000004634577E16000000C2F8137E86FA6CD2B5A6E0CBBEA5485DCC427C5F1C9AC98F7A35E84CF0A28877C00000000000000060000000000000003B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29000000000198544198AD8BAAB80B1DC684542EC175259711AB2C41D2FE4DA9AD0000010000000000EEAFF441BA994BE780969800000000006000000000000000D04AB232742BB4AB3A1368BD4615E4E6D0224AB71A016BAF8520A332C97787370000000001985441988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE90000010000000000C2621B75BE14136D0100000000000000"
}
[Account A] ==> Payload sent to Account B (offchain)
[Account B] Cosigning...
[Account B] Cosignature created: {
  "version": "0",
  "signer_public_key": "D04AB232742BB4AB3A1368BD4615E4E6D0224AB71A016BAF8520A332C9778737",
  "signature": "7037EBED281136D1ADAF2F1CC1721ABC58F6CFC6130C6B6864057BC77F6167AAF31271751E2E93BB0993CC1A99F2A6807C1DE87A16A9DF1C44133652F939A90F"
}
[Account B] <== Cosignature sent back to Account A (offchain)
[Account A] Ready to announce
Transaction hash: 7F8BE244311CEB28C77CBACE81469DDAD231A48C954961F0E04E38A2B7AA2016
Announcing transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: confirmed
transaction confirmed in 14 seconds

Key points in the output:

  • Line 8 ("signature": "0000..."): Shows all zeros initially because the transaction hasn't been signed yet.
  • Line 12 ("type": 16705): Indicates this is an AggregateCompleteTransactionV3.
  • Line 16 ("transactions"): Contains the two embedded transfers that will execute atomically.
  • Line 46 ("cosignatures": []): Initially empty. Account B's cosignature is added before announcement. Note how Account A's signature is only needed once, even though it appears as signer in both the aggregate and the first embedded transaction.
  • Line 51 ("payload": "6801..."): The transaction payload computed from the aggregate transaction and its embedded transactions.
  • Line 58 ("signature": "7037..."): Account B's cosignature for the aggregate transaction.
  • Line 62 (Transaction hash): The hash can be used to search for the transaction in the Symbol Testnet Explorer.

The aggregate transaction is treated as a single atomic unit by the network. The swap executes completely: Account A receives the custom mosaic and Account B receives the XYM, or the entire transaction fails and no assets are transferred.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Create embedded transactions
TransferTransactionV1
Build the aggregate
AggregateCompleteTransactionV3
Sign the transaction
Verify and cosign
Collect the cosignature

Next Steps⚓︎