Skip to content

feat(sql): add catalog list and paid query sessions - #60

Draft
johnpmitsch wants to merge 2 commits into
mainfrom
dx-6602-sql-x402-mpp
Draft

feat(sql): add catalog list and paid query sessions#60
johnpmitsch wants to merge 2 commits into
mainfrom
dx-6602-sql-x402-mpp

Conversation

@johnpmitsch

@johnpmitsch johnpmitsch commented Aug 24, 2026

Copy link
Copy Markdown
Collaborator

Adds SQL Explorer methods for a public catalog and two paid query lanes.

list_clusters reads GET /sql/rest/v1/clusters on a keyless client. query_with_session sends a SIWX Bearer token and does not sign a per-request payment. query_with_mpp_session posts the SQL body to the MPP session route and advances the voucher by the SQL challenge amount, not per_call.

Channel accounting

query_with_mpp_session takes &mut ChannelState and advances cumulative_spent whenever the voucher reached the gateway — a non-2xx body and a lost response included. Only a connect failure, which never puts the voucher on the wire, leaves the channel untouched.

The gateway refuses a re-signed stale cumulative, so a channel left behind the gateway cannot be used again, while one slightly ahead still works. Callers persist on every outcome, not just after a 200:

let result = qn
    .sql
    .query_with_mpp_session(&params, &payment, &mut channel)
    .await;
save_channel(&channel)?; // persist first — the voucher may have settled
let result = result?;

Previously the payment-receipt header was parsed and then discarded on any non-2xx, so a gateway that banked a voucher and then failed the query body stranded the channel.

Test plan

  • cargo test -p quicknode-sdk --features rust,payments,payments-tempo --lib sql — 13 passed
  • cargo test -p quicknode-sdk --features rust,payments,payments-tempo --lib — 331 passed
  • cargo fmt --check
  • CI

New coverage: a 500 carrying a receipt advances the channel to the receipt value; a 402 with no receipt advances to the signed value; a failed probe leaves the channel unchanged.

Notes

cargo clippy --all-targets reports three pre-existing E0308 errors in examples/streams.rs and examples/webhooks_e2e.rs (stream compression, webhook templates). Confirmed present with this branch's changes stashed; untouched here.

Bindings parity for the new SQL surface (Python/Node/Ruby) is not in this PR.

SQL Explorer can now list clusters without an account key, run a
drawdown query with a SIWX Bearer session, and run an MPP session
query. The MPP increment is the SQL challenge amount, not per_call.
sql_voucher_call parsed the payment-receipt header and then discarded it
whenever the status check failed, and the caller only persisted the
accepted cumulative on success. When the gateway banked a voucher and
then failed the query body, local spend stayed behind the gateway's
accepted cumulative. Re-signing that stale value is refused, so the
channel could not be used again.

sql_voucher_call and query_with_mpp_session now take &mut ChannelState
and advance cumulative_spent whenever the voucher reached the gateway:
on a non-2xx body, and on a lost response. A connect failure leaves the
channel untouched because nothing was sent. Trailing the gateway strands
the channel; leading it stays recoverable.

Also states the SQL increment rule without live-traffic values, drops
CLI flag wording from the X402_SQL_BASE_URL doc, removes get_schema from
the x402 host list (it reads the configured base and sends the API key),
and adds the SQL subheadings to the TOC.
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.

1 participant