**Migrated from GitHub issue icub3d/decentcom#85** **Original Author:** @icub3d **Original Date:** 2026-04-18T03:56:20Z --- # Feature: Rust SDK (Base Protocol & Identity) ## Overview Develop a foundational Rust SDK crate that provides a high-level, typed interface for interacting with the decentcom protocol. This SDK will handle identity management (Ed25519), authentication flows, REST API interactions, and low-level Gateway (WebSocket) connectivity. This crate is intended to be the base layer for the Bot SDK (#76) and other Rust-based clients, ensuring protocol consistency and reducing boilerplate. ## Background Currently, the Tauri client (#client) and the server (#server) share types via the `shared/` crate, but the logic for authentication, signing, and API interaction is implemented separately (and sometimes in JS/TS in the frontend). A dedicated Rust SDK allows any Rust application—whether a bot, a CLI tool, or a desktop client—to speak the decentcom protocol correctly and securely. ## Requirements - [x] **New Rust crate** at `sdk/rust/` (internal name: `decentcom-sdk`). - [x] **Identity Management**: - BIP39 mnemonic generation and parsing. - Ed25519 key derivation from seed. - Signature generation for auth challenges. - [x] **Authentication**: - Full implementation of the two-step challenge-response flow. - Session token management. - [x] **REST API Client**: - Typed wrappers for all server modules: Channels, Messages, Members, Roles, Profiles, Invites, Threads, Reactions, Attachments. - Support for multi-server management (client can maintain sessions with multiple servers). - [x] **Low-level Gateway Client**: - WebSocket connection management. - Automatic Heartbeat handling. - Typed event stream (exposing `shared::gateway::Op` events). - [x] **Error Handling**: Comprehensive custom error types for protocol and transport failures. - [x] **Async/Await**: Built on `tokio`, `reqwest`, and `tokio-tungstenite`. ## Design ### Component Changes - New workspace member at `sdk/rust/`. - Re-exports or integrates types from `shared/`. ### API Sketch ```rust use decentcom_sdk::{Identity, Client, Config}; // 1. Setup Identity let identity = Identity::from_mnemonic("...")?; // 2. Initialize Client let mut client = Client::new("https://decentcom.example.com"); // 3. Authenticate client.authenticate(&identity).await?; // 4. Interact let channel = client.channels().get("general").await?; client.messages().send(&channel.id, "Hello from the SDK!").await?; // 5. Gateway let mut stream = client.gateway().connect().await?; while let Some(event) = stream.next().await { println!("Received event: {:?}", event); } ``` ## Task List ### Phase 1: Identity & Auth - [x] Scaffold `sdk/rust/` crate. - [x] Port identity logic (BIP39/Ed25519) from Tauri client/test-setup. - [x] Implement `AuthClient` for challenge-response flow. ### Phase 2: REST Client - [x] Implement base `RestClient` with middleware for auth headers. - [x] Add modules for Channels, Messages, and Members. - [x] Add modules for Roles, Profiles, and Invites. - [x] Add modules for Threads, Reactions, and Attachments. ### Phase 3: Gateway - [x] Implement `GatewayClient` using `tokio-tungstenite`. - [x] Implement background heartbeat task. - [x] Expose an async stream of gateway events. ## Test List - [x] Unit tests for identity derivation and signing. - [x] Mock server tests for REST API modules. - [ ] Integration tests against a running dev server (Auth + basic REST actions). ## Open Questions - Should this crate eventually absorb `shared/` or stay separate? (Recommendation: Keep `shared/` for pure types, SDK for logic). **Resolved: keeping `shared/` for pure wire types; SDK carries the logic and its own request/response wrappers.** - How to handle file uploads for attachments? (Recommendation: Start with basic REST, add multipart support in Phase 2). **Resolved: SDK ships the REST read path (`fetch_media`/`media_url`) now; multipart upload helper is deferred to a follow-up.** ## Dependencies - Blocks: #76 (Bot SDK - which will add the high-level event loop and bot-specific DSL).

icub3d commented

2026-04-26 16:46:16 +00:00

Owner

Migrated from GitHub issue icub3d/decentcom#85
Original Author: @icub3d
Original Date: 2026-04-18T03:56:20Z

Feature: Rust SDK (Base Protocol & Identity)

Overview

Develop a foundational Rust SDK crate that provides a high-level, typed interface for interacting with the decentcom protocol. This SDK will handle identity management (Ed25519), authentication flows, REST API interactions, and low-level Gateway (WebSocket) connectivity.

This crate is intended to be the base layer for the Bot SDK (#76) and other Rust-based clients, ensuring protocol consistency and reducing boilerplate.

Background

Currently, the Tauri client (#client) and the server (#server) share types via the shared/ crate, but the logic for authentication, signing, and API interaction is implemented separately (and sometimes in JS/TS in the frontend). A dedicated Rust SDK allows any Rust application—whether a bot, a CLI tool, or a desktop client—to speak the decentcom protocol correctly and securely.

Requirements

New Rust crate at sdk/rust/ (internal name: decentcom-sdk).
Identity Management:
- BIP39 mnemonic generation and parsing.
- Ed25519 key derivation from seed.
- Signature generation for auth challenges.
Authentication:
- Full implementation of the two-step challenge-response flow.
- Session token management.
REST API Client:
- Typed wrappers for all server modules: Channels, Messages, Members, Roles, Profiles, Invites, Threads, Reactions, Attachments.
- Support for multi-server management (client can maintain sessions with multiple servers).
Low-level Gateway Client:
- WebSocket connection management.
- Automatic Heartbeat handling.
- Typed event stream (exposing shared::gateway::Op events).
Error Handling: Comprehensive custom error types for protocol and transport failures.
Async/Await: Built on tokio, reqwest, and tokio-tungstenite.

Design

Component Changes

New workspace member at sdk/rust/.
Re-exports or integrates types from shared/.

API Sketch

use decentcom_sdk::{Identity, Client, Config};

// 1. Setup Identity
let identity = Identity::from_mnemonic("...")?;

// 2. Initialize Client
let mut client = Client::new("https://decentcom.example.com");

// 3. Authenticate
client.authenticate(&identity).await?;

// 4. Interact
let channel = client.channels().get("general").await?;
client.messages().send(&channel.id, "Hello from the SDK!").await?;

// 5. Gateway
let mut stream = client.gateway().connect().await?;
while let Some(event) = stream.next().await {
    println!("Received event: {:?}", event);
}

Task List

Phase 1: Identity & Auth

Scaffold sdk/rust/ crate.
Port identity logic (BIP39/Ed25519) from Tauri client/test-setup.
Implement AuthClient for challenge-response flow.

Phase 2: REST Client

Implement base RestClient with middleware for auth headers.
Add modules for Channels, Messages, and Members.
Add modules for Roles, Profiles, and Invites.
Add modules for Threads, Reactions, and Attachments.

Phase 3: Gateway

Implement GatewayClient using tokio-tungstenite.
Implement background heartbeat task.
Expose an async stream of gateway events.

Test List

Unit tests for identity derivation and signing.
Mock server tests for REST API modules.
Integration tests against a running dev server (Auth + basic REST actions).

Open Questions

Should this crate eventually absorb shared/ or stay separate? (Recommendation: Keep shared/ for pure types, SDK for logic). Resolved: keeping shared/ for pure wire types; SDK carries the logic and its own request/response wrappers.
How to handle file uploads for attachments? (Recommendation: Start with basic REST, add multipart support in Phase 2). Resolved: SDK ships the REST read path (fetch_media/media_url) now; multipart upload helper is deferred to a follow-up.

Dependencies

Blocks: #76 (Bot SDK - which will add the high-level event loop and bot-specific DSL).

icub3d

closed this issue
added the
area:api

area:core

type:feature

status:complete
labels

Rows
Columns

Feature: Rust SDK (Base Protocol & Identity) #60