Skip to content

Commit 69a2a8f

Browse files
RigidityRigidity
authored
Merge pull request #5 from xch-dev/greimela.chia-wallet-sdk-docs
Add Wallet SDK documentation section
2 parents 9a7da06 + dfe6c4d commit 69a2a8f

13 files changed

Lines changed: 5767 additions & 0 deletions

File tree

‎docs/sdk/actions.md‎

Lines changed: 1112 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/sdk/connectivity.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
slug: /sdk/connectivity
3+
title: Connectivity
4+
---
5+
6+
# Connectivity
7+
8+
The Wallet SDK provides client crates for connecting to the Chia network. This page covers the basics of establishing connections and querying blockchain state.
9+
10+
## Overview
11+
12+
The SDK includes two client approaches:
13+
14+
| Crate | Use Case |
15+
|-------|----------|
16+
| `chia-sdk-client` | Direct peer-to-peer connections using the Chia protocol |
17+
| `chia-sdk-coinset` | HTTP/RPC client for querying coin state |
18+
19+
## Peer Connections
20+
21+
The `Peer` type provides direct connections to Chia full nodes using the native protocol:
22+
23+
```rust
24+
use chia_wallet_sdk::prelude::*;
25+
26+
// Connect to a peer
27+
let peer = Peer::connect(
28+
"node.example.com:8444",
29+
network_id,
30+
tls_connector,
31+
).await?;
32+
33+
// Query coin state
34+
let coin_states = peer.request_coin_state(
35+
coin_ids,
36+
None, // previous_height
37+
genesis_challenge,
38+
).await?;
39+
```
40+
41+
### Connection Requirements
42+
43+
Peer connections require:
44+
45+
- Network ID (mainnet, testnet, etc.)
46+
- TLS configuration
47+
- Knowledge of the genesis challenge for the network
48+
49+
## Coinset Client
50+
51+
For simpler HTTP-based queries, use `CoinsetClient`:
52+
53+
```rust
54+
use chia_wallet_sdk::prelude::*;
55+
56+
// Create client for a coinset API endpoint
57+
let client = CoinsetClient::new(
58+
"https://api.example.com",
59+
network_id,
60+
);
61+
62+
// Query coins by puzzle hash
63+
let coins = client.get_coins_by_puzzle_hash(puzzle_hash).await?;
64+
65+
// Get coin state
66+
let states = client.get_coin_state(coin_ids).await?;
67+
```
68+
69+
## Full Node Client
70+
71+
For direct full node RPC access:
72+
73+
```rust
74+
use chia_wallet_sdk::prelude::*;
75+
76+
let client = FullNodeClient::new(
77+
"https://localhost:8555",
78+
cert_path,
79+
key_path,
80+
)?;
81+
82+
// Use full node RPC methods
83+
let blockchain_state = client.get_blockchain_state().await?;
84+
```
85+
86+
## Broadcasting Transactions
87+
88+
After building a spend bundle, broadcast it to the network:
89+
90+
```rust
91+
// Build your transaction
92+
let ctx = &mut SpendContext::new();
93+
// ... add spends ...
94+
let coin_spends = ctx.take();
95+
96+
// Sign the spend bundle
97+
let spend_bundle = SpendBundle::new(coin_spends, aggregated_signature);
98+
99+
// Broadcast via peer
100+
let response = peer.send_transaction(spend_bundle).await?;
101+
102+
// Or via full node client
103+
let response = client.push_tx(spend_bundle).await?;
104+
```
105+
106+
## Network Configuration
107+
108+
Different networks require different configuration:
109+
110+
| Network | Default Port | Genesis Challenge |
111+
|---------|--------------|-------------------|
112+
| Mainnet | 8444 | See Chia docs |
113+
| Testnet | 58444 | See Chia docs |
114+
115+
:::info
116+
For production applications, consider connecting to multiple peers for redundancy and using the coinset API for efficient queries.
117+
:::
118+
119+
## TLS Configuration
120+
121+
Peer connections require TLS. The SDK supports both `native-tls` and `rustls` backends via feature flags:
122+
123+
```toml
124+
# Use native TLS (default)
125+
chia-wallet-sdk = { version = "0.32", features = ["native-tls"] }
126+
127+
# Or use rustls
128+
chia-wallet-sdk = { version = "0.32", features = ["rustls"] }
129+
```
130+
131+
## Beyond This Guide
132+
133+
Detailed network programming with the SDK is beyond the scope of this documentation. For:
134+
135+
- Production connection management
136+
- Peer discovery
137+
- Network protocol details
138+
139+
See the [chia-sdk-client rustdocs](https://docs.rs/chia-sdk-client) and [chia-sdk-coinset rustdocs](https://docs.rs/chia-sdk-coinset).

‎docs/sdk/index.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
slug: /sdk
3+
title: Quick Start
4+
---
5+
6+
# Wallet SDK
7+
8+
The Chia Wallet SDK is a Rust library for building applications that interact with the Chia blockchain. It provides high-level abstractions for creating transactions, managing coins, and working with Chia primitives like CATs, NFTs, and Vaults.
9+
10+
:::info
11+
This documentation assumes familiarity with Chia blockchain concepts such as coins, puzzles, conditions, and singletons. For background, see the [Chia Documentation](https://docs.chia.net) and [Chialisp Documentation](https://chialisp.com).
12+
:::
13+
14+
## Installation
15+
16+
import Tabs from '@theme/Tabs';
17+
import TabItem from '@theme/TabItem';
18+
19+
<Tabs>
20+
<TabItem value="rust" label="Rust" default>
21+
22+
Add the SDK to your `Cargo.toml`:
23+
24+
```toml
25+
[dependencies]
26+
chia-wallet-sdk = "0.32"
27+
```
28+
29+
For the latest version and detailed API reference, see [docs.rs/chia-wallet-sdk](https://docs.rs/chia-wallet-sdk).
30+
31+
</TabItem>
32+
<TabItem value="nodejs" label="Node.js">
33+
34+
Install via npm:
35+
36+
```bash
37+
npm install chia-wallet-sdk
38+
```
39+
40+
The Node.js bindings provide a similar API with JavaScript/TypeScript support. Full TypeScript type definitions are included.
41+
42+
</TabItem>
43+
<TabItem value="python" label="Python">
44+
45+
Install via pip:
46+
47+
```bash
48+
pip install chia-wallet-sdk
49+
```
50+
51+
The Python bindings provide a Pythonic API with full type stub support for IDE autocompletion.
52+
53+
</TabItem>
54+
</Tabs>
55+
56+
## Quick Example
57+
58+
Here's a minimal example that creates and spends a standard XCH coin:
59+
60+
<Tabs>
61+
<TabItem value="rust" label="Rust" default>
62+
63+
```rust
64+
use chia_wallet_sdk::prelude::*;
65+
66+
// Create a spend context to build the transaction
67+
let ctx = &mut SpendContext::new();
68+
69+
// Define the conditions for this spend:
70+
// - Create a new coin with 900 mojos
71+
// - Reserve 100 mojos as transaction fee
72+
let conditions = Conditions::new()
73+
.create_coin(puzzle_hash, 900, Memos::None)
74+
.reserve_fee(100);
75+
76+
// Create the spend using StandardLayer (p2 puzzle)
77+
StandardLayer::new(public_key).spend(ctx, coin, conditions)?;
78+
79+
// Extract the coin spends for signing and broadcast
80+
let coin_spends = ctx.take();
81+
```
82+
83+
</TabItem>
84+
<TabItem value="nodejs" label="Node.js">
85+
86+
```typescript
87+
import { Clvm, Coin, Simulator } from "chia-wallet-sdk";
88+
89+
// Create a CLVM instance to build the transaction
90+
const clvm = new Clvm();
91+
92+
// Create conditions:
93+
// - Create a new coin with 900 mojos
94+
// - Reserve 100 mojos as transaction fee
95+
const conditions = [
96+
clvm.createCoin(puzzleHash, 900n, null),
97+
clvm.reserveFee(100n),
98+
];
99+
100+
// Create and spend using delegated spend (p2 puzzle)
101+
clvm.spendStandardCoin(
102+
coin,
103+
publicKey,
104+
clvm.delegatedSpend(conditions)
105+
);
106+
107+
// Extract the coin spends for signing and broadcast
108+
const coinSpends = clvm.coinSpends();
109+
```
110+
111+
</TabItem>
112+
<TabItem value="python" label="Python">
113+
114+
```python
115+
from chia_wallet_sdk import Clvm, Coin, Simulator
116+
117+
# Create a CLVM instance to build the transaction
118+
clvm = Clvm()
119+
120+
# Create conditions:
121+
# - Create a new coin with 900 mojos
122+
# - Reserve 100 mojos as transaction fee
123+
conditions = [
124+
clvm.create_coin(puzzle_hash, 900, None),
125+
clvm.reserve_fee(100),
126+
]
127+
128+
# Create and spend using delegated spend (p2 puzzle)
129+
clvm.spend_standard_coin(
130+
coin,
131+
public_key,
132+
clvm.delegated_spend(conditions)
133+
)
134+
135+
# Extract the coin spends for signing and broadcast
136+
coin_spends = clvm.coin_spends()
137+
```
138+
139+
</TabItem>
140+
</Tabs>
141+
142+
This example demonstrates the core pattern you'll use throughout the SDK:
143+
144+
1. **Create a context** - In Rust, use `SpendContext`; in Node.js/Python, use the `Clvm` class
145+
2. **Build conditions** - Define what the transaction should do (create coins, fees, announcements)
146+
3. **Spend coins** - Use primitives like `StandardLayer` (Rust) or `spendStandardCoin` (bindings)
147+
4. **Extract and broadcast** - Take the collected spends, sign them, and submit to the network
148+
149+
## Core Concepts
150+
151+
The SDK is organized around these key abstractions:
152+
153+
| Concept | Rust | Node.js / Python | Description |
154+
|---------|------|------------------|-------------|
155+
| **Context** | `SpendContext` | `Clvm` | Transaction builder that manages memory and collects coin spends |
156+
| **Conditions** | `Conditions` builder | Method calls (`createCoin`, etc.) | Output conditions (create coin, fees, announcements) |
157+
| **Actions** | `Action`, `Spends` | `Action`, `Spends` | High-level declarative transaction API |
158+
| **Primitives** | `Cat`, `Nft`, `Vault`, etc. | `spendCats`, `spendNft`, etc. | High-level APIs for Chia constructs |
159+
| **Simulator** | `Simulator` | `Simulator` | Test transaction validation locally |
160+
161+
## Next Steps
162+
163+
- [SpendContext](/sdk/spend-context) - Understanding the core transaction builder
164+
- [Action System](/sdk/actions) - High-level declarative transaction API
165+
- [Standard (XCH)](/sdk/primitives/standard) - Working with basic XCH coins
166+
- [CAT](/sdk/primitives/cat) - Issuing and spending custom asset tokens
167+
- [NFT](/sdk/primitives/nft) - Minting and transferring NFTs
168+
169+
## Relationship to chia-rs
170+
171+
The Wallet SDK builds on top of the lower-level [chia-rs](https://github.com/Chia-Network/chia_rs) crates, providing ergonomic APIs for common operations. If you need lower-level control, the underlying types from `chia-protocol`, `clvm-traits`, and `clvmr` are re-exported through the SDK.

0 commit comments

Comments
 (0)