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

package/README.md

@@ -57,7 +57,36 @@ 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. Every output the module files (token
+  change, owned outputs, receipts, deploys and handoff splits) carries the tag
+  `p color <hex>`: the lowercase hex of the SHA-256 of the UTF-8 bytes of its
+  custody's derivation suffix. The tag is 72 characters
+  whatever the suffix, and storage keeps nothing of the suffix itself. The module reads the
+  transactions of the inputs it selects with one `listOutputs` per asset
+  basket, by their tags (`tagQueryMode: 'any'`, `limit` the number of
+  selected inputs), checks that the wallet returned exactly the selected
+  outputs, and keeps only each selected transaction with its proof or
+  unproven ancestors. An output without its suffix tag is not selected, and an app-named
+  input without it is refused, so outputs filed without the tag are not spent
+  through the module. Suffix tags are
+  left out of the `p color assets` view. A selected output whose transaction
+  the wallet does not return in full fails the call, naming the outpoint. The
+  module stages its record of each input it signs for (outpoint, script,
+  satoshis, asset and decrypted custody) when `createAction` funds the action,
+  and when the wallet's `createAction` comes back it binds the records of the
+  inputs of the returned unsigned transaction to that action's reference.
+  `signAction` signs only the inputs bound to its reference, 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). Which outputs are
+  available is storage's to decide; the module also skips outputs staged or
+  being selected by its own calls. A reference's records are dropped when
+  `signAction` signs or refuses, and on `dispose()`. Two cases leave records
+  until `dispose()`: an action aborted before `signAction` leaves its bound
+  records unused, and a wallet `createAction` that fails after the module
+  funded it leaves its inputs staged, so the module does not select them again
+  until `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 +148,9 @@ 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 module supplies `inputBEEF` for the inputs it selects; the source
+transactions of an input the app names are the app's to supply in `inputBEEF`,
+as wallet-toolbox requires for explicit inputs. `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, CreateActionResult, 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;
@@ -188,12 +188,16 @@ interface Candidate extends SourceOutput {
   token: TokenOutput;
   amount: bigint;
   customInstructions: string;
+  /** The tags the wallet listed for the output. */
+  tags: readonly string[];
 }
 interface ManagedInput extends SourceOutput {
   assetId: string;
   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 +351,14 @@ 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 funded actions whose createAction has not come back, by outpoint. */
+  protected readonly staged: Map<string, ManagedInput>;
+  /** The managed inputs the module signs for, by the action reference they were bound to. */
+  protected readonly bound: 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, staged and bound 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>;
@@ -369,8 +377,11 @@ export declare class ColorPermissionModule implements PermissionsModule {
    * before it can be spent.
    */
   protected fileDeploy(result: SignActionResult, action: PermissionsModuleAction, originator: string): Promise<void>;
-  /** Verifies every `p color` receipt; the caller must already have submitted the transaction. */
-  protected internalizeAction(args: InternalizeActionArgs, originator: string): Promise<void>;
+  /**
+   * Verifies every `p color` receipt and tags it with its derivation suffix; the caller must
+   * already have submitted the transaction.
+   */
+  protected internalizeAction(args: InternalizeActionArgs, originator: string): Promise<InternalizeActionArgs>;
   /**
    * Checks a received transaction: every input unlocks its source and every asset it involves is
    * supported. Token amounts are not re-evaluated: the received output must be admitted and
@@ -380,9 +391,16 @@ export declare class ColorPermissionModule implements PermissionsModule {
   /** Checks each distinct asset in order, so the first unsupported one is the one reported. */
   protected assertSupportedAssets(assetIds: Iterable<string>): Promise<void>;
   /** One receipt: its custody, its output's asset, owner and basket, and overlay admission. */
-  protected verifyReceipt(tx: Transaction, outputIndex: number, remittance: BasketInsertion, originator: string): Promise<void>;
+  protected verifyReceipt(tx: Transaction, outputIndex: number, remittance: BasketInsertion, originator: string): Promise<Custody>;
   /** Checks a planned token action and adds its selected token inputs and per-asset change. */
   protected createAction(args: CreateActionArgs, originator: string): Promise<CreateActionArgs>;
+  /** Stages a funded action's managed inputs until its createAction comes back. */
+  protected stage(inputs: readonly ManagedInput[]): void;
+  /**
+   * Moves the staged inputs the returned transaction spends to its action reference. A result
+   * without a signable transaction binds nothing; its named inputs are only unstaged.
+   */
+  protected bindAction(result: CreateActionResult): void;
   protected reserve(reserved: Set<string>, inputs: ReadonlyArray<{
     outpoint: string;
   }>): void;
@@ -461,6 +479,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>;
+  /**
+   * The selected inputs of one basket with their entire transactions, in one listing by their
+   * suffix tags. The listing must return exactly the selected outputs.
+   */
+  protected sourceTransactions(basket: string, selected: 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 +517,13 @@ 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[]>;
+  /** Rechecks, approves and signs the module's inputs of a funded action. */
+  protected signBound(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.
@@ -529,7 +563,7 @@ export declare class ColorPermissionModule implements PermissionsModule {
   /** The queried outputs the overlay reports admitted and unspent, matched to their source bytes. */
   protected spendable(assetId: string, outputs: readonly SourceOutput[]): Promise<Set<string>>;
   /** All spendable outputs of one basket, with locking scripts and custom instructions. */
-  protected listBasket(basket: string, originator: string, filter: Pick<ListOutputsArgs, 'tags' | 'tagQueryMode'>): Promise<WalletOutput[]>;
+  protected listBasket(basket: string, originator: string, filter: Pick<ListOutputsArgs, 'tags' | 'tagQueryMode' | 'includeTags'>): Promise<WalletOutput[]>;
   protected sourceOutput(output: WalletOutput): SourceOutput;
   protected preimage(tx: Transaction, inputIndex: number, source: SourceOutput, scope: number): number[];
   /** Unlocking scripts for this module's inputs of `template`, keyed by input index. */

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Beef, LockingScript, PublicKey, Signature, Spend, Transaction, TransactionSignature, UnlockingScript } from "@bsv/sdk";
-import { hash160, hash256 } from "@bsv/sdk/primitives/Hash";
+import { hash160, hash256, sha256 } from "@bsv/sdk/primitives/Hash";
 import Random from "@bsv/sdk/primitives/Random";
 import { toArray, toBase64, toHex } from "@bsv/sdk/primitives/utils";
 import { Bsv21Token, OneColor, StrictCborLink, isTokenShaped, tryDecodeStrictCbor } from "@bsv/templates";
@@ -140,6 +140,19 @@ function parseBalanceSelector(basket) {
 }
 /** The shared deployment discovery topic. */
 const DISCOVERY_TOPIC = "tm_color";
+const SUFFIX_TAG = /^p color [0-9a-f]{64}$/;
+/**
+* The tag filed on a managed output: `p color ` and the lowercase hex of the SHA-256 of the UTF-8
+* bytes of its custody's derivation suffix. It has a fixed length whatever the suffix, and storage
+* keeps nothing of the suffix itself.
+*/
+function derivationSuffixTag(derivationSuffix) {
+	return `${COLOR_BASKET_NAMESPACE} ${toHex(sha256(toArray(derivationSuffix, "utf8")))}`;
+}
+/** Whether a tag is a derivation suffix tag. */
+function isDerivationSuffixTag(tag) {
+	return SUFFIX_TAG.test(tag);
+}
 function colorTopic(assetId) {
 	return `tm_color_${assetId}`;
 }
@@ -727,6 +740,36 @@ 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));
+}
+/** The tag every output the module files carries: the module finds an output's transaction by it. */
+function suffixTagOf(custody) {
+	return derivationSuffixTag(custody.derivationSuffix);
+}
+/** `tags` with the custody's suffix tag added. */
+function withSuffixTag(tags, custody) {
+	return [.../* @__PURE__ */ new Set([...tags ?? [], suffixTagOf(custody)])];
+}
+/** Whether a listed output carries the suffix tag of its custody. */
+function carriesSuffixTag(tags, custody) {
+	return tags?.includes(suffixTagOf(custody)) === true;
+}
+/** The BEEF a listOutputs result returns, empty when it returns none. */
+function listingBeef(listing) {
+	return listing.BEEF === void 0 ? new Beef() : Beef.fromBinary(listing.BEEF);
+}
 function tokenInputs(inputs) {
 	return inputs.map((input) => ({
 		outpoint: input.outpoint,
@@ -1161,13 +1204,13 @@ function tryReadTokenOutput(lockingScript, outpoint) {
 		return;
 	}
 }
-/** A record with its stored tags and the computed state tag in place of any stored one. */
+/** A record with its stored tags, less suffix tags, and the computed state tag in place of any stored one. */
 function inventoryView(record) {
 	const state = inventoryState(record);
 	return {
 		record,
 		state,
-		tags: [...(record.output.tags ?? []).filter((tag) => !tag.startsWith(STATE_TAG_PREFIX)), `${STATE_TAG_PREFIX}${state}`]
+		tags: [...(record.output.tags ?? []).filter((tag) => !tag.startsWith(STATE_TAG_PREFIX) && !isDerivationSuffixTag(tag)), `${STATE_TAG_PREFIX}${state}`]
 	};
 }
 /** A BEEF holding only the transactions of the returned page. */
@@ -1199,6 +1242,10 @@ 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 funded actions whose createAction has not come back, by outpoint. */
+	staged = /* @__PURE__ */ new Map();
+	/** The managed inputs the module signs for, by the action reference they were bound to. */
+	bound = /* @__PURE__ */ new Map();
 	supportedAssets = /* @__PURE__ */ new Map();
 	identityKey;
 	constructor(options) {
@@ -1209,9 +1256,11 @@ var ColorPermissionModule = class {
 		this.provider = options.provider;
 		this.requestTokenAccess = options.requestTokenAccess;
 	}
-	/** Clears in-memory selections and asset checks. */
+	/** Clears in-memory selections, staged and bound input records and asset checks. */
 	dispose() {
 		this.selected.clear();
+		this.staged.clear();
+		this.bound.clear();
 		this.supportedAssets.clear();
 		this.identityKey = void 0;
 	}
@@ -1244,11 +1293,7 @@ var ColorPermissionModule = class {
 		switch (req.method) {
 			case "createAction": return { args: await this.createAction(req.args, req.originator) };
 			case "signAction": return { args: await this.signAction(req.args, req.action, req.originator) };
-			case "internalizeAction": {
-				const args = req.args;
-				await this.internalizeAction(args, req.originator);
-				return { args };
-			}
+			case "internalizeAction": return { args: await this.internalizeAction(req.args, req.originator) };
 			case "listActions": {
 				const args = req.args;
 				await this.authorizeRead(req.originator, {
@@ -1261,6 +1306,7 @@ var ColorPermissionModule = class {
 		}
 	}
 	async onResponse(res, context) {
+		if (context.method === "createAction") this.bindAction(res);
 		if (context.method === "signAction" && context.action !== void 0) {
 			await this.fileDeploy(res, context.action, context.originator);
 			if (!context.action.noSend) await this.submitSigned(res, context.action.transaction);
@@ -1280,8 +1326,8 @@ var ColorPermissionModule = class {
 			txid,
 			vout: 0
 		});
-		const owned = ColorPlan.fromLabels(action.createArgs?.labels)?.ownedOutputs.some((remittance) => remittance.outputIndex === 0 && remittance.assetId === "ISSUE");
-		if (deploy?.deploy !== true || owned !== true) return;
+		const remittance = ColorPlan.fromLabels(action.createArgs?.labels)?.ownedOutputs.find((owned) => owned.outputIndex === 0 && owned.assetId === "ISSUE");
+		if (deploy?.deploy !== true || remittance === void 0) return;
 		const customInstructions = action.createArgs?.outputs?.[0]?.customInstructions;
 		await this.wallet.internalizeAction({
 			tx: result.tx,
@@ -1291,12 +1337,16 @@ var ColorPermissionModule = class {
 				protocol: "basket insertion",
 				insertionRemittance: {
 					basket: assetBasket(deploy.assetId, deploy.role),
-					...customInstructions === void 0 ? {} : { customInstructions }
+					...customInstructions === void 0 ? {} : { customInstructions },
+					tags: [suffixTagOf(remittance)]
 				}
 			}]
 		}, originator);
 	}
-	/** Verifies every `p color` receipt; the caller must already have submitted the transaction. */
+	/**
+	* Verifies every `p color` receipt and tags it with its derivation suffix; the caller must
+	* already have submitted the transaction.
+	*/
 	async internalizeAction(args, originator) {
 		if ((args.labels ?? []).some((label) => label.startsWith(`p color `))) throw new Error("BRC-207: p color labels have no meaning in internalizeAction");
 		const tx = parsed("the received transaction", () => Transaction.fromAtomicBEEF(args.tx));
@@ -1307,11 +1357,23 @@ var ColorPermissionModule = class {
 				remittance
 			}] : [];
 		});
-		if (receipts.length === 0) return;
+		if (receipts.length === 0) return args;
 		await this.assertCompletedTransaction(tx);
+		const tags = /* @__PURE__ */ new Map();
 		await eachInOrder(receipts, async ({ outputIndex, remittance }) => {
-			await this.verifyReceipt(tx, outputIndex, remittance, originator);
+			const custody = await this.verifyReceipt(tx, outputIndex, remittance, originator);
+			tags.set(outputIndex, withSuffixTag(remittance.tags, custody));
 		});
+		return {
+			...args,
+			outputs: args.outputs.map((output) => output.insertionRemittance === void 0 || !tags.has(output.outputIndex) ? output : {
+				...output,
+				insertionRemittance: {
+					...output.insertionRemittance,
+					tags: tags.get(output.outputIndex)
+				}
+			})
+		};
 	}
 	/**
 	* Checks a received transaction: every input unlocks its source and every asset it involves is
@@ -1352,6 +1414,7 @@ var ColorPermissionModule = class {
 			lockingScript: source.lockingScript,
 			satoshis: source.satoshis
 		}])).has(outpoint)) throw new Error("BRC-207: the received output is not admitted and unspent in its asset overlay");
+		return custody;
 	}
 	/** Checks a planned token action and adds its selected token inputs and per-asset change. */
 	async createAction(args, originator) {
@@ -1368,15 +1431,48 @@ 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)));
-			return {
+			const inputBEEF = await this.inputBeef(args.inputBEEF, inputs, originator);
+			const funded = {
 				...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 }
 			};
+			this.stage([...explicit.managed, ...inputs]);
+			return funded;
 		} finally {
 			for (const outpoint of reserved) this.selected.delete(outpoint);
 		}
 	}
+	/** Stages a funded action's managed inputs until its createAction comes back. */
+	stage(inputs) {
+		for (const input of inputs) this.staged.set(input.outpoint, input);
+	}
+	/**
+	* Moves the staged inputs the returned transaction spends to its action reference. A result
+	* without a signable transaction binds nothing; its named inputs are only unstaged.
+	*/
+	bindAction(result) {
+		const signable = result.signableTransaction;
+		const atomic = signable?.tx ?? result.tx;
+		if (atomic === void 0) return;
+		let tx;
+		try {
+			tx = Transaction.fromAtomicBEEF(atomic);
+		} catch {
+			return;
+		}
+		for (const input of tx.inputs) {
+			const outpoint = inputOutpoint(input);
+			const staged = this.staged.get(outpoint);
+			if (staged === void 0) continue;
+			this.staged.delete(outpoint);
+			if (signable === void 0) continue;
+			const records = this.bound.get(signable.reference) ?? [];
+			records.push(staged);
+			this.bound.set(signable.reference, records);
+		}
+	}
 	reserve(reserved, inputs) {
 		for (const input of inputs) {
 			this.selected.add(input.outpoint);
@@ -1408,7 +1504,8 @@ var ColorPermissionModule = class {
 			basket: sdk.specOpBasketPrefixOutputs,
 			tags: [COLOR_BASKET_NAMESPACE],
 			include: "locking scripts",
-			includeCustomInstructions: true
+			includeCustomInstructions: true,
+			includeTags: true
 		}, originator);
 		const own = new Map(listed.outputs.filter((output) => outpoints.has(output.outpoint)).map((output) => [output.outpoint, output]));
 		const beef = args.inputBEEF === void 0 ? void 0 : parsed("inputBEEF", () => Beef.fromBinary(args.inputBEEF));
@@ -1421,9 +1518,10 @@ var ColorPermissionModule = class {
 	}
 	/** Counts one of this wallet's `p color` outputs once it is managed, admitted and unspent. */
 	async ownInput(explicit, output, originator) {
-		if (!output.spendable) throw new Error("BRC-207: an explicit p color input is reserved by another action");
+		if (!output.spendable || this.staged.has(output.outpoint) || this.selected.has(output.outpoint)) throw new Error("BRC-207: an explicit p color input is reserved by another action");
 		const managed = await this.managedInput(output, originator);
 		if (managed === void 0) throw new Error("BRC-207: an explicit p color input is not a managed token output");
+		if (!carriesSuffixTag(output.tags, managed.custody)) throw new Error(`BRC-207: token output ${managed.outpoint} was filed without its suffix tag and is not spendable through the module`);
 		await this.assertSupportedAsset(managed.assetId);
 		if (!(await this.spendable(managed.assetId, [managed])).has(managed.outpoint) && !(await this.resubmitHeld(managed.assetId, managed.role, [managed], originator)).has(managed.outpoint)) throw new Error("BRC-207: an explicit p color input is not admitted and unspent");
 		explicit.managed.push(managed);
@@ -1543,7 +1641,8 @@ var ColorPermissionModule = class {
 		return {
 			...output,
 			basket,
-			customInstructions: custodyInstructions(custodyOf(remittance))
+			customInstructions: custodyInstructions(custodyOf(remittance)),
+			tags: withSuffixTag(output.tags, remittance)
 		};
 	}
 	/**
@@ -1696,10 +1795,52 @@ 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) {
+				mergeSource(beef, Beef.fromBinary(input.sourceBEEF), input.outpoint);
+				continue;
+			}
+			const basket = assetBasket(input.assetId, input.role);
+			baskets.set(basket, [...baskets.get(basket) ?? [], input]);
+		}
+		await eachInOrder(baskets, async ([basket, selected]) => {
+			const sources = await this.sourceTransactions(basket, selected, originator);
+			for (const input of selected) mergeSource(beef, sources, input.outpoint);
+		});
+		return beef.toBinary();
+	}
+	/**
+	* The selected inputs of one basket with their entire transactions, in one listing by their
+	* suffix tags. The listing must return exactly the selected outputs.
+	*/
+	async sourceTransactions(basket, selected, originator) {
+		const listing = await this.wallet.listOutputs({
+			basket,
+			tags: selected.map((input) => suffixTagOf(input.custody)),
+			tagQueryMode: "any",
+			include: "entire transactions",
+			limit: selected.length
+		}, originator);
+		const wanted = new Set(selected.map((input) => input.outpoint));
+		const returned = new Set(listing.outputs.map((output) => output.outpoint));
+		const missing = [...wanted].filter((outpoint) => !returned.has(outpoint));
+		const extra = [...returned].filter((outpoint) => !wanted.has(outpoint));
+		if (missing.length > 0 || extra.length > 0 || listing.outputs.length !== wanted.size) throw new Error(`BRC-207: the wallet returned other outputs than the selected token inputs: missing ${missing.join(", ") || "none"}; extra ${extra.join(", ") || "none"}`);
+		return listingBeef(listing);
+	}
 	/** 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) => {
-			if (this.selected.has(output.outpoint) || output.customInstructions === void 0) return [];
+		return (await this.listBasket(assetBasket(assetId, role), originator, { includeTags: true })).flatMap((output) => {
+			if (output.spendable === false || this.selected.has(output.outpoint) || this.staged.has(output.outpoint) || output.customInstructions === void 0 || !(output.tags ?? []).some(isDerivationSuffixTag)) return [];
 			const source = this.sourceOutput(output);
 			const token = tryReadTokenOutput(source.lockingScript, parseOutpoint(output.outpoint));
 			if (token?.assetId !== assetId || token.role !== role) return [];
@@ -1707,20 +1848,23 @@ var ColorPermissionModule = class {
 				...source,
 				token,
 				amount: token.amount,
-				customInstructions: output.customInstructions
+				customInstructions: output.customInstructions,
+				tags: output.tags ?? []
 			}];
 		});
 	}
 	/** A chosen candidate with its custody, or undefined when its custody record is unreadable. */
 	async readableInput(candidate, originator) {
 		try {
-			const { outpoint, lockingScript, satoshis, token, customInstructions } = candidate;
-			return await this.custodyInput({
+			const { outpoint, lockingScript, satoshis, token, customInstructions, tags } = candidate;
+			const input = await this.custodyInput({
 				outpoint,
 				lockingScript,
 				satoshis,
 				token
 			}, customInstructions, originator);
+			if (input === void 0 || !carriesSuffixTag(tags, input.custody)) return void 0;
+			return input;
 		} catch {
 			return;
 		}
@@ -1782,6 +1926,7 @@ var ColorPermissionModule = class {
 				sighashTypes: []
 			}),
 			inputs: tokenInputs(selected),
+			inputBEEF: await this.inputBeef(void 0, selected, originator),
 			outputs,
 			options: {
 				randomizeOutputs: false,
@@ -1810,7 +1955,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. */
@@ -1829,6 +1975,7 @@ var ColorPermissionModule = class {
 				satoshis: TOKEN_CARRIER_SATOSHIS,
 				basket: assetBasket(assetId, "value"),
 				customInstructions: custodyInstructions(custody),
+				tags: [suffixTagOf(custody)],
 				outputDescription: "BRC-207 token change"
 			}
 		};
@@ -1846,7 +1993,21 @@ 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.bound.get(action.reference) ?? [];
+		try {
+			return await this.signBound(args, {
+				plan,
+				createArgs,
+				tx,
+				tokens
+			}, managed, originator);
+		} finally {
+			this.bound.delete(action.reference);
+		}
+	}
+	/** Rechecks, approves and signs the module's inputs of a funded action. */
+	async signBound(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 +2023,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.
@@ -2126,6 +2276,7 @@ var ColorPermissionModule = class {
 				basket,
 				tags: filter.tags,
 				tagQueryMode: filter.tagQueryMode,
+				includeTags: filter.includeTags,
 				include: "locking scripts",
 				includeCustomInstructions: true,
 				limit: LIST_PAGE_LIMIT,