Small updates to WizardConnect utils

Author: rkalis

packages/cashscript/src/TransactionBuilder.ts

@@ -18,11 +18,11 @@ import {
   isStandardUnlockableUtxo,
   StandardUnlockableUtxo,
   VmResourceUsage,
-  isContractUnlocker,
-  BchChangeOutputOptions,
-  TokenChangeOutputOptions,
-  isPlaceholderUnlocker,
-} from './interfaces.js';
+  isContractUnlocker,
+  BchChangeOutputOptions,
+  TokenChangeOutputOptions,
+  isPlaceholderUnlocker,
+} from './interfaces.js';
 import { NetworkProvider } from './network/index.js';
 import {
   calculateDust,
@@ -37,15 +37,15 @@ import {
 import { FailedTransactionError } from './Errors.js';
 import { DebugResults } from './debugging.js';
 import { debugLibauthTemplate, getLibauthTemplate, getBitauthUri } from './libauth-template/LibauthTemplate.js';
-import {
-  getWcContractInfo,
-  WcSourceOutput,
-  WcTransactionOptions,
-  WizardConnectInputPath,
-  WizardConnectTransactionObject,
-} from './walletconnect-utils.js';
+import {
+  getWcContractInfo,
+  WalletConnectSourceOutput,
+  WalletConnectTransactionOptions,
+  WizardConnectInputPath,
+  WizardConnectTransactionObject,
+} from './walletconnect-utils.js';
 import semver from 'semver';
-import { WcTransactionObject } from './walletconnect-utils.js';
+import { WalletConnectTransactionObject } from './walletconnect-utils.js';
 
 /**
  * Options accepted by the `TransactionBuilder` constructor.
@@ -558,6 +558,13 @@ export class TransactionBuilder {
     throw new Error('Could not retrieve transaction details for over 10 minutes');
   }
 
+  /**
+   * @deprecated Use `generateWalletConnectTransactionObject` instead.
+   */
+  generateWcTransactionObject(options?: WalletConnectTransactionOptions): WalletConnectTransactionObject {
+    return this.generateWalletConnectTransactionObject(options);
+  }
+
   /**
    * Build the transaction and format it as a BCH WalletConnect transaction object suitable for
    * signing and broadcasting via a BCH WalletConnect-compatible Bitcoin Cash wallet.
@@ -568,52 +575,52 @@ export class TransactionBuilder {
    * @returns A WalletConnect transaction object ready to be sent to a WalletConnect wallet.
    * @throws If the transaction cannot be built (fee exceeds limit or fungible tokens burned).
    */
-  generateWcTransactionObject(options?: WcTransactionOptions): WcTransactionObject {
-    const encodedTransaction = this.build();
-    const transaction = decodeTransactionUnsafe(hexToBin(encodedTransaction));
+  generateWalletConnectTransactionObject(options?: WalletConnectTransactionOptions): WalletConnectTransactionObject {
+    const encodedTransaction = this.build();
+    const transaction = decodeTransactionUnsafe(hexToBin(encodedTransaction));
 
     const libauthSourceOutputs = generateLibauthSourceOutputs(this.inputs);
-    const sourceOutputs: WcSourceOutput[] = libauthSourceOutputs.map((sourceOutput, index) => {
+    const sourceOutputs: WalletConnectSourceOutput[] = libauthSourceOutputs.map((sourceOutput, index) => {
       return {
         ...sourceOutput,
         ...transaction.inputs[index],
         ...getWcContractInfo(this.inputs[index]),
       };
-    });
-    return { ...options, transaction, sourceOutputs };
-  }
-
-  /**
-   * Build the transaction and format it as a WizardConnect transaction request.
-   *
-   * WizardConnect uses the standard BCH WalletConnect transaction object plus HD path metadata for
-   * each placeholder P2PKH input that the wallet must sign.
-   *
-   * @param options - Optional WalletConnect options such as `broadcast` and `userPrompt`.
-   * @returns A WizardConnect transaction object ready to be sent to a WizardConnect wallet.
-   * @throws If the transaction cannot be built, or if a placeholder input is missing HD path metadata.
-   */
-  generateWizardConnectTransactionObject(options?: WcTransactionOptions): WizardConnectTransactionObject {
-    const transaction = this.generateWcTransactionObject(options);
-    const inputPaths = this.generateWizardConnectInputPaths();
-
-    return { transaction, inputPaths };
-  }
-
-  private generateWizardConnectInputPaths(): WizardConnectInputPath[] {
-    const inputPaths: WizardConnectInputPath[] = [];
-
-    this.inputs.forEach((input, inputIndex) => {
-      if (!isPlaceholderUnlocker(input.unlocker)) return;
-
-      const hdPath = input.unlocker.hdPath;
-      if (!hdPath) {
-        throw new Error(`Placeholder P2PKH input ${inputIndex} is missing WizardConnect HD path metadata`);
-      }
-
-      inputPaths.push([inputIndex, hdPath.name, hdPath.addressIndex]);
-    });
-
-    return inputPaths;
-  }
-}
+    });
+    return { ...options, transaction, sourceOutputs };
+  }
+
+  /**
+   * Build the transaction and format it as a WizardConnect transaction request.
+   *
+   * WizardConnect uses the standard BCH WalletConnect transaction object plus HD path metadata for
+   * each placeholder P2PKH input that the wallet must sign.
+   *
+   * @param options - Optional WalletConnect options such as `broadcast` and `userPrompt`.
+   * @returns A WizardConnect transaction object ready to be sent to a WizardConnect wallet.
+   * @throws If the transaction cannot be built, or if a placeholder input is missing HD path metadata.
+   */
+  generateWizardConnectTransactionObject(options?: WalletConnectTransactionOptions): WizardConnectTransactionObject {
+    const transaction = this.generateWalletConnectTransactionObject(options);
+    const inputPaths = this.generateWizardConnectInputPaths();
+
+    return { transaction, inputPaths };
+  }
+
+  private generateWizardConnectInputPaths(): WizardConnectInputPath[] {
+    const inputPaths: WizardConnectInputPath[] = [];
+
+    this.inputs.forEach((input, inputIndex) => {
+      if (!isPlaceholderUnlocker(input.unlocker)) return;
+
+      const hdPath = input.unlocker.hdPath;
+      if (!hdPath) {
+        throw new Error(`Placeholder P2PKH input ${inputIndex} is missing WizardConnect HD path metadata`);
+      }
+
+      inputPaths.push([inputIndex, hdPath.name, hdPath.addressIndex]);
+    });
+
+    return inputPaths;
+  }
+}

