cashscript 0.13.0-next.7 → 0.13.0-next.8

package/dist/Errors.d.ts

@@ -17,6 +17,12 @@ export declare class OutputTokenCategoryInvalidError extends Error {
 export declare class OutputTokenCommitmentInvalidError extends Error {
     constructor(commitment: string);
 }
+export declare class OutputBchChangeLockedError extends Error {
+    constructor();
+}
+export declare class OutputTokenChangeLockedError extends Error {
+    constructor(category: string);
+}
 export declare class TokensToNonTokenAddressError extends Error {
     constructor(address: string);
 }

package/dist/Errors.js

@@ -29,6 +29,16 @@ export class OutputTokenCommitmentInvalidError extends Error {
         super(`Provided token commitment ${commitment} is not a hex string`);
     }
 }
+export class OutputBchChangeLockedError extends Error {
+    constructor() {
+        super('Tried to add a BCH input or output after a BCH change output was already added');
+    }
+}
+export class OutputTokenChangeLockedError extends Error {
+    constructor(category) {
+        super(`Tried to add a token input or output with category ${category} after a change output with the same category was already added`);
+    }
+}
 export class TokensToNonTokenAddressError extends Error {
     constructor(address) {
         super(`Tried to send tokens to an address without token support, ${address}.`);

package/dist/TransactionBuilder.d.ts

@@ -1,5 +1,5 @@
 import { WalletTemplate } from '@bitauth/libauth';
-import { Unlocker, Output, TransactionDetails, UnlockableUtxo, Utxo, InputOptions, VmResourceUsage, BchChangeOutputOptions } from './interfaces.js';
+import { Unlocker, Output, TransactionDetails, UnlockableUtxo, Utxo, InputOptions, VmResourceUsage, BchChangeOutputOptions, TokenChangeOutputOptions } from './interfaces.js';
 import { NetworkProvider } from './network/index.js';
 import { DebugResults } from './debugging.js';
 import { WcTransactionOptions } from './walletconnect-utils.js';
@@ -30,6 +30,7 @@ export declare class TransactionBuilder {
     outputs: Output[];
     locktime: number;
     options: TransactionBuilderOptions;
+    private changeLocks;
     /**
      * Create a new TransactionBuilder.
      *
@@ -95,11 +96,28 @@ export declare class TransactionBuilder {
      * fee is computed from the transaction size at the configured fee rate; dust-sized change is
      * simply absorbed into the fee.
      *
+     * Should be called *after* all explicit inputs and outputs are added.
+     *
      * @param changeOutputOptions - The destination address and the fee rate (in sats/byte) to use.
      * @returns This builder for chaining.
-     * @throws If the available surplus is insufficient to cover the fee for the configured rate.
+     * @throws If the available surplus is insufficient to cover the fee for the configured rate or
+     * if a BCH change output was already added.
      */
     addBchChangeOutputIfNeeded(changeOutputOptions: BchChangeOutputOptions): this;
+    /**
+     * Add a fungible token change output for the configured category if the transaction's inputs
+     * contain more tokens of that category than its outputs. The change output is sent to the
+     * provided token address and carries the dust-minimum BCH amount.
+     *
+     * Should be called *after* all explicit token outputs for the category are added and *before*
+     * `addBchChangeOutputIfNeeded`.
+     *
+     * @param changeOutputOptions - The token category to handle and the destination token address.
+     * @returns This builder for chaining.
+     * @throws If the destination is not a token-supporting address, or if a corresponding change output
+     * or BCH change output was already added.
+     */
+    addTokenChangeOutputIfNeeded(changeOutputOptions: TokenChangeOutputOptions): this;
     /**
      * Build the transaction (skipping fee and burn checks) and return its encoded byte length.
      *

package/dist/TransactionBuilder.js

@@ -23,6 +23,7 @@ export class TransactionBuilder {
         this.inputs = [];
         this.outputs = [];
         this.locktime = 0;
+        this.changeLocks = {};
         this.provider = options.provider;
         this.options = {
             allowImplicitFungibleTokenBurn: options.allowImplicitFungibleTokenBurn ?? false,
@@ -43,7 +44,7 @@ export class TransactionBuilder {
         return this.addInputs([utxo], unlocker, options);
     }
     addInputs(utxos, unlocker, options) {
-        utxos.forEach(validateInput);
+        utxos.forEach((utxo) => validateInput(utxo, this.changeLocks));
         if ((!unlocker && utxos.some((utxo) => !isUnlockableUtxo(utxo)))
             || (unlocker && utxos.some((utxo) => isUnlockableUtxo(utxo)))) {
             throw new Error('Either all UTXOs must have an individual unlocker specified, or no UTXOs must have an individual unlocker specified and a shared unlocker must be provided');
@@ -74,7 +75,7 @@ export class TransactionBuilder {
      * @throws If any output is invalid.
      */
     addOutputs(outputs) {
-        outputs.forEach((output) => validateOutput(output, this.provider.network));
+        outputs.forEach((output) => validateOutput(output, this.provider.network, this.changeLocks));
         this.outputs = this.outputs.concat(outputs);
         return this;
     }
@@ -87,7 +88,7 @@ export class TransactionBuilder {
      * @returns This builder for chaining.
      */
     addOpReturnOutput(chunks) {
-        this.outputs.push(createOpReturnOutput(chunks));
+        this.addOutput(createOpReturnOutput(chunks));
         return this;
     }
     /**
@@ -95,9 +96,12 @@ export class TransactionBuilder {
      * fee is computed from the transaction size at the configured fee rate; dust-sized change is
      * simply absorbed into the fee.
      *
+     * Should be called *after* all explicit inputs and outputs are added.
+     *
      * @param changeOutputOptions - The destination address and the fee rate (in sats/byte) to use.
      * @returns This builder for chaining.
-     * @throws If the available surplus is insufficient to cover the fee for the configured rate.
+     * @throws If the available surplus is insufficient to cover the fee for the configured rate or
+     * if a BCH change output was already added.
      */
     addBchChangeOutputIfNeeded(changeOutputOptions) {
         const totalBchInputAmount = this.inputs.reduce((total, input) => total + input.satoshis, 0n);
@@ -119,9 +123,47 @@ export class TransactionBuilder {
         const changeOutput = { to: changeOutputOptions.to, amount: changeAmount };
         const changeOutputDust = calculateDust(changeOutput);
         if (changeAmount < changeOutputDust) {
+            this.changeLocks.BCH = true;
+            return this;
+        }
+        this.addOutput(changeOutput);
+        this.changeLocks.BCH = true;
+        return this;
+    }
+    /**
+     * Add a fungible token change output for the configured category if the transaction's inputs
+     * contain more tokens of that category than its outputs. The change output is sent to the
+     * provided token address and carries the dust-minimum BCH amount.
+     *
+     * Should be called *after* all explicit token outputs for the category are added and *before*
+     * `addBchChangeOutputIfNeeded`.
+     *
+     * @param changeOutputOptions - The token category to handle and the destination token address.
+     * @returns This builder for chaining.
+     * @throws If the destination is not a token-supporting address, or if a corresponding change output
+     * or BCH change output was already added.
+     */
+    addTokenChangeOutputIfNeeded(changeOutputOptions) {
+        const { category, to } = changeOutputOptions;
+        const inputAmount = this.inputs
+            .filter((input) => input.token?.category === category)
+            .reduce((total, input) => total + input.token.amount, 0n);
+        const outputAmount = this.outputs
+            .filter((output) => output.token?.category === category)
+            .reduce((total, output) => total + output.token.amount, 0n);
+        const changeAmount = inputAmount - outputAmount;
+        if (changeAmount <= 0n) {
+            this.changeLocks[category] = true;
             return this;
         }
-        this.outputs.push(changeOutput);
+        const changeOutput = {
+            to,
+            amount: 0n,
+            token: { amount: changeAmount, category },
+        };
+        changeOutput.amount = BigInt(calculateDust(changeOutput));
+        this.addOutput(changeOutput);
+        this.changeLocks[category] = true;
         return this;
     }
     /**
@@ -318,7 +360,14 @@ export class TransactionBuilder {
         }
         catch (e) {
             const reason = e.error ?? e.message;
-            throw new FailedTransactionError(reason, getBitauthUri(this.getLibauthTemplate()));
+            try {
+                const bitauthUri = getBitauthUri(this.getLibauthTemplate());
+                throw new FailedTransactionError(reason, bitauthUri);
+            }
+            catch {
+                // Preserve the original broadcast failure reason if URI generation fails
+                throw new FailedTransactionError(reason, 'Bitauth URI generation failed');
+            }
         }
     }
     async getTxDetails(txid, raw) {

package/dist/interfaces.d.ts

@@ -62,6 +62,10 @@ export interface BchChangeOutputOptions {
     to: string | Uint8Array;
     feeRate: number;
 }
+export interface TokenChangeOutputOptions {
+    category: string;
+    to: string | Uint8Array;
+}
 export interface TokenDetails {
     amount: bigint;
     category: string;

package/dist/utils.d.ts

@@ -1,8 +1,8 @@
 import { Transaction } from '@bitauth/libauth';
 import { Script } from '@cashscript/utils';
 import { Utxo, Output, Network, LibauthOutput, TokenDetails, AddressType, UnlockableUtxo, LibauthTokenDetails, ContractType } from './interfaces.js';
-export declare function validateInput(utxo: Utxo): void;
-export declare function validateOutput(output: Output, network: Network): void;
+export declare function validateInput(utxo: Utxo, changeLocks: Record<string, boolean>): void;
+export declare function validateOutput(output: Output, network: Network, changeLocks: Record<string, boolean>): void;
 export declare function isOpReturnOutput(output: Output): boolean;
 export declare function calculateDust(output: Output): number;
 export declare function getOutputSize(output: Output): number;

package/dist/utils.js

@@ -2,14 +2,16 @@ import { cashAddressToLockingBytecode, decodeCashAddress, addressContentsToLocki
 import { encodeInt, hash160, hash256, sha256, Op, scriptToBytecode, encodeNullDataScript, } from '@cashscript/utils';
 import { Network, } from './interfaces.js';
 import { VERSION_SIZE, LOCKTIME_SIZE } from './constants.js';
-import { OutputSatoshisTooSmallError, OutputTokenAmountTooSmallError, TokensToNonTokenAddressError, UndefinedInputError, OutputAddressNetworkMismatchError, OutputTokenCategoryInvalidError, OutputTokenCommitmentInvalidError, } from './Errors.js';
+import { OutputSatoshisTooSmallError, OutputTokenAmountTooSmallError, TokensToNonTokenAddressError, UndefinedInputError, OutputAddressNetworkMismatchError, OutputTokenCategoryInvalidError, OutputTokenCommitmentInvalidError, OutputBchChangeLockedError, OutputTokenChangeLockedError, } from './Errors.js';
 // ////////// PARAMETER VALIDATION ////////////////////////////////////////////
-export function validateInput(utxo) {
+export function validateInput(utxo, changeLocks) {
     if (!utxo) {
         throw new UndefinedInputError();
     }
+    validateChangeLocks(changeLocks, utxo.token?.category);
 }
-export function validateOutput(output, network) {
+export function validateOutput(output, network, changeLocks) {
+    validateChangeLocks(changeLocks, output.token?.category);
     if (isOpReturnOutput(output))
         return;
     const minimumAmount = calculateDust(output);
@@ -39,6 +41,14 @@ export function validateOutput(output, network) {
         throw new OutputAddressNetworkMismatchError(output.to, networkPrefix);
     }
 }
+function validateChangeLocks(changeLocks, category) {
+    if (changeLocks.BCH) {
+        throw new OutputBchChangeLockedError();
+    }
+    if (category && changeLocks[category]) {
+        throw new OutputTokenChangeLockedError(category);
+    }
+}
 export function isOpReturnOutput(output) {
     return typeof output.to !== 'string' && output.to[0] === Op.OP_RETURN;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cashscript",
-  "version": "0.13.0-next.7",
+  "version": "0.13.0-next.8",
   "description": "Easily write and interact with Bitcoin Cash contracts",
   "keywords": [
     "bitcoin cash",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@bitauth/libauth": "^3.1.0-next.8",
-    "@cashscript/utils": "^0.13.0-next.7",
+    "@cashscript/utils": "^0.13.0-next.8",
     "@electrum-cash/network": "^4.1.3",
     "fflate": "^0.8.2",
     "semver": "^7.7.2"
@@ -56,5 +56,5 @@
     "typescript": "^5.9.2",
     "vitest": "^4.0.15"
   },
-  "gitHead": "4e8e91589e1218a7c04db1a4772f625efb0140e9"
+  "gitHead": "579998062f2f9c52393568b09b580407228cb79f"
 }