Skip to content

Creating a Bonded Aggregate Transaction⚓︎

ADVANCED

This tutorial shows how to create an asset swap using bonded 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:

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

Two types of aggregate transactions

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

A bonded aggregate transaction remains pending on the network until all required cosignatures have been announced. This works well when off-chain coordination is impractical. For example:

  • No shared infrastructure: Parties cannot coordinate through a common system, so the blockchain serves as the common interface.
  • Asynchronous workflows: Cosigners are not available at the same time or cannot coordinate in real-time.

To prevent spam, bonded aggregates require a hash lock (a deposit of 10 XYM). The network returns this deposit when all cosignatures arrive and the transaction reaches confirmation. If the transaction times out, the deposit is forfeited.

If parties can communicate off-chain to exchange signatures, complete aggregate transactions do not require this deposit.

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
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
244
245
246
247
248
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 transaction
def announce_transaction(payload, endpoint, label):
    print(f'Announcing {label} to {endpoint}')
    request = urllib.request.Request(
        f'{NODE_URL}{endpoint}',
        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 status
def wait_for_status(hash_value, expected_status, label):
    print(f'Waiting for {label} to reach {expected_status} status...')
    attempts = 0
    max_attempts = 60

    while attempts < max_attempts:
        try:
            url = f'{NODE_URL}/transactionStatus/{hash_value}'
            with urllib.request.urlopen(url) as status_response:
                status = json.loads(status_response.read().decode())

                print(f'  Transaction status: {status["group"]}')

                if status['group'] == 'failed':
                    raise RuntimeError(
                        f'{label} failed: {status["code"]}')

                if status['group'] == expected_status:
                    print(f'{label} {expected_status} ' +
                    f'in {attempts} seconds')
                    return

        except urllib.error.HTTPError as err:
            if err.code != 404:
                raise
            print('  Transaction status: not yet available')

        attempts += 1
        time.sleep(1)

    raise TimeoutError(
        f'{label} not {expected_status} after {max_attempts} attempts'
    )


# 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 bonded aggregate transaction
    embedded_transactions = [
        embedded_transaction_1, embedded_transaction_2]
    bonded_transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_bonded_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 without signatures:')
    print(json.dumps(bonded_transaction.to_json(), indent=2))

    # --- ACCOUNT A (Initiator) ---
    # Sign the bonded aggregate transaction
    print('[Account A] Signing the bonded aggregate...')
    bonded_signature = facade.sign_transaction(
        account_a_key_pair, bonded_transaction)
    bonded_json_payload = facade.transaction_factory.attach_signature(
        bonded_transaction, bonded_signature)
    bonded_hash = facade.hash_transaction(bonded_transaction)
    print(f'Bonded aggregate transaction hash: {bonded_hash}')

    # Create hash lock transaction
    print('Creating hash lock transaction...')
    hash_lock = facade.create_transaction_from_descriptor(
        {
            'type': 'hash_lock_transaction_v1',
            'mosaic': {
                'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
                'amount': 10_000_000  # 10 XYM deposit
            },
            'duration': 100,  # Lock duration in blocks
            'hash': bonded_hash
        },
        account_a_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

    # Sign hash lock
    print('[Account A] Signing the hash lock...')
    hash_lock_signature = facade.sign_transaction(
        account_a_key_pair, hash_lock)
    hash_lock_payload = facade.transaction_factory.attach_signature(
        hash_lock, hash_lock_signature)
    hash_lock_hash = facade.hash_transaction(hash_lock)
    print(f'Hash lock transaction hash: {hash_lock_hash}')

    # Announce hash lock and wait for confirmation
    announce_transaction(hash_lock_payload, '/transactions', 'Hash lock')
    wait_for_status(hash_lock_hash, 'confirmed', 'Hash lock')

    # Announce bonded aggregate and wait for partial status
    announce_transaction(
        bonded_json_payload, '/transactions/partial',
        'Bonded aggregate transaction'
    )
    wait_for_status(
        bonded_hash, 'partial',
        'Bonded aggregate transaction'
    )

    # --- ACCOUNT B (Cosigner) ---
    # Retrieves partial transactions waiting for signature
    partial_path = f'/transactions/partial?address={account_b_address}'
    print(
        '[Account B] Checking for partial transactions from '
        '/transactions/partial'
    )
    with urllib.request.urlopen(f'{NODE_URL}{partial_path}') as response:
        partial_txs = json.loads(response.read().decode())
        if not partial_txs['data']:
            raise RuntimeError('No partial transactions found')

    print(f'Found {len(partial_txs["data"])} partial transaction(s)')

    # Find the transaction matching the expected hash
    found = any(
        tx['meta']['hash'] == str(bonded_hash)
        for tx in partial_txs['data']
    )
    if not found:
        raise RuntimeError(
            f'Expected transaction {bonded_hash} not found in '
            f'partial transactions')
    print(f'Found matching transaction: {bonded_hash}')

    # Fetch full transaction details using the hash
    detail_path = f'/transactions/partial/{bonded_hash}'
    with urllib.request.urlopen(f'{NODE_URL}{detail_path}') as response:
        partial_tx_json = json.loads(response.read().decode())

    # Verify transaction content before cosigning
    tx_data = partial_tx_json['transaction']
    print(
        f'[Account B] Verifying transaction: '
        f'{len(tx_data["transactions"])} embedded transactions'
    )

    # Submit Account B's cosignature using the transaction hash
    cosignature_path = '/transactions/cosignature'
    print('[Account B] Cosigning the bonded aggregate...')
    cosignature = facade.cosign_transaction_hash(
        account_b_key_pair, bonded_hash, True)
    cosignature_payload = json.dumps({
        'version': str(cosignature.version),
        'signerPublicKey': str(cosignature.signer_public_key),
        'signature': str(cosignature.signature),
        'parentHash': str(cosignature.parent_hash)
    })

    # Announce cosignature
    announce_transaction(
        cosignature_payload, cosignature_path, 'cosignature'
    )

    # Wait for final confirmation
    wait_for_status(
        bonded_hash, 'confirmed',
        'Bonded aggregate 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
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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
import { Hash256, 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 transaction
async function announceTransaction(payload, endpoint, label) {
    console.log(`Announcing ${label} to ${endpoint}`);
    const response = await fetch(`${NODE_URL}${endpoint}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: payload
    });
    console.log('  Response:', await response.text());
}

// Helper function to wait for transaction status
async function waitForStatus(hash, expectedStatus, label) {
    console.log(
        `Waiting for ${label} to reach ${expectedStatus} status...`);
    let attempts = 0;
    const maxAttempts = 60;

    while (attempts < maxAttempts) {
        try {
            const url = `${NODE_URL}/transactionStatus/${hash}`;
            const response = await fetch(url);

            if (!response.ok) {
                const error = new Error(
                    `HTTP ${response.status}: ${response.statusText}`);
                error.status = response.status;
                throw error;
            }

            const status = await response.json();

            console.log('  Transaction status:', status.group);

            if ('failed' === status.group)
                throw new Error(`${label} failed: ${status.code}`);

            if (status.group === expectedStatus) {
                console.log(
                    `${label} ${expectedStatus} in ${attempts} seconds`
                );
                return;
            }
        } catch (error) {
            if (404 === error.status)
                console.log('  Transaction status: not yet available');
            else
                throw error;
        }

        attempts++;
        await new Promise(resolve => { setTimeout(resolve, 1000); });
    }

    throw new Error(
        `${label} not ${expectedStatus} after ${maxAttempts} attempts`
    );
}

// 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 bonded aggregate transaction
    const embeddedTransactions = [
        embeddedTransaction1, embeddedTransaction2];
    const bondedTransaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateBondedTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60,
        1);
    console.log('Built aggregate without signatures:');
    console.log(JSON.stringify(bondedTransaction.toJson(), null, 2));

    // --- ACCOUNT A (Initiator) ---
    // Sign the bonded aggregate transaction
    console.log('[Account A] Signing the bonded aggregate...');
    const bondedSignature = facade.signTransaction(
        accountAKeyPair, bondedTransaction);
    const bondedJsonPayload = facade.transactionFactory.static
        .attachSignature(bondedTransaction, bondedSignature);
    const bondedHash = facade.hashTransaction(
        bondedTransaction).toString();
    console.log('Bonded aggregate transaction hash:', bondedHash);

    // Create hash lock transaction
    console.log('Creating hash lock transaction...');
    const hashLock = facade.createTransactionFromTypedDescriptor(
        new descriptors.HashLockTransactionV1Descriptor(
            new descriptors.UnresolvedMosaicDescriptor(
                generateMosaicAliasId('symbol.xym'),
                new models.Amount(10_000_000n)), // 10 XYM deposit
            new models.BlockDuration(100n),
            new Hash256(bondedHash)),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

    // Sign hash lock
    console.log('[Account A] Signing the hash lock...');
    const hashLockSignature = facade.signTransaction(
        accountAKeyPair, hashLock);
    const hashLockPayload = facade.transactionFactory.static
        .attachSignature(hashLock, hashLockSignature);
    const hashLockHash = facade.hashTransaction(hashLock)
        .toString();
    console.log('Hash lock transaction hash:', hashLockHash);

    // Announce hash lock and wait for confirmation
    await announceTransaction(
        hashLockPayload, '/transactions', 'Hash lock'
    );
    await waitForStatus(hashLockHash, 'confirmed', 'Hash lock');

    // Announce bonded aggregate and wait for partial status //
    await announceTransaction(
        bondedJsonPayload, '/transactions/partial',
        'Bonded aggregate transaction'
    );
    await waitForStatus(
        bondedHash, 'partial', 'Bonded aggregate transaction'
    );

    // --- ACCOUNT B (Cosigner) ---
    // Retrieves partial transactions waiting for signature
    const partialPath =
        `/transactions/partial?address=${accountBAddress}`;
    console.log(
        '[Account B] Checking for partial transactions from ' +
        '/transactions/partial'
    );
    const partialResponse = await fetch(`${NODE_URL}${partialPath}`);
    const partialTxs = await partialResponse.json();
    if (!partialTxs.data || 0 === partialTxs.data.length)
        throw new Error('No partial transactions found');

    console.log(
        `Found ${partialTxs.data.length} partial transaction(s)`);

    // Find the transaction matching the expected hash
    const found = partialTxs.data.some(
        tx => tx.meta.hash === bondedHash
    );
    if (!found) {
        throw new Error(
            `Expected transaction ${bondedHash} not found in ` +
            'partial transactions'
        );
    }
    console.log(`Found matching transaction: ${bondedHash}`);

    // Fetch full transaction details using the hash
    const detailPath = `/transactions/partial/${bondedHash}`;
    const detailResponse = await fetch(`${NODE_URL}${detailPath}`);
    const partialTxJson = await detailResponse.json();

    // Verify transaction content before cosigning
    const txData = partialTxJson.transaction;
    console.log('[Account B] Verifying transaction: ' +
        `${txData.transactions.length} embedded transactions`
    );

    // Submit Account B's cosignature using the transaction hash
    const cosignaturePath = '/transactions/cosignature';
    console.log('[Account B] Cosigning the bonded aggregate...');
    const cosignature = SymbolFacade.cosignTransactionHash(
        accountBKeyPair, new Hash256(bondedHash), true
    );
    const cosignaturePayload = JSON.stringify({
        version: cosignature.version.toString(),
        signerPublicKey: cosignature.signerPublicKey.toString(),
        signature: cosignature.signature.toString(),
        parentHash: cosignature.parentHash.toString()
    });

    // Announce cosignature
    await announceTransaction(
        cosignaturePayload, cosignaturePath, 'cosignature'
    );

    // Wait for final confirmation
    await waitForStatus(
        new Hash256(bondedHash), 'confirmed',
        'Bonded aggregate 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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
//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.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 BondedAggregate {
    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 KeyPair accountAKeyPair;

    private KeyPair accountBKeyPair;

    private Address accountAAddress;

    private Address accountBAddress;

    // Helper method to announce transaction
    private void announceTransaction(
        final String payload,
        final String endpoint,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf("Announcing %s to %s%n", label, endpoint);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + endpoint))
            .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());
    }

    // Helper method to wait for transaction status
    private void waitForStatus(
        final String hash,
        final String expectedStatus,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf(
            "Waiting for %s to reach %s status...%n",
            label, expectedStatus);
        int attempts = 0;
        final int maxAttempts = 60;

        while (attempts < maxAttempts) {
            final String url = nodeUrl + "/transactionStatus/" + hash;
            final HttpRequest request = HttpRequest.newBuilder(
                URI.create(url)).GET().build();
            final HttpResponse<String> response = HTTP_CLIENT.send(
                request, BodyHandlers.ofString());

            if (response.statusCode() / 100 != 2) {
                if (404 == response.statusCode()) {
                    System.out.println(
                        "  Transaction status: not yet available");
                } else
                    throw new IOException(
                        "HTTP " + response.statusCode());
            } else {
                final JsonNode status = JSON_MAPPER.readTree(
                    response.body());

                System.out.printf("  Transaction status: %s%n",
                    status.get("group").asText());

                if ("failed".equals(status.get("group").asText()))
                    throw new IOException(String.format("%s failed: %s",
                        label, status.get("code").asText()));

                if (status.get("group").asText().equals(expectedStatus)) {
                    System.out.printf("%s %s in %d seconds%n",
                        label, expectedStatus, attempts);
                    return;
                }
            }

            ++attempts;
            Thread.sleep(1000);
        }

        throw new IOException(String.format(
            "%s not %s after %d attempts",
            label, expectedStatus, maxAttempts));
    }

    public static void main(final String[] args) {
        try {
            new BondedAggregate().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));
        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));
        accountBKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountBPrivateKey));

        accountAAddress = facade.network.publicKeyToAddress(
            accountAKeyPair.getPublicKey());
        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 bonded aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction1, embeddedTransaction2);
        final Transaction bondedTransaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateBondedTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(
                        embeddedTransactions),
                    embeddedTransactions,
                    null),
                accountAKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60,
                1);
        System.out.println("Built aggregate without signatures:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(bondedTransaction.toJson()));

        // --- ACCOUNT A (Initiator) ---
        // Sign the bonded aggregate transaction
        System.out.println("[Account A] Signing the bonded aggregate...");
        final CryptoTypes.Signature bondedSignature =
            facade.signTransaction(accountAKeyPair, bondedTransaction);
        final String bondedJsonPayload = SymbolTransactionFactory
            .attachSignature(bondedTransaction, bondedSignature);
        final String bondedHash = facade.hashTransaction(
            bondedTransaction).toString();
        System.out.printf("Bonded aggregate transaction hash: %s%n",
            bondedHash);

        // Create hash lock transaction
        System.out.println("Creating hash lock transaction...");
        final Transaction hashLock =
            facade.createTransactionFromTypedDescriptor(
                new HashLockTransactionV1Descriptor(
                    new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(
                            IdGenerator.generateMosaicAliasId(
                                "symbol.xym")),
                        new Amount(10_000_000)), // 10 XYM deposit
                    new BlockDuration(100),
                    new CryptoTypes.Hash256(bondedHash)),
                accountAKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

        // Sign hash lock
        System.out.println("[Account A] Signing the hash lock...");
        final CryptoTypes.Signature hashLockSignature =
            facade.signTransaction(accountAKeyPair, hashLock);
        final String hashLockPayload = SymbolTransactionFactory
            .attachSignature(hashLock, hashLockSignature);
        final String hashLockHash = facade.hashTransaction(hashLock)
            .toString();
        System.out.printf("Hash lock transaction hash: %s%n",
            hashLockHash);

        // Announce hash lock and wait for confirmation
        announceTransaction(
            hashLockPayload, "/transactions", "Hash lock"
        );
        waitForStatus(hashLockHash, "confirmed", "Hash lock");

        // Announce bonded aggregate and wait for partial status
        announceTransaction(
            bondedJsonPayload, "/transactions/partial",
            "Bonded aggregate transaction"
        );
        waitForStatus(
            bondedHash, "partial", "Bonded aggregate transaction"
        );

        // --- ACCOUNT B (Cosigner) ---
        // Retrieves partial transactions waiting for signature
        final String partialPath =
            "/transactions/partial?address=" + accountBAddress;
        System.out.println(
            "[Account B] Checking for partial transactions from "
            + "/transactions/partial"
        );
        final HttpRequest partialRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + partialPath)).GET().build();
        final HttpResponse<String> partialResponse = HTTP_CLIENT.send(
            partialRequest, BodyHandlers.ofString());
        final JsonNode partialTxs = JSON_MAPPER.readTree(
            partialResponse.body());
        if (!partialTxs.has("data") || partialTxs.get("data").isEmpty())
            throw new IOException("No partial transactions found");

        System.out.printf("Found %d partial transaction(s)%n",
            partialTxs.get("data").size());

        // Find the transaction matching the expected hash
        boolean found = false;
        for (final JsonNode tx : partialTxs.get("data"))
                found |= bondedHash.equals(
                    tx.get("meta").get("hash").asText());
        if (!found) {
            throw new IOException(
                "Expected transaction " + bondedHash
                + " not found in partial transactions"
            );
        }
        System.out.printf("Found matching transaction: %s%n", bondedHash);

        // Fetch full transaction details using the hash
        final String detailPath = "/transactions/partial/" + bondedHash;
        final HttpRequest detailRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + detailPath)).GET().build();
        final HttpResponse<String> detailResponse = HTTP_CLIENT.send(
            detailRequest, BodyHandlers.ofString());
        final JsonNode partialTxJson = JSON_MAPPER.readTree(
            detailResponse.body());

        // Verify transaction content before cosigning
        final JsonNode txData = partialTxJson.get("transaction");
        System.out.println("[Account B] Verifying transaction: "
            + txData.get("transactions").size()
            + " embedded transactions"
        );

        // Submit Account B's cosignature using the transaction hash
        final String cosignaturePath = "/transactions/cosignature";
        System.out.println(
            "[Account B] Cosigning the bonded aggregate...");
        final DetachedCosignature cosignature =
            SymbolFacade.cosignTransactionHashDetached(
                accountBKeyPair, new CryptoTypes.Hash256(bondedHash)
            );
        final String cosignaturePayload =
            JSON_MAPPER.writeValueAsString(cosignature.toJson());

        // Announce cosignature
        announceTransaction(
            cosignaturePayload, cosignaturePath, "cosignature"
        );

        // Wait for final confirmation
        waitForStatus(
            bondedHash, "confirmed",
            "Bonded aggregate transaction"
        );
    }
}

Download source

A bonded aggregate transaction involves two distinct roles: an initiator (Account A) that builds, signs, and announces the aggregate, and one or more cosigners (Account B, and any additional cosigners) that poll for pending transactions and add their signatures after verifying the transaction.

In practice, each role runs as a separate program on a separate machine. This tutorial combines both roles in a single script for simplicity.

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.

Account A: Initiator Workflow⚓︎

Setting Up Accounts⚓︎

63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# 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}')

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
// 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());

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
        // 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));
        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));
        accountBKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(accountBPrivateKey));

        accountAAddress = facade.network.publicKeyToAddress(
            accountAKeyPair.getPublicKey());
        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.

84
85
86
87
88
89
90
91
92
    # 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}')

 93
 94
 95
 96
 97
 98
 99
100
101
    // 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);

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
        // 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⚓︎

 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
    # 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))

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
    // 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);

164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
        // 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⚓︎

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
    # Build the bonded aggregate transaction
    embedded_transactions = [
        embedded_transaction_1, embedded_transaction_2]
    bonded_transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_bonded_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 without signatures:')
    print(json.dumps(bonded_transaction.to_json(), indent=2))

130
131
132
133
134
135
136
137
138
139
140
141
142
143
    // Build the bonded aggregate transaction
    const embeddedTransactions = [
        embeddedTransaction1, embeddedTransaction2];
    const bondedTransaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateBondedTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60,
        1);
    console.log('Built aggregate without signatures:');
    console.log(JSON.stringify(bondedTransaction.toJson(), null, 2));

189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
        // Build the bonded aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction1, embeddedTransaction2);
        final Transaction bondedTransaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateBondedTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(
                        embeddedTransactions),
                    embeddedTransactions,
                    null),
                accountAKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60,
                1);
        System.out.println("Built aggregate without signatures:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(bondedTransaction.toJson()));

Once the embedded transactions are prepared, create the bonded 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.

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 Bonded Transaction⚓︎

138
139
140
141
142
143
144
145
146
    # --- ACCOUNT A (Initiator) ---
    # Sign the bonded aggregate transaction
    print('[Account A] Signing the bonded aggregate...')
    bonded_signature = facade.sign_transaction(
        account_a_key_pair, bonded_transaction)
    bonded_json_payload = facade.transaction_factory.attach_signature(
        bonded_transaction, bonded_signature)
    bonded_hash = facade.hash_transaction(bonded_transaction)
    print(f'Bonded aggregate transaction hash: {bonded_hash}')

145
146
147
148
149
150
151
152
153
154
    // --- ACCOUNT A (Initiator) ---
    // Sign the bonded aggregate transaction
    console.log('[Account A] Signing the bonded aggregate...');
    const bondedSignature = facade.signTransaction(
        accountAKeyPair, bondedTransaction);
    const bondedJsonPayload = facade.transactionFactory.static
        .attachSignature(bondedTransaction, bondedSignature);
    const bondedHash = facade.hashTransaction(
        bondedTransaction).toString();
    console.log('Bonded aggregate transaction hash:', bondedHash);

207
208
209
210
211
212
213
214
215
216
217
        // --- ACCOUNT A (Initiator) ---
        // Sign the bonded aggregate transaction
        System.out.println("[Account A] Signing the bonded aggregate...");
        final CryptoTypes.Signature bondedSignature =
            facade.signTransaction(accountAKeyPair, bondedTransaction);
        final String bondedJsonPayload = SymbolTransactionFactory
            .attachSignature(bondedTransaction, bondedSignature);
        final String bondedHash = facade.hashTransaction(
            bondedTransaction).toString();
        System.out.printf("Bonded aggregate transaction hash: %s%n",
            bondedHash);

Account A signs the bonded transaction, producing the main signature and finalizing the transaction hash.

This hash is required for the next step: creating a hash lock transaction.

Creating the Hash Lock⚓︎

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
    # Create hash lock transaction
    print('Creating hash lock transaction...')
    hash_lock = facade.create_transaction_from_descriptor(
        {
            'type': 'hash_lock_transaction_v1',
            'mosaic': {
                'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
                'amount': 10_000_000  # 10 XYM deposit
            },
            'duration': 100,  # Lock duration in blocks
            'hash': bonded_hash
        },
        account_a_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

    # Sign hash lock
    print('[Account A] Signing the hash lock...')
    hash_lock_signature = facade.sign_transaction(
        account_a_key_pair, hash_lock)
    hash_lock_payload = facade.transaction_factory.attach_signature(
        hash_lock, hash_lock_signature)
    hash_lock_hash = facade.hash_transaction(hash_lock)
    print(f'Hash lock transaction hash: {hash_lock_hash}')

    # Announce hash lock and wait for confirmation
    announce_transaction(hash_lock_payload, '/transactions', 'Hash lock')
    wait_for_status(hash_lock_hash, 'confirmed', 'Hash lock')

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
    // Create hash lock transaction
    console.log('Creating hash lock transaction...');
    const hashLock = facade.createTransactionFromTypedDescriptor(
        new descriptors.HashLockTransactionV1Descriptor(
            new descriptors.UnresolvedMosaicDescriptor(
                generateMosaicAliasId('symbol.xym'),
                new models.Amount(10_000_000n)), // 10 XYM deposit
            new models.BlockDuration(100n),
            new Hash256(bondedHash)),
        accountAKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

    // Sign hash lock
    console.log('[Account A] Signing the hash lock...');
    const hashLockSignature = facade.signTransaction(
        accountAKeyPair, hashLock);
    const hashLockPayload = facade.transactionFactory.static
        .attachSignature(hashLock, hashLockSignature);
    const hashLockHash = facade.hashTransaction(hashLock)
        .toString();
    console.log('Hash lock transaction hash:', hashLockHash);

    // Announce hash lock and wait for confirmation
    await announceTransaction(
        hashLockPayload, '/transactions', 'Hash lock'
    );
    await waitForStatus(hashLockHash, 'confirmed', 'Hash lock');

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
244
245
246
247
248
249
250
        // Create hash lock transaction
        System.out.println("Creating hash lock transaction...");
        final Transaction hashLock =
            facade.createTransactionFromTypedDescriptor(
                new HashLockTransactionV1Descriptor(
                    new UnresolvedMosaicDescriptor(
                        new UnresolvedMosaicId(
                            IdGenerator.generateMosaicAliasId(
                                "symbol.xym")),
                        new Amount(10_000_000)), // 10 XYM deposit
                    new BlockDuration(100),
                    new CryptoTypes.Hash256(bondedHash)),
                accountAKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

        // Sign hash lock
        System.out.println("[Account A] Signing the hash lock...");
        final CryptoTypes.Signature hashLockSignature =
            facade.signTransaction(accountAKeyPair, hashLock);
        final String hashLockPayload = SymbolTransactionFactory
            .attachSignature(hashLock, hashLockSignature);
        final String hashLockHash = facade.hashTransaction(hashLock)
            .toString();
        System.out.printf("Hash lock transaction hash: %s%n",
            hashLockHash);

        // Announce hash lock and wait for confirmation
        announceTransaction(
            hashLockPayload, "/transactions", "Hash lock"
        );
        waitForStatus(hashLockHash, "confirmed", "Hash lock");

Before announcing a bonded aggregate, a hash lock transaction must be created and confirmed. The hash lock serves as a deposit to prevent spam and ensure network resources are not exhausted by unfinished partial transactions.

The hash lock transaction specifies:

  • Type: Use HashLockTransactionV1.

  • Mosaic: The deposit amount (10 XYM). This deposit is locked temporarily while waiting for cosignatures.

  • Duration: The number of blocks the deposit remains locked (100 blocks in this example). If all cosignatures are collected and the bonded aggregate confirms before the duration expires, the deposit is returned. Otherwise, it is forfeited and sent to the harvester of the block where the transactions expired.

  • Hash: The hash of the bonded aggregate transaction being locked.

The hash lock is signed using and announced using the helper function. It must be confirmed before the bonded aggregate can be announced.

Then, the helper function polls the transaction status until confirmation.

Announcing the Bonded Transaction⚓︎

177
178
179
180
181
182
183
184
185
    # Announce bonded aggregate and wait for partial status
    announce_transaction(
        bonded_json_payload, '/transactions/partial',
        'Bonded aggregate transaction'
    )
    wait_for_status(
        bonded_hash, 'partial',
        'Bonded aggregate transaction'
    )

185
186
187
188
189
190
191
192
    // Announce bonded aggregate and wait for partial status //
    await announceTransaction(
        bondedJsonPayload, '/transactions/partial',
        'Bonded aggregate transaction'
    );
    await waitForStatus(
        bondedHash, 'partial', 'Bonded aggregate transaction'
    );

252
253
254
255
256
257
258
259
        // Announce bonded aggregate and wait for partial status
        announceTransaction(
            bondedJsonPayload, "/transactions/partial",
            "Bonded aggregate transaction"
        );
        waitForStatus(
            bondedHash, "partial", "Bonded aggregate transaction"
        );

Once the hash lock is confirmed, the bonded aggregate is announced to /transactions/partial PUT using the helper.

The node validates the transaction, checks that a valid hash lock exists, and places it in a partial state. The helper monitors the transaction until it reaches this state, at which point it can collect cosignatures.

Account B: Cosigner Workflow⚓︎

Recovering the Transaction⚓︎

187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    # --- ACCOUNT B (Cosigner) ---
    # Retrieves partial transactions waiting for signature
    partial_path = f'/transactions/partial?address={account_b_address}'
    print(
        '[Account B] Checking for partial transactions from '
        '/transactions/partial'
    )
    with urllib.request.urlopen(f'{NODE_URL}{partial_path}') as response:
        partial_txs = json.loads(response.read().decode())
        if not partial_txs['data']:
            raise RuntimeError('No partial transactions found')

    print(f'Found {len(partial_txs["data"])} partial transaction(s)')

    # Find the transaction matching the expected hash
    found = any(
        tx['meta']['hash'] == str(bonded_hash)
        for tx in partial_txs['data']
    )
    if not found:
        raise RuntimeError(
            f'Expected transaction {bonded_hash} not found in '
            f'partial transactions')
    print(f'Found matching transaction: {bonded_hash}')

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
    // --- ACCOUNT B (Cosigner) ---
    // Retrieves partial transactions waiting for signature
    const partialPath =
        `/transactions/partial?address=${accountBAddress}`;
    console.log(
        '[Account B] Checking for partial transactions from ' +
        '/transactions/partial'
    );
    const partialResponse = await fetch(`${NODE_URL}${partialPath}`);
    const partialTxs = await partialResponse.json();
    if (!partialTxs.data || 0 === partialTxs.data.length)
        throw new Error('No partial transactions found');

    console.log(
        `Found ${partialTxs.data.length} partial transaction(s)`);

    // Find the transaction matching the expected hash
    const found = partialTxs.data.some(
        tx => tx.meta.hash === bondedHash
    );
    if (!found) {
        throw new Error(
            `Expected transaction ${bondedHash} not found in ` +
            'partial transactions'
        );
    }
    console.log(`Found matching transaction: ${bondedHash}`);

261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
        // --- ACCOUNT B (Cosigner) ---
        // Retrieves partial transactions waiting for signature
        final String partialPath =
            "/transactions/partial?address=" + accountBAddress;
        System.out.println(
            "[Account B] Checking for partial transactions from "
            + "/transactions/partial"
        );
        final HttpRequest partialRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + partialPath)).GET().build();
        final HttpResponse<String> partialResponse = HTTP_CLIENT.send(
            partialRequest, BodyHandlers.ofString());
        final JsonNode partialTxs = JSON_MAPPER.readTree(
            partialResponse.body());
        if (!partialTxs.has("data") || partialTxs.get("data").isEmpty())
            throw new IOException("No partial transactions found");

        System.out.printf("Found %d partial transaction(s)%n",
            partialTxs.get("data").size());

        // Find the transaction matching the expected hash
        boolean found = false;
        for (final JsonNode tx : partialTxs.get("data"))
                found |= bondedHash.equals(
                    tx.get("meta").get("hash").asText());
        if (!found) {
            throw new IOException(
                "Expected transaction " + bondedHash
                + " not found in partial transactions"
            );
        }
        System.out.printf("Found matching transaction: %s%n", bondedHash);

Unlike complete aggregates where the transaction payload is shared off-chain, bonded aggregates enable coordination through the network.

First, Account B polls /transactions/partial GET with the address parameter to find transactions waiting for its signature. This returns a list of partial transactions involving Account B.

This example looks for a specific transaction hash because both accounts run in the same script. In practice, Account B would discover pending transactions by polling and decide which ones to cosign based on their content.

Verifying the Transaction⚓︎

212
213
214
215
216
217
218
219
220
221
222
    # Fetch full transaction details using the hash
    detail_path = f'/transactions/partial/{bonded_hash}'
    with urllib.request.urlopen(f'{NODE_URL}{detail_path}') as response:
        partial_tx_json = json.loads(response.read().decode())

    # Verify transaction content before cosigning
    tx_data = partial_tx_json['transaction']
    print(
        f'[Account B] Verifying transaction: '
        f'{len(tx_data["transactions"])} embedded transactions'
    )

222
223
224
225
226
227
228
229
230
231
    // Fetch full transaction details using the hash
    const detailPath = `/transactions/partial/${bondedHash}`;
    const detailResponse = await fetch(`${NODE_URL}${detailPath}`);
    const partialTxJson = await detailResponse.json();

    // Verify transaction content before cosigning
    const txData = partialTxJson.transaction;
    console.log('[Account B] Verifying transaction: ' +
        `${txData.transactions.length} embedded transactions`
    );

294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
        // Fetch full transaction details using the hash
        final String detailPath = "/transactions/partial/" + bondedHash;
        final HttpRequest detailRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + detailPath)).GET().build();
        final HttpResponse<String> detailResponse = HTTP_CLIENT.send(
            detailRequest, BodyHandlers.ofString());
        final JsonNode partialTxJson = JSON_MAPPER.readTree(
            detailResponse.body());

        // Verify transaction content before cosigning
        final JsonNode txData = partialTxJson.get("transaction");
        System.out.println("[Account B] Verifying transaction: "
            + txData.get("transactions").size()
            + " embedded transactions"
        );

Once a transaction is found, Account B uses its hash to fetch the full details (including embedded transactions) from /transactions/partial/{transactionId} GET.

Before cosigning, Account B should verify that the embedded transactions match the expected operations. This example simply logs the number of embedded transactions, but it could also check amounts, recipients, and mosaics to ensure the swap terms are correct.

Verify before cosigning

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

Cosigning the Transaction⚓︎

224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
    # Submit Account B's cosignature using the transaction hash
    cosignature_path = '/transactions/cosignature'
    print('[Account B] Cosigning the bonded aggregate...')
    cosignature = facade.cosign_transaction_hash(
        account_b_key_pair, bonded_hash, True)
    cosignature_payload = json.dumps({
        'version': str(cosignature.version),
        'signerPublicKey': str(cosignature.signer_public_key),
        'signature': str(cosignature.signature),
        'parentHash': str(cosignature.parent_hash)
    })

    # Announce cosignature
    announce_transaction(
        cosignature_payload, cosignature_path, 'cosignature'
    )

233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
    // Submit Account B's cosignature using the transaction hash
    const cosignaturePath = '/transactions/cosignature';
    console.log('[Account B] Cosigning the bonded aggregate...');
    const cosignature = SymbolFacade.cosignTransactionHash(
        accountBKeyPair, new Hash256(bondedHash), true
    );
    const cosignaturePayload = JSON.stringify({
        version: cosignature.version.toString(),
        signerPublicKey: cosignature.signerPublicKey.toString(),
        signature: cosignature.signature.toString(),
        parentHash: cosignature.parentHash.toString()
    });

    // Announce cosignature
    await announceTransaction(
        cosignaturePayload, cosignaturePath, 'cosignature'
    );

310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
        // Submit Account B's cosignature using the transaction hash
        final String cosignaturePath = "/transactions/cosignature";
        System.out.println(
            "[Account B] Cosigning the bonded aggregate...");
        final DetachedCosignature cosignature =
            SymbolFacade.cosignTransactionHashDetached(
                accountBKeyPair, new CryptoTypes.Hash256(bondedHash)
            );
        final String cosignaturePayload =
            JSON_MAPPER.writeValueAsString(cosignature.toJson());

        // Announce cosignature
        announceTransaction(
            cosignaturePayload, cosignaturePath, "cosignature"
        );

Account B cosigns the transaction using with the transaction hash and the detached parameter set to .

A detached cosignature is a standalone object that can be submitted independently to the network. This is required for bonded aggregates because the cosigner submits directly to the node.

The resulting detached cosignature payload includes:

  • Version: The cosignature format version.
  • Signer public key: Account B's public key, identifying who cosigned.
  • Signature: The cryptographic signature computed from the transaction hash and Account B's private key.
  • Parent hash: The hash of the bonded transaction being cosigned.

The cosignature payload is submitted using the helper function to /transactions/cosignature PUT. The network validates the cosignature and attaches it to the partial transaction.

Once enough cosignatures are collected to satisfy all embedded transactions, the network automatically processes the bonded aggregate and includes it in a block.

Waiting for Confirmation⚓︎

241
242
243
244
245
    # Wait for final confirmation
    wait_for_status(
        bonded_hash, 'confirmed',
        'Bonded aggregate transaction'
    )

251
252
253
254
255
    // Wait for final confirmation
    await waitForStatus(
        new Hash256(bondedHash), 'confirmed',
        'Bonded aggregate transaction'
    );

326
327
328
329
330
        // Wait for final confirmation
        waitForStatus(
            bondedHash, "confirmed",
            "Bonded aggregate transaction"
        );

The helper function polls /transactionStatus/{hash} GET until the transaction is confirmed or fails.

If all required cosignatures are collected before the deadline, the transaction confirms, both transfers execute, and the hash lock deposit is returned to Account A.

If the deadline expires or any cosignature is invalid, the transaction fails and the deposit is forfeited.

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
71
72
73
74
75
76
77
78
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 without signatures:
{
  "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 3,
  "network": 152,
  "type": 16961,
  "fee": "46400",
  "deadline": "96991154275",
  "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 bonded aggregate...
Bonded aggregate transaction hash: 59CD54BA6EFC220C9C0C8DA6C7615F2A7F23A302836A69ACE29D48569D8CBAF8
Creating hash lock transaction...
[Account A] Signing the hash lock...
Hash lock transaction hash: 8E7AB27A920195BB783F822C39E14A42E2BA965250114E619D011CFE437ACC68
Announcing Hash lock to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for Hash lock confirmation...
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: confirmed
Hash lock confirmed in 24 seconds
Announcing Bonded aggregate transaction to /transactions/partial
  Response: {"message":"packet 256 was pushed to the network via /transactions/partial"}
Waiting for Bonded aggregate transaction to reach partial status...
  Transaction status: partial
Bonded aggregate transaction partial in 1 seconds
[Account B] Checking for partial transactions from /transactions/partial
Found 1 partial transaction(s)
Found matching transaction: 59CD54BA6EFC220C9C0C8DA6C7615F2A7F23A302836A69ACE29D48569D8CBAF8
[Account B] Verifying transaction: 2 embedded transactions
[Account B] Cosigning the bonded aggregate...
Announcing cosignature to /transactions/cosignature
  Response: {"message":"packet 257 was pushed to the network via /transactions/cosignature"}
Waiting for Bonded aggregate transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: confirmed
Bonded aggregate transaction confirmed in 16 seconds

Key points in the output:

  • Line 12 ("type": 16961): Indicates this is an AggregateBondedTransactionV3.
  • Line 16 ("transactions"): Contains the two embedded transfers that will execute atomically.
  • Line 46 ("cosignatures": []): Initially empty. Cosignatures are submitted after announcement.
  • Line 49 (Bonded aggregate transaction hash:): The hash of the bonded aggregate, required for creating the hash lock and announcing the transaction.
  • Line 53 (Announcing Hash lock to /transactions): A hash lock must be announced and confirmed before the bonded aggregate.
  • Line 61 (Announcing Bonded aggregate transaction to /transactions/partial): Bonded aggregates use a different endpoint than regular transactions.
  • Line 65 (Bonded aggregate transaction partial in 1 seconds): The bonded aggregate is now waiting for cosignatures to be submitted to the network.
  • Line 69 ([Account B] Verifying transaction: 2 embedded transactions): Account B inspects the transaction content before cosigning to ensure they agree with all operations.
  • Line 71 (Announcing cosignature to /transactions/cosignature): The cosignature is submitted to the network.

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
AggregateBondedTransactionV3
Sign the bonded transaction
Create hash lock
HashLockTransactionV1
/transactions PUT
Announce bonded transaction /transactions/partial PUT
Recover the transaction /transactions/partial GET
Verify the transaction /transactions/partial/{transactionId} GET
Cosign the transaction
/transactions/cosignature PUT
Wait for confirmation /transactionStatus/{hash} GET

Next Steps⚓︎