packages/cashscript/src/interfaces.ts

@@ -65,10 +65,6 @@ export interface PlaceholderP2PKHUnlockerOptions {
   hdPath?: PlaceholderHdPath;
 }
 
-export interface PlaceholderP2PKHUnlockerConfig extends PlaceholderP2PKHUnlockerOptions {
-  address: string;
-}
-
 export interface PlaceholderP2PKHUnlocker extends Unlocker {
   placeholder: true;
   address: string;

packages/cashscript/src/walletconnect-utils.ts

@@ -1,7 +1,6 @@
 import {
   type LibauthOutput,
   isContractUnlocker,
-  type PlaceholderP2PKHUnlockerConfig,
   type PlaceholderP2PKHUnlocker,
   type PlaceholderP2PKHUnlockerOptions,
   type UnlockableUtxo,
@@ -12,52 +11,68 @@ import { cashAddressToLockingBytecode, hexToBin, type Input, type TransactionCom
 // Wallet Connect interfaces according to the spec
 // see https://github.com/mainnet-pat/wc2-bch-bcr
 
-export interface WcTransactionOptions {
+export interface WalletConnectTransactionOptions {
   broadcast?: boolean;
   userPrompt?: string;
 }
 
-export interface WcTransactionObject {
+/** @deprecated Use `WalletConnectTransactionOptions` instead. */
+export type WcTransactionOptions = WalletConnectTransactionOptions;
+
+export interface WalletConnectTransactionObject {
   transaction: TransactionCommon; // spec also allows for a tx hex string but we use the libauth transaction object
-  sourceOutputs: WcSourceOutput[];
+  sourceOutputs: WalletConnectSourceOutput[];
   broadcast?: boolean;
   userPrompt?: string;
 }
 
+/** @deprecated Use `WalletConnectTransactionObject` instead. */
+export type WcTransactionObject = WalletConnectTransactionObject;
+
 export type WizardConnectInputPath = [inputIndex: number, pathName: string, addressIndex: number];
 
 export interface WizardConnectTransactionObject {
-  transaction: WcTransactionObject;
+  transaction: WalletConnectTransactionObject;
   inputPaths: WizardConnectInputPath[];
 }
 
-export type WcSourceOutput = Input & LibauthOutput & WcContractInfo;
+export type WalletConnectSourceOutput = Input & LibauthOutput & WalletConnectContractInfo;
+
+/** @deprecated Use `WalletConnectSourceOutput` instead. */
+export type WcSourceOutput = WalletConnectSourceOutput;
 
-export interface WcContractInfo {
+export interface WalletConnectContractInfo {
   contract?: {
     abiFunction: AbiFunction;
     redeemScript: Uint8Array;
     artifact: Partial<Artifact>;
   }
 }
 
-export function getWcContractInfo(input: UnlockableUtxo): WcContractInfo | {} {
+/** @deprecated Use `WalletConnectContractInfo` instead. */
+export type WcContractInfo = WalletConnectContractInfo;
+
+export function getWcContractInfo(input: UnlockableUtxo): WalletConnectContractInfo | {} {
   // If the input does not have a contract unlocker, return an empty object
   if (!(isContractUnlocker(input.unlocker))) return {};
+
   const contract = input.unlocker.contract;
   const abiFunctionName = input.unlocker.abiFunction?.name;
   const abiFunction = contract.artifact.abi.find(abi => abi.name === abiFunctionName);
+
   if (!abiFunction) {
     throw new Error(`ABI function ${abiFunctionName} not found in contract artifact`);
   }
-  const wcContractObj: WcContractInfo = {
+
+  const walletConnectContractObject: WalletConnectContractInfo = {
     contract: {
       abiFunction: abiFunction,
       redeemScript: hexToBin(contract.bytecode),
       artifact: contract.artifact,
     },
   };
-  return wcContractObj;
+
+  return walletConnectContractObject;
 }
 
 /**
@@ -80,28 +95,18 @@ export const placeholderPublicKey = (): Uint8Array => Uint8Array.from(Array(33))
 /**
  * Create a placeholder P2PKH `Unlocker` for the provided user address. The returned unlocker
  * generates an empty unlocking bytecode and is flagged as `placeholder: true`, which is useful
- * when building a transaction object for WalletConnect signing where the final signing is
- * performed by the connected wallet.
+ * when building a transaction object for WalletConnect / WizardConnect signing where the final
+ * signing is performed by the connected wallet.
  *
- * @param userAddress - The user's CashAddress that will eventually sign the input, or an object
- * containing the address and signing metadata.
+ * @param userAddress - The user's CashAddress that will eventually sign the input
  * @param options - Optional signing metadata, such as HD path information for WizardConnect.
  * @returns A placeholder unlocker that can be passed to `TransactionBuilder.addInput`.
  * @throws If `userAddress` is not a valid CashAddress.
  */
 export function placeholderP2PKHUnlocker(
   userAddress: string,
-  options?: PlaceholderP2PKHUnlockerOptions,
-): PlaceholderP2PKHUnlocker;
-export function placeholderP2PKHUnlocker(options: PlaceholderP2PKHUnlockerConfig): PlaceholderP2PKHUnlocker;
-export function placeholderP2PKHUnlocker(
-  userAddressOrOptions: string | PlaceholderP2PKHUnlockerConfig,
   options: PlaceholderP2PKHUnlockerOptions = {},
 ): PlaceholderP2PKHUnlocker {
-  const userAddress = typeof userAddressOrOptions === 'string'
-    ? userAddressOrOptions
-    : userAddressOrOptions.address;
-  const unlockerOptions = typeof userAddressOrOptions === 'string' ? options : userAddressOrOptions;
   const decodeAddressResult = cashAddressToLockingBytecode(userAddress);
 
   if (typeof decodeAddressResult === 'string') {
@@ -114,6 +119,6 @@ export function placeholderP2PKHUnlocker(
     generateUnlockingBytecode: () => Uint8Array.from(Array(0)),
     placeholder: true,
     address: userAddress,
-    ...unlockerOptions,
+    ...options,
   };
 }