quicknode_sdk 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e3ff0b06165dc1014255f5cb518cc2fe4cebc2a77aaf689cc52aac5638951b7
-  data.tar.gz: edd43ef70ecb2948887ed7cb9668ec4e19eb325bcf0d2ace387dc8007a239724
+  metadata.gz: 2afee73b31e4a4f431a7ab86b558494e0ceeb517e8d9d63e7d1aa3c9a14ee6b3
+  data.tar.gz: 92170453b26ae7adaeded2f165c8af400f5b4069f8bfd6f3aa2b01db352433ac
 SHA512:
-  metadata.gz: 33cac6ddae2a468b0b721e91124846c9dd5d0bc9c1a907e43ec4d7833d34715603427bbfb11b6ab20c0a4b4f9bd163a220b97e3b0d14a8cf9db29c59de439626
-  data.tar.gz: 87e8aac27445983d1fc63ece74ae63929bd92dcbfcb0df155fc377d75f839397b4eb9843d341c233f43cdda77464af72313cdbdf856bebd2d10edd54ec021fd7
+  metadata.gz: 9203bd871fed1d37968af3a7fec28b806ea1b71031fce35ede41046fa6b3ee8ece3ab437af56e9e26c5122ecb008a0d8492042a076e9b0c3b2bcd5e7364dca25
+  data.tar.gz: 7992a01650e089989aefbf02763b3148109dc236651dec8d42d9018bba525296c9ab655e34cdfe65f7c7bd20cf4c470dd2127dd3715ae565d174056c3597366c

data/README.md

@@ -11,8 +11,12 @@ This is one of four language bindings published from the same Rust core. See the
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+  - [Option A — Pass config directly](#option-a--pass-config-directly)
+  - [Option B — Load from environment (`from_env()`)](#option-b--load-from-environment-from_env)
+  - [Custom headers and `User-Agent`](#custom-headers-and-user-agent)
 - [Platform Support](#platform-support)
 - [API Reference](#api-reference)
+  - [Language conventions](#language-conventions)
   - [Admin Client](#admin-client)
     - [Endpoints](#endpoints)
     - [Endpoint Tags](#endpoint-tags)
@@ -38,6 +42,7 @@ This is one of four language bindings published from the same Rust core. See the
     - [Billing](#billing)
     - [Bulk Operations](#bulk-operations)
     - [Account Tags](#account-tags)
+    - [Tag / delete method parameter quick-reference](#tag--delete-method-parameter-quick-reference)
   - [Streams Client](#streams-client)
     - [Datasets, Regions, and Destinations](#datasets-regions-and-destinations)
     - [Streams methods](#streams-methods)
@@ -48,6 +53,12 @@ This is one of four language bindings published from the same Rust core. See the
     - [Sets](#sets)
     - [Lists](#lists)
   - [SQL Client](#sql-client)
+  - [RPC & Tooling Access](#rpc--tooling-access)
+- [Crypto-micropayment lane (`rpc.call`)](#crypto-micropayment-lane-rpccall)
+  - [Wallet generation](#wallet-generation)
+  - [x402 credit drawdown (authenticate once, then draw one credit per call)](#x402-credit-drawdown-authenticate-once-then-draw-one-credit-per-call)
+    - [Testnet faucet](#testnet-faucet)
+  - [MPP payment channel (deposit once, then vouchers)](#mpp-payment-channel-deposit-once-then-vouchers)
 - [Error Handling](#error-handling)
 - [License](#license)
 
@@ -76,6 +87,10 @@ There are two ways to configure the SDK.
 
 ```ruby
 qn = QuicknodeSdk::SDK.from_config(api_key: "your-key")
+
+# api_key is optional: the crypto-micropayment lane pays per request instead, so
+# api_key: nil builds a usable SDK. Every other client still needs one, and
+# from_env always requires QN_SDK__API_KEY.
 ```
 
 ### Option B — Load from environment (`from_env()`)
@@ -1730,6 +1745,169 @@ re-seed it via the `rpc: { seed: ... }` config key; `refresh_margin_secs` (defau
 tunes how early the token is refreshed. Set `rpc: { endpoint_url: ... }` to route every
 call to a custom HTTP URL by default (no JWT minted); a per-call `endpoint_url` overrides it.
 
+## Crypto-micropayment lane (`rpc.call`)
+
+Pay per RPC request with a stablecoin instead of a provisioned account + API key,
+against Quicknode's `x402.quicknode.com` and `mpp.quicknode.com` gateways. Configure
+it by setting `payment` on the RPC config; the SDK runs the `402` → sign → resend
+handshake for you. An API key is **not** required for this lane — build a keyless SDK.
+
+There are four payment paths. Two pay per request; two amortize one signature over many
+calls.
+
+| Path | Entry point | Gateway | Signs |
+|---|---|---|---|
+| Per-request x402 | `call` / `call_with_receipt` with `scheme: "x402"` | x402 | once per call |
+| Per-request MPP charge | `call` / `call_with_receipt` with `scheme: "mpp"` | mpp | once per call |
+| [x402 credit drawdown](#x402-credit-drawdown-authenticate-once-then-draw-one-credit-per-call) | `gateway_authenticate` → `gateway_drawdown_call` | x402 | once per session |
+| [MPP payment channel](#mpp-payment-channel-deposit-once-then-vouchers) | `mpp_open` → `mpp_session_call` | mpp | once per channel |
+
+The signer construction is derived from the scheme and pay network, never stated directly:
+**x402/EVM** signs an EIP-712 `TransferWithAuthorization`, **x402/Solana** an SPL
+`TransferChecked` in a v0 tx (the gateway sponsors gas), and **MPP/Tempo** a native Tempo
+transaction.
+
+`scheme` selects the gateway for `call` only. The `gateway_*` drawdown methods always use
+the x402 gateway and the `mpp_*` channel methods always use the MPP gateway, whatever
+`scheme` is set to.
+
+`PaymentConfig` fields:
+
+| Field | Meaning |
+|---|---|
+| `scheme` | `"x402"` (pay-per-request) or `"mpp"` (MPP charge; `"mpp-charge"` is accepted too) |
+| `key` | raw private key — EVM/Tempo: hex; Solana: base58 64-byte secret |
+| `pay_network` | CAIP-2 pay network, e.g. `eip155:84532`, `solana:5eykt4…` |
+| `asset` | token address/mint to pay in (matches the offered menu entry) |
+| `max_amount` | **required** spend ceiling in integer base units of `asset` |
+| `svm_rpc_url` | optional Solana RPC for x402/Solana payment-build reads (mint + blockhash) |
+| `base_url_override` | optional gateway base (testing) |
+
+`network` on the call is the **query** chain (gateway path slug), independent of the
+pay network. Use `call_with_receipt` to also get the settlement receipt (`reference` =
+settlement tx hash) — populated on the MPP lane, `null`/`None`/`nil` for x402.
+
+**Things to know:**
+
+- **Do not log your own `PaymentConfig`** — the `key` field is readable. The SDK
+  never prints it in its own errors/`Debug`, but a plain `p config` will show it.
+- **`max_amount` is integer base units of the selected asset.** The SDK skips any offered
+  entry above it and refuses to sign one — a guard against an overcharging gateway.
+- **`PaymentIndeterminateError` means the paid request was sent but the response was lost.**
+  You MAY have been charged — do **not** blindly retry.
+- **x402/Solana: one payment per call.** Building a payment reads the mint and a recent
+  blockhash from a Solana RPC. The default is a public RPC that **rate-limits
+  aggressively** — set `svm_rpc_url` to your own endpoint at any volume.
+
+```ruby
+sdk = QuicknodeSdk::SDK.from_config(
+  api_key: nil,
+  rpc: {
+    payment: {
+      scheme: "x402",
+      key: ENV.fetch("QN_PAYMENT_KEY"),
+      pay_network: "eip155:84532",
+      asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+      max_amount: "10000"
+    }
+  }
+)
+resp = sdk.rpc.call_with_receipt(method: "eth_blockNumber", params: [], network: "base-sepolia")
+puts resp["result"]
+```
+
+### Wallet generation
+
+`QuicknodeSdk.generate_payment_wallet(chain: "evm")` creates a fresh keypair offline — no network call, no funds — for
+`"evm"`, `"svm"`, or `"tempo"`. The private key is returned **exactly once**, at
+generation; nothing in the SDK stores or re-derives it, so persist it immediately.
+
+```ruby
+wallet = QuicknodeSdk.generate_payment_wallet(chain: "evm")
+puts "fund this address: #{wallet[:address]}"
+File.write("payment.key", wallet[:key])  # returned exactly once
+```
+
+### x402 credit drawdown (authenticate once, then draw one credit per call)
+
+Cheaper per call than paying per request: one SIWE signature mints a session JWT, then
+each call draws a single credit from the account balance instead of signing a fresh
+settlement. Minting the session is free and moves no funds, so a host can re-authenticate
+transparently. Persist it between processes.
+
+Fund the payment wallet out of band — the testnet faucet below, or by sending funds to
+`payment_address` directly. Credits are provisioned against the account gateway-side.
+
+EVM signers only: SIWE is an EIP-4361 construction, so an x402/Solana key errors here.
+
+| Method | Cost | Returns |
+|---|---|---|
+| `payment_address` | free, offline | the wallet address derived from the key |
+| `gateway_authenticate` | free | a Hash `{token:, exp_unix:, account_id:}` |
+| `gateway_credits(session:)` | free | a Hash `{account_id:, credits:}` |
+| `gateway_drip(session:)` | free (testnet) | a Hash `{account_id:, transaction_hash:}` |
+| `gateway_drawdown_call(method:, session:, network:, params:)` | 1 credit | the JSON-RPC `result` |
+
+```ruby
+session = sdk.rpc.gateway_authenticate
+balance = sdk.rpc.gateway_credits(session: session)
+puts "credits: #{balance[:credits]}"
+result = sdk.rpc.gateway_drawdown_call(
+  method: "eth_blockNumber", session: session, network: "base-sepolia"
+)
+```
+
+A `token_expired` surfaces as an `ApiError` with status 401/403; re-authenticate and retry
+that call.
+
+#### Testnet faucet
+
+`gateway_drip` requests testnet tokens for the payment **wallet** on Base Sepolia. The
+gateway allows one drip per account, and it returns the on-chain funding transaction hash
+— not a credit balance.
+
+### MPP payment channel (deposit once, then vouchers)
+
+Open a payment channel by depositing into the escrow, then authorize each call with a
+cumulative voucher — one `ecrecover` server-side, no on-chain transaction per call.
+
+| Method | Cost | Returns |
+|---|---|---|
+| `mpp_open(deposit:)` | **moves funds** | the channel state Hash |
+| `mpp_top_up(channel:, additional_deposit:)` | **moves funds** | the updated channel state |
+| `mpp_status(channel:)` | **1 request unit** | a Hash `{channel_id:, accepted_cumulative:, spent:}` |
+| `mpp_session_call(method:, network:, channel:, new_cumulative:, params:)` | 1 request unit | the JSON-RPC `result` |
+| `mpp_close(channel:)` | settles on-chain | nothing — refunds the unused deposit |
+
+```ruby
+channel = sdk.rpc.mpp_open(deposit: "1000000")    # persist this Hash
+new_total = (channel[:cumulative_spent].to_i + channel[:per_call].to_i).to_s
+result = sdk.rpc.mpp_session_call(
+  method: "eth_blockNumber", network: "base-sepolia",
+  channel: channel, new_cumulative: new_total
+)
+# On success, store new_total as the channel's cumulative_spent.
+```
+
+**Things to know:**
+
+- **Persist the channel state.** The gateway exposes no read-only channel endpoint, so a
+  lost local record means opening (and funding) a new channel.
+- **`mpp_status` is not free.** The gateway prices every session POST as a chargeable
+  request and computes the balance from the *new* spend a voucher authorizes, so the
+  probe advances `cumulative_spent` by `per_call` exactly like a call. Re-persist the
+  advanced total. It raises `PaymentUnsupportedError` before any network I/O when the
+  channel has no room left for the probe.
+- **The lifecycle takes no query network.** A channel is scoped by the configured pay
+  network and asset, so one channel funds calls to every supported network. Only
+  `mpp_session_call` takes a network, because it routes an RPC method.
+- **Amounts are decimal strings, not numbers.** They are `u128` in the core; magnus has no `u128` conversion, so pass and store them as Strings.
+- **Advance `cumulative_spent` only after a success.** A voucher authorizes the running total
+  *after* the call; re-presenting the current high-water mark authorizes zero and is
+  always refused with `insufficient-balance`.
+
+
+
 ## Error Handling
 
 Every binding exposes a typed exception hierarchy derived from the core `SdkError`
@@ -1746,8 +1924,12 @@ subclass to branch on transport vs. API semantics.
 | `ApiError`           | non-2xx HTTP response                                       | `status`, `body`     |
 | `DecodeError`        | 2xx response but JSON parse failed                          | `body`               |
 | `RpcError`           | JSON-RPC call returned an `error` member                    | `code`, `message`    |
+| `PaymentError`       | base class for the crypto-micropayment lane                 | —                    |
+| `PaymentUnsupportedError` | no offered payment option matched your selector (or all were over `max_amount`/unsupported) | — |
+| `PaymentRejectedError` | the gateway rejected a signed payment (terminal, one resend only) | `status`, `body` |
+| `PaymentIndeterminateError` | paid request sent but response lost — MAY have been charged; do NOT blindly retry | — |
 
-Class names: `QuicknodeSdk::Error`, `QuicknodeSdk::ConfigError`, `QuicknodeSdk::HttpError`, `QuicknodeSdk::TimeoutError`, `QuicknodeSdk::ConnectionError`, `QuicknodeSdk::ApiError`, `QuicknodeSdk::DecodeError`, `QuicknodeSdk::RpcError`. All extend `StandardError`. Hash-key validation still raises `ArgumentError`.
+Class names: `QuicknodeSdk::Error`, `QuicknodeSdk::ConfigError`, `QuicknodeSdk::HttpError`, `QuicknodeSdk::TimeoutError`, `QuicknodeSdk::ConnectionError`, `QuicknodeSdk::ApiError`, `QuicknodeSdk::DecodeError`, `QuicknodeSdk::RpcError`, `QuicknodeSdk::PaymentError`, `QuicknodeSdk::PaymentUnsupportedError`, `QuicknodeSdk::PaymentRejectedError`, `QuicknodeSdk::PaymentIndeterminateError`. All extend `StandardError`. Hash-key validation still raises `ArgumentError`.
 
 ```ruby
 # Ruby

data/lib/quicknode_sdk.rb

@@ -16,3 +16,15 @@ require_relative "quicknode_sdk/clients/kvstore"
 require_relative "quicknode_sdk/clients/sql"
 require_relative "quicknode_sdk/clients/rpc"
 require_relative "quicknode_sdk/sdk"
+
+module QuicknodeSdk
+  # Generates a fresh payment keypair for :evm, :svm, or :tempo. Offline — no
+  # network call, no funds. Returns {address:, chain:, key:}; `key` is the raw
+  # private key in the format the payment config's key: accepts.
+  #
+  # The key is returned exactly once, at generation: nothing in the SDK stores
+  # or re-derives it, so persist it before discarding the Hash.
+  def self.generate_payment_wallet(**opts)
+    wrap(Native.generate_payment_wallet(opts))
+  end
+end

data/sig/quicknode_sdk.rbs

@@ -1,6 +1,11 @@
 module QuicknodeSdk
   def self.wrap: (untyped v) -> untyped
 
+  # Generates a fresh payment keypair for "evm", "svm", or "tempo". Offline: no
+  # network call. Returns {address:, chain:, key:} — `key` is the raw private
+  # key, returned exactly once at generation.
+  def self.generate_payment_wallet: (chain: String) -> untyped
+
   class Error < StandardError
   end
 
@@ -30,6 +35,35 @@ module QuicknodeSdk
     attr_reader message: String
   end
 
+  # Payment-lane errors. PaymentIndeterminateError means the paid request was
+  # sent but its response was lost — do not retry (may have been charged).
+  class PaymentError < Error
+  end
+
+  class PaymentUnsupportedError < PaymentError
+  end
+
+  class PaymentRejectedError < PaymentError
+    attr_reader status: Integer
+    attr_reader body: String
+  end
+
+  class PaymentIndeterminateError < PaymentError
+  end
+
+  # The `rpc: {payment: {...}}` sub-hash accepted by SDK.from_config. An alias
+  # rather than a class because the config crosses the boundary as a plain
+  # Hash, not a wrapper object.
+  type payment_config = {
+    scheme: String,
+    key: String,
+    pay_network: String,
+    asset: String,
+    max_amount: String,
+    ?svm_rpc_url: String,
+    ?base_url_override: String
+  }
+
   class SDK
     def self.from_env: () -> SDK
     def self.from_config: (Hash[Symbol | String, untyped] opts) -> SDK
@@ -183,8 +217,25 @@ module QuicknodeSdk
     def initialize: (untyped native) -> void
 
     def call: (method: String, ?params: untyped, ?network: String, ?endpoint_url: String) -> untyped
+    def call_with_receipt: (method: String, ?params: untyped, ?network: String, ?endpoint_url: String) -> untyped
     def set_networks: (networks: Hash[String, String]) -> void
     def clear_cached_token: () -> void
     def current_token: () -> untyped
+
+    # Payment lanes. Base-unit amounts are decimal Strings, not Integers: they
+    # are u128 in the core and magnus has no u128 conversion. `session` and
+    # `channel` are the Hashes returned by gateway_authenticate and
+    # mpp_open/mpp_top_up — persist them and hand them straight back.
+    def payment_address: () -> String
+    def gateway_authenticate: () -> untyped
+    def gateway_credits: (session: untyped) -> untyped
+    def gateway_buy_credits: (session: untyped, network: String) -> untyped
+    def gateway_drip: (session: untyped) -> untyped
+    def gateway_drawdown_call: (method: String, session: untyped, network: String, ?params: untyped) -> untyped
+    def mpp_open: (deposit: String) -> untyped
+    def mpp_top_up: (channel: untyped, additional_deposit: String) -> untyped
+    def mpp_close: (channel: untyped) -> void
+    def mpp_status: (channel: untyped) -> untyped
+    def mpp_session_call: (method: String, network: String, channel: untyped, new_cumulative: String, ?params: untyped) -> untyped
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quicknode_sdk
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Quicknode
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie