Expand crate docs, add examples, and LLM-friendly docs by dkijania · Pull Request #11 · MinaProtocol/mina-sdk-rust

dkijania · 2026-04-16T22:29:39Z

Summary

Include examples and unit tests in the published crate (commit a3c0e3b on this branch)
Expand lib.rs rustdoc with Features, Custom Configuration, Currency, Error Handling, and API Overview sections
Add 6 runnable examples: send_payment, stake_delegation, node_monitoring, custom_query, error_handling, currency_operations
Add llms.txt / llms-full.txt for LLM consumers
Cargo.toml: add web3 keyword, cryptography::cryptocurrencies category, and [package.metadata.docs.rs] block
README: document the available examples and the llms.txt files

Test plan

cargo build --examples — all examples compile
cargo test --doc — 6 doc tests pass
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps — clean, no broken intra-doc links

🤖 Generated with Claude Code

- Enrich lib.rs rustdoc with Features, Custom Configuration, Currency, Error Handling, and API Overview sections (6 doc tests pass) - Add 6 runnable examples: send_payment, stake_delegation, node_monitoring, custom_query, error_handling, currency_operations - Add llms.txt / llms-full.txt for LLM consumers - Cargo.toml: add web3 keyword, cryptography::cryptocurrencies category, docs.rs metadata block - README: document available examples and llms.txt files Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

master introduced a fluent builder API for send_payment/send_delegation; the new examples still used the old positional-args signature. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Add a "Run examples" step in integration.yml that loops over every example and runs `cargo run --example` against the lightnet daemon, so we catch runtime regressions — not just compile errors. - Examples that need real unlocked accounts (basic_usage, send_payment, stake_delegation) now read MINA_TEST_SENDER_KEY / MINA_TEST_RECEIVER_KEY from env and short-circuit cleanly when unset. Keeps them usable as standalone docs and runnable in CI with acquired keys. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dkijania · 2026-04-17T10:56:56Z

