unisat-dev-docs

Derive Context Hash

[!WARNING] Experimental API: deriveContextHash is experimental and may change in future versions. Use feature detection and provide a fallback path in production integrations.

deriveContextHash

unisat.deriveContextHash(appName, context)

Derive a deterministic 32-byte value from the wallet’s key material, the wallet’s current Bitcoin network, the currently-connected public key, an application name, and an application-supplied context string. The derivation uses HKDF-SHA-256 (RFC 5869).

Requires user approval — the wallet shows a confirmation dialog displaying the application name, the connected account address, the current Bitcoin network, the requesting origin, and the context string before deriving the value.

Supported keyring types: HD wallets (mnemonic), HD wallets (xpriv), and imported private keys.

Parameters

Returns

Derivation Scheme (v2.0)

ikm    = BIP-32 private key at m/73681862' (32 bytes)
salt   = "derive-context-hash"
info   = SHA-256(UTF8(appName))                  (32B)
      || SHA-256(UTF8(canonicalNetworkName))     (32B)
      || connectedPubkey                          (33B, compressed SEC1)
      || decode_hex(context)                      (variable)
output = HKDF-SHA-256(ikm, salt, info, 32)

Where:

Account/network resolution. The wallet uses the currently selected account and network at the time the controller processes the request, matching how signMessage resolves the signer. If the user switches account or network between the dApp call and approving, the derivation reflects the post-switch state. The approval dialog displays the account address and network so the user can confirm before signing.


Example

try {
  const appName = "test-app";
  const context = "deadbeef"; // hex-encoded context
  const hash = await window.unisat.deriveContextHash(appName, context);
  console.log(hash);
  // For the canonical "abandon × 11 about" BIP-39 mnemonic on Bitcoin mainnet
  // with the default BIP-44 receive account, this returns exactly:
  // => "f82ced3be0e29591a7863ece03d65f79fb494fe0de7203549855f462455df008"
} catch (e) {
  if (e.code === 4901) {
    // UnsupportedNetwork: prompt user to switch wallet to a supported Bitcoin network.
    console.log("switch wallet to a supported Bitcoin network");
  } else {
    console.log(e);
  }
}

Errors


Security

Use Cases