feat: update UTXO selection logic to require specific UTXOs and remove skipUtxoSelection option

[originalix]

Summary by CodeRabbit

• New Features

  • Added support for marking specific UTXOs as required, ensuring they are included in coin selection.

• Chores

  • Version updated to 3.1.16.
  • Removed the skipUtxoSelection option from coin selection logic, replaced by the required UTXO mechanism.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR replaces the skipUtxoSelection parameter with an optional required flag on individual UTXOs. The parameter is removed from function signatures and the type definition gains a new property. Test fixtures are updated to reflect the new selection behavior.

Changes

Cohort / File(s)	Summary
Version Bump package.json	Version incremented from 3.1.15 to 3.1.16.
Type Definition witness.d.ts	Added optional required?: boolean property to IUtxo interface.
Core Implementation witness.js	Removed skipUtxoSelection parameter from coinSelect() function signature and from the composeTx() call.
Test Updates test/witness.js, test/fixtures/witness.js	Removed skipUtxoSelection property from test calls. Updated fixture to replace "skipUtxoSelection" behavior with required UTXO logic: changed test description, added mixed required/not-required UTXOs, adjusted values/outputs, and recalculated totals and change amounts.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Focus areas: Verify that the required flag logic in UTXO selection matches the removed skipUtxoSelection behavior; check test fixture calculations (inputs, outputs, change amounts, totals) align with the new selection policy.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main changes: removing skipUtxoSelection and implementing required UTXO selection logic across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/coin-control

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[revan-zhang]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

witness.js (1)

3-12: Breaking API change: skipUtxoSelection parameter removed.

This removes skipUtxoSelection from the function signature. Any existing callers passing this parameter will experience a breaking change. Ensure this is documented in release notes or a migration guide.

test/fixtures/witness.js (1)

369-511: Test fixture is correct but needs edge case coverage.

The math checks out:

• Inputs: 5000 + 3000 = 8000
• Payment: 1000
• Fee: 2090
• Change: 4910 ✓
• totalSpent: 3090 ✓

The test correctly validates that only required UTXOs are selected, ignoring larger non-required ones.

Add test fixtures for these edge cases:

• Insufficient required UTXOs (required UTXOs can't cover payment + fees)
• All UTXOs marked as required
• No UTXOs marked as required (backward compatibility check)
• Required UTXOs exceed payment amount significantly

Example fixture to add:

{
  description: 'required utxo - insufficient required UTXOs',
  feeRate: 10,
  inputs: [
    {
      txId: 'large_optional',
      vout: 0,
      value: 100000,
      amount: '100000',
      confirmations: 100,
      own: true,
      coinbase: false,
      address: 'tb1qul5mzh5phe7xqyqek0nl42hflfrn7ugxck59jd',
      path: "m/84'/1'/0'/0/0"
    },
    {
      txId: 'small_required',
      vout: 0,
      value: 1000,
      amount: '1000',
      confirmations: 100,
      own: true,
      coinbase: false,
      address: 'tb1qul5mzh5phe7xqyqek0nl42hflfrn7ugxck59jd',
      path: "m/84'/1'/0'/0/1",
      required: true
    }
  ],
  outputs: [
    {
      type: 'payment',
      address: 'tb1quawu6eyfuechu3qhdeejnrzne9y7shr08u8zzt',
      value: 50000,
      amount: '50000'
    }
  ],
  network: testnet,
  changeAddress: {
    address: 'tb1qul5mzh5phe7xqyqek0nl42hflfrn7ugxck59jd',
    path: "m/84'/1'/0'/0/0"
  },
  txType: 'p2wpkh',
  expected: 'Insufficient required UTXOs',
  shouldThrow: true
}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 950a313 and 9b6e754.

📒 Files selected for processing (5)

• package.json (1 hunks)
• test/fixtures/witness.js (2 hunks)
• test/witness.js (1 hunks)
• witness.d.ts (1 hunks)
• witness.js (2 hunks)

🔇 Additional comments (3)

test/witness.js (1)

28-28: LGTM!

Correctly removes skipUtxoSelection from the coinSelect call, aligning with the updated API.

witness.d.ts (1)

9-9: I'll help you verify whether the composeTx function in third-party/utxo-lib actually implements the required flag logic. Let me search the codebase for this.
<function_calls>

#!/bin/bash

First, check if third-party/utxo-lib directory exists

ls -la third-party/ 2>/dev/null | head -20

Find all relevant files in third-party/utxo-lib

echo "--- Finding files in third-party/utxo-lib ---"
find third-party/utxo-lib -type f ( -name ".js" -o -name ".ts" -o -name "*.d.ts" ) 2>/dev/null | head -30


</function_calls>

<function_calls>

#!/bin/bash

Search for composeTx function definition

echo "--- Searching for composeTx function ---"
rg -n "composeTx" --type=ts --type=js third-party/utxo-lib -A 5 -B 2 2>/dev/null | head -100


</function_calls>

<function_calls>

#!/bin/bash

Search for 'required' property usage in third-party/utxo-lib

echo "--- Searching for 'required' in third-party/utxo-lib ---"
rg -n "required" third-party/utxo-lib -A 3 -B 3 2>/dev/null | head -150


</function_calls>

<function_calls>

#!/bin/bash

Also check witness.d.ts to understand the context

echo "--- Checking witness.d.ts context ---"
cat -n witness.d.ts 2>/dev/null | head -50


</function_calls>

witness.js (1)

13-23: Verified: composeTx properly implements handling of the required property on UTXOs.

The implementation respects the required flag through multiple layers:

• In tryconfirmed.js, UTXOs marked as required are included regardless of confirmation count
• In accumulative.js, required UTXOs are separated and checked first before attempting optional selection
• In branchAndBound.js, the algorithm defers when required UTXOs are present
• In coinselectUtils.js, the coinbase filter excludes coinbase UTXOs unless they're marked as required

The property is preserved through the request transformation via Object.assign and properly utilized throughout the coin selection algorithms. The feature will work as intended.