@bopen-io/color-permission-module 0.1.0 → 0.1.1

package/README.md

@@ -57,7 +57,21 @@ the manager's `getVersion` string.
   `p color plan` labels, built with `ColorPlan.toLabels`, and
   `options.randomizeOutputs: false` (every plan requires it: the plan's output
   indices and the approved facts name the requested outputs). The module selects
-  admitted token inputs and adds token change in `createAction`. In
+  admitted token inputs and adds token change in `createAction`, and supplies
+  the source transactions of the inputs it selects in `inputBEEF`, merged with
+  any `inputBEEF` the caller gave: it reads the asset basket with entire
+  transactions a page of 10 outputs at a time, stops at the page that returns
+  the last selected transaction, and keeps only each selected transaction with
+  its proof or unproven ancestors. A selected output whose transaction the
+  wallet does not return in full fails the call, naming the outpoint. The
+  module keeps its record of each input it signs for (outpoint, script,
+  satoshis, asset and decrypted custody) from `createAction` until that
+  action's `signAction`, and signs from those records without listing the
+  wallet's outputs; a wallet may hide an action's reserved inputs from its
+  listings (wallet-toolbox's `auto` action-batch mode does). The records are
+  dropped when `signAction` signs or refuses, and on `dispose()`; a record of an
+  action aborted before `signAction` stays until the output is selected again
+  or `dispose()`. In
   `signAction` it checks the funded transaction against the plan, asks the user
   to approve it (`color_send`: every asset leg, satoshi totals and fee, the
   signatures it releases), signs the token inputs with any `sighashTypes`
@@ -119,8 +133,10 @@ The module fails explicitly, rather than falling back, on:
 
 Explicit inputs are supported: this wallet's `p color` outputs are signed by the
 module, and foreign token inputs count only once their asset's overlay admits
-them. An input missing from `inputBEEF` is resolved by the wallet and checked
-in `signAction`. `inputPositions` and token `changePositions` are honored; change
+them. The caller supplies the source transactions of the inputs it names in
+`inputBEEF`, as wallet-toolbox requires for explicit inputs; the module adds
+them only for the inputs it selects. An input missing from `inputBEEF` is
+resolved by the wallet and checked in `signAction`. `inputPositions` and token `changePositions` are honored; change
 positions follow the requested outputs.
 
 The module does not validate BRC-176 lineage: proof transport is not part of

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AtomicBEEF, BasketInsertion, Beef, CreateActionArgs, CreateActionInput, CreateActionOutput, CreateSignatureArgs, InternalizeActionArgs, ListOutputsArgs, ListOutputsResult, LockingScript, LookupAnswer, STEAK, SignActionArgs, SignActionResult, Transaction, WalletCounterparty, WalletInterface, WalletOutput, WalletProtocol } from "@bsv/sdk";
+import { AtomicBEEF, BEEF, BasketInsertion, Beef, CreateActionArgs, CreateActionInput, CreateActionOutput, CreateSignatureArgs, InternalizeActionArgs, ListOutputsArgs, ListOutputsResult, LockingScript, LookupAnswer, STEAK, SignActionArgs, SignActionResult, Transaction, WalletCounterparty, WalletInterface, WalletOutput, WalletProtocol } from "@bsv/sdk";
 import { PermissionsModule, PermissionsModuleAction, PermissionsModuleNext, PermissionsModuleRequest } from "@bsv/wallet-toolbox-client";
 //#region src/strictJson.d.ts
 type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
@@ -194,6 +194,8 @@ interface ManagedInput extends SourceOutput {
   role: TokenRole;
   amount: bigint;
   custody: Custody;
+  /** The source transaction as BEEF, when the module made it (a handoff split). */
+  sourceBEEF?: BEEF;
 }
 type InventoryState = 'available' | 'reserved';
 /** One asset's token units and authority outputs on one side of a transaction. */
@@ -347,10 +349,15 @@ export declare class ColorPermissionModule implements PermissionsModule {
   readonly capabilities: Readonly<Record<string, string>>;
   /** Outputs a send in progress has selected, so a concurrent send does not select them too. */
   protected readonly selected: Set<string>;
+  /**
+   * The managed inputs of each funded action, by outpoint, kept from createAction until its
+   * signAction so the module signs from its own records instead of listing the wallet's outputs.
+   */
+  protected readonly held: Map<string, ManagedInput>;
   protected readonly supportedAssets: Map<string, Promise<void>>;
   protected identityKey?: Promise<string>;
   constructor(options: ColorPermissionModuleOptions);
-  /** Clears in-memory selections and asset checks. */
+  /** Clears in-memory selections, kept input records and asset checks. */
   dispose(): void;
   /** Protocol- and basket-routed calls: key and signature operations and the read views. */
   handleRequest(req: PermissionsModuleRequest, next: PermissionsModuleNext): Promise<unknown>;
@@ -461,6 +468,17 @@ export declare class ColorPermissionModule implements PermissionsModule {
    * does not report, as BTMS does when it selects, and returns the outputs it then admits.
    */
   protected resubmitHeld(assetId: string, role: TokenRole, outputs: readonly SourceOutput[], originator: string): Promise<Set<string>>;
+  /**
+   * `callerBEEF` with the source transactions of the module's selected inputs merged in, each with
+   * its proof or unproven ancestors and nothing else. Inputs the caller named keep the BEEF the
+   * caller gave; the module adds none for them.
+   */
+  protected inputBeef(callerBEEF: BEEF | undefined, inputs: readonly ManagedInput[], originator: string): Promise<BEEF | undefined>;
+  /**
+   * Reads one basket with entire transactions, a page at a time, until every input's source
+   * transaction has been returned, so no more BEEF is read than the selection needs.
+   */
+  protected sourceTransactions(basket: string, inputs: readonly ManagedInput[], originator: string): Promise<Beef>;
   /** One basket's token outputs of the asset, read from their locking scripts, excluding selected ones. */
   protected candidates(assetId: string, role: TokenRole, originator: string): Promise<Candidate[]>;
   /** A chosen candidate with its custody, or undefined when its custody record is unreadable. */
@@ -488,8 +506,15 @@ export declare class ColorPermissionModule implements PermissionsModule {
    * `p color` outputs.
    */
   protected signAction(args: SignActionArgs, action: PermissionsModuleAction | undefined, originator: string): Promise<SignActionArgs>;
-  /** The transaction's inputs that spend this wallet's `p color` outputs, with their stored custody. */
-  protected actionInputs(tx: Transaction, originator: string): Promise<ManagedInput[]>;
+  /** The kept records of the module's inputs among the action's inputs. */
+  protected heldInputs(createArgs: CreateActionArgs): ManagedInput[];
+  /** Rechecks, approves and signs the module's inputs of a funded action. */
+  protected signHeld(args: SignActionArgs, funded: {
+    plan: ColorPlan;
+    createArgs: CreateActionArgs;
+    tx: Transaction;
+    tokens: TransactionTokens;
+  }, managed: ManagedInput[], originator: string): Promise<SignActionArgs>;
   /**
    * Submits a signed token transaction to the topic of every asset among its inputs and outputs,
    * and a deploy to the discovery topic.

package/dist/index.mjs

@@ -698,6 +698,8 @@ const DEFAULT_SIGHASH = TransactionSignature.SIGHASH_ALL | TransactionSignature.
 const MAX_ENVELOPE_BYTES = 16777216;
 const MAX_RECEIPT_INSTRUCTION_BYTES = 1e3;
 const LIST_PAGE_LIMIT = 1e4;
+/** Outputs per page when reading selected inputs' source transactions, which carry BEEF. */
+const INPUT_BEEF_PAGE_LIMIT = 10;
 const SUBMIT_ATTEMPTS = 3;
 const NOSEND_EXPIRY_LABEL_PREFIX = "p nosend expiry ";
 const STATE_TAG_PREFIX = "color_state_";
@@ -727,6 +729,20 @@ function custodyOf(remittance) {
 		senderIdentityKey
 	};
 }
+/** Whether `beef` holds the transaction `txid` in full, not by txid alone. */
+function holdsTransaction(beef, txid) {
+	const found = beef.findTxid(txid);
+	return found !== void 0 && !found.isTxidOnly;
+}
+/**
+* Merges the source transaction of `outpoint` from `from` into `into` with only its own proof or
+* unproven ancestors, so other transactions in `from` are left out.
+*/
+function mergeSource(into, from, outpoint) {
+	const { txid } = parseOutpoint(outpoint);
+	if (!holdsTransaction(from, txid)) throw new Error(`BRC-207: the wallet returned no source transaction for token input ${outpoint}`);
+	into.mergeBeef(from.toBinaryAtomic(txid));
+}
 function tokenInputs(inputs) {
 	return inputs.map((input) => ({
 		outpoint: input.outpoint,
@@ -1199,6 +1215,11 @@ var ColorPermissionModule = class {
 	capabilities = { "brc207-color": "5" };
 	/** Outputs a send in progress has selected, so a concurrent send does not select them too. */
 	selected = /* @__PURE__ */ new Set();
+	/**
+	* The managed inputs of each funded action, by outpoint, kept from createAction until its
+	* signAction so the module signs from its own records instead of listing the wallet's outputs.
+	*/
+	held = /* @__PURE__ */ new Map();
 	supportedAssets = /* @__PURE__ */ new Map();
 	identityKey;
 	constructor(options) {
@@ -1209,9 +1230,10 @@ var ColorPermissionModule = class {
 		this.provider = options.provider;
 		this.requestTokenAccess = options.requestTokenAccess;
 	}
-	/** Clears in-memory selections and asset checks. */
+	/** Clears in-memory selections, kept input records and asset checks. */
 	dispose() {
 		this.selected.clear();
+		this.held.clear();
 		this.supportedAssets.clear();
 		this.identityKey = void 0;
 	}
@@ -1368,10 +1390,13 @@ var ColorPermissionModule = class {
 			this.reserve(reserved, explicit.managed);
 			const { inputs, changes } = await this.fund(reserved, plan, planned, explicit, handoff, originator);
 			sighashScopes(plan, new Set([...explicit.managed, ...inputs].map((input) => input.outpoint)));
+			const inputBEEF = await this.inputBeef(args.inputBEEF, inputs, originator);
+			for (const input of [...explicit.managed, ...inputs]) this.held.set(input.outpoint, input);
 			return {
 				...args,
 				inputs: orderInputs(explicit.inputs, tokenInputs(inputs), plan.inputPositions),
-				outputs: placeChange(outputs, changes, plan.changePositions)
+				outputs: placeChange(outputs, changes, plan.changePositions),
+				...inputBEEF === void 0 ? {} : { inputBEEF }
 			};
 		} finally {
 			for (const outpoint of reserved) this.selected.delete(outpoint);
@@ -1696,6 +1721,45 @@ var ColorPermissionModule = class {
 		});
 		return await this.spendable(assetId, outputs);
 	}
+	/**
+	* `callerBEEF` with the source transactions of the module's selected inputs merged in, each with
+	* its proof or unproven ancestors and nothing else. Inputs the caller named keep the BEEF the
+	* caller gave; the module adds none for them.
+	*/
+	async inputBeef(callerBEEF, inputs, originator) {
+		if (inputs.length === 0) return callerBEEF;
+		const beef = callerBEEF === void 0 ? new Beef() : parsed("inputBEEF", () => Beef.fromBinary(callerBEEF));
+		const baskets = /* @__PURE__ */ new Map();
+		for (const input of inputs) if (input.sourceBEEF === void 0) {
+			const basket = assetBasket(input.assetId, input.role);
+			baskets.set(basket, [...baskets.get(basket) ?? [], input]);
+		} else mergeSource(beef, Beef.fromBinary(input.sourceBEEF), input.outpoint);
+		await eachInOrder(baskets, async ([basket, held]) => {
+			const sources = await this.sourceTransactions(basket, held, originator);
+			for (const input of held) mergeSource(beef, sources, input.outpoint);
+		});
+		return beef.toBinary();
+	}
+	/**
+	* Reads one basket with entire transactions, a page at a time, until every input's source
+	* transaction has been returned, so no more BEEF is read than the selection needs.
+	*/
+	async sourceTransactions(basket, inputs, originator) {
+		const txids = new Set(inputs.map((input) => parseOutpoint(input.outpoint).txid));
+		const beef = new Beef();
+		for (let offset = 0; [...txids].some((txid) => !holdsTransaction(beef, txid));) {
+			const page = await this.wallet.listOutputs({
+				basket,
+				include: "entire transactions",
+				limit: INPUT_BEEF_PAGE_LIMIT,
+				offset
+			}, originator);
+			if (page.BEEF !== void 0) beef.mergeBeef(page.BEEF);
+			offset += page.outputs.length;
+			if (page.outputs.length < INPUT_BEEF_PAGE_LIMIT) break;
+		}
+		return beef;
+	}
 	/** One basket's token outputs of the asset, read from their locking scripts, excluding selected ones. */
 	async candidates(assetId, role, originator) {
 		return (await this.listBasket(assetBasket(assetId, role), originator, {})).flatMap((output) => {
@@ -1782,6 +1846,7 @@ var ColorPermissionModule = class {
 				sighashTypes: []
 			}),
 			inputs: tokenInputs(selected),
+			inputBEEF: await this.inputBeef(void 0, selected, originator),
 			outputs,
 			options: {
 				randomizeOutputs: false,
@@ -1810,7 +1875,8 @@ var ColorPermissionModule = class {
 			assetId,
 			role: "value",
 			amount,
-			custody: exact.custody
+			custody: exact.custody,
+			sourceBEEF: signed.tx
 		};
 	}
 	/** A fresh wallet-owned value output in the asset's basket, keyed to this wallet. */
@@ -1846,7 +1912,28 @@ var ColorPermissionModule = class {
 		const tx = action.transaction;
 		const tokens = transactionTokens(tx, true);
 		assertTransactionOperations(plan, tokens);
-		const managed = await this.actionInputs(tx, originator);
+		const managed = this.heldInputs(createArgs);
+		try {
+			return await this.signHeld(args, {
+				plan,
+				createArgs,
+				tx,
+				tokens
+			}, managed, originator);
+		} finally {
+			for (const input of managed) this.held.delete(input.outpoint);
+		}
+	}
+	/** The kept records of the module's inputs among the action's inputs. */
+	heldInputs(createArgs) {
+		return (createArgs.inputs ?? []).flatMap((input) => {
+			const managed = this.held.get(input.outpoint);
+			return managed === void 0 ? [] : [managed];
+		});
+	}
+	/** Rechecks, approves and signs the module's inputs of a funded action. */
+	async signHeld(args, funded, managed, originator) {
+		const { plan, createArgs, tx, tokens } = funded;
 		const scopes = sighashScopes(plan, new Set(managed.map((input) => input.outpoint)));
 		await eachInOrder(new Set(tokens.consumed.map((input) => input.assetId)), async (assetId) => {
 			const assetInputs = tokens.consumed.filter((input) => input.assetId === assetId);
@@ -1862,17 +1949,6 @@ var ColorPermissionModule = class {
 			}
 		};
 	}
-	/** The transaction's inputs that spend this wallet's `p color` outputs, with their stored custody. */
-	async actionInputs(tx, originator) {
-		const outpoints = new Set(tx.inputs.map((input) => inputOutpoint(input)));
-		const listed = await this.wallet.listOutputs({
-			basket: sdk.specOpBasketPrefixOutputs,
-			tags: [COLOR_BASKET_NAMESPACE],
-			include: "locking scripts",
-			includeCustomInstructions: true
-		}, originator);
-		return (await Promise.all(listed.outputs.filter((output) => outpoints.has(output.outpoint)).map(async (output) => await this.managedInput(output, originator)))).filter((input) => input !== void 0);
-	}
 	/**
 	* Submits a signed token transaction to the topic of every asset among its inputs and outputs,
 	* and a deploy to the discovery topic.