Wallet in-memory encryption

ChainGate's in-memory encryption safeguards private keys and recovery phrases while your wallet application is active. This security layer requires user authentication whenever sensitive data is accessed, preventing unauthorized use if your application's memory is compromised.

Note

In-memory encryption is mainly relevant for browser or apps. If you're working in a secure backend environment, you might not need it—see When is in-memory encryption needed? below.

Real-World Example

Think of initializing your wallet with encryption like buying a new safe: you set a combination (password), and the safe always requires it. Even if someone inspects your device’s memory, they can’t access your private key or recovery phrase without that password.

Create your wallet safely

To enable in-memory encryption, provide a password and an askForPassword function during wallet creation. The library will automatically call this function whenever it needs to access your private key or recovery phrase (e.g., signing a transaction).

import { initializeWallet } from 'chaingate'

async function askForPassword(attempts: number, reject: () => void) {
  // Display a secure password prompt (like a login popup)
  const userInput = prompt(`Type in the password (Attempt ${attempts}/3):`)
  return userInput
}

// Creating a wallet from a BIP39 phrase with in-memory encryption
const { wallet } = await initializeWallet.fromPhrase({
  phrase: 'your recovery phrase here...',
  encrypt: {
    password: 'Tr0ub4dor&3', // The "main lock combination"
    askForPassword: askForPassword,
  }
})

Never log passwords

Never store or log user passwords in plain text. This can expose them to attackers and completely undermine your wallet’s security.

Example: Signing and broadcasting a Bitcoin transaction

const bitcoin = wallet.currency('bitcoin')

// Create a new transfer
const transfer = await bitcoin.createTransfer(
    'bc1qv5r9mr7ajz2jh04d87c4nnhfjj0jqhm3z5v0hx',
    await bitcoin.amount('0.000005', 'btc')
)

// Fetch suggested fees
const fees = await transfer.getSuggestedFees()

// Check if you have enough funds for normal fee
if (fees.normal.enoughFunds) {
    // Broadcasting the transaction requires decrypting the private key
    // -> This triggers askForPassword()
    const broadcasted = await transfer.broadcast('normal')

    console.log(broadcasted.txId)
    // e.g. "98f04fb1e708cc18525e49ad05b4d6055496a86f231b04bc132f2fd712d1f488"
}

Password prompt

During the .broadcast() call, your askForPassword function will be invoked if the private key is not currently decrypted. Once the correct password is entered, the transaction is signed and sent to the network.

Automatic caching for non-sensitive data

ChainGate reduces repeated prompts by caching non-sensitive data (e.g., public keys, addresses, derivation paths) once decrypted:

• You typically only enter your password once per session or until the system deems it necessary to re-prompt.
• Public information is stored in a readily accessible manner, while private data (like private keys) always requires decryption.

This design strikes a balance between user experience and security:

• You won’t be prompted for a password every time you ask for an address or public key.
• You will be prompted whenever the private key or recovery phrase is directly accessed (e.g., signing a transaction).

When is in-memory encryption needed?

In-memory encryption is a powerful tool—but it's not always necessary, depending on where your wallet is running.

✅ Use it in browser-based applications or apps

In browser environments or apps, memory is more exposed:

• Malicious browser extensions
• Compromised third-party scripts
• Memory inspection tools
• Shared access on a compromised machine

In these cases, sensitive data stored in memory (like private keys) could be at risk. In-memory encryption protects against this by requiring a password before anything critical is decrypted.

Not required in most backend environments

If you're using ChainGate in a backend environment (e.g., a Node.js server or cloud function with restricted access):

• Only your own trusted code runs
• The OS and runtime prevent outside access to memory
• Users never interact directly with the server’s memory

In such environments, you typically don’t need in-memory encryption, and omitting it can simplify your implementation. However, if untrusted plugins, sandboxed logic, or shared runtimes are involved, adding this layer may still offer useful protection.

Key takeaways

• User authentication: Your askForPassword function is the front line of defense, ensuring the user must provide the correct password whenever critical wallet actions occur.
• Secure defaults: ChainGate uses AES-CTR and PBKDF2 under the hood, providing robust encryption for sensitive data in memory.
• Convenient caching: Public data (e.g., addresses) is cached to reduce how often the password is needed, without compromising security for private data.
• Safeguard your password: Always choose a strong password and handle user input securely—never log or expose the entered password.