ddk: validate an offer's structure without a timeout policy

[bennyhodl]

Summary

Item 8 of #225. validate_offer(offer, min_timeout_interval, max_timeout_interval, now_unix) bundled structural checks with the accepting party's timeout policy and clock. Lygos re-implemented the structural half. This PR splits them, with one place per check.

API

• ddk::contract::validate_offer_structure(offer) checks:
  • the oracle announcements;
  • the protocol version;
  • fee rate and collateral;
  • payout and change scripts against the spec's standard forms;
  • locktime units and order, and a CET locktime no later than maturity;
  • unique funding serial ids, and distinct change and fund output serial ids;
  • splice inputs against the 2-of-2 they name;
  • payouts that convert for every outcome the oracles can attest.
    It doesn't decode ordinary funding inputs, so it checks neither their values nor the spec's SegWit rule. The docs say so.
• validate_offer = validate_offer_structure + the timeout and maturity policy. Its signature is unchanged.
• dlc-messages: OfferDlc::validate is split into validate_announcements, validate_terms and validate_timing. validate runs all three and keeps its signature.
• ddk_dlc::util::validate_collateral (offer ≤ total, total ≥ 1000 sats, offer collateral 0 or ≥ 1000 sats) is shared with ContractInput::validate in ddk-manager.
• create_offer drops its own copies of these checks and runs the shared policy-free checks on the offer it built.

Creation doesn't validate announcements

create_offer, and the manager's own outgoing offers, skip announcement validation, as master did. The offering party chose its own oracles; validating announcements is the receiver's check. This also keeps Lygos's offers building: its oracle commits one nonce per enum outcome, which OracleEvent::validate rejects. Whether DDK supports that convention is item 7 of #225, which is undecided. A test pins the difference.

Fixes found along the way

• ddk-manager/src/conversion_utils.rs subtracted an enum payout from total collateral unchecked, and expected a non-empty numeric payout function. A crafted offer panicked accept_offer on master; this PR would also have exposed that panic through validate_offer. Both cases now return InvalidParameters. The payout-function conversion is TryFrom instead of From.

Behaviour changes

• Incoming offers, through accept_offer and the manager's on_offer_message, are now rejected for:
  • non-standard payout or change scripts;
  • mixed locktime units;
  • a change serial id equal to the fund output's;
  • non-zero offer collateral under 1000 sats.
    These are protocol requirements in the DLC spec.
• Two deliberate exceptions, each documented where it's checked:
  • cet_locktime = 0 passes against either locktime unit (it locks nothing, and an existing test relies on it);
  • zero offer collateral is allowed, so the accepting party can fund the whole contract.
• Duplicate funding serial ids from create_offer now return InvalidOffer; they used to return InvalidFundingInput.

Testing

• New stateless tests:
  • offer_structure_is_validated_without_a_timeout_policy: a create_offer offer passes, and nine structural defects are each rejected.
  • validate_offer_adds_the_timeout_policy_to_the_structure
  • only_the_receiver_checks_the_announcements
  • unrepresentable_payouts_are_rejected: an enum payout above total and an empty numeric curve return errors from both validate_offer_structure and accept_offer, with no panic.
• Unit suites: stateless 46, ddk contract lib 42, ddk-messages 73, ddk-dlc 22, ddk-manager lib 59, manager_tests 5 and contract_updater 1, all passing.
• Before the review fixes, all 47 stateless_execution ignored tests and 5 of the 80 manager_execution tests passed on regtest. The fixes don't touch the funding or settlement path.
• Doc tests weren't run locally. CI runs them.
• 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:
  • the Lygos creation regression;
  • panics on untrusted payouts;
  • docs that claimed more than the function checks.

[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 structure-versus-policy split is right, and it would replace about 70 lines of offer checks in lygos-utils/src/dlc/validate.rs. As it stands we can't use it:

1. Creation and validation disagree. create_offer validates without the announcement check, so an offer with per-outcome enum nonces is created, then rejected by validate_offer_structure; only_the_receiver_checks_the_announcements records exactly this. Decide contract: the primitives the Lygos wallet had to write itself (external-signer split, keyless settle, tracker, verification) #225 item 7 (see the ddk: settle a contract from its messages without a key #228 comment) before 2.0.0, so the two sides agree.
2. Behaviour differences to settle on purpose. It permits zero offer collateral and a zero CET locktime across units; orange-grove refuses both. If these are intended, say so in the docs; if not, refuse them here.
3. A policy-free accept validator alongside this one would let consumers delete their accept checks too.