docs: add Evo SDK chapters

book/src/SUMMARY.md

@@ -66,7 +66,20 @@
 - [Strategy Tests](testing/strategy-tests.md)
 - [Test Configuration](testing/test-configuration.md)
 
-# SDK
+# Evo SDK (JavaScript/TypeScript)
+
+- [Overview](evo-sdk/overview.md)
+- [Getting Started](evo-sdk/getting-started.md)
+- [Trusted Mode and Proofs](evo-sdk/trusted-mode.md)
+- [State Transitions](evo-sdk/state-transitions.md)
+- [Wallet Utilities](evo-sdk/wallet-utilities.md)
+- [Networks and Environments](evo-sdk/networks-and-environments.md)
+- [Tutorials]()
+  - [Car Sales Management](evo-sdk/tutorials/car-sales.md)
+  - [Creating a Basic Token](evo-sdk/tutorials/basic-token.md)
+  - [Card Game with Tokens](evo-sdk/tutorials/card-game.md)
+
+# Rust SDK
 
 - [Builder Pattern](sdk/builder-pattern.md)
 - [Fetch Traits](sdk/fetch-traits.md)

book/src/evo-sdk/getting-started.md

@@ -0,0 +1,106 @@
+# Getting Started
+
+## Installation
+
+```sh
+npm install @dashevo/evo-sdk
+```
+
+The package is **ESM-only** (`"type": "module"`). In CommonJS projects use a
+dynamic `import()`:
+
+```js
+const { EvoSDK } = await import('@dashevo/evo-sdk');
+```
+
+Requirements: Node.js ≥ 18.18 or any modern browser with WebAssembly support.
+
+## Quick start
+
+```typescript
+import { EvoSDK } from '@dashevo/evo-sdk';
+
+// Create a trusted testnet instance and connect
+const sdk = EvoSDK.testnetTrusted();
+await sdk.connect();
+
+// Query the current epoch
+const epoch = await sdk.epoch.current();
+console.log('Current epoch:', epoch.index);
+
+// Fetch an identity by its base58 ID
+const identity = await sdk.identities.fetch('4EfA9Jrvv3nnCFdSf7fad59851iiTRZ6Wcu6YVJ4iSeF');
+console.log('Balance:', identity?.getBalance());
+```
+
+## Connecting
+
+The SDK must be connected before making any queries. Calling `connect()` is
+asynchronous because it initialises the WASM module and, in trusted mode,
+pre-fetches quorum public keys.
+
+```typescript
+const sdk = new EvoSDK({ network: 'testnet', trusted: true });
+await sdk.connect();
+```
+
+After connecting, all facade properties (`sdk.identities`, `sdk.documents`,
+etc.) are ready to use. Calling `connect()` more than once is a no-op.
+
+### Factory helpers
+
+| Helper | Equivalent |
+|--------|-----------|
+| `EvoSDK.testnet()` | `new EvoSDK({ network: 'testnet' })` |
+| `EvoSDK.mainnet()` | `new EvoSDK({ network: 'mainnet' })` |
+| `EvoSDK.testnetTrusted()` | `new EvoSDK({ network: 'testnet', trusted: true })` |
+| `EvoSDK.mainnetTrusted()` | `new EvoSDK({ network: 'mainnet', trusted: true })` |
+| `EvoSDK.local()` | `new EvoSDK({ network: 'local' })` |
+| `EvoSDK.localTrusted()` | `new EvoSDK({ network: 'local', trusted: true })` |
+
+### Custom addresses
+
+To connect to specific masternodes (useful for testing or private networks):
+
+```typescript
+const sdk = EvoSDK.withAddresses(
+  ['https://52.12.176.90:1443'],
+  'testnet',
+);
+await sdk.connect();
+```
+
+## Connection options
+
+All factory helpers and the constructor accept an optional `ConnectionOptions`
+object:
+
+```typescript
+const sdk = EvoSDK.testnetTrusted({
+  settings: {
+    connectTimeoutMs: 5000,
+    timeoutMs: 10000,
+    retries: 3,
+    banFailedAddress: true,
+  },
+  logs: 'info',         // 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+  proofs: true,          // request proofs with every query
+  version: 8,           // pin a specific protocol version
+});
+```
+
+### Logging
+
+The SDK delegates logging to the underlying Rust/WASM layer. Pass a simple
+level string or a full `EnvFilter` directive:
+
+```typescript
+// Simple level
+const sdk = EvoSDK.testnetTrusted({ logs: 'debug' });
+
+// Granular filter
+const sdk = EvoSDK.testnetTrusted({ logs: 'wasm_sdk=debug,rs_dapi_client=warn' });
+
+// Change level at runtime (static, affects all instances)
+await EvoSDK.setLogLevel('trace');
+```

book/src/evo-sdk/networks-and-environments.md

