Skip to content

Configuring a Multisignature Account⚓︎

ADVANCED

A multisignature account, also called multisig, cannot initiate transactions on its own. Instead, it relies on cosignatory accounts to create transactions and sign them on its behalf.

This tutorial shows how to convert a regular account into a multisig account that requires approval from one of two cosignatories. If the account is already multisig, the tutorial instead demonstrates how to remove the cosignatories and revert the account to a regular account.

The multisignature structure used in this tutorial is shown below:

Multisignature TreeMultisignature AccountMultisignature AccountCosignatory 0Cosignatory 0Cosignatory 0->Multisignature AccountCosignatory 1Cosignatory 1Cosignatory 1->Multisignature Account

Prerequisites⚓︎

Before you start, make sure to:

Additionally, review the Transfer XEM 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
import json
import os
import time
import urllib.request

from symbolchain.CryptoTypes import PrivateKey
from symbolchain.facade.NemFacade import NemFacade
from symbolchain.nc import Amount
from symbolchain.nem.FeeCalculator import calculate_transaction_fee

NODE_URL = os.getenv('NODE_URL', 'http://libertalia.nemtest.net:7890')
print(f'Using node {NODE_URL}')

facade = NemFacade('testnet')

KEY_TEMPLATE = '0' * 63 + '{}'

# Set up the keys for the multisig account and its two cosignatories
MULTISIG_PRIVATE_KEY = os.getenv(
    'MULTISIG_PRIVATE_KEY', KEY_TEMPLATE.format(1))
multisig_key_pair = NemFacade.KeyPair(PrivateKey(MULTISIG_PRIVATE_KEY))
multisig_address = facade.network.public_key_to_address(
    multisig_key_pair.public_key)
print(f'Multisig address: {multisig_address} '
    f'(public key {multisig_key_pair.public_key})')

cosignatory_key_pairs = []
for i in range(2):
    COSIGNATORY_PRIVATE_KEY = os.getenv(
        f'COSIGNATORY{i}_PRIVATE_KEY', KEY_TEMPLATE.format(i + 2))
    key_pair = NemFacade.KeyPair(PrivateKey(COSIGNATORY_PRIVATE_KEY))
    cosignatory_key_pairs.append(key_pair)
    addr = facade.network.public_key_to_address(key_pair.public_key)
    print(f'Cosignatory {i} address: '
        f'{addr} (public key {key_pair.public_key})')


# Helper function to announce a transaction
def announce_transaction(payload, label):
    announce_path = '/transaction/announce'
    print(f'Announcing {label} to {announce_path}')
    request = urllib.request.Request(
        f'{NODE_URL}{announce_path}',
        data=payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='POST'
    )
    with urllib.request.urlopen(request) as announce_response:
        result = json.loads(announce_response.read().decode())
    print(f'  Result: {result["message"]}')
    return result['message']


# Helper function to wait for transaction confirmation
def wait_for_confirmation(tx_hash, label):
    status_path = f'/transaction/get?hash={tx_hash}'
    print(f'Waiting for {label} confirmation from {status_path}')
    is_confirmed = False
    for _ in range(120):
        try:
            with urllib.request.urlopen(
                f'{NODE_URL}{status_path}'
            ) as status_response:
                confirmed = json.loads(status_response.read().decode())
                height = confirmed['meta']['height']
                print(f'{label} confirmed in block {height}')
                is_confirmed = True
                break
        except urllib.error.HTTPError:
            print('  Transaction status: pending')
        time.sleep(1)
    if not is_confirmed:
        print(f'{label} confirmation took too long.')


# Returns the cosignatory addresses of the provided multisig
# account, or an empty list if the account is not multisig
def get_multisig_cosignatories(address):
    account_path = f'/account/get?address={address}'
    print(f'Getting cosignatories from {account_path}')
    url = f'{NODE_URL}{account_path}'
    with urllib.request.urlopen(url) as account_response:
        account_info = json.loads(account_response.read().decode())
        found_cosignatories = [
            cosignatory['address']
            for cosignatory in account_info['meta']['cosignatories']
        ]
        if not found_cosignatories:
            print('  Response: No cosignatories')
            return []
        print(f'  Response: {found_cosignatories}')
        return found_cosignatories



