Source: custom.js

  1. /**
  2.  * Provides classes for interacting via text-based copy/paste XPUBs and
  3.  * download/sign generic PSBT files using a custom "device'
  4.  *
  5.  * The following API classes are implemented:
  6.  *
  7.  * * CustomExportExtendedPublicKey
  8.  * * CustomSignMultisigTransaction
  9.  *
  10.  * @module custom
  11.  */
  12. import {
  13.   unsignedMultisigPSBT,
  14.   parseSignaturesFromPSBT,
  15.   MAINNET,
  16.   TESTNET,
  17.   validateBIP32Path,
  18.   validateRootFingerprint,
  19.   ExtendedPublicKey,
  20. } from "unchained-bitcoin";
  21. import {
  22.   IndirectKeystoreInteraction,
  23.   PENDING,
  24.   ACTIVE,
  25.   INFO,
  26.   ERROR,
  27. } from "./interaction";
  29. export const CUSTOM = "custom";
  31. /**
  32.  * Base class for interactions with Custom "devices"
  33.  *
  34.  * @extends {module:interaction.IndirectKeystoreInteraction}
  35.  */
  36. export class CustomInteraction extends IndirectKeystoreInteraction {}
  38. /**
  39.  * Base class for text-based (or clipboard pasted) ExtendedPublicKey
  40.  * This class handles parsing/validating the xpub and relevant
  41.  * derivation properties. If no root fingerprint is provided, one will
  42.  * be deterministically assigned.
  43.  *
  44.  * @extends {module:custom.CustomInteraction}
  45.  * @example
  46.  * const interaction = new CustomExportExtendedPublicKey({network: MAINNET, bip32Path: "m/45'/0'/0'"});
  47.  * const {xpub, rootFingerprint, bip32Path} = interaction.parse({xpub: xpub..., rootFingerprint: 0f056943});
  48.  * console.log(xpub);
  49.  * // "xpub..."
  50.  * console.log(rootFingerprint);
  51.  * // "0f056943"
  52.  * console.log(bip32Path);
  53.  * // "m/45'/0'/0'"
  54.  * ** OR **
  55.  * * const {xpub, rootFingerprint, bip32Path} = interaction.parse({xpub: xpub...});
  56.  * console.log(xpub);
  57.  * // "xpub..."
  58.  * console.log(rootFingerprint);
  59.  * // "096aed5e"
  60.  * console.log(bip32Path);
  61.  * // "m/45'/0'/0'"
  62.  */
  63. export class CustomExportExtendedPublicKey extends CustomInteraction {
  65.   /**
  66.    * @param {object} options - options argument
  67.    * @param {string} options.network - bitcoin network (needed for derivations)
  68.    * @param {string} options.bip32Path - bip32Path to interrogate
  69.    */
  70.   constructor({ network, bip32Path }) {
  71.     super();
  72.     if ([MAINNET, TESTNET].find((net) => net === network)) {
  73.       this.network = network;
  74.     } else {
  75.       throw new Error("Unknown network.");
  76.     }
  77.     this.validationErrorMessages = [];
  78.     this.bip32Path = bip32Path;
  79.     const bip32PathError = validateBIP32Path(bip32Path);
  80.     if (bip32PathError.length) {
  81.       this.validationErrorMessages.push({
  82.         code: "custom.bip32_path.path_error",
  83.         text: bip32PathError,
  84.       });
  85.     }
  86.   }
  88.   isSupported() {
  89.     return this.validationErrorMessages.length === 0;
  90.   }
  92.   messages() {
  93.     const messages = super.messages();
  95.     if (this.validationErrorMessages.length) {
  96.       this.validationErrorMessages.forEach((e) => {
  97.         messages.push({
  98.           state: PENDING,
  99.           level: ERROR,
  100.           code: e.code,
  101.           text: e.text,
  102.         });
  103.       });
  104.     }
  106.     messages.push({
  107.       state: PENDING,
  108.       level: INFO,
  109.       code: "custom.import_xpub",
  110.       text: "Type or paste the extended public key here.",
  111.     });
  112.     return messages;
  113.   }
  115.   /**
  116.    * Parse the provided JSON and do some basic error checking
  117.    *
  118.    * @param {Object} data - JSON object with incoming data to be parsed (read: reformatted)
  119.    * @returns {Object} Object - ExtendedPublicKeyDerivation {xpub, bip32path, rootFingerprint}
  120.    */
  121.   parse(data) {
  122.     // build ExtendedPublicKey struct (validation happens in constructor)
  123.     let xpubClass;
  124.     let rootFingerprint;
  125.     try {
  126.       xpubClass = ExtendedPublicKey.fromBase58(data.xpub);
  127.     } catch (e) {
  128.       throw new Error("Not a valid ExtendedPublicKey.");
  129.     }
  130.     try {
  131.       if (data.rootFingerprint === "" || !data.rootFingerprint) {
  132.         const pkLen = xpubClass.pubkey.length;
  133.         // If no fingerprint is provided, we will assign one deterministically
  134.         rootFingerprint = xpubClass.pubkey.substring(pkLen - 8);
  135.       } else {
  136.         validateRootFingerprint(data.rootFingerprint);
  137.         rootFingerprint = data.rootFingerprint;
  138.       }
  139.     } catch (e) {
  140.       throw new Error(
  141.         `Root fingerprint validation error: ${e.message.toLowerCase()}.`
  142.       );
  143.     }
  144.     const numSlashes = this.bip32Path.split("/").length;
  145.     const bipDepth = this.bip32Path.startsWith("m/")
  146.       ? numSlashes - 1
  147.       : numSlashes;
  149.     if (xpubClass.depth !== bipDepth) {
  150.       throw new Error(
  151.         `Depth of ExtendedPublicKey (${xpubClass.depth}) does not match depth of BIP32 path (${bipDepth}).`
  152.       );
  153.     }
  155.     return {
  156.       xpub: xpubClass.base58String,
  157.       rootFingerprint,
  158.       bip32Path: this.bip32Path,
  159.     };
  160.   }
  161. }
  163. /**
  164.  * Returns signature request data via a PSBT for a Custom "device" to sign and
  165.  * accepts a PSBT for parsing signatures from a Custom "device"
  166.  *
  167.  * @extends {module:custom.CustomInteraction}
  168.  * @example
  169.  * const interaction = new CustomSignMultisigTransaction({network, inputs, outputs, bip32paths, psbt});
  170.  * console.log(interaction.request());
  171.  * // "cHNidP8BA..."
  172.  *
  173.  * // Parse signatures from a signed PSBT
  174.  * const signatures = interaction.parse(psbt);
  175.  * console.log(signatures);
  176.  * // {'029e866...': ['3045...01', ...]}
  177.  *
  178.  */
  179. export class CustomSignMultisigTransaction extends CustomInteraction {
  181.   /**
  182.    * @param {object} options - options argument
  183.    * @param {string} options.network - bitcoin network
  184.    * @param {array<object>} options.inputs - inputs for the transaction
  185.    * @param {array<object>} options.outputs - outputs for the transaction
  186.    * @param {array<string>} options.bip32Paths - BIP32 paths
  187.    * @param {object} [options.psbt] - PSBT of the transaction to sign, included or generated from the other options
  188.    */
  189.   constructor({ network, inputs, outputs, bip32Paths, psbt }) {
  190.     super();
  191.     this.network = network;
  192.     this.inputs = inputs;
  193.     this.outputs = outputs;
  194.     this.bip32Paths = bip32Paths;
  196.     if (psbt) {
  197.       this.psbt = psbt;
  198.     } else {
  199.       try {
  200.         this.psbt = unsignedMultisigPSBT(network, inputs, outputs);
  201.       } catch (e) {
  202.         throw new Error(
  203.           "Unable to build the PSBT from the provided parameters."
  204.         );
  205.       }
  206.     }
  207.   }
  209.   messages() {
  210.     const messages = super.messages();
  211.     messages.push({
  212.       state: PENDING,
  213.       level: INFO,
  214.       code: "custom.download_psbt",
  215.       text: `Download and save this PSBT file.`,
  216.     });
  217.     messages.push({
  218.       state: PENDING,
  219.       level: INFO,
  220.       code: "custom.sign_psbt",
  221.       text: `Add your signature to the PSBT.`,
  222.     });
  223.     messages.push({
  224.       state: ACTIVE,
  225.       level: INFO,
  226.       code: "custom.sign_psbt",
  227.       text: `Verify the transaction details and sign.`,
  228.     });
  229.     messages.push({
  230.       state: ACTIVE,
  231.       level: INFO,
  232.       code: "custom.upload_signed_psbt",
  233.       text: `Upload the signed PSBT.`,
  234.     });
  235.     return messages;
  236.   }
  238.   /**
  239.    * Request for the PSBT data that needs to be signed.
  240.    *
  241.    * NOTE: the application may be expecting the PSBT in some format
  242.    * other than the direct Object.
  243.    *
  244.    * E.g. PSBT in Base64 is interaction().request().toBase64()
  245.    *
  246.    * @returns {Object} Returns the local unsigned PSBT from transaction details
  247.    */
  248.   request() {
  249.     return this.psbt;
  250.   }
  252.   /**
  253.    *
  254.    * @param {Object} psbtObject - the PSBT
  255.    * @returns {Object} signatures - This calls a function in unchained-bitcoin which parses
  256.    * PSBT files for sigantures and then returns an object with the format
  257.    * {
  258.    *   pubkey1 : [sig1, sig2, ...],
  259.    *   pubkey2 : [sig1, sig2, ...]
  260.    * }
  261.    * This format may change in the future or there may be additional options for return type.
  262.    */
  263.   parse(psbtObject) {
  264.     const signatures = parseSignaturesFromPSBT(psbtObject);
  265.     if (!signatures || signatures.length === 0) {
  266.       throw new Error(
  267.         "No signatures found in the PSBT. Did you upload the right one?"
  268.       );
  269.     }
  270.     return signatures;
  271.   }
  272. }