quicknode-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/Cargo.lock

@@ -154,9 +154,9 @@ checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "bytes"
-version = "1.12.0"
+version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
@@ -1175,9 +1175,9 @@ dependencies = [
 
 [[package]]
 name = "memchr"
-version = "2.8.2"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "memoffset"
@@ -1684,7 +1684,7 @@ dependencies = [
 
 [[package]]
 name = "quicknode-sdk"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "bon",
  "config",
@@ -1870,9 +1870,9 @@ checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
 
 [[package]]
 name = "regex"
-version = "1.12.4"
+version = "1.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
+checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -1882,9 +1882,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.14"
+version = "0.4.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2159,7 +2159,7 @@ dependencies = [
 
 [[package]]
 name = "sdk-node"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "napi",
  "napi-build",
@@ -2171,7 +2171,7 @@ dependencies = [
 
 [[package]]
 name = "sdk-python"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "pyo3",
  "pyo3-async-runtimes",
@@ -2183,7 +2183,7 @@ dependencies = [
 
 [[package]]
 name = "sdk-python-stubs"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "pyo3-stub-gen",
  "sdk-python",
@@ -2191,7 +2191,7 @@ dependencies = [
 
 [[package]]
 name = "sdk-ruby"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "magnus",
  "quicknode-sdk",
@@ -3180,18 +3180,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.53"
+version = "0.8.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75726053136156d419e285b9b7eddaaea9e3fea6ce32eed44a89901f0bd98de1"
+checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.53"
+version = "0.8.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4714fd92cf900833d49538023a9b3915155210801d1c1169eba513b2addefd71"
+checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
 dependencies = [
  "proc-macro2",
  "quote",

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/core", "crates/python"]
 
 [workspace.package]
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 license = "MIT"
 

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quicknode-sdk
-Version: 0.6.0
+Version: 0.7.0
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: POSIX :: Linux
@@ -1698,6 +1698,55 @@ schema = await qn.sql.get_schema("hyperliquid-core-mainnet")
 print(len(schema.tables))
 ```
 
+---
+
+### RPC & Tooling Access
+
+Tooling Access provisions a single multichain, read-only endpoint per account and
+mints short-lived session JWTs. `qn.rpc` makes JSON-RPC calls directly against that
+endpoint, minting and refreshing the JWT automatically — no endpoint URL or token to
+manage.
+
+Tooling Access must be enabled once (admin role + eligible plan). The control-plane
+methods live on `qn.admin`:
+
+```python
+# Python
+status = await qn.admin.tooling_access_status()
+if not status.enabled:
+    await qn.admin.enable_tooling_access()  # idempotent; admin role required
+
+# Make on-chain calls. params defaults to []; pass a list (positional) or dict.
+block_number = await qn.rpc.call("eth_blockNumber")
+balance = await qn.rpc.call("eth_getBalance", ["0xabc...", "latest"])
+
+# Multichain: select a network by its multichain_urls key. Seed the map first
+# (from admin.get_endpoint_urls), then pass network=.
+urls = await qn.admin.get_endpoint_urls(endpoint_id)
+mc = urls.data.multichain_urls if urls.data else {}
+qn.rpc.set_networks({k: v.http_url for k, v in (mc or {}).items()})
+slot = await qn.rpc.call("getSlot", network="solana-mainnet")
+
+# Custom endpoint URL: send to a fully-formed HTTP URL, bypassing Tooling Access
+# and the JWT (no Authorization header). Per-call via endpoint_url=, or
+# client-wide via RpcConfig(endpoint_url=...). endpoint_url and network are
+# mutually exclusive (a custom URL is not multichain-routed).
+block = await qn.rpc.call("eth_blockNumber", endpoint_url="https://my-endpoint.example/rpc")
+
+# A JSON-RPC error member is raised as RpcError (with .code and .message).
+from quicknode_sdk import RpcError
+try:
+    await qn.rpc.call("eth_getBalance", ["bad"])
+except RpcError as e:
+    print(e.code, e.message)
+```
+
+A host that persists across processes can snapshot the cached token with
+`qn.rpc.current_token()` and re-seed it via `RpcConfig(seed=...)` on the next
+construction; `refresh_margin_secs` (default 60) tunes how early the token is
+refreshed. Set `RpcConfig(endpoint_url=...)` to route every call to a custom
+HTTP URL by default (no JWT minted); a per-call `endpoint_url` overrides it.
+
 ## Error Handling
 
 Every binding exposes a typed exception hierarchy derived from the core `SdkError`
@@ -1713,8 +1762,9 @@ subclass to branch on transport vs. API semantics.
 | `ConnectionError`    | connection refused / DNS / TLS (subclass of `HttpError`)    | —                    |
 | `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`    |
 
-Class names: Importable from `quicknode_sdk`: `QuicknodeError`, `ConfigError`, `HttpError`, `TimeoutError`, `ConnectionError`, `ApiError`, `DecodeError`.
+Class names: Importable from `quicknode_sdk`: `QuicknodeError`, `ConfigError`, `HttpError`, `TimeoutError`, `ConnectionError`, `ApiError`, `DecodeError`, `RpcError`.
 
 ```python
 # Python

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/crates/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "quicknode-sdk"
-version = "0.6.0"
+version = "0.7.0"
 edition.workspace = true
 license.workspace = true
 description = "Core library for quicknode sdk"
@@ -34,6 +34,10 @@ bon = { version = "3.9", optional = true }
 config = "0.15"
 url = "2.5.8"
 secrecy = "0.8"
+# sync-only: provides tokio::sync::Mutex for single-flight JWT refresh in the
+# rpc client without pulling in the tokio runtime. The async runtime itself is
+# supplied by the caller (bindings or the user's own runtime).
+tokio = { version = "1", default-features = false, features = ["sync"] }
 
 [[example]]
 name = "admin"
@@ -55,6 +59,10 @@ required-features = ["rust"]
 name = "webhooks_e2e"
 required-features = ["rust"]
 
+[[example]]
+name = "rpc"
+required-features = ["rust"]
+
 [dev-dependencies]
 tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }
 wiremock = "0.6"

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/crates/core/README.md

@@ -1760,6 +1760,67 @@ let schema = qn.sql.get_schema("hyperliquid-core-mainnet").await?;
 println!("{} tables", schema.tables.len());
 ```
 
+---
+
+### RPC & Tooling Access
+
+Tooling Access provisions a single multichain, read-only endpoint per account and
+mints short-lived session JWTs. `qn.rpc` makes JSON-RPC calls directly against that
+endpoint, minting and refreshing the JWT automatically — no endpoint URL or token to
+manage.
+
+Tooling Access must be enabled once (admin role + eligible plan). The control-plane
+methods live on `qn.admin`:
+
+```rust
+// Rust
+let status = qn.admin.tooling_access_status().await?;
+if !status.enabled {
+    qn.admin.enable_tooling_access().await?; // idempotent; admin role required
+}
+
+// call(method, params, network, endpoint_url). params is Option<serde_json::Value>;
+// None defaults to []. Both trailing args are Option and independently omittable.
+let block_number = qn.rpc.call("eth_blockNumber", None, None, None).await?;
+let balance = qn
+    .rpc
+    .call(
+        "eth_getBalance",
+        Some(serde_json::json!(["0xabc...", "latest"])),
+        None,
+        None,
+    )
+    .await?;
+
+// Multichain: seed the per-network URL map (from get_endpoint_urls), then pass
+// the network key as the third arg.
+let urls = qn.admin.get_endpoint_urls(endpoint_id).await?;
+if let Some(data) = urls.data {
+    if let Some(mc) = data.multichain_urls {
+        qn.rpc
+            .set_networks(mc.into_iter().map(|(k, v)| (k, v.http_url)).collect());
+    }
+}
+let slot = qn.rpc.call("getSlot", None, Some("solana-mainnet".into()), None).await?;
+
+// Custom endpoint URL: send to a fully-formed HTTP URL, bypassing Tooling Access
+// and the JWT (no Authorization header). Per-call via the 4th arg, or client-wide
+// via RpcConfig { endpoint_url, .. }. endpoint_url and network are mutually
+// exclusive (a custom URL is not multichain-routed).
+let block = qn
+    .rpc
+    .call("eth_blockNumber", None, None, Some("https://my-endpoint.example/rpc".into()))
+    .await?;
+
+// A JSON-RPC error member is returned as SdkError::Rpc { code, message }.
+```
+
+A host that persists across processes can snapshot the cached token with
+`qn.rpc.current_token()` and re-seed it via `RpcConfig { seed, .. }`;
+`refresh_margin_secs` (default 60) tunes how early the token is refreshed. Set
+`RpcConfig { endpoint_url, .. }` to route every call to a custom HTTP URL by
+default (no JWT minted); a per-call `endpoint_url` overrides it.
+
 ## Error Handling
 
 Every binding exposes a typed exception hierarchy derived from the core `SdkError`
@@ -1775,8 +1836,9 @@ subclass to branch on transport vs. API semantics.
 | `ConnectionError`    | connection refused / DNS / TLS (subclass of `HttpError`)    | —                    |
 | `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`    |
 
-Variants: pattern-match on `SdkError { Http, Api, Decode, UrlParse, Config }`; use `err.http_kind()` to classify `Http` into `Timeout`, `Connect`, or `Other`.
+Variants: pattern-match on `SdkError { Http, Api, Decode, UrlParse, Config, Rpc }`; use `err.http_kind()` to classify `Http` into `Timeout`, `Connect`, or `Other`.
 
 ```rust
 // Rust

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/crates/core/examples/admin_e2e.rs

@@ -874,6 +874,7 @@ async fn main() {
         webhooks: None,
         kvstore: None,
         sql: None,
+        rpc: None,
     };
     let headered = QuicknodeSdk::new(&with_headers).expect("build sdk with custom headers");
     match headered
@@ -900,6 +901,8 @@ async fn main() {
         streams: None,
         webhooks: None,
         kvstore: None,
+        sql: None,
+        rpc: None,
     };
     let tiny = QuicknodeSdk::new(&blackhole).expect("build tiny sdk");
     match tiny

quicknode_sdk-0.7.0/crates/core/examples/rpc.rs

@@ -0,0 +1,83 @@
+use quicknode_sdk::{errors::SdkError, QuicknodeSdk, SdkFullConfig};
+
+#[tokio::main]
+#[allow(clippy::unwrap_used, clippy::expect_used)]
+async fn main() {
+    let config = SdkFullConfig::from_env().expect("Config from env failed");
+    let qn = QuicknodeSdk::new(&config).expect("sdk failed to initialize");
+
+    // Ensure Tooling Access is provisioned (idempotent; requires admin role).
+    let status = qn
+        .admin
+        .tooling_access_status()
+        .await
+        .expect("tooling_access_status failed");
+    println!("tooling access enabled: {}", status.enabled);
+    if !status.enabled {
+        match qn.admin.enable_tooling_access().await {
+            Ok(s) => println!("enabled tooling access: {}", s.enabled),
+            Err(e) => {
+                eprintln!("could not enable tooling access: {e}");
+                return;
+            }
+        }
+    }
+
+    // Make a JSON-RPC call. The SDK mints and refreshes the session JWT.
+    match qn.rpc.call("eth_blockNumber", None, None, None).await {
+        Ok(result) => println!("eth_blockNumber => {result}"),
+        Err(e) => eprintln!("rpc call error: {e}"),
+    }
+
+    // Multichain: seed the per-network URL map from the endpoint id (returned by
+    // status), then route a call to a specific network by its key.
+    if let Some(id) = &status.endpoint_id {
+        if let Ok(urls) = qn.admin.get_endpoint_urls(id).await {
+            if let Some(mc) = urls.data.and_then(|d| d.multichain_urls) {
+                qn.rpc
+                    .set_networks(mc.into_iter().map(|(k, v)| (k, v.http_url)).collect());
+                match qn
+                    .rpc
+                    .call("getSlot", None, Some("solana-mainnet".to_string()), None)
+                    .await
+                {
+                    Ok(result) => println!("solana getSlot => {result}"),
+                    Err(e) => eprintln!("solana rpc error: {e}"),
+                }
+            }
+        }
+    }
+
+    // Demonstrate the typed JSON-RPC error path.
+    match qn
+        .rpc
+        .call(
+            "eth_getBalance",
+            Some(serde_json::json!(["not-an-address"])),
+            None,
+            None,
+        )
+        .await
+    {
+        Ok(result) => println!("unexpected ok: {result}"),
+        Err(SdkError::Rpc { code, message }) => {
+            println!("got expected RpcError: code={code} message={message}");
+        }
+        Err(e) => eprintln!("other error: {e}"),
+    }
+
+    // Custom endpoint URL: send a call to a fully-formed HTTP URL, bypassing the
+    // Tooling Access endpoint and the session JWT entirely. Useful for a
+    // provisioned `.quiknode.pro` URL or a self-hosted node. Set it per-call
+    // here, or client-wide via `RpcConfig::endpoint_url`.
+    if let Ok(custom_url) = std::env::var("QN_RPC_ENDPOINT_URL") {
+        match qn
+            .rpc
+            .call("eth_blockNumber", None, None, Some(custom_url))
+            .await
+        {
+            Ok(result) => println!("custom endpoint eth_blockNumber => {result}"),
+            Err(e) => eprintln!("custom endpoint rpc error: {e}"),
+        }
+    }
+}

{quicknode_sdk-0.6.0 → quicknode_sdk-0.7.0}/crates/core/src/admin/mod.rs

@@ -11,6 +11,7 @@ pub mod endpoints;
 pub mod logs;
 pub mod tags;
 pub mod teams;
+pub mod tooling_access;
 pub mod usage;
 
 pub use account::{AccountInfo, AccountInfoResponse, AccountSubscription};
@@ -66,6 +67,7 @@ pub use teams::{
     TeamDetail, TeamEndpoint, TeamMessageData, TeamSummary, TeamUser, UpdateTeamEndpointsData,
     UpdateTeamEndpointsRequest, UpdateTeamEndpointsResponse,
 };
+pub use tooling_access::ToolingAccessStatus;
 
 pub use usage::{
     ChainUsage, EndpointUsage, GetUsageByChainResponse, GetUsageByEndpointResponse,
@@ -1957,6 +1959,7 @@ mod tests {
             webhooks: None,
             kvstore: None,
             sql: None,
+            rpc: None,
         })
         .unwrap()
     }
@@ -3847,6 +3850,7 @@ mod tests {
             webhooks: None,
             kvstore: None,
             sql: None,
+            rpc: None,
         });
         assert!(matches!(result, Err(crate::errors::SdkError::Config(_))));
     }