Restore from serialized data

Deserialization allows you to restore a previously saved wallet from serialized data. Every wallet type — phrase-based, seed-based, xpriv-based, private key-based, xpub-based, and public key-based — can be serialized and later reconstructed via deserializeWallet().

info

Serialization is the recommended way to back up wallets. Check the Serialization guide to learn how to generate serialized wallet data.

Restore from serialized data

import { deserializeWallet } from 'chaingate'

// For encrypted wallets, provide an askForPassword callback
const wallet = deserializeWallet(serializedData, async () => {
  return prompt('Enter your wallet password:')
})

Once deserialized, the wallet is fully operational:

import { ChainGate } from 'chaingate'

const cg = new ChainGate({ apiKey: 'your-api-key' })
const bitcoin = cg.connect(cg.networks.bitcoin, wallet)
console.log(await bitcoin.address())

Encrypted wallets

If the wallet was serialized in an encrypted state, you must provide the askForPassword callback. This function will be called whenever the wallet needs to decrypt its secret material (e.g., when signing transactions).

Validate before deserializing

You can check if data is valid serialized wallet data before attempting to deserialize:

import { isValidSerialized, deserializeWallet } from 'chaingate'

if (!isValidSerialized(data)) {
  throw new Error('Invalid serialized wallet data')
}

const wallet = deserializeWallet(data)

Checking the wallet type

Since deserializeWallet() can return different wallet types, you can use the supports() type guard or instanceof to determine the wallet's capabilities:

import { deserializeWallet, supports, PhraseWallet, SeedWallet, PrivateKeyWallet } from 'chaingate'

const wallet = deserializeWallet(data, askForPassword)

// Using the supports() type guard
if (supports(wallet, 'hdwallet')) {
  // HD wallet: PhraseWallet, SeedWallet, or XprivWallet
  // Supports multiple address derivation
}

if (supports(wallet, 'signingwallet')) {
  // Can sign transactions (has private key material)
}

if (supports(wallet, 'viewonly')) {
  // View-only wallet (xpub or public key)
  // Can derive addresses but cannot sign
}

// Using instanceof for specific types
if (wallet instanceof PhraseWallet) {
  const phraseEntity = await wallet.getPhrase()
  console.log(phraseEntity.toString())
} else if (wallet instanceof SeedWallet) {
  const seedEntity = await wallet.getSeed()
  console.log(seedEntity.hex)
} else if (wallet instanceof PrivateKeyWallet) {
  const pk = await wallet.getPrivateKey()
  console.log(pk.hex)
}

Secure your secrets

Remember that phrases, seeds, and private keys are extremely sensitive. If anyone gains access to them, they have full control over your wallet.

Key points

• Universal format: All wallet types can be serialized for easy storage or transfer.
• Deserialization: Restores the wallet exactly as it was, including derivation state.
• Type-safe: Use supports() or instanceof to determine wallet capabilities.
• View-only support: Wallets from xpub or public key can be deserialized too.
• Security: Handle serialized data with care. Although it can be encrypted, a compromised file could enable brute-force attacks.