solana_client_wasip2/lib.rs
1//! # solana-client-wasip2
2//!
3//! A Solana **JSON-RPC client** for **WebAssembly components** (`wasm32-wasip2`).
4//! The official `solana-client` / `solana-sdk` stack does not build for that
5//! target — it pulls in `reqwest`/`tokio` and other host-only machinery. This
6//! crate provides the piece with no upstream equivalent there: a JSON-RPC client
7//! that speaks over the host's `wasi:http`, returning Anza's official RPC types.
8//!
9//! It was written for [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)
10//! tool plugins, where TLS and the socket are provided by the host's
11//! `wasi:http` and the guest only speaks HTTP.
12//!
13//! ## What it does
14//!
15//! - **Query** the chain — the full JSON-RPC method surface ([`rpc`]).
16//! - **Submit & confirm** — [`send_and_confirm_transaction`] and the
17//! confirmation pollers, with automatic retry/backoff on transient failures,
18//! a configurable transport timeout, and a client-level default commitment.
19//!
20//! Building and signing transactions is out of scope — see below. This crate
21//! never signs.
22//!
23//! [`send_and_confirm_transaction`]: rpc::client::RpcClient::send_and_confirm_transaction
24//!
25//! ## How the RPC client fits together
26//!
27//! ```text
28//! caller ── RpcClient::get_balance(..) (rpc::methods)
29//! │ builds params, picks a method name
30//! ▼
31//! RpcClient dispatch + retry (rpc::client) ← the engine
32//! │ frames the JSON-RPC request, sequences ids,
33//! │ extracts `result` / surfaces `error`, deserializes
34//! ▼
35//! RpcTransport::post(url, body) (transport) ← the seam
36//! ├─ WakiTransport → wasi:http (only on wasm targets)
37//! └─ MockTransport → canned reply (host tests)
38//! ```
39//!
40//! ## Building a transaction
41//!
42//! This crate is an RPC client; it does not build or sign transactions. The
43//! upstream SDK crates do that, and they compile for `wasm32-wasip2`, so add the
44//! ones you need directly (they are ordinary dependencies you own and version):
45//!
46//! ```toml
47//! solana-system-interface = { version = "3", features = ["bincode"] } # transfer, etc.
48//! solana-keypair = "3" # signing keys
49//! solana-signer = "3"
50//! spl-token-interface = "3" # SPL builders
51//! ```
52//!
53//! Compile a v0 [`message`], sign into a
54//! [`VersionedTransaction`](transaction::versioned::VersionedTransaction), and
55//! hand it to [`RpcClient::send_transaction`] — which takes the typed
56//! transaction and serializes it internally, so the caller needs no `bincode`.
57//! Building an *unsigned* transaction (to propose for external signing) needs no
58//! key: construct a `VersionedTransaction` with default signature placeholders.
59//! The `message` and `transaction` types the RPC methods speak are re-exported
60//! here (see below) so they match versions with no effort.
61//!
62//! ## Module map
63//!
64//! The RPC client (this crate's own code):
65//! - [`transport`] — the [`RpcTransport`] trait and its two implementations.
66//! - [`rpc::client`] — [`RpcClient`], the transport-agnostic JSON-RPC engine.
67//! - [`rpc::methods`] — the JSON-RPC method surface, thin wrappers over the engine.
68//! - [`rpc::config`] / [`rpc::response`] — request and response types.
69//! - [`error`] — the [`Error`] taxonomy.
70//!
71//! The upstream types that appear in method signatures, re-exported under their
72//! conventional names so callers can name them without version-matching:
73//! [`pubkey`], [`hash`], [`signature`], [`message`], [`transaction`],
74//! [`commitment_config`].
75//!
76//! A separate `tests/rpc_coverage.rs` diffs our method list against Anza's
77//! canonical `RpcRequest` enum, so a newly-added upstream method fails the build
78//! until it is implemented or explicitly skipped.
79
80pub mod error;
81pub mod rpc;
82pub mod transport;
83
84// ---- Upstream types that appear in this client's method signatures, re-exported
85// under their conventional ecosystem names so a caller can name what the RPC
86// methods accept and return — a `Pubkey` argument, a returned `Hash`/`Signature`,
87// a `VersionedTransaction`/`VersionedMessage` to submit — without matching the
88// exact upstream release themselves. Verbatim re-exports: no wrappers, no renamed
89// types. Transaction-building crates are not re-exported; add those you need
90// directly (see the crate docs).
91
92/// `solana-pubkey` — addresses and PDA derivation.
93pub mod pubkey {
94 pub use solana_pubkey::*;
95}
96/// `solana-hash` — 32-byte hashes / blockhashes.
97pub mod hash {
98 pub use solana_hash::*;
99}
100/// `solana-signature` — transaction signatures.
101pub mod signature {
102 pub use solana_signature::*;
103}
104/// `solana-message` — legacy and v0 messages (the input to `get_fee_for_message`).
105pub mod message {
106 pub use solana_message::*;
107}
108/// `solana-transaction` — legacy and versioned transactions (the input to
109/// `send_transaction` / `simulate_transaction`).
110pub mod transaction {
111 pub use solana_transaction::*;
112}
113/// `solana-commitment-config` — commitment levels.
114pub mod commitment_config {
115 pub use solana_commitment_config::*;
116}
117
118// `CommitmentConfig` / `CommitmentLevel` appear in RPC method signatures, so they
119// are also surfaced at the crate root for convenience.
120pub use solana_commitment_config::{CommitmentConfig, CommitmentLevel};
121
122// Flatten the RPC layer for callers: `solana_client_wasip2::RpcClient` etc.
123pub use error::*;
124pub use rpc::*;
125pub use transport::*;