@bitgo/wasm-utxo 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,33 @@
+# wasm-utxo
+
+This project is the successor of the Javascript `utxo-lib` package.
+
+It provides WASM bindings for the `rust-bitcoin` and `rust-miniscript` crates
+that help verify and co-sign transactions built by the BitGo Wallet Platform API.
+
+## Documentation
+
+- **[`src/wasm-bindgen.md`](src/wasm-bindgen.md)** - Guide for creating WASM bindings using the namespace pattern
+- **[`js/README.md`](js/README.md)** - TypeScript wrapper layer architecture and best practices
+- **[`cli/README.md`](cli/README.md)** - Command-line interface for address and PSBT operations
+
+## Status
+
+This project is under active development.
+
+| Feature                                 | Bitcoin     | BitcoinCash | BitcoinGold | Dash        | Doge        | Litecoin    | Zcash       |
+| --------------------------------------- | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- |
+| Descriptor Wallet: Address Support      | ✅ Complete | 🚫          | 🚫          | 🚫          | 🚫          | 🚫          | 🚫          |
+| Descriptor Wallet: Transaction Support  | ✅ Complete | 🚫          | 🚫          | 🚫          | 🚫          | 🚫          | 🚫          |
+| FixedScript Wallet: Address Generation  | ✅ Complete | ✅ Complete | ✅ Complete | ✅ Complete | ✅ Complete | ✅ Complete | ✅ Complete |
+| FixedScript Wallet: Transaction Support | ⏳ TODO     | ⏳ TODO     | ⏳ TODO     | ⏳ TODO     | ⏳ TODO     | ⏳ TODO     | ⏳ TODO     |
+
+## Building
+
+If your system has problems with `wasm-pack` (Mac M1), you can use the `Container.mk` Makefile to build the wasm files:
+
+```bash
+cd packages/wasm-utxo
+make -f Container.mk build-image
+make -f Container.mk build-wasm
+```

package/dist/browser/js/ast/formatNode.d.ts

@@ -0,0 +1,88 @@
+type Key = string;
+type Identities = "a" | "s" | "c" | "t" | "d" | "v" | "j" | "n" | "l" | "u" | "r";
+type PrefixWith<T, P extends string> = {
+    [K in keyof T & string as `${P}:${K}`]: T[K];
+};
+type PrefixIdUnion<T> = {
+    [P in Identities]: PrefixWith<T, P>;
+}[Identities];
+type Wrap<T> = T | PrefixIdUnion<T>;
+type Miniscript = Wrap<{
+    pk: Key;
+}> | Wrap<{
+    pkh: Key;
+}> | Wrap<{
+    wpkh: Key;
+}> | Wrap<{
+    multi: [number, ...Key[]];
+}> | Wrap<{
+    sortedmulti: [number, ...Key[]];
+}> | Wrap<{
+    multi_a: [number, ...Key[]];
+}> | Wrap<{
+    sortedmulti_a: [number, ...Key[]];
+}> | Wrap<{
+    tr: Key | [Key, Miniscript];
+}> | Wrap<{
+    sh: Miniscript;
+}> | Wrap<{
+    wsh: Miniscript;
+}> | Wrap<{
+    and_v: [Miniscript, Miniscript];
+}> | Wrap<{
+    and_b: [Miniscript, Miniscript];
+}> | Wrap<{
+    andor: [Miniscript, Miniscript, Miniscript];
+}> | Wrap<{
+    or_b: [Miniscript, Miniscript];
+}> | Wrap<{
+    or_c: [Miniscript, Miniscript];
+}> | Wrap<{
+    or_d: [Miniscript, Miniscript];
+}> | Wrap<{
+    or_i: [Miniscript, Miniscript];
+}> | Wrap<{
+    thresh: [number, ...Miniscript[]];
+}> | Wrap<{
+    sha256: string;
+}> | Wrap<{
+    ripemd160: string;
+}> | Wrap<{
+    hash256: string;
+}> | Wrap<{
+    hash160: string;
+}> | Wrap<{
+    older: number;
+}> | Wrap<{
+    after: number;
+}>;
+type TapTree = [TapTree, TapTree] | Miniscript;
+type Descriptor = {
+    sh: Miniscript | {
+        wsh: Miniscript;
+    };
+} | {
+    wsh: Miniscript;
+} | {
+    pk: Key;
+} | {
+    pkh: Key;
+} | {
+    wpkh: Key;
+} | {
+    combo: Key;
+} | {
+    tr: [Key, TapTree];
+} | {
+    addr: string;
+} | {
+    raw: string;
+} | {
+    rawtr: string;
+};
+export type TapTreeNode = TapTree;
+export type MiniscriptNode = Miniscript;
+export type DescriptorNode = Descriptor;
+/** Format a Miniscript or Descriptor node as a descriptor string (without checksum) */
+export declare function formatNode(n: MiniscriptNode | DescriptorNode): string;
+export {};

package/dist/browser/js/ast/formatNode.js

@@ -0,0 +1,36 @@
+/**
+ * Format a TapTree as a string
+ * If the argument is an array, descend recursively with formatTr and wrap result in curly braces
+ * Otherwise, format the node with formatN
+ */
+function formatTr(tree) {
+    return Array.isArray(tree) ? `{` + tree.map(formatTr).join(",") + `}` : formatN(tree);
+}
+function formatN(n) {
+    if (typeof n === "string") {
+        return n;
+    }
+    if (typeof n === "number") {
+        return String(n);
+    }
+    if (Array.isArray(n)) {
+        return n.map(formatN).join(",");
+    }
+    if (n && typeof n === "object") {
+        const entries = Object.entries(n);
+        if (entries.length !== 1) {
+            throw new Error(`Invalid node: ${n}`);
+        }
+        const [name, value] = entries[0];
+        if (name === "tr" && Array.isArray(value)) {
+            const [key, tree] = value;
+            return formatN({ tr: formatN([key, formatTr(tree)]) });
+        }
+        return `${name}(${formatN(value)})`;
+    }
+    throw new Error(`Invalid node: ${n}`);
+}
+/** Format a Miniscript or Descriptor node as a descriptor string (without checksum) */
+export function formatNode(n) {
+    return formatN(n);
+}

package/dist/browser/js/ast/fromWasmNode.d.ts

@@ -0,0 +1,4 @@
+import { DescriptorNode, MiniscriptNode } from "./formatNode";
+import { Descriptor, Miniscript } from "../index";
+export declare function fromDescriptor(d: Descriptor): DescriptorNode;
+export declare function fromMiniscript(m: Miniscript): MiniscriptNode;

package/dist/browser/js/ast/fromWasmNode.js

@@ -0,0 +1,120 @@
+function getSingleEntry(v) {
+    if (typeof v === "object" && v) {
+        const entries = Object.entries(v);
+        if (entries.length === 1) {
+            return entries[0];
+        }
+    }
+    throw new Error("Expected single entry object");
+}
+function node(type, value) {
+    return { [type]: fromUnknown(value) };
+}
+function wrap(type, value) {
+    const n = fromWasmNode(value);
+    const [name, inner] = getSingleEntry(n);
+    return { [`${type}:${name}`]: inner };
+}
+function fromUnknown(v) {
+    if (typeof v === "number" || typeof v === "string") {
+        return v;
+    }
+    if (Array.isArray(v)) {
+        return v.map(fromUnknown);
+    }
+    if (typeof v === "object" && v) {
+        const [type, value] = getSingleEntry(v);
+        switch (type) {
+            case "Bare":
+            case "Single":
+            case "Ms":
+            case "XPub":
+            case "relLockTime":
+            case "absLockTime":
+                return fromUnknown(value);
+            case "Sh":
+            case "Wsh":
+            case "Tr":
+            case "Pk":
+            case "Pkh":
+            case "PkH":
+            case "Wpkh":
+            case "Combo":
+            case "SortedMulti":
+            case "Addr":
+            case "Raw":
+            case "RawTr":
+            case "After":
+            case "Older":
+            case "Sha256":
+            case "Hash256":
+            case "Ripemd160":
+            case "Hash160":
+                return node(type.toLocaleLowerCase(), value);
+            case "PkK":
+                return node("pk", value);
+            case "RawPkH":
+                return node("raw_pkh", value);
+            // Wrappers
+            case "Alt":
+                return wrap("a", value);
+            case "Swap":
+                return wrap("s", value);
+            case "Check":
+                return fromUnknown(value);
+            case "DupIf":
+                return wrap("d", value);
+            case "Verify":
+                return wrap("v", value);
+            case "ZeroNotEqual":
+                return wrap("n", value);
+            case "Drop":
+                return wrap("r", value);
+            // Conjunctions
+            case "AndV":
+                return node("and_v", value);
+            case "AndB":
+                return node("and_b", value);
+            case "AndOr":
+                if (!Array.isArray(value)) {
+                    throw new Error(`Invalid AndOr node: ${JSON.stringify(value)}`);
+                }
+                const [cond, success, failure] = value;
+                if (failure === false) {
+                    return node("and_n", [cond, success]);
+                }
+                return node("andor", [cond, success, failure]);
+            // Disjunctions
+            case "OrB":
+                return node("or_b", value);
+            case "OrD":
+                return node("or_d", value);
+            case "OrC":
+                return node("or_c", value);
+            case "OrI":
+                return node("or_i", value);
+            // Thresholds
+            case "Thresh":
+                return node("thresh", value);
+            case "Multi":
+                return node("multi", value);
+            case "MultiA":
+                return node("multi_a", value);
+            case "Tree":
+                if (!Array.isArray(value) || value.length !== 2) {
+                    throw new Error(`Invalid Tree node: ${JSON.stringify(value)}`);
+                }
+                return [fromUnknown(value[0]), fromUnknown(value[1])];
+        }
+    }
+    throw new Error(`Unknown node ${JSON.stringify(v)}`);
+}
+function fromWasmNode(v) {
+    return fromUnknown(v);
+}
+export function fromDescriptor(d) {
+    return fromWasmNode(d.node());
+}
+export function fromMiniscript(m) {
+    return fromWasmNode(m.node());
+}

package/dist/browser/js/ast/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./formatNode";
+export * from "./fromWasmNode";

package/dist/browser/js/ast/index.js

@@ -0,0 +1,2 @@
+export * from "./formatNode";
+export * from "./fromWasmNode";

package/dist/browser/js/index.d.ts

@@ -0,0 +1,37 @@
+export * as address from "./address";
+export * as ast from "./ast";
+export * as utxolibCompat from "./utxolibCompat";
+export * as fixedScriptWallet from "./fixedScriptWallet";
+export type { CoinName } from "./coinName";
+export type { Triple } from "./triple";
+export type { AddressFormat } from "./address";
+export type DescriptorPkType = "derivable" | "definite" | "string";
+export type ScriptContext = "tap" | "segwitv0" | "legacy";
+export type SignPsbtResult = {
+    [inputIndex: number]: [pubkey: string][];
+};
+declare module "./wasm/wasm_utxo" {
+    interface WrapDescriptor {
+        /** These are not the same types of nodes as in the ast module */
+        node(): unknown;
+    }
+    namespace WrapDescriptor {
+        function fromString(descriptor: string, pkType: DescriptorPkType): WrapDescriptor;
+        function fromStringDetectType(descriptor: string): WrapDescriptor;
+    }
+    interface WrapMiniscript {
+        /** These are not the same types of nodes as in the ast module */
+        node(): unknown;
+    }
+    namespace WrapMiniscript {
+        function fromString(miniscript: string, ctx: ScriptContext): WrapMiniscript;
+        function fromBitcoinScript(script: Uint8Array, ctx: ScriptContext): WrapMiniscript;
+    }
+    interface WrapPsbt {
+        signWithXprv(this: WrapPsbt, xprv: string): SignPsbtResult;
+        signWithPrv(this: WrapPsbt, prv: Uint8Array): SignPsbtResult;
+    }
+}
+export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo";
+export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo";
+export { WrapPsbt as Psbt } from "./wasm/wasm_utxo";

package/dist/browser/js/index.js

@@ -0,0 +1,11 @@
+import * as wasm from "./wasm/wasm_utxo";
+// we need to access the wasm module here, otherwise webpack gets all weird
+// and forgets to include it in the bundle
+void wasm;
+export * as address from "./address";
+export * as ast from "./ast";
+export * as utxolibCompat from "./utxolibCompat";
+export * as fixedScriptWallet from "./fixedScriptWallet";
+export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo";
+export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo";
+export { WrapPsbt as Psbt } from "./wasm/wasm_utxo";

package/dist/browser/js/wasm/wasm_utxo.d.ts

@@ -0,0 +1,75 @@
+/* tslint:disable */
+/* eslint-disable */
+export class AddressNamespace {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static to_output_script_with_coin(address: string, coin: string): Uint8Array;
+  static from_output_script_with_coin(script: Uint8Array, coin: string, format?: string | null): string;
+}
+export class FixedScriptWalletNamespace {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static output_script(keys: any, chain: number, index: number, network: any): Uint8Array;
+  static address(keys: any, chain: number, index: number, network: any, address_format?: string | null): string;
+}
+export class UtxolibCompatNamespace {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Convert address string to output script
+   *
+   * # Arguments
+   * * `address` - The address string
+   * * `network` - The UtxolibNetwork object from JavaScript
+   * * `format` - Optional address format (currently unused for decoding as all formats are accepted)
+   */
+  static to_output_script(address: string, network: any, format?: string | null): Uint8Array;
+  /**
+   * Convert output script to address string
+   *
+   * # Arguments
+   * * `script` - The output script as a byte array
+   * * `network` - The UtxolibNetwork object from JavaScript
+   * * `format` - Optional address format: "default" or "cashaddr" (only applicable for Bitcoin Cash and eCash)
+   */
+  static from_output_script(script: Uint8Array, network: any, format?: string | null): string;
+}
+export class WrapDescriptor {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  hasWildcard(): boolean;
+  scriptPubkey(): Uint8Array;
+  toAsmString(): string;
+  atDerivationIndex(index: number): WrapDescriptor;
+  maxWeightToSatisfy(): number;
+  node(): any;
+  encode(): Uint8Array;
+  descType(): any;
+  toString(): string;
+}
+export class WrapMiniscript {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  toAsmString(): string;
+  node(): any;
+  encode(): Uint8Array;
+  toString(): string;
+}
+export class WrapPsbt {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static deserialize(psbt: Uint8Array): WrapPsbt;
+  finalize(): void;
+  signWithPrv(prv: Uint8Array): any;
+  signWithXprv(xprv: string): any;
+  updateInputWithDescriptor(input_index: number, descriptor: WrapDescriptor): void;
+  updateOutputWithDescriptor(output_index: number, descriptor: WrapDescriptor): void;
+  clone(): WrapPsbt;
+  serialize(): Uint8Array;
+}

package/dist/browser/js/wasm/wasm_utxo.js

@@ -0,0 +1,4 @@
+import * as wasm from "./wasm_utxo_bg.wasm";
+export * from "./wasm_utxo_bg.js";
+import { __wbg_set_wasm } from "./wasm_utxo_bg.js";
+__wbg_set_wasm(wasm);