# Returns a transaction that turns a regular account into a multisig
def multisig_enable_transaction(approval_delta):
    # Create a multisig account modification transaction
    # that adds the cosignatories
    modifications = [
        {'modification': {
            'modification_type': 'add_cosignatory',
            'cosignatory_public_key': key_pair.public_key
        }}
        for key_pair in cosignatory_key_pairs
    ]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_account_modification_transaction_v2',
            # Change of the number of cosignatures
            # required to approve transactions
            'min_approval_delta': approval_delta,
            'modifications': modifications
        },
        # This is the account that will be turned into a multisig
        multisig_key_pair.public_key,
        0,
        2 * 60 * 60)

    # Calculate and attach the transaction fee
    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {fee / 1_000_000} XEM')
    print('Enabling the multisig with the modification transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

    # Sign the transaction with the multisig's key
    signature = facade.sign_transaction(multisig_key_pair, transaction)
    facade.transaction_factory.attach_signature(transaction, signature)
    return transaction



# Returns a transaction that removes one cosignatory from the multisig
def multisig_removal_transaction(removed_key_pair, approval_delta):
    # Create a multisig account modification transaction
    # that removes a single cosignatory
    inner_transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_account_modification_transaction_v2',
            # Change of the number of cosignatures
            # required to approve transactions
            'min_approval_delta': approval_delta,
            'modifications': [
                {'modification': {
                    'modification_type': 'delete_cosignatory',
                    'cosignatory_public_key': removed_key_pair.public_key
                }}
            ]
        },
        # This is the multisig account that will be modified
        multisig_key_pair.public_key,
        0,
        2 * 60 * 60)

    # Wrap the modification in a multisig transaction
    inner_fee = calculate_transaction_fee(inner_transaction)
    inner_transaction.fee = Amount(inner_fee)
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_transaction_v1',
            'inner_transaction':
                facade.transaction_factory.to_non_verifiable_transaction(
                    inner_transaction)
        },
        # This is the cosignatory that initiates the removal
        cosignatory_key_pairs[0].public_key,
        0,
        2 * 60 * 60)

    # Calculate and attach the transaction fee
    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {(inner_fee + fee) / 1_000_000} XEM')
    print('Disabling the multisig with the multisig transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

    # Sign the transaction with the cosignatory's key
    signature = facade.sign_transaction(
        cosignatory_key_pairs[0], transaction)
    facade.transaction_factory.attach_signature(transaction, signature)
    return transaction


try:
    # Get current state of the multisig account and decide which
    # operation to perform
    cosignatories = get_multisig_cosignatories(multisig_address)
    if len(cosignatories) == 0:
        # Enable the multisig
        transactions = [multisig_enable_transaction(1)]
    else:
        # Disable the multisig
        transactions = [
            multisig_removal_transaction(cosignatory_key_pairs[1], 0),
            multisig_removal_transaction(cosignatory_key_pairs[0], -1)
        ]

    # Announce each transaction and wait for confirmation
    for signed_transaction in transactions:
        transaction_hash = facade.hash_transaction(signed_transaction)
        print(f'Built transaction with hash: {transaction_hash}')
        json_payload = facade.transaction_factory.to_json(
            signed_transaction)
        announce_result = announce_transaction(
            json_payload, 'transaction')
        if 'SUCCESS' != announce_result:
            print('Transaction rejected')
            break
        wait_for_confirmation(transaction_hash, 'transaction')

except Exception as error:
    print(error)

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
import { PrivateKey } from 'symbol-sdk';
import {
    NemFacade,
    calculateTransactionFee,
    descriptors,
    models
} from 'symbol-sdk/nem';

const NODE_URL = process.env.NODE_URL ||
    'http://libertalia.nemtest.net:7890';
console.log('Using node', NODE_URL);

const facade = new NemFacade('testnet');

const KEY_PREFIX = '0'.repeat(63);

// Set up the keys for the multisig account and its two cosignatories
const MULTISIG_PRIVATE_KEY = process.env.MULTISIG_PRIVATE_KEY || (
    `${KEY_PREFIX}1`);
const multisigKeyPair = new NemFacade.KeyPair(
    new PrivateKey(MULTISIG_PRIVATE_KEY));
const multisigAddress = facade.network.publicKeyToAddress(
    multisigKeyPair.publicKey);
console.log(`Multisig address: ${multisigAddress}`,
    `(public key ${multisigKeyPair.publicKey})`);

const cosignatoryKeyPairs = [];
for (let i = 0; 2 > i; i++) {
    const COSIGNATORY_PRIVATE_KEY =
        process.env[`COSIGNATORY${i}_PRIVATE_KEY`] || (
            KEY_PREFIX + String(i + 2));
    const keyPair = new NemFacade.KeyPair(
        new PrivateKey(COSIGNATORY_PRIVATE_KEY));
    cosignatoryKeyPairs.push(keyPair);
    const addr = facade.network.publicKeyToAddress(keyPair.publicKey);
    console.log(`Cosignatory ${i} address: ${addr}`,
        `(public key ${keyPair.publicKey})`);
}

// Helper function to announce a transaction
async function announceTransaction(payload, label) {
    const announcePath = '/transaction/announce';
    console.log(`Announcing ${label} to ${announcePath}`);
    const response = await fetch(`${NODE_URL}${announcePath}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: payload
    });
    if (!response.ok)
        throw new Error(`HTTP ${response.status}`);
    const result = await response.json();
    console.log('  Result:', result.message);
    return result.message;
}

// Helper function to wait for transaction confirmation
async function waitForConfirmation(transactionHash, label) {
    const statusPath = `/transaction/get?hash=${transactionHash}`;
    console.log(`Waiting for ${label} confirmation from`, statusPath);
    let isConfirmed = false;
    for (let attempt = 1; 120 >= attempt; ++attempt) {
        const response = await fetch(`${NODE_URL}${statusPath}`);
        if (!response.ok) {
            console.log('  Transaction status: pending');
            await new Promise(resolve => { setTimeout(resolve, 1000); });
        } else {
            const confirmed = await response.json();
            console.log(`${label} confirmed in block`,
                confirmed.meta.height);
            isConfirmed = true;
            break;
        }
    }
    if (!isConfirmed)
        console.warn(`${label} confirmation took too long.`);
}

// Returns the cosignatory addresses of the provided multisig
// account, or an empty list if the account is not multisig
async function getMultisigCosignatories(address) {
    const accountPath = `/account/get?address=${address}`;
    console.log(`Getting cosignatories from ${accountPath}`);
    const response = await fetch(`${NODE_URL}${accountPath}`);
    const accountInfo = await response.json();
    const foundCosignatories = accountInfo.meta.cosignatories
        .map(cosignatory => cosignatory.address);
    if (0 === foundCosignatories.length) {
        console.log('  Response: No cosignatories');
        return [];
    }
    console.log('  Response:', JSON.stringify(foundCosignatories));
    return foundCosignatories;
}


// Returns a transaction that turns a regular account into a multisig
function multisigEnableTransaction(approvalDelta) {
    // Create a multisig account modification transaction
    // that adds the cosignatories
    const modifications = cosignatoryKeyPairs.map(keyPair =>
        new descriptors.SizePrefixedMultisigAccountModificationDescriptor(
            new descriptors.MultisigAccountModificationDescriptor(
                models.MultisigAccountModificationType.ADD_COSIGNATORY,
                keyPair.publicKey)));
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigAccountModificationTransactionV2Descriptor(
        // Change of the number of cosignatures
        // required to approve transactions
            approvalDelta,
            modifications),
        // This is the account that will be turned into a multisig
        multisigKeyPair.publicKey,
        0n,
        2 * 60 * 60);

    // Calculate and attach the transaction fee
    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log(`  Transaction fee: ${Number(fee) / 1_000_000} XEM`);
    console.log(
        'Enabling the multisig with the modification transaction:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

    // Sign the transaction with the multisig's key
    const signature = facade.signTransaction(
        multisigKeyPair, transaction);
    facade.transactionFactory.static.attachSignature(
        transaction, signature);
    return transaction;
}


// Returns a transaction that removes one cosignatory from the multisig
function multisigRemovalTransaction(removedKeyPair, approvalDelta) {
    // Create a multisig account modification transaction
    // that removes a single cosignatory
    const innerTransaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigAccountModificationTransactionV2Descriptor(
        // Change of the number of cosignatures
        // required to approve transactions
            approvalDelta,
            [new descriptors.SizePrefixedMultisigAccountModificationDescriptor(
                new descriptors.MultisigAccountModificationDescriptor(
                    models.MultisigAccountModificationType.DELETE_COSIGNATORY,
                    removedKeyPair.publicKey))]),
        // This is the multisig account that will be modified
        multisigKeyPair.publicKey,
        0n,
        2 * 60 * 60);

    // Wrap the modification in a multisig transaction
    const innerFee = calculateTransactionFee(innerTransaction);
    innerTransaction.fee = new models.Amount(innerFee);
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigTransactionV1Descriptor(
            facade.transactionFactory.static.toNonVerifiableTransaction(
                innerTransaction)),
        // This is the cosignatory that initiates the removal
        cosignatoryKeyPairs[0].publicKey,
        0n,
        2 * 60 * 60);

    // Calculate and attach the transaction fee
    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log('  Transaction fee:',
        `${Number(innerFee + fee) / 1_000_000} XEM`);
    console.log(
        'Disabling the multisig with the multisig transaction:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

    // Sign the transaction with the cosignatory's key
    const signature = facade.signTransaction(
        cosignatoryKeyPairs[0], transaction);
    facade.transactionFactory.static
        .attachSignature(transaction, signature);
    return transaction;
}

try {
    // Get current state of the multisig account and decide
    // which operation to perform
    const cosignatories = await getMultisigCosignatories(multisigAddress);
    let transactions;
    if (0 === cosignatories.length) {
        // Enable the multisig
        transactions = [multisigEnableTransaction(1)];
    } else {
        // Disable the multisig
        transactions = [
            multisigRemovalTransaction(cosignatoryKeyPairs[1], 0),
            multisigRemovalTransaction(cosignatoryKeyPairs[0], -1)
        ];
    }

    // Announce each transaction and wait for confirmation
    for (const signedTransaction of transactions) {
        const transactionHash = facade.hashTransaction(signedTransaction)
            .toString();
        console.log('Built transaction with hash:', transactionHash);
        const jsonPayload = facade.transactionFactory.static
            .toJson(signedTransaction);
        const result = await announceTransaction(
            jsonPayload, 'transaction');
        if ('SUCCESS' !== result) {
            console.log('Transaction rejected');
            break;
        }
        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
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
//JAVA 21+
//DEPS org.symbol:symbol-sdk:3.3.3

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.ArrayList;
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.NemFacade;
import org.symbol.sdk.nem.Address;
import org.symbol.sdk.nem.FeeCalculator;
import org.symbol.sdk.nem.KeyPair;
import org.symbol.sdk.nem.NemTransactionFactory;
import org.symbol.sdk.nem.descriptors.*;
import org.symbol.sdk.nem.models.Amount;
import org.symbol.sdk.nem.models.MultisigAccountModificationType;
import org.symbol.sdk.nem.models.Transaction;

public final class ConfigureMultisig {
    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", "http://libertalia.nemtest.net:7890");

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

    // Helper method to announce a transaction
    private String announceTransaction(
        final String payload,
        final String label
    ) throws IOException, InterruptedException {
        final String announcePath = "/transaction/announce";
        System.out.printf("Announcing %s to %s%n", label, announcePath);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + announcePath))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        final HttpResponse<String> response = HTTP_CLIENT.send(
            request, BodyHandlers.ofString());
        if (2 != response.statusCode() / 100)
            throw new IOException("HTTP " + response.statusCode());
        final String result = JSON_MAPPER.readTree(response.body())
            .get("message").asText();
        System.out.printf("  Result: %s%n", result);
        return result;
    }
    // Helper method to wait for transaction confirmation
    private void waitForConfirmation(
        final String transactionHash,
        final String label
    ) throws IOException, InterruptedException {
        final String statusPath = String.format(
            "/transaction/get?hash=%s", transactionHash);
        System.out.printf("Waiting for %s confirmation from %s%n",
            label, statusPath);
        boolean isConfirmed = false;
        for (int attempt = 1; 120 >= attempt; ++attempt) {
            final HttpRequest request = HttpRequest.newBuilder(
                URI.create(nodeUrl + statusPath)).GET().build();
            final HttpResponse<String> response = HTTP_CLIENT.send(
                request, BodyHandlers.ofString());
            if (2 != response.statusCode() / 100) {
                System.out.println("  Transaction status: pending");
                Thread.sleep(1000);
            } else {
                final JsonNode confirmed = JSON_MAPPER.readTree(
                    response.body());
                System.out.printf("%s confirmed in block %s%n", label,
                    confirmed.get("meta").get("height").asText());
                isConfirmed = true;
                break;
            }
        }
        if (!isConfirmed)
        System.out.printf("%s confirmation took too long.%n", label);
    }

    public static void main(final String[] args) {
        try {
            new ConfigureMultisig().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);


        final String keyPrefix = "0".repeat(63);
        final String multisigPrivateKey = System.getenv().getOrDefault(
            "MULTISIG_PRIVATE_KEY", keyPrefix + "1");
        final KeyPair multisigKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(multisigPrivateKey));
        final Address multisigAddress = facade.network.publicKeyToAddress(
            multisigKeyPair.getPublicKey());
        System.out.printf("Multisig address: %s (public key %s)%n",
            multisigAddress, multisigKeyPair.getPublicKey());
        final List<KeyPair> cosignatoryKeyPairs = new ArrayList<>();
        for (int i = 0; 2 > i; ++i) {
            final String privateKey = System.getenv().getOrDefault(
                String.format("COSIGNATORY%d_PRIVATE_KEY", i),
                keyPrefix + (i + 2));
            final KeyPair keyPair = new KeyPair(
                new CryptoTypes.PrivateKey(privateKey));
            cosignatoryKeyPairs.add(keyPair);
            final Address address = facade.network.publicKeyToAddress(
                keyPair.getPublicKey());
            System.out.printf(
                "Cosignatory %d address: %s (public key %s)%n",
                i, address, keyPair.getPublicKey());
        }

        // Get the current state of the multisig account
        final List<String> cosignatories = getMultisigCosignatories(
            multisigAddress);
        // Decide which operation to perform
        final List<Transaction> transactions;
        if (cosignatories.isEmpty()) {
            transactions = List.of(multisigEnableTransaction(
                multisigKeyPair, cosignatoryKeyPairs, 1));
        } else {
            transactions = List.of(
                multisigRemovalTransaction(multisigKeyPair,
                    cosignatoryKeyPairs, cosignatoryKeyPairs.get(1), 0),
                multisigRemovalTransaction(multisigKeyPair,
                    cosignatoryKeyPairs, cosignatoryKeyPairs.get(0), -1));
        }

        // Announce each transaction and wait for confirmation
        for (final Transaction transaction : transactions) {
            final String hash = facade.hashTransaction(transaction)
                .toString();
            System.out.printf("Built transaction with hash: %s%n", hash);
            final String result = announceTransaction(
                NemTransactionFactory.toJson(transaction), "transaction");
            if (!"SUCCESS".equals(result)) {
                System.out.println("Transaction rejected");
                break;
            }
            waitForConfirmation(hash, "transaction");
        }

    }

    // Returns the cosignatory addresses of the provided multisig
    // account, or an empty list if the account is not multisig
    private List<String> getMultisigCosignatories(
        final Address address
    ) throws IOException, InterruptedException {
        final String path = "/account/get?address=" + address;
        System.out.printf("Getting cosignatories from %s%n", path);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + path)).GET().build();
        final JsonNode found = JSON_MAPPER.readTree(HTTP_CLIENT.send(
            request, BodyHandlers.ofString()).body())
            .get("meta").get("cosignatories");
        final List<String> result = new ArrayList<>();
        for (final JsonNode cosignatory : found)
            result.add(cosignatory.get("address").asText());
        if (result.isEmpty())
            System.out.println("  Response: No cosignatories");
        else
            System.out.printf("  Response: %s%n", result);
        return result;
    }



    // Returns a transaction that turns a regular account into a multisig
    private Transaction multisigEnableTransaction(
        final KeyPair multisigKeyPair,
        final List<KeyPair> cosignatoryKeyPairs,
        final int approvalDelta
    ) throws IOException {
        final List<SizePrefixedMultisigAccountModificationDescriptor>
            modifications = new ArrayList<>();
        for (final KeyPair keyPair : cosignatoryKeyPairs)
            modifications.add(
                new SizePrefixedMultisigAccountModificationDescriptor(
                    new MultisigAccountModificationDescriptor(
                        MultisigAccountModificationType.ADD_COSIGNATORY,
                        keyPair.getPublicKey())));
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigAccountModificationTransactionV2Descriptor(
                    approvalDelta, modifications),
                multisigKeyPair.getPublicKey(), 0, 2 * 60 * 60);

        // Calculate and attach the transaction fee
        final long fee = FeeCalculator.calculateTransactionFee(
            transaction);
        transaction.setFee(new Amount(fee));
        System.out.printf("  Transaction fee: %s XEM%n",
            (double) fee / 1_000_000);
        System.out.println(
            "Enabling the multisig with the modification transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

        // Sign the transaction with the multisig's key
        NemTransactionFactory.attachSignature(transaction,
            facade.signTransaction(multisigKeyPair, transaction));
        return transaction;
    }


    // Returns a transaction that removes one cosignatory from the multisig
    private Transaction multisigRemovalTransaction(
        final KeyPair multisigKeyPair,
        final List<KeyPair> cosignatoryKeyPairs,
        final KeyPair removedKeyPair,
        final int approvalDelta
    ) throws IOException {
        final SizePrefixedMultisigAccountModificationDescriptor removal =
            new SizePrefixedMultisigAccountModificationDescriptor(
                new MultisigAccountModificationDescriptor(
                    MultisigAccountModificationType.DELETE_COSIGNATORY,
                    removedKeyPair.getPublicKey()));
        final Transaction innerTransaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigAccountModificationTransactionV2Descriptor(
                    approvalDelta, List.of(removal)),
                multisigKeyPair.getPublicKey(), 0, 2 * 60 * 60);

        // Wrap the modification in a multisig transaction
        final long innerFee = FeeCalculator.calculateTransactionFee(
            innerTransaction);
        innerTransaction.setFee(new Amount(innerFee));
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigTransactionV1Descriptor(
                    NemTransactionFactory.toNonVerifiableTransaction(
                        innerTransaction), List.of()),
                cosignatoryKeyPairs.get(0).getPublicKey(),
                0, 2 * 60 * 60);

        // Calculate and attach the transaction fee
        final long fee = FeeCalculator.calculateTransactionFee(
            transaction);
        transaction.setFee(new Amount(fee));
        System.out.printf("  Transaction fee: %s XEM%n",
            (double) (innerFee + fee) / 1_000_000);
        System.out.println(
            "Disabling the multisig with the multisig transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

        // Sign the transaction with the cosignatory's key
        NemTransactionFactory.attachSignature(transaction,
            facade.signTransaction(
                cosignatoryKeyPairs.get(0), transaction));
        return transaction;
    }
}

Download source

Code Explanation⚓︎

The code defines two helper functions, for announcing a transaction and waiting for its confirmation. For details on how these work, see the Transfer XEM tutorial. The remaining helper functions are described in the sections below.

The tutorial then proceeds to set up the required keys and detect the current configuration of the multisig account.

Depending on whether the account is already configured as a multisig, transactions are created to enable or disable it as appropriate. Finally, the transactions are announced and confirmed.

Setting Up the Accounts⚓︎

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
KEY_TEMPLATE = '0' * 63 + '{}'

# Set up the keys for the multisig account and its two cosignatories
MULTISIG_PRIVATE_KEY = os.getenv(
    'MULTISIG_PRIVATE_KEY', KEY_TEMPLATE.format(1))
multisig_key_pair = NemFacade.KeyPair(PrivateKey(MULTISIG_PRIVATE_KEY))
multisig_address = facade.network.public_key_to_address(
    multisig_key_pair.public_key)
print(f'Multisig address: {multisig_address} '
    f'(public key {multisig_key_pair.public_key})')

cosignatory_key_pairs = []
for i in range(2):
    COSIGNATORY_PRIVATE_KEY = os.getenv(
        f'COSIGNATORY{i}_PRIVATE_KEY', KEY_TEMPLATE.format(i + 2))
    key_pair = NemFacade.KeyPair(PrivateKey(COSIGNATORY_PRIVATE_KEY))
    cosignatory_key_pairs.append(key_pair)
    addr = facade.network.public_key_to_address(key_pair.public_key)
    print(f'Cosignatory {i} address: '
        f'{addr} (public key {key_pair.public_key})')

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
const KEY_PREFIX = '0'.repeat(63);

// Set up the keys for the multisig account and its two cosignatories
const MULTISIG_PRIVATE_KEY = process.env.MULTISIG_PRIVATE_KEY || (
    `${KEY_PREFIX}1`);
const multisigKeyPair = new NemFacade.KeyPair(
    new PrivateKey(MULTISIG_PRIVATE_KEY));
const multisigAddress = facade.network.publicKeyToAddress(
    multisigKeyPair.publicKey);
console.log(`Multisig address: ${multisigAddress}`,
    `(public key ${multisigKeyPair.publicKey})`);

const cosignatoryKeyPairs = [];
for (let i = 0; 2 > i; i++) {
    const COSIGNATORY_PRIVATE_KEY =
        process.env[`COSIGNATORY${i}_PRIVATE_KEY`] || (
            KEY_PREFIX + String(i + 2));
    const keyPair = new NemFacade.KeyPair(
        new PrivateKey(COSIGNATORY_PRIVATE_KEY));
    cosignatoryKeyPairs.push(keyPair);
    const addr = facade.network.publicKeyToAddress(keyPair.publicKey);
    console.log(`Cosignatory ${i} address: ${addr}`,
        `(public key ${keyPair.publicKey})`);
}

104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
        final String keyPrefix = "0".repeat(63);
        final String multisigPrivateKey = System.getenv().getOrDefault(
            "MULTISIG_PRIVATE_KEY", keyPrefix + "1");
        final KeyPair multisigKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(multisigPrivateKey));
        final Address multisigAddress = facade.network.publicKeyToAddress(
            multisigKeyPair.getPublicKey());
        System.out.printf("Multisig address: %s (public key %s)%n",
            multisigAddress, multisigKeyPair.getPublicKey());
        final List<KeyPair> cosignatoryKeyPairs = new ArrayList<>();
        for (int i = 0; 2 > i; ++i) {
            final String privateKey = System.getenv().getOrDefault(
                String.format("COSIGNATORY%d_PRIVATE_KEY", i),
                keyPrefix + (i + 2));
            final KeyPair keyPair = new KeyPair(
                new CryptoTypes.PrivateKey(privateKey));
            cosignatoryKeyPairs.add(keyPair);
            final Address address = facade.network.publicKeyToAddress(
                keyPair.getPublicKey());
            System.out.printf(
                "Cosignatory %d address: %s (public key %s)%n",
                i, address, keyPair.getPublicKey());
        }

The tutorial requires three separate accounts. Their private keys can be provided through environment variables. If not set, default values are used:

Environment Variable Default value Purpose
MULTISIG_PRIVATE_KEY 0000..0001 Multisig account
COSIGNATORY0_PRIVATE_KEY 0000..0002 First cosignatory account
COSIGNATORY1_PRIVATE_KEY 0000..0003 Second cosignatory account

Each private key is a 64-character hexadecimal string.

The multisig account must hold enough funds to pay the transaction fees. If the default values are used, this account may already be funded.

The snippet above derives and stores the key pair and address of each account for later use.

Determining the Multisig Operation⚓︎

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
# Returns the cosignatory addresses of the provided multisig
# account, or an empty list if the account is not multisig
def get_multisig_cosignatories(address):
    account_path = f'/account/get?address={address}'
    print(f'Getting cosignatories from {account_path}')
    url = f'{NODE_URL}{account_path}'
    with urllib.request.urlopen(url) as account_response:
        account_info = json.loads(account_response.read().decode())
        found_cosignatories = [
            cosignatory['address']
            for cosignatory in account_info['meta']['cosignatories']
        ]
        if not found_cosignatories:
            print('  Response: No cosignatories')
            return []
        print(f'  Response: {found_cosignatories}')
        return found_cosignatories

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
// Returns the cosignatory addresses of the provided multisig
// account, or an empty list if the account is not multisig
async function getMultisigCosignatories(address) {
    const accountPath = `/account/get?address=${address}`;
    console.log(`Getting cosignatories from ${accountPath}`);
    const response = await fetch(`${NODE_URL}${accountPath}`);
    const accountInfo = await response.json();
    const foundCosignatories = accountInfo.meta.cosignatories
        .map(cosignatory => cosignatory.address);
    if (0 === foundCosignatories.length) {
        console.log('  Response: No cosignatories');
        return [];
    }
    console.log('  Response:', JSON.stringify(foundCosignatories));
    return foundCosignatories;
}

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
    // Returns the cosignatory addresses of the provided multisig
    // account, or an empty list if the account is not multisig
    private List<String> getMultisigCosignatories(
        final Address address
    ) throws IOException, InterruptedException {
        final String path = "/account/get?address=" + address;
        System.out.printf("Getting cosignatories from %s%n", path);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + path)).GET().build();
        final JsonNode found = JSON_MAPPER.readTree(HTTP_CLIENT.send(
            request, BodyHandlers.ofString()).body())
            .get("meta").get("cosignatories");
        final List<String> result = new ArrayList<>();
        for (final JsonNode cosignatory : found)
            result.add(cosignatory.get("address").asText());
        if (result.isEmpty())
            System.out.println("  Response: No cosignatories");
        else
            System.out.printf("  Response: %s%n", result);
        return result;
    }

This helper retrieves the list of current cosignatories for a given address using the /account/get GET endpoint. If it returns an empty list, the account is not currently configured as a multisig account.

Check the existing multisig configuration

For simplicity, the tutorial assumes that if the list of cosignatories is not empty, then the account is a multisig configured by the tutorial itself.

If the configuration is not the expected one, for example, because the cosignatories are different, the removal transactions will be rejected.

Applications should always check the current configuration before trying to modify it, including the full list of cosignatories and the minimum number of signatures required.

186
187
188
189
190
191
192
193
194
195
196
197
    # Get current state of the multisig account and decide which
    # operation to perform
    cosignatories = get_multisig_cosignatories(multisig_address)
    if len(cosignatories) == 0:
        # Enable the multisig
        transactions = [multisig_enable_transaction(1)]
    else:
        # Disable the multisig
        transactions = [
            multisig_removal_transaction(cosignatory_key_pairs[1], 0),
            multisig_removal_transaction(cosignatory_key_pairs[0], -1)
        ]

181
182
183
184
185
186
187
188
189
190
191
192
193
194
    // Get current state of the multisig account and decide
    // which operation to perform
    const cosignatories = await getMultisigCosignatories(multisigAddress);
    let transactions;
    if (0 === cosignatories.length) {
        // Enable the multisig
        transactions = [multisigEnableTransaction(1)];
    } else {
        // Disable the multisig
        transactions = [
            multisigRemovalTransaction(cosignatoryKeyPairs[1], 0),
            multisigRemovalTransaction(cosignatoryKeyPairs[0], -1)
        ];
    }

131
132
133
134
135
136
137
138
139
140
141
142
        // Decide which operation to perform
        final List<Transaction> transactions;
        if (cosignatories.isEmpty()) {
            transactions = List.of(multisigEnableTransaction(
                multisigKeyPair, cosignatoryKeyPairs, 1));
        } else {
            transactions = List.of(
                multisigRemovalTransaction(multisigKeyPair,
                    cosignatoryKeyPairs, cosignatoryKeyPairs.get(1), 0),
                multisigRemovalTransaction(multisigKeyPair,
                    cosignatoryKeyPairs, cosignatoryKeyPairs.get(0), -1));
        }

The returned cosignatories determine whether the account is configured as a multisig account, and therefore whether to create the transactions to enable or disable multisig.

The functions that build them and the delta values they use are described in the next two sections.

Enabling the Multisig⚓︎

 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# Returns a transaction that turns a regular account into a multisig
def multisig_enable_transaction(approval_delta):
    # Create a multisig account modification transaction
    # that adds the cosignatories
    modifications = [
        {'modification': {
            'modification_type': 'add_cosignatory',
            'cosignatory_public_key': key_pair.public_key
        }}
        for key_pair in cosignatory_key_pairs
    ]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_account_modification_transaction_v2',
            # Change of the number of cosignatures
            # required to approve transactions
            'min_approval_delta': approval_delta,
            'modifications': modifications
        },
        # This is the account that will be turned into a multisig
        multisig_key_pair.public_key,
        0,
        2 * 60 * 60)

 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
// Returns a transaction that turns a regular account into a multisig
function multisigEnableTransaction(approvalDelta) {
    // Create a multisig account modification transaction
    // that adds the cosignatories
    const modifications = cosignatoryKeyPairs.map(keyPair =>
        new descriptors.SizePrefixedMultisigAccountModificationDescriptor(
            new descriptors.MultisigAccountModificationDescriptor(
                models.MultisigAccountModificationType.ADD_COSIGNATORY,
                keyPair.publicKey)));
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigAccountModificationTransactionV2Descriptor(
        // Change of the number of cosignatures
        // required to approve transactions
            approvalDelta,
            modifications),
        // This is the account that will be turned into a multisig
        multisigKeyPair.publicKey,
        0n,
        2 * 60 * 60);

184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
    // Returns a transaction that turns a regular account into a multisig
    private Transaction multisigEnableTransaction(
        final KeyPair multisigKeyPair,
        final List<KeyPair> cosignatoryKeyPairs,
        final int approvalDelta
    ) throws IOException {
        final List<SizePrefixedMultisigAccountModificationDescriptor>
            modifications = new ArrayList<>();
        for (final KeyPair keyPair : cosignatoryKeyPairs)
            modifications.add(
                new SizePrefixedMultisigAccountModificationDescriptor(
                    new MultisigAccountModificationDescriptor(
                        MultisigAccountModificationType.ADD_COSIGNATORY,
                        keyPair.getPublicKey())));
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigAccountModificationTransactionV2Descriptor(
                    approvalDelta, modifications),
                multisigKeyPair.getPublicKey(), 0, 2 * 60 * 60);

All changes to the multisig configuration of an account, including adding or removing cosignatories, are performed using a MultisigAccountModificationTransactionV2.

The transaction specifies:

  • Transaction type: Multisig configuration changes use MultisigAccountModificationTransactionV2.

  • : difference between the desired value and the current value of the number of cosignatures required to approve transactions from the multisig account.

    In this case, the account is initially a regular account, so the current number of required cosignatures is 0. To convert it into a multisig account that requires one signature from one of its cosignatories, the delta is set to 1.

    The delta value can be negative to reduce the current value, as shown in the next section.

  • : list of changes to the account's cosignatories. Each modification adds or removes one cosignatory, identified by its public key.

    In this case, two add_cosignatory modifications add the cosignatories prepared during the setup phase.

The facade adds the account whose multisig configuration will be modified as signer and derives the timestamp and deadline from the two-hour deadline duration.

Safety measures

The protocol includes safety mechanisms that help prevent locking an account into an invalid state. Transactions that would result in an invalid multisig configuration are rejected with an error. For example, when:

  • The number of cosignatories is lower than the number of required cosignatures
  • An account that is already a cosignatory is added
  • An account that is not a cosignatory is removed
  • More than one cosignatory is removed in a single transaction
  • A multisig account is added as a cosignatory
120
121
122
123
124
125
    # Calculate and attach the transaction fee
    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {fee / 1_000_000} XEM')
    print('Enabling the multisig with the modification transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

116
117
118
119
120
121
122
    // Calculate and attach the transaction fee
    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log(`  Transaction fee: ${Number(fee) / 1_000_000} XEM`);
    console.log(
        'Enabling the multisig with the modification transaction:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

204
205
206
207
208
209
210
211
212
213
        // Calculate and attach the transaction fee
        final long fee = FeeCalculator.calculateTransactionFee(
            transaction);
        transaction.setFee(new Amount(fee));
        System.out.printf("  Transaction fee: %s XEM%n",
            (double) fee / 1_000_000);
        System.out.println(
            "Enabling the multisig with the modification transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

The transaction fee is calculated with and attached to the transaction. Multisig account modification transactions pay a fixed transaction fee of 0.5 XEM, as shown in the fee schedule.

127
128
129
130
    # Sign the transaction with the multisig's key
    signature = facade.sign_transaction(multisig_key_pair, transaction)
    facade.transaction_factory.attach_signature(transaction, signature)
    return transaction

124
125
126
127
128
129
    // Sign the transaction with the multisig's key
    const signature = facade.signTransaction(
        multisigKeyPair, transaction);
    facade.transactionFactory.static.attachSignature(
        transaction, signature);
    return transaction;

215
216
217
218
        // Sign the transaction with the multisig's key
        NemTransactionFactory.attachSignature(transaction,
            facade.signTransaction(multisigKeyPair, transaction));
        return transaction;

Finally, the transaction is signed. In this case, only the signature of the account being converted into a multisig is required. The cosignatories do not sign the conversion transaction.

From now on, cosignatories must initiate transactions

Once an account has multisig enabled, its own signature is no longer accepted. Any transaction sent from that account, such as a transfer or a further multisig modification, must instead be initiated and signed by its cosignatories, as shown in the next section.

Disabling the Multisig⚓︎

Disabling a multisig configuration requires removing all cosignatories. The process is similar to enabling it, with two key differences: cosignatories must be removed one by one, and the multisig account itself cannot sign the transactions.

134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
# Returns a transaction that removes one cosignatory from the multisig
def multisig_removal_transaction(removed_key_pair, approval_delta):
    # Create a multisig account modification transaction
    # that removes a single cosignatory
    inner_transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_account_modification_transaction_v2',
            # Change of the number of cosignatures
            # required to approve transactions
            'min_approval_delta': approval_delta,
            'modifications': [
                {'modification': {
                    'modification_type': 'delete_cosignatory',
                    'cosignatory_public_key': removed_key_pair.public_key
                }}
            ]
        },
        # This is the multisig account that will be modified
        multisig_key_pair.public_key,
        0,
        2 * 60 * 60)

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
// Returns a transaction that removes one cosignatory from the multisig
function multisigRemovalTransaction(removedKeyPair, approvalDelta) {
    // Create a multisig account modification transaction
    // that removes a single cosignatory
    const innerTransaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigAccountModificationTransactionV2Descriptor(
        // Change of the number of cosignatures
        // required to approve transactions
            approvalDelta,
            [new descriptors.SizePrefixedMultisigAccountModificationDescriptor(
                new descriptors.MultisigAccountModificationDescriptor(
                    models.MultisigAccountModificationType.DELETE_COSIGNATORY,
                    removedKeyPair.publicKey))]),
        // This is the multisig account that will be modified
        multisigKeyPair.publicKey,
        0n,
        2 * 60 * 60);

222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
    // Returns a transaction that removes one cosignatory from the multisig
    private Transaction multisigRemovalTransaction(
        final KeyPair multisigKeyPair,
        final List<KeyPair> cosignatoryKeyPairs,
        final KeyPair removedKeyPair,
        final int approvalDelta
    ) throws IOException {
        final SizePrefixedMultisigAccountModificationDescriptor removal =
            new SizePrefixedMultisigAccountModificationDescriptor(
                new MultisigAccountModificationDescriptor(
                    MultisigAccountModificationType.DELETE_COSIGNATORY,
                    removedKeyPair.getPublicKey()));
        final Transaction innerTransaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigAccountModificationTransactionV2Descriptor(
                    approvalDelta, List.of(removal)),
                multisigKeyPair.getPublicKey(), 0, 2 * 60 * 60);

This helper builds a MultisigAccountModificationTransactionV2 that removes a cosignatory. It takes the cosignatory to remove and the approval delta to apply as parameters. The multisig account's public key is passed as the signer because its configuration is being modified.

As shown in Determining the Multisig Operation, the helper is called twice.

The first call removes with an approval delta of 0, because one cosignatory still remains.

The second removes the remaining cosignatory with an approval delta of -1, reducing the approval requirement from 1 back to 0.

156
157
158
159
160
161
162
163
164
165
166
167
168
169
    # Wrap the modification in a multisig transaction
    inner_fee = calculate_transaction_fee(inner_transaction)
    inner_transaction.fee = Amount(inner_fee)
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'multisig_transaction_v1',
            'inner_transaction':
                facade.transaction_factory.to_non_verifiable_transaction(
                    inner_transaction)
        },
        # This is the cosignatory that initiates the removal
        cosignatory_key_pairs[0].public_key,
        0,
        2 * 60 * 60)

151
152
153
154
155
156
157
158
159
160
161
    // Wrap the modification in a multisig transaction
    const innerFee = calculateTransactionFee(innerTransaction);
    innerTransaction.fee = new models.Amount(innerFee);
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.MultisigTransactionV1Descriptor(
            facade.transactionFactory.static.toNonVerifiableTransaction(
                innerTransaction)),
        // This is the cosignatory that initiates the removal
        cosignatoryKeyPairs[0].publicKey,
        0n,
        2 * 60 * 60);

240
241
242
243
244
245
246
247
248
249
250
        // Wrap the modification in a multisig transaction
        final long innerFee = FeeCalculator.calculateTransactionFee(
            innerTransaction);
        innerTransaction.setFee(new Amount(innerFee));
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new MultisigTransactionV1Descriptor(
                    NemTransactionFactory.toNonVerifiableTransaction(
                        innerTransaction), List.of()),
                cosignatoryKeyPairs.get(0).getPublicKey(),
                0, 2 * 60 * 60);

Since a multisig account cannot sign transactions on its own, each modification is wrapped in a MultisigTransactionV1.

The inner modification transaction is converted with so it can be embedded in the wrapping multisig transaction.

171
172
173
174
175
176
    # Calculate and attach the transaction fee
    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {(inner_fee + fee) / 1_000_000} XEM')
    print('Disabling the multisig with the multisig transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

163
164
165
166
167
168
169
170
    // Calculate and attach the transaction fee
    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log('  Transaction fee:',
        `${Number(innerFee + fee) / 1_000_000} XEM`);
    console.log(
        'Disabling the multisig with the multisig transaction:');
    console.log(JSON.stringify(transaction.toJson(), null, 2));

252
253
254
255
256
257
258
259
260
261
        // Calculate and attach the transaction fee
        final long fee = FeeCalculator.calculateTransactionFee(
            transaction);
        transaction.setFee(new Amount(fee));
        System.out.printf("  Transaction fee: %s XEM%n",
            (double) (innerFee + fee) / 1_000_000);
        System.out.println(
            "Disabling the multisig with the multisig transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(transaction.toJson()));

Both the inner transaction and the wrapper pay a transaction fee: 0.5 XEM for the modification and 0.15 XEM for the multisig wrapper, as shown in the fee schedule. Both fees are deducted from the multisig account. Cosignatories never pay fees for the transactions they initiate on behalf of a multisig.

178
179
180
181
182
    # Sign the transaction with the cosignatory's key
    signature = facade.sign_transaction(
        cosignatory_key_pairs[0], transaction)
    facade.transaction_factory.attach_signature(transaction, signature)
    return transaction

172
173
174
175
176
177
    // Sign the transaction with the cosignatory's key
    const signature = facade.signTransaction(
        cosignatoryKeyPairs[0], transaction);
    facade.transactionFactory.static
        .attachSignature(transaction, signature);
    return transaction;

263
264
265
266
267
        // Sign the transaction with the cosignatory's key
        NemTransactionFactory.attachSignature(transaction,
            facade.signTransaction(
                cosignatoryKeyPairs.get(0), transaction));
        return transaction;

Finally, each multisig transaction is signed by the cosignatory that initiates it, whose public key is passed to the facade as the wrapper's signer. Here, both removals are initiated and signed by .

In this case, a single signature is enough because this multisig requires only one cosignature. In stricter configurations, a removal requires approval from additional cosignatories, like any other transaction, although the signature of the cosignatory being removed never counts toward the requirement.

The removal of the last remaining cosignatory is a special case. Only cosignatories can sign transactions on behalf of the multisig account, so the last cosignatory signs its own removal, as the second transaction in this tutorial shows.

The cosignatories could also have been removed in the opposite order. The only difference would be which cosignatory initiates and signs each transaction.

Disabling other configurations

If the removal transactions are rejected, the account may have been configured differently from this tutorial's default, such as a 2-of-2 multisig instead of a 1-of-2.

Check the number of required cosignatures in the minCosignatories field returned by /account/get GET, and adjust the removal transactions as needed.

For example, to disable a 2-of-2 multisig:

  1. Remove Cosignatory 1 with min_approval_delta set to -1, because the account cannot keep requiring two cosignatures once a single cosignatory remains.
  2. Once confirmed, remove Cosignatory 0 with min_approval_delta set to -1.

In this case, Cosignatory 0 can still sign both removals, since the signature of the cosignatory being removed never counts toward the required approvals.

Submitting the Transactions⚓︎

199
200
201
202
203
204
205
206
207
208
209
210
    # Announce each transaction and wait for confirmation
    for signed_transaction in transactions:
        transaction_hash = facade.hash_transaction(signed_transaction)
        print(f'Built transaction with hash: {transaction_hash}')
        json_payload = facade.transaction_factory.to_json(
            signed_transaction)
        announce_result = announce_transaction(
            json_payload, 'transaction')
        if 'SUCCESS' != announce_result:
            print('Transaction rejected')
            break
        wait_for_confirmation(transaction_hash, 'transaction')

196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    // Announce each transaction and wait for confirmation
    for (const signedTransaction of transactions) {
        const transactionHash = facade.hashTransaction(signedTransaction)
            .toString();
        console.log('Built transaction with hash:', transactionHash);
        const jsonPayload = facade.transactionFactory.static
            .toJson(signedTransaction);
        const result = await announceTransaction(
            jsonPayload, 'transaction');
        if ('SUCCESS' !== result) {
            console.log('Transaction rejected');
            break;
        }
        await waitForConfirmation(transactionHash, 'transaction');
    }

144
145
146
147
148
149
150
151
152
153
154
155
156
        // Announce each transaction and wait for confirmation
        for (final Transaction transaction : transactions) {
            final String hash = facade.hashTransaction(transaction)
                .toString();
            System.out.printf("Built transaction with hash: %s%n", hash);
            final String result = announceTransaction(
                NemTransactionFactory.toJson(transaction), "transaction");
            if (!"SUCCESS".equals(result)) {
                System.out.println("Transaction rejected");
                break;
            }
            waitForConfirmation(hash, "transaction");
        }

The final step is to announce the transactions and wait for their confirmation, as described in the Transfer XEM tutorial.

When disabling the multisig, the two multisig transactions are announced sequentially. The code waits for the first transaction to be confirmed before announcing the second one, because the second removal is only valid once the first one has been processed.

Output⚓︎

The output shown below corresponds to two typical runs 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
Using node http://libertalia.nemtest.net:7890
Multisig address: TBLXIOUO4EP5YR74HYXS3BFBGONZBUHP3NIS2HJ6 (public key D656155B48D4E71E4C59EC6FAEB5EB4F214DE8BC3C65D5BF6A3D9931B4E5ACF2)
Cosignatory 0 address: TAWOQNIMCCFO6MT7JLLFER746HKBBUVU7KQUSDJX (public key AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3)
Cosignatory 1 address: TC7BQFXISQEOPN2PCPPPOM3V4R3XDPNVEHEQLID4 (public key 26D999AD34795F20D33886047A8CB7DE1ED0042AB7ED1017C602222C8B2A4C23)
Getting cosignatories from /account/get?address=TBLXIOUO4EP5YR74HYXS3BFBGONZBUHP3NIS2HJ6
  Response: No cosignatories
  Transaction fee: 0.5 XEM
Enabling the multisig with the modification transaction:
{
  "type": 4097,
  "version": 2,
  "network": 152,
  "timestamp": 357324103,
  "signer_public_key": "D656155B48D4E71E4C59EC6FAEB5EB4F214DE8BC3C65D5BF6A3D9931B4E5ACF2",
  "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "fee": "500000",
  "deadline": 357331303,
  "modifications": [
    {
      "modification": {
        "modification_type": 1,
        "cosignatory_public_key": "AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3"
      }
    },
    {
      "modification": {
        "modification_type": 1,
        "cosignatory_public_key": "26D999AD34795F20D33886047A8CB7DE1ED0042AB7ED1017C602222C8B2A4C23"
      }
    }
  ],
  "min_approval_delta": 1
}
Built transaction with hash: 4F50710F7AB5C92ED1913D0EB4EE2E29D2AA6CC9C5C6509FB1C43BFDAF124C8B
Announcing transaction to /transaction/announce
  Result: SUCCESS
Waiting for transaction confirmation from /transaction/get?hash=4F50710F7AB5C92ED1913D0EB4EE2E29D2AA6CC9C5C6509FB1C43BFDAF124C8B
  Transaction status: pending
  Transaction status: pending
  ...
transaction confirmed in block 715434

Key points in the output:

  • Lines 2-4: Addresses and public keys of all involved accounts.
  • Line 6 (Response: No cosignatories): No cosignatories are currently configured.
  • Lines 22 and 28 (cosignatory_public_key): Public keys of the cosignatories that will be added.
  • Line 32 ("min_approval_delta": 1): The number of required cosignatures will be increased by one.
 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
Using node http://libertalia.nemtest.net:7890
Multisig address: TBLXIOUO4EP5YR74HYXS3BFBGONZBUHP3NIS2HJ6 (public key D656155B48D4E71E4C59EC6FAEB5EB4F214DE8BC3C65D5BF6A3D9931B4E5ACF2)
Cosignatory 0 address: TAWOQNIMCCFO6MT7JLLFER746HKBBUVU7KQUSDJX (public key AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3)
Cosignatory 1 address: TC7BQFXISQEOPN2PCPPPOM3V4R3XDPNVEHEQLID4 (public key 26D999AD34795F20D33886047A8CB7DE1ED0042AB7ED1017C602222C8B2A4C23)
Getting cosignatories from /account/get?address=TBLXIOUO4EP5YR74HYXS3BFBGONZBUHP3NIS2HJ6
  Response: ['TC7BQFXISQEOPN2PCPPPOM3V4R3XDPNVEHEQLID4', 'TAWOQNIMCCFO6MT7JLLFER746HKBBUVU7KQUSDJX']
  Transaction fee: 0.65 XEM
Disabling the multisig with the multisig transaction:
{
  "type": 4100,
  "version": 1,
  "network": 152,
  "timestamp": 357324204,
  "signer_public_key": "AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3",
  "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "fee": "150000",
  "deadline": 357331404,
  "inner_transaction": {
    "type": 4097,
    "version": 2,
    "network": 152,
    "timestamp": 357324204,
    "signer_public_key": "D656155B48D4E71E4C59EC6FAEB5EB4F214DE8BC3C65D5BF6A3D9931B4E5ACF2",
    "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "fee": "500000",
    "deadline": 357331404,
    "modifications": [
      {
        "modification": {
          "modification_type": 2,
          "cosignatory_public_key": "26D999AD34795F20D33886047A8CB7DE1ED0042AB7ED1017C602222C8B2A4C23"
        }
      }
    ],
    "min_approval_delta": 0
  },
  "cosignatures": []
}
  Transaction fee: 0.65 XEM
Disabling the multisig with the multisig transaction:
{
  "type": 4100,
  "version": 1,
  "network": 152,
  "timestamp": 357324204,
  "signer_public_key": "AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3",
  "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "fee": "150000",
  "deadline": 357331404,
  "inner_transaction": {
    "type": 4097,
    "version": 2,
    "network": 152,
    "timestamp": 357324204,
    "signer_public_key": "D656155B48D4E71E4C59EC6FAEB5EB4F214DE8BC3C65D5BF6A3D9931B4E5ACF2",
    "signature": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "fee": "500000",
    "deadline": 357331404,
    "modifications": [
      {
        "modification": {
          "modification_type": 2,
          "cosignatory_public_key": "AC1FC0D95CA3255D20C57C179EE6E694A47A725C48DB362CC4978D7745C6A5C3"
        }
      }
    ],
    "min_approval_delta": -1
  },
  "cosignatures": []
}
Built transaction with hash: E66D3B5D36D7711C5A3C0D99C502258345E086241DF7CCD810DFB4A0ED8CC90D
Announcing transaction to /transaction/announce
  Result: SUCCESS
Waiting for transaction confirmation from /transaction/get?hash=E66D3B5D36D7711C5A3C0D99C502258345E086241DF7CCD810DFB4A0ED8CC90D
  Transaction status: pending
  Transaction status: pending
  ...
transaction confirmed in block 715438
Built transaction with hash: 70CAE1EEF8432A834C0E4EBE3A1EB6A1774F4AE42939E05AE9F120A9AF456051
Announcing transaction to /transaction/announce
  Result: SUCCESS
Waiting for transaction confirmation from /transaction/get?hash=70CAE1EEF8432A834C0E4EBE3A1EB6A1774F4AE42939E05AE9F120A9AF456051
  Transaction status: pending
  Transaction status: pending
  ...
transaction confirmed in block 715439

Key points in the output:

  • Lines 2-4: Addresses and public keys of all involved accounts.
  • Line 6 (Response: [ ... ]): Existing cosignatories have been detected.
  • Lines 27-35 (First multisig transaction): The number of required cosignatures will remain unchanged and one existing cosignatory will be removed.
  • Lines 59-67 (Second multisig transaction): The number of required cosignatures will be decreased by one and the last remaining cosignatory will be removed.

The transaction hashes shown in the output can be used to look up the transactions in the NEM testnet explorer.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Retrieve the current multisig configuration /account/get GET
Enable a multisig account MultisigAccountModificationTransactionV2
Disable a multisig account MultisigAccountModificationTransactionV2
Wrap a modification in a multisig transaction MultisigTransactionV1