[bennyhodl]

Summary

Item 1 of #225. accept_offer, sign_accept and sign_cet took the DLC funding secret key in-process, and the funding PSBT only covered wallet inputs. So a vault, an HSM, a browser extension or a hardware signer could not drive the stateless API. Lygos wrote ~1,700 lines (lygos_utils::dlc) to fill the gap. The new ddk::contract::external module splits each step around the signer.

API (ddk::contract::external, builds without manager)

Step	Prepare	Complete
accept	accept_request(&OfferDlc, AcceptOfferParams) -> AcceptRequest	complete_accept(AcceptRequest, ContractSignatures) -> AcceptResult
sign	sign_request(&OfferDlc, &AcceptDlc) -> SignRequest	complete_sign(SignRequest, ContractSignatures, &Psbt) -> SignResult
finalize	finalize_request(&OfferDlc, &AcceptDlc, &SignDlc) -> FinalizeRequest	complete_finalize(FinalizeRequest, &Psbt) -> Transaction

• ContractSigningRequest { funding_pubkey, refund: Psbt, cets: Vec<Psbt>, adaptor_points } is what the contract key signs. Each PSBT carries witness_utxo, the 2-of-2 witness_script and SIGHASH_ALL.
• ContractSignatures { refund_signature, cet_adaptor_signatures } is the signer's answer.
• FundingSigningRequest { psbt, splice_inputs } is the funding PSBT plus the splice inputs this party half-signs. A splice half travels back as a SIGHASH_ALL partial signature in that PSBT.
• Preparation needs no placeholder signatures. Completion verifies the refund signature, every adaptor signature and every splice half before it builds a message. It rejects a changed funding transaction (PsbtMismatch), a wrong key, a non-SIGHASH_ALL sighash and a wrong adaptor count (InvalidSignature).
• accept_offer, sign_accept(_spliced) and finalize_sign(_spliced) are now request → in-process signer → complete. There is one code path.
• Request types hold private state and aren't serializable. A remote signer gets the PSBTs, points and keys inside them. The caller keeps the request or rebuilds it from the messages. accept_request draws random serial ids unless the params pin them.

Supporting primitives (one implementation each)

• advanced::cet_adaptor_points(&OfferDlc), from ContractInfo::get_adaptor_points (ddk-manager) over a new DlcTrie::generate_adaptor_points. Signing and verification compute the points once per step.
• advanced::contract_id_from_outpoint and its inverse temporary_contract_id_from_outpoint live in ddk-manager and replace utils::compute_id and ddk's copy. Contract-id bytes are unchanged.
• funding_input_index and decode_previous_transaction are public in advanced.
• contract::network_from_chain_hash is public and knows Testnet4.
• create_funding_psbt fills witness_utxo, witness_script and the sighash on splice inputs. The DDK wallet signer skips those inputs; the xpriv and descriptor signers reject them as unsupported.
• New ContractError::InvalidSignature.

Breaking changes

• ContractKeyProvider::dlc_input_signing_key(&self, splice_input: &FundingInput) now takes only the splice input. It recovers the previous temporary id from the input and returns whichever of the two prior funding keys the provider derives. ddk-ffi (ffi/src/contract.rs:282) drops its prior_temporary_contract_id / prior_funding_pubkey plumbing and passes the input.
• The new ContractError variant needs a match arm in ddk-ffi's error conversion.
• A splice input with no key and no half now fails at completion with InvalidSignature. It used to be InvalidFundingInput("missing prior funding secret key").

Behaviour notes

• The in-process path now verifies its own signatures too, because there is one path. accept_offer does about twice the adaptor-signature crypto it did; sign_accept adds one verification pass and drops one point computation.

Follow-up

• Wallet-input witnesses returned by the signer are still taken as finalized. Funding-witness verification is item 2 (verify_funding_witness, in a separate PR). Once both land, complete_sign and complete_finalize should run it on the signer's wallet witnesses.

Testing

• New in ddk/tests/stateless.rs:
  • external_signers_fund_a_contract_that_settles (settles through sign_cet and sign_refund);
  • external_signers_splice_a_contract;
  • one rejection test each for a changed transaction, a wrong contract key, a wrong splice key, a non-ALL refund sighash, a non-ALL splice sighash, and a wrong adaptor count.
  • The test signer (tests/external_signer) uses only rust-bitcoin and secp256k1-zkp, as a real external signer would.
• New on-chain test: external_signers_fund_splice_and_close in stateless_execution.rs.
• cargo test -p ddk --lib --test stateless (80 + 48) and cargo test -p ddk-trie -p ddk-manager --lib (59 + 42) pass.
• Nine selected stateless_execution ignored tests pass on regtest: numeric-with-difference splices, disjoint, accept-side splice, mnemonic key recovery, and the new external-signer flow.
• cargo fmt --check, cargo clippy -- -D warnings, cargo check -p ddk --no-default-features and cargo run --example stateless_splice pass.
• Reviewed by GPT-6 Astra:
  • no mutation path into the completion requests;
  • adaptor-point generation and contract-id bytes match master;
  • two findings: the wallet-witness check is left to item 2 (the follow-up above), and the dlc_input_signing_key break is kept as described above.

[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.

The biggest deletion of the set: with #231, roughly 400–600 lines of request building and completion in lygos-utils/src/dlc/request.rs and complete.rs, plus dlcd-rs's adaptor-point code. The request/complete seam is right. Before freezing:

1. Accept-time funding request. AcceptRequest exposes only contract(); the accepting party's splice halves are requested at finalize. Our lender signs through an HSM: it signs its splice halves with the refund and CETs in one batch at accept, stores them, and finalizes without asking the HSM again. Please expose the accepting party's funding/splice request on AcceptRequest, and accept the halves in complete_accept.
2. Pinned ids. accept_request draws omitted serial ids, so a request made again differs. Expose the chosen ids on the request (or require them) so a crashed signer can rebuild the same request.
3. External wallet witnesses. "Wallet input witnesses are taken as finalized". For an external signer that is the one place nothing checks what came back. With ddk: verify a signed contract from its three messages #231's verify_funding_witness available, verify the ordinary funding witnesses a signer returns at sign and finalize, not only the splice halves.
4. ddk: sign contracts with keys held outside the process #229 and ddk: verify a signed contract from its three messages #231 both rewrite finalization. Land them together and keep fee-rule recovery, strict splice parsing, and the checks on both parties' witnesses in the merged path.