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

package/README.md

@@ -59,19 +59,34 @@ the manager's `getVersion` string.
   indices and the approved facts name the requested outputs). The module selects
   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
+  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`
@@ -133,10 +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. 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
+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, BEEF, 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,6 +188,8 @@ 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;
@@ -349,15 +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 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>;
+  /** 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, kept input records 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>;
@@ -376,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
@@ -387,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;
@@ -475,10 +486,10 @@ export declare class ColorPermissionModule implements PermissionsModule {
    */
   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.
+   * 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, inputs: readonly ManagedInput[], originator: string): Promise<Beef>;
+  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. */
@@ -506,10 +517,8 @@ export declare class ColorPermissionModule implements PermissionsModule {
    * `p color` outputs.
    */
   protected signAction(args: SignActionArgs, action: PermissionsModuleAction | undefined, originator: string): Promise<SignActionArgs>;
-  /** 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: {
+  protected signBound(args: SignActionArgs, funded: {
     plan: ColorPlan;
     createArgs: CreateActionArgs;
     tx: Transaction;
@@ -554,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}`;
 }
@@ -698,8 +711,6 @@ 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_";
@@ -743,6 +754,22 @@ function mergeSource(into, from, 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,
@@ -1177,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. */
@@ -1215,11 +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 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();
+	/** 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) {
@@ -1230,10 +1256,11 @@ var ColorPermissionModule = class {
 		this.provider = options.provider;
 		this.requestTokenAccess = options.requestTokenAccess;
 	}
-	/** Clears in-memory selections, kept input records and asset checks. */
+	/** Clears in-memory selections, staged and bound input records and asset checks. */
 	dispose() {
 		this.selected.clear();
-		this.held.clear();
+		this.staged.clear();
+		this.bound.clear();
 		this.supportedAssets.clear();
 		this.identityKey = void 0;
 	}
@@ -1266,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, {
@@ -1283,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);
@@ -1302,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,
@@ -1313,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));
@@ -1329,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
@@ -1374,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) {
@@ -1391,17 +1432,47 @@ var ColorPermissionModule = class {
 			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 {
+			const funded = {
 				...args,
 				inputs: orderInputs(explicit.inputs, tokenInputs(inputs), plan.inputPositions),
 				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);
@@ -1433,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));
@@ -1446,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);
@@ -1568,7 +1641,8 @@ var ColorPermissionModule = class {
 		return {
 			...output,
 			basket,
-			customInstructions: custodyInstructions(custodyOf(remittance))
+			customInstructions: custodyInstructions(custodyOf(remittance)),
+			tags: withSuffixTag(output.tags, remittance)
 		};
 	}
 	/**
@@ -1730,40 +1804,43 @@ var ColorPermissionModule = class {
 		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) {
+		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]);
-		} 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);
+		}
+		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();
 	}
 	/**
-	* 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.
+	* 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, 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;
+	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 [];
@@ -1771,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;
 		}
@@ -1895,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"
 			}
 		};
@@ -1912,27 +1993,20 @@ var ColorPermissionModule = class {
 		const tx = action.transaction;
 		const tokens = transactionTokens(tx, true);
 		assertTransactionOperations(plan, tokens);
-		const managed = this.heldInputs(createArgs);
+		const managed = this.bound.get(action.reference) ?? [];
 		try {
-			return await this.signHeld(args, {
+			return await this.signBound(args, {
 				plan,
 				createArgs,
 				tx,
 				tokens
 			}, managed, originator);
 		} finally {
-			for (const input of managed) this.held.delete(input.outpoint);
+			this.bound.delete(action.reference);
 		}
 	}
-	/** 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) {
+	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) => {
@@ -2202,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,