[bennyhodl]

Summary

Item 6 of #225. Lygos's offer builder probes a fabricated accept and parses required_input_funds= out of an InvalidArgument string to size its coin selection. This PR gives constructors a typed shortfall error, and gives coin selection a pure function that returns the exact requirement without building a transaction.

API

• ddk_dlc::Error::InsufficientFunds { required: Amount, available: Amount } replaces the string error from the fund-transaction constructor.
• ddk_dlc::FundingRequirements { required, fund_fee, cet_fee } with change(available).
• PartyParams::funding_requirements(total_collateral, fee_rate_per_vb, extra_fee, counterparty_payout_spk, fee_rule) is now the single fee formula, and the constructor uses it.
• PartyParams::spliced() holds the spliced constructor's input layout (drop inputs whose witness is over 108 bytes, add DLC inputs as ordinary ones). Construction and pricing share it, so splice offers are priced the way they're built.
• ddk::contract::funding_requirements(offer, accept_payout_spk) -> FundingRequirements is what accept_offer will require of the offering party, splice inputs included. It builds without manager, and FundingRequirements is re-exported from ddk::contract.
• ContractError::InsufficientFunds { required, available }. From<ddk_manager::error::Error> unwraps DlcError through the same conversion, so the typed error survives a manager wrapper.

Breaking changes

• PartyParams::get_change_output_and_fees_with_counterparty is removed. It was the workaround; use funding_requirements. get_change_output_and_fees stays, as an OwnPayoutOnly wrapper.
• Downstream: ddk-ffi's exhaustive ContractError match needs an InsufficientFunds arm. Lygos's required_funds can call ddk::contract::funding_requirements and match the typed error.

Compatibility

• Fees, change and funding transactions are unchanged for every contract shape that built before, under both fee rules. That includes a zero-collateral party, which still gets a zero-value change output whatever its inputs hold.

Known issue (predates this PR, not fixed)

A splice offer that also has an ordinary input declaring a witness over 108 bytes can't be accepted. The spliced constructor leaves that input out of the funding transaction, build_funding_psbt then fails to match it, and its value still counts toward the party's input total. funding_requirements prices it the way the constructor does. The constructor behaviour itself needs its own fix.

Not changed

• ddk-manager/src/utils.rs::get_approximate_required_amount is still a separate, approximate pre-selection estimate. Moving it onto this formula changes the manager's coin-selection amounts.
• The error doesn't say which party is short. An accept_offer caller can compare available with its own inputs.

Testing

• New in ddk-dlc:
  • funding_requirements_are_exactly_sufficient: covers both fee rules, single- and dual-funded contracts, and both sides being short. Inputs at exactly required build; one sat less fails with the exact InsufficientFunds { required, available }.
  • a_zero_collateral_party_gets_no_change: a regression test for a zero-collateral party with an extra fee.
  • a_splicing_party_is_priced_on_its_spliced_inputs.
• New stateless tests:
  • an_offer_funded_with_exactly_its_requirement_is_accepted
  • a_splice_offer_funded_with_exactly_its_requirement_is_accepted
  • a_splice_offer_is_priced_as_the_spliced_constructor_funds_it
• Unit suites: ddk-dlc 25, ddk contract lib 42, stateless 45, ddk-manager lib 59, all passing.
• stateless_execution --ignored on regtest: splice-in, single-funded and dual-funded closes pass.
• cargo fmt --check, cargo clippy -- -D warnings and cargo check -p ddk --no-default-features pass.
• Reviewed by GPT-6 Astra. Fixed from the review:
  • an unintended change to zero-collateral allocation, now reverted;
  • splice pricing drifting from the constructor.

[bennyhodl]

Note

🤖 Claude Opus 5.5 responding on behalf of bennyhodl

Review against orange-grove's consumers (lygos_utils::dlc, the wallet crate, the server's Fordefi signer) before 2.0.0. Change first.

Right owner for the fee math: orange-grove's required_funds (lygos-utils/src/dlc/offer.rs) becomes one call. Before freezing:

1. PartyParams::spliced() as public API. It drops every ordinary input whose max_witness_len exceeds a P2WPKH witness, not only the duplicated splice input. The doc says that's deliberate so old spliced contracts rebuild identically, which is right for rebuilding. Published in 2.0.0, though, it freezes a lossy rule for new contracts. Keep the legacy layout behind a clearly legacy name (or private), and for new contracts dedupe splice inputs by outpoint.
2. Who is short. ContractError::InsufficientFunds { required, available } doesn't say which party. A two-party funding failure is ambiguous without it; add the party now, since adding a field later breaks matches.
3. Consider #[non_exhaustive] on ContractError before 2.0.0, so new typed variants (this one, ddk: verify a signed contract from its three messages #231's signature errors) don't need a major release.

[bennyhodl]

Note

🤖 Claude Opus 5.5 responding on behalf of bennyhodl

Follow-up on the review above:

1. spliced(): done in 5471cb1. spliced() now drops only the ordinary copy of each splice input, matched by outpoint. The old rule is kept as legacy_spliced() and is used only to rebuild contracts from rc.8 and earlier. signed_context tries the new layout first, then the legacy one. The legacy step is needed: an rc.8 splice with a small P2WSH input does not rebuild under the new rule. All six pinned contract fixtures still rebuild byte for byte.
2. Which party is short: not adding it. The shortfall also comes from the single-party PartyParams::get_change_output_and_fees, which has no role to report, and neither does its one outside caller (ddk-ffi's change_output_and_fees). The options were a party argument the caller can't fill, an Option<Party> that every consumer would need a fallback for, or removing that function from the public API. None is worth it for this release. InsufficientFunds { required, available } stays as it is. The two-party callers already know which party they asked about.
3. #[non_exhaustive] on ContractError: done in 5471cb1. No match in the workspace needed changing. ddk-ffi's exhaustive match will need a wildcard arm when it moves to this release.