@@ -0,0 +1,74 @@
+# Networks and Environments
+
+The Evo SDK supports three built-in network configurations plus custom
+addresses for private or development networks.
+
+## Built-in networks
+
+| Network | Factory | DAPI discovery | Use case |
+|---------|---------|---------------|----------|
+| **Testnet** | `EvoSDK.testnetTrusted()` | Automatic via seed nodes | Development and testing |
+| **Mainnet** | `EvoSDK.mainnetTrusted()` | Automatic via seed nodes | Production applications |
+| **Local** | `EvoSDK.localTrusted()` | `127.0.0.1:1443` | Docker-based local development |
+
+For each network, the SDK discovers DAPI endpoints from seed nodes and rotates
+between them automatically. Failed nodes are temporarily banned so the SDK
+retries against healthy nodes.
+
+## Local development with Docker
+
+When running a local Platform network via
+[dashmate](https://github.com/dashpay/platform/tree/master/packages/dashmate),
+use the `local` network:
+
+```typescript
+const sdk = EvoSDK.localTrusted();
+await sdk.connect();
+```
+
+This connects to `https://127.0.0.1:1443` by default. If your local setup uses
+different ports, use custom addresses:
+
+```typescript
+const sdk = EvoSDK.withAddresses(
+  ['https://127.0.0.1:2443'],
+  'local',
+);
+await sdk.connect();
+```
+
+## Custom masternode addresses
+
+For private devnets, specific nodes, or debugging:
+
+```typescript
+const sdk = EvoSDK.withAddresses(
+  [
+    'https://52.12.176.90:1443',
+    'https://34.217.100.50:1443',
+  ],
+  'testnet',
+);
+await sdk.connect();
+```
+
+When custom addresses are provided, the SDK does not perform automatic node
+discovery — it uses only the addresses you supply.
+
+## Browser vs Node.js
+
+The SDK works identically in both environments. The underlying WASM module
+handles platform differences transparently.
+
+**Node.js considerations:**
+
+- Requires Node.js ≥ 18.18 (for WebAssembly and `fetch` support)
+- ESM-only package — use `import`, not `require`
+- No additional polyfills needed
+
+**Browser considerations:**
+
+- Works in any browser with WebAssembly support (all modern browsers)
+- The WASM module is loaded asynchronously on first `connect()` call
+- Total bundle size includes the compiled Rust SDK (~2-4 MB gzipped)
+- gRPC calls use `grpc-web` over HTTPS, compatible with standard CORS

book/src/evo-sdk/overview.md

@@ -0,0 +1,74 @@
+# Evo SDK Overview
+
+The **Evo SDK** (`@dashevo/evo-sdk`) is the primary JavaScript/TypeScript SDK
+for building applications on Dash Platform. It provides a high-level,
+strongly-typed facade over the WebAssembly-based Rust SDK, working in both
+Node.js (≥ 18.18) and modern browsers.
+
+> **API reference**: For detailed per-method documentation with interactive
+> examples, see the [Evo SDK Docs](https://dashpay.github.io/evo-sdk-website/docs.html).
+
+## How it works
+
+```
+┌──────────────────┐
+│  Your TypeScript  │
+│   Application     │
+└────────┬─────────┘
+         │  EvoSDK facades (identities, documents, tokens, …)
+┌────────▼─────────┐
+│   @dashevo/       │
+│   evo-sdk         │  TypeScript wrapper layer
+└────────┬─────────┘
+         │  calls into compiled WASM module
+┌────────▼─────────┐
+│   @dashevo/       │
+│   wasm-sdk        │  Rust SDK compiled to WebAssembly
+└────────┬─────────┘
+         │  gRPC over HTTPS
+┌────────▼─────────┐
+│  DAPI nodes       │  Dash Platform's decentralized API
+└──────────────────┘
+```
+
+The Evo SDK does **not** use JSON-RPC or REST. Every request is a gRPC call to
+one of the Platform's DAPI nodes. Responses include cryptographic proofs that
+the SDK verifies against the platform state root, so you do not need to trust
+any single node.
+
+## Facades
+
+The SDK organises its API into domain-specific facades, each accessible as a
+property on the `EvoSDK` instance:
+
+| Facade | Description |
+|--------|-------------|
+| `sdk.identities` | Fetch, create, update, and top up identities |
+| `sdk.contracts` | Fetch, publish, and update data contracts |
+| `sdk.documents` | Query, create, replace, delete, and transfer documents |
+| `sdk.tokens` | Mint, burn, transfer, freeze tokens and query balances |
+| `sdk.dpns` | Register and resolve Dash Platform names |
+| `sdk.addresses` | Query balances, transfer credits, withdraw to L1 |
+| `sdk.epoch` | Query epoch information and evonode proposed blocks |
+| `sdk.protocol` | Protocol version upgrade state and voting |
+| `sdk.stateTransitions` | Broadcast and wait for state transitions |
+| `sdk.system` | System status, quorum info, and total credits |
+| `sdk.group` | Group membership, actions, and contested resources |
+| `sdk.voting` | Contested resource vote states and polls |
+
+A standalone `wallet` namespace is also exported for mnemonic generation, key
+derivation, address validation, and message signing — see the
+[Wallet Utilities](wallet-utilities.md) chapter.
+
+## What it covers
+
+The SDK supports the full set of Platform operations:
+
+- **Queries** (read-only): fetch identities, contracts, documents, token
+  balances, DPNS names, epoch info, vote states, and more. Every query can
+  return a cryptographic proof.
+- **State transitions** (writes): create identities, deploy contracts, manage
+  documents and tokens, register names, cast votes, and transfer credits.
+
+See the [API reference](https://dashpay.github.io/evo-sdk-website/docs.html) for the
+complete list of operations with interactive examples.