cdp-sdk 0.2.0

SDK for interacting with the Coinbase Developer Platform Wallet API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Rust Development Guide

This guide covers Rust-specific setup and development for the CDP SDK.

## Contents

- [Development Setup](#development-setup)
- [Updating the SDK to use a new version of the OpenAPI specification](#updating-the-sdk-to-use-a-new-version-of-the-openapi-specification)
- [Testing](#testing)
- [Example Scripts](#example-scripts)
- [Code Style](#code-style)

## Development Setup

The CDP SDK uses Rust 1.86 or higher.

You can run the following to check your Rust version:

```bash
rustc --version
cargo --version
```

If you don't have Rust installed, download it from [rustup.rs](https://rustup.rs/).

Then, build the project and install dependencies by running:

```bash
cargo build
```

## Updating the SDK to use a new version of the OpenAPI specification

Fronm the root of the repository, run `make update-openapi` to pull the latest version of the spec.

Then, run `cd rust` and `make generate` to regenerate `api.rs`.

### No additional wrapping required:

Unlike other SDK implementations, the Rust SDK uses [Progenitor](https://github.com/sammccord/progenitor) to automatically generate type-safe client bindings from the OpenAPI specification at build time. This means:

- **No manual API wrapping** - All client methods are automatically generated with proper types
- **No separate generation step** - The OpenAPI client is generated during `cargo build`
- **Type safety** - Request/response types are automatically derived from the OpenAPI spec

The generated client is located in `src/api.rs` and provides:
- Strongly-typed request builders (e.g., `client.create_evm_account().body(body).send()`)
- Automatic serialization/deserialization of all types
- Builder patterns for all endpoints

If you need to add new functionality, focus on:
1. **Authentication middleware** (`src/auth.rs`) - for new auth requirements
2. **Error handling** (`src/error.rs`) - for custom error types
3. **Examples** (`examples/`) - to demonstrate new features
4. **Tests** (`tests/`) - to validate new functionality

## Testing

### Running Tests

Run `make test` to run all unit tests in the SDK.

Run `make test-e2e` to run the end-to-end tests. Make sure to set the required environment variables:

```bash
export CDP_API_KEY_ID="your-api-key-id"
export CDP_API_KEY_SECRET="your-api-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"
```

You can also set `E2E_LOGGING=true` to enable detailed logging during e2e tests:

```bash
E2E_LOGGING=true make test-e2e
```

### Test Structure

- **Unit tests** - Located in `src/` modules using `#[cfg(test)]`
- **Integration tests** - Located in `tests/e2e.rs` for comprehensive API testing
- **Example validation** - Examples serve as both documentation and integration tests

## Example Scripts

The CDP SDK includes several runnable examples in the `examples/` directory:

- `evm_account_management` - EVM account CRUD operations
- `evm_signing` - EVM transaction and message signing
- `smart_account_management` - Smart account operations
- `solana_account_management` - Solana account CRUD operations
- `solana_signing` - Solana transaction and message signing
- `token_balances` - Multi-chain token balance queries

Run any example with:

```bash
cargo run --example evm_account_management
```

When you make changes to the SDK code, your changes will automatically take effect when you run an example.

## Code Style

We use `rustfmt` and `clippy` for formatting and linting:

```bash
# Format code
make format

# Lint code
make lint

# Fix linting issues
make lint-fix

# Check code without building
make check
```

### Rust-Specific Guidelines

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `#[must_use]` for functions where ignoring the return value is likely a bug
- Prefer `impl Trait` over generic type parameters where appropriate
- Use `thiserror` for error types and `anyhow` for error handling in examples
- Document all public APIs with `///` comments including examples where helpful

### Code Organization

- **Generated code** (`src/api.rs`) - Do not modify directly, regenerated on build
- **Authentication** (`src/auth.rs`) - JWT generation and middleware
- **Error types** (`src/error.rs`) - Custom error handling
- **Library exports** (`src/lib.rs`) - Public API surface
- **Examples** (`examples/`) - Practical usage demonstrations
- **Tests** (`tests/`) - Integration and e2e testing