Overview

Fireblocks workspaces support non-custodial wallets with two algorithms: MPC_ECDSA_SECP256K1 (ECDSA) and MPC_EDDSA_ED25519 (EdDSA).

Each algorithm allows the addition of different assets. For example, generating an ECDSA key set will let you add asset such as Bitcoin, or Ethereum, while generating an EdDSA key set will let you add Solana, or Algorand, for example.

A wallet can meet one of the following states:

• Generate ECDSA keys only.
• Generate EdDSA keys only.
• Generate ECDSA & EdDSA keys.
• Add EdDSA keys to an already existing ECDSA key set.
• Add ECDSA keys to an already existing EdDSA key set.

🚧

Version Compatibility

To fully utilize an expandable wallet with your preferred algorithms, ensure that you are using Web SDK version >=12.2.0 and Mobile SDK version >=2.6.0.

Extending Your Key Set

🚧

Post Extension Backup

It is crucial to perform another backup after you have extended your key set. Please refer to the first point below, and make sure you follow the instructions there.

Should you face a situation where you already have an existing key set, you can generate another key set for the different algorithm, as shown in MPC Key Generation.

Assuming you have generated an ECDSA key set, you should now trigger the key generation function with the EdDSA algorithm (MPC_EDDSA_ED25519) only.

In cases of extending your key set, you are required to make sure you have performed the same flows you have implemented for your already existing key set, that is:

1. Backup and Recovery, as seen here. Make sure you back up the new key set after generating the keys. By default, backup enforcement is enabled and you won't be able to add assets to your newly extended key set (e.g. Solana for EdDSA) until you have backed up your key set.
2. Multiple Devices, as seen here. In case there are multiple devices for the same wallet, and one of them has extended its key set, you are required to run the join wallet operation again, for your newly extended key set.

Retrieving the Device Keys Status

The MPC Keys Generation process is a multi-step operation that can fail or stop in the middle for various reasons, such as a network error or the end user leaving the application midway through the process. If a failure or stoppage occurs, you end up with a device and a deviceId that cannot be used until you complete the MPC key generation process.

To check the current key status for a device, there are two methods you can use:

1. Call the getKeysStatus function on the web SDK or mobile SDK. When keyStatus returns READY, the MPC key generation process has been completed. Note that READY is the only valid final status for the key.
2. Call the Get device key setup state endpoint. This endpoint returns the device's current status and includes some additional response parameters:
   1. SetupStatus: Returns as COMPLETE or INCOMPLETE per key that started creation on the device.
   2. Algorithm name: Returns as MPC_ECDSA_SECP256K1 or MPC_EDDSA_ED25519.
   3. backedUp: This boolean flag indicates whether the keys were backed up by any of the wallet's devices. Remember, a wallet can have multiple devices associated with it.

Note that a device's status will only return as COMPLETE when all the keys declared in its workspace have reached the COMPLETE status and the device's backup flag is set to true.

Retrieving the Wallet Key Status

You can also query a wallet's status by calling the Get wallet key setup state endpoint. The response includes the current status of all devices associated with the wallet. Note that a wallet is considered COMPLETE as long as at least one of its devices also has the COMPLETE status.

If you send a request to an incomplete wallet or device, your request will fail and Fireblocks may return error codes to provide context for the request's failure.

Re-Extending your Key Set

In rare cases, a device may be lost while extending the wallet's key set.
For instance, if a wallet originally contained ECDSA keys that have been backed up, and new EdDSA keys are generated but not yet backed up.
In this scenario, if the device with the EdDSA keys is lost now, the wallet itself will be incomplete and therefore causing most operations to fail, in all the wallet's devices.

To resolve this issue and regain control of the already backed-up ECDSA keys, you will need to remove the EdDSA keys from the wallet's algorithms set by executing the following function, within the Fireblocks SDK, on your server:

const response = await fireblocksNCW.deleteSigningAlgorithm(walletId, [SigningAlgorithm.MPC_EDDSA_ED25519])

This will allow the ECDSA keys to be used again for this wallet.

In addition, your wallet is now capable of re-generating the EDDSA key set. In order to do that, you will have to re-trigger the EdDSA key set generation, in the client application, as mentioned in MPC Key Generation:

import { IKeyDescriptor } from "@fireblocks/ncw-js-sdk";

// Generate MPC Keys
const algorithms = new Set(["MPC_CMP_EDDSA_ED25519"]);
const keyDescriptor: Set<IKeyDescriptor> = await fireblocksNCW.generateMPCKeys(algorithms);

val algorithms = setOf(Algorithm.MPC_EDDSA_ED25519)
fireblocksSdk.generateMPCKeys(algorithms = algorithms){ result ->
    Timber.i("generateMPCKeys result: $result")
}

// generate MPC key for EDDSA using concurrency
let algorithms = Set([.MPC_EDDSA_ED25519])
let keys = try await instance.generateMPCKeys(algorithms: algorithms)

<----OR---->

// generate MPC key for EDDSA using callback
let algorithms = Set([.MPC_EDDSA_ED25519])
try instance.generateMPCKeys(algorithms: algorithms, callback: { [weak self] result in
	//handle result
})

Note: The above example takes into consideration that an ECDSA key set has been created, and the extended EdDSA key set has been lost. The opposite can happen as well, and the mentioned functions will take any type of algorithm from the SigningAlgorithm enum.

Note: You cannot remove an algorithm if it's already in use, meaning -

• If assets were created already under that algorithm.
• If the public key was requested via the getPublicKey endpoint.
• If takeover has been performed for that wallet.

This can only happen if "Backup Enforcement" was disabled intentionally (it's enabled by default).

Note: This API should be used only to remove an algorithm from the wallet's required algorithms. Extending the wallet's algorithms set is done by Extending Your Key Set