Dfns secures private keys by generating them as MPC key shares in our decentralized key management network. This happens by default when you create a wallet.
In some circumstances, however, you may need to import an existing wallet (an existing private key) into Dfns infrastructure, instead of creating a brand new wallet with Dfns and transfer funds to it. As an example, you might want to keep an existing wallet if its address is tied to a smart contract which you don't want to re-deploy.
In such a case, Dfns exposes this wallet import API endpoint, which can be used in conjunction with our import SDK. Note this is intended to be used only to migrate wallets when first onboarding onto the Dfns platform.
Dfns can not guarantee the security of imported wallets, as we have no way to control who had access to the private key prior to import. For this reason, this feature is restricted to Enterprise customers who have signed a contractual addendum limiting our liability for imported keys. Please contact your sales representative for more information.
Required Permissions
Name
Conditions
Signers:ListSigners
Always Required
Wallets:Import
Always Required
Wallet Import Flow
The wallet private key which you need to import will never be transmitted to Dfns API in one piece or in the clear (un-encrypted). The process is:
On your side (client-side), you call our GET /signers endpoint to get some information about your Signing Cluster. Your Signing Cluster is the network of nodes (also referred as "signers") the wallet key shares will be imported to. This will provide you with useful information for import (signer IDs, import encryption keys, etc.). This step corresponds to this line in our SDK wallet import example.
With the help of our import SDK libraries, the private key is MPC-sharded on the client side, and each key share is then get encrypted with the corresponding signer encryption key it will get imported to. This step corresponds to this line in our SDK wallet import example.
You then call the Wallet Import endpoint, providing the API with each encrypted key share. This step corresponds to this line in our SDK wallet import example.
Each of those encrypted key shares is transmitted to the corresponding secure node in the Signing Cluster. Each node will then be able to securely decrypt its key share, validate that it is correct, secure it and store it the same way as any wallet in Dfns infrastructure.
Request body
Property
Type - Required/Optional
Description
network
String - Required
name
String - Required
A name for the wallet
protocol
String - Required
CGGMP21 / FROST/ FROST_BITCOIN / KU23
curve
String - Required
secp256k1 / edd25519/ stark
minSigners
Integer - Required
Always 3. Min number of signers to complete a signature (TSS threshold).
encryptedKeyShares
Object Array - Required
An array of objects containing the encrypted keyshares. See format below.
encryptedKeyShares
Property
Type - Required/Optional
Description
signerId
String - Required
ID of the signer returned from GET /signers
encryptedKeyShare
String - Required
The key share encrypted with the signer encryption key (public key, asymmetric encryption)