-            println!("Nonce: {}", account.nonce);
+    // Query an account. Set MINA_TEST_SENDER_KEY to a valid public key to run;
+    // otherwise skip this section.
+    if let Ok(public_key) = std::env::var("MINA_TEST_SENDER_KEY") {


remove that nesting also show example format of this key

Flattened to a let-else early return and added a real B62q… key in the comment so readers see the format. Fixed in a7e157d.

dkijania · 2026-04-17T10:58:28Z

+    println!("Node version: {}", data["version"]);
+
+    // Example 2: Query with variables
+    let query = r#"query ($maxLength: Int) {


Shouldn't this query be in sdk? That's the very purpose of this project to encapsulate those graphql calls

Agreed — bestChain is already wrapped by get_best_chain, so this demo was misleading. Replaced with genesisConstants (genuinely not in the SDK) plus a variables-based pooledUserCommands example. Fixed in a7e157d.

dkijania · 2026-04-17T11:05:37Z

+
+    if let Some(chain) = data["bestChain"].as_array() {
+        for block in chain {
+            let consensus = &block["protocolState"]["consensusState"];


Why not produce nice wrapper around block? and consensus too , user should not be force to use response as array

Resolved by dropping the raw bestChain demo entirely — the SDK's typed get_best_chain returns Vec<BlockInfo>. The example now uses genesisConstants, which returns scalar fields (coinbase, genesisTimestamp), so no array-indexing gymnastics. Fixed in a7e157d.

dkijania · 2026-04-17T11:06:37Z

+
+    // Example 3: The built-in query constants are also available
+    let data = client
+        .execute_query(mina_sdk::queries::DAEMON_STATUS, None, "daemon_status")


It's good to have execute_query but all others parameters should be names . maybe builder type (I already forgot what argument None is referring to

Added a MinaClient::query("...") builder that returns QueryBuilder with opt-in .variables(json) and .name("…") — no more bare None. The low-level execute_query stays so existing downstream crates (mina-perf-testing) don't break. Fixed in a7e157d.

dkijania · 2026-04-17T11:07:47Z

+
+#[tokio::main]
+async fn main() {
+    let client = MinaClient::new("http://127.0.0.1:3085/graphql");


Maybe let's introduce default() for this and it will automatically connect to this url ? also some helper method like from URI or inet or host_and_port() erc

Added impl Default for MinaClient (connects to http://127.0.0.1:3085/graphql with default retries/timeout) and MinaClient::from_host_and_port(host, port). All examples now use MinaClient::default(). Fixed in a7e157d.

dkijania · 2026-04-17T11:11:32Z

+    // Set MINA_TEST_SENDER_KEY to an unlocked account and MINA_TEST_RECEIVER_KEY
+    // to any account to run. Without them, this example short-circuits.
+    let (Ok(sender), Ok(receiver)) = (
+        std::env::var("MINA_TEST_SENDER_KEY"),


Document what those variables are , how to generated them etc.

Added a doc section at the top of the example explaining both env vars, what a B62q… key looks like, and two ways to generate/unlock one (mina advanced generate-keypair for a fresh key, or curl …/acquire-account?unlockAccount=true on a lightnet node). Fixed in a7e157d.

dkijania · 2026-04-17T11:12:50Z

+
+    // Send with an explicit nonce (useful for sending multiple transactions)
+    let result2 = client
+        .send_payment(


I think it would be more clear would be in this example to first define paymnet and then pass it to .send_payment()

Refactored to build the Payment as a named variable first, then pass it to client.send_payment(payment).await?. Same pattern applied to stake_delegation. Fixed in a7e157d.

dkijania · 2026-04-17T11:13:48Z

@@ -0,0 +1,374 @@
+# mina-sdk — Complete API Reference


Is there any way to autogenerate those ? so we won't allow them to drift?

Drift is a real concern and I don't want hand-maintained API summaries rotting silently. Proper autogeneration needs either nightly rustdoc --output-format=json or a syn-based generator — both meaningful work. For this PR I removed llms.txt / llms-full.txt so there's nothing to drift; docs.rs remains the always-current reference. Happy to open a follow-up issue if you want the LLM-friendly format back with a real generator behind it. Fixed in a7e157d.

Client ergonomics: - MinaClient::default() returns a client connected to the local daemon. - MinaClient::from_host_and_port(host, port) as a convenience constructor. - New MinaClient::query(&str) returns a QueryBuilder with opt-in variables/name, so callers don't pass bare None sentinels. The low-level execute_query(query, vars, name) stays for downstream crates. Examples: - basic_usage: flatten env-key nesting with let-else; show a real B62q... key format in the comment. - send_payment / stake_delegation: document MINA_TEST_SENDER_KEY and MINA_TEST_RECEIVER_KEY (how to generate/unlock via mina CLI or lightnet acquire-account). Build the Payment/Delegation as a named variable first, then submit. - custom_query: rewritten to use the new query builder. Drop the bestChain demo (redundant with the typed get_best_chain) — instead query genesisConstants, which is not wrapped by the SDK. Add a variables-based pooledUserCommands query as the multi-argument demo. - error_handling / node_monitoring: use MinaClient::default() / from_host_and_port for clarity. llms.txt: - Remove llms.txt / llms-full.txt. Drift risk outweighs their value until we have proper autogeneration (nightly rustdoc-json or syn-based). docs.rs remains the always-current reference; follow-up issue can track a generator if we want the LLM-friendly format back. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dkijania and others added 3 commits April 17, 2026 10:56

Apply cargo fmt to new examples

ec27e4b

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Update new examples to use Payment/Delegation builder API

b6e4c88

master introduced a fluent builder API for send_payment/send_delegation; the new examples still used the old positional-args signature. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dkijania force-pushed the fix/cargo-publish-includes branch from 2714fc7 to b6e4c88 Compare April 17, 2026 09:33

dkijania commented Apr 17, 2026

View reviewed changes

dkijania self-assigned this Apr 17, 2026

dkijania merged commit 3093ac8 into master Apr 17, 2026
4 checks passed

dkijania deleted the fix/cargo-publish-includes branch April 17, 2026 21:34

Conversation

dkijania commented Apr 16, 2026

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant