Skip to content

Support CLINK offer quantity and payer-data discovery - #1077

Merged
shocknet-justin merged 3 commits into
dash2from
offer-payer-data-quantity
Nov 9, 2026
Merged

shocknet-justin merged 3 commits into
dash2from
offer-payer-data-quantity

Conversation

@shocknet-justin

@shocknet-justin shocknet-justin commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds quantity support to CLINK Offers and a distinct, recoverable response for missing or invalid required payer data.

Aligned with:

Payer Data

Missing or invalid required payer fields now return offer code 6, with the full list of required field names and no invoice. Wallets can collect or correct those fields and retry.

Malformed offer requests remain code 1. This includes malformed JSON, which previously returned code 6 through the shared transport. Other CLINK operations retain their existing error codes.

Quantity and Pricing

When an offer requires quantity:

  • Require a positive safe-integer JSON number. Do not accept numeric strings or default a missing quantity to 1.
  • Determine the unit price using the existing pricing path, then multiply by quantity.
  • For fixed-price offers, use the configured price per unit.
  • For spontaneous offers, treat the request’s amount_sats as the price per unit.
  • Check the final invoice total against amount limits. Unsafe or out-of-range totals return code 5 without creating an invoice.

An unsolicited quantity does not change pricing or reach seller fulfillment data. Offers that do not require quantity retain their existing amount semantics.

The spec also defines quantity for host-resolved variable pricing, where the encoded offer may contain no satoshi price. This PR supports Pub’s existing fixed and spontaneous pricing paths; it does not introduce a variable-pricing engine.

Seller Fulfillment

Accepted quantity is retained as a number in invoice payer data and is available to seller callback URL templates alongside the total amount.

The existing GetUserOfferInvoices RPC retains its string-map contract, returning quantity as a string there.

Release Coordination

Targets dash2.

The SDK dependency and lockfile are intentionally unchanged because SDK 1.8 has not been released. Pub uses a local quantity-aware request type until that dependency is updated.

Update the SDK dependency on dash2 after 1.8 is published and before the Pub release merge.

Testing

  • Pub build passed.
  • Targeted tests passed for quantity validation, fixed and spontaneous pricing, total limits, overflow, payer-data discovery and retry, numeric storage, seller RPC compatibility, and callback expansion.
  • CLINK transport regression tests passed.
  • Updated the Lightning-backed payer-data test to verify a multiplied invoice amount and stored quantity.
  • Full Docker/Lightning CI must pass before merge.

Optional Manage Callbacks

  • Omitted callback_url on create stores SQL NULL. Omission on update preserves the existing URL; null or an empty string clears it, including on the default offer.
  • Label remains required and is never invented. Updates require offer.id.
  • A reversible migration converts legacy empty callback strings to NULL and preserves other offer data and uniqueness.
  • Backups retain the existing binary representation for absent callbacks. Native RPC responses retain their string contract; Manage responses can return null.
  • Temporary validation/type overrides support the installed SDK until the new release is cut; no dependency or lockfile bump.
  • Regression tests passed for create/update, default offers, label/id rejection, invoices, backup restore, migration upgrade/rollback, and candidate-SDK compatibility.

SDK: shocknet/ClinkSDK#37
Spec: shocknet/CLINK#18

@shocknet-justin
shocknet-justin marked this pull request as ready for review November 6, 2026 18:51
- Introduced `assertNoReservedOfferPayerData` function to validate payer data fields.
- Updated `ManagementManager` and `OfferManager` to utilize the new validation.
- Enhanced tests to ensure reserved fields are correctly rejected during offer creation and updates.
@shocknet-justin
shocknet-justin merged commit 3108e12 into dash2 Nov 9, 2026
4 checks passed
@shocknet-justin
shocknet-justin deleted the offer-payer-data-quantity branch November 9, 2026 20:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants