ssi.bitcoin.shareWith()

Request the secret you want the user to share, and get back the encrypted secret by Nostr NIP-44. During the execution process, an internal authorization check is performed similar to browser.ssi.askConsent.

Syntax

const promiseValue = await window.ssi.bitcoin.shareWith(
	pubkey, // string
	options, // object
)

Parameters

pubkey

string. Your Nostr public key for encrypting the shared secret. Either npub or hex format.

options

object. Direction about the secret you want the user to share. "mnemonic" and "derivation" use the seed specified by the user as the primary.

path(optional)

string. The Hierarchical Deterministic (HD) path that specifies the secret you want the user to share: e.g. "m/0'/1/2'". The return value is encrypted xprv key. The seed specified by the user as the primary will be used. This is required when type is "derivation".

type

BitcoinShareType. The type that specifies the secret you want the user to share: e.g. "mnemonic", "derivation", "xprv".

xpub(optional)

string. The Bitcoin public key that specifies the secret you want the user to share: e.g. "xpub123...". The return value is encrypted xprv key. This is required when type is "xprv".

Return value

A Promise that will be fulfilled with a ssi.bitcoin.SharedSecret object.

Exceptions

Throw error If failed

Examples

Sharing BIP-39 mnemonic

Combined with the Nostr protocol, it allows users to securely share their Bitcoin secrets.

// Generate a random mnemonic inside the browser
const xpub = await window.ssi.bitcoin.generate({type: "mnemonic", strength: 256})

// Ask the user to share the mnemonic encrypted with Nostr NIP-44.
// The mnemonic currently set as the primary for the user will be the one that is shared.
// Additionally, the nostr key used to pair with the yourNpubKey will also be the one currently set as the primary.
// During execution, authentication is performed to request user consent.
const encryptedSecret = await window.ssi.bitcoin.shareWith(yourNpubKey, {type: "mnemonic"})
if (!encryptedSecret) {
  // The user declined, or some error occured.
  return
}

passSomewhere(encryptedSecret)


// Decryption. Follow NIP-44 spec.
const userNpubkey = await browser.ssi.nostr.getPublicKey()
const sharedKey = nip44.getConversationKey(yourNsecKey, userNpubkey)
const mnemonic = nip44.decrypt(encryptedSecret, sharedKey)