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.

This is an asynchronous function that returns a Promise.

This interface requires the ssi.nostr permission.

Syntax

const objectValue = await browser.ssi.bitcoin.shareWith(
	tabId, // integer
	pubkey, // string
	options, // object
	dialogOption, // optional object
)

Parameters

tabId

integer. This is tabs.Tab.id. See also MDN Reference.

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.

type

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

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 xpriv key. This is required when type is "xpriv".

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 xpriv key. The seed specified by the user as the primary will be used. This is required when type is "derivation".

dialogOption (optional)

ssi.DialogInfo. Parameters to build Auth dialog.

Return value

A Promise that will be fulfilled with a ssi.bitcoin.SharedSecret object. Returns Promise<null> if error.

Examples

Sharing BIP-39 mnemonic

Combined with the Nostr protocol, you can ask the user to share the bitcoin secret with you.

// Generate a random mnemonic inside the browser
const xpub = await browser.ssi.bitcoin.generate(tabId, {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 browser.ssi.bitcoin.shareWith(
  tabId,
  yourNpubKey,
  { type: "mnemonic" },
  { caption: "The shared secret is only used by the client machine and we do not transmit it over the network." }
)
if (!encryptedSecret) {
  // The user declined, or some error occured.
  return
}

passSomewhere(encryptedSecret)


// Decryption. Follow NIP-44 spec.
const credentials = await browser.ssi.searchCredentials({
  protocolName: "nostr",
  credentialName: "nsec",
  primary: true
})
const userNpubKey = decodeNpub(credentials[0].identifier)
const sharedKey = nip44.getConversationKey(yourNsecKey, userNpubkey)
const mnemonic = nip44.decrypt(encryptedSecret, sharedKey)