Merge branch 'develop' into docs/stellar-multisig-withdrawal

Author: baedboibidex-cmyk

.github/workflows/snippets.yml

@@ -0,0 +1,48 @@
+name: Snippet checks
+
+on:
+  pull_request:
+  push:
+    branches:
+      - develop
+      - main
+
+jobs:
+  check-snippets:
+    name: Compile docs snippets
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check snippets
+        run: npm run check:snippets
+
+  stellar-testnet-snippets:
+    name: Stellar snippet testnet validation
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate Stellar testnet snippets
+        run: npm run check:stellar-testnet

.gitignore

@@ -1 +1,3 @@
 reference/
+node_modules/
+.npm/

api-reference/endpoints.mdx

@@ -34,7 +34,7 @@ Create a new agent with a `.wraith` name.
 
 **Request:**
 
-```typescript
+```typescript no-check
 {
   name: string;          // "alice" (becomes alice.wraith)
   chain: string;         // "horizen" | "stellar" | "ethereum" | ...
@@ -154,7 +154,7 @@ Send a natural language message to the AI agent.
 
 **Request:**
 
-```typescript
+```typescript no-check
 {
   message: string;
   conversationId?: string;  // continue existing conversation
@@ -163,7 +163,7 @@ Send a natural language message to the AI agent.
 
 **Response:**
 
-```typescript
+```typescript no-check
 {
   response: string;          // agent's text reply
   toolCalls?: ToolCall[];    // tools the agent executed
@@ -276,7 +276,7 @@ GET /agent/:id/notifications
 
 **Response:**
 
-```typescript
+```typescript no-check
 {
   notifications: Notification[];
   unreadCount: number;
@@ -363,7 +363,7 @@ All errors return JSON with a `message` field:
 
 ### Example
 
-```typescript
+```typescript no-check
 // 400 Bad Request
 {
   "message": "Name must be 3-32 characters, lowercase alphanumeric and hyphens only",

api-reference/types.mdx

@@ -37,6 +37,7 @@ enum Chain {
   Base = "base",
   Stellar = "stellar",
   Solana = "solana",
+  CKB = "ckb",
   All = "all",
 }
 ```
@@ -281,6 +282,10 @@ import type {
   GeneratedStealthAddress,
   Announcement,
   MatchedAnnouncement,
+  FederationRecord,
+  FederationCache,
+  FederationError,
+  FederationErrorCode,
 } from "@wraith-protocol/sdk/chains/stellar";
 ```
 
@@ -330,6 +335,72 @@ interface MatchedAnnouncement extends Announcement {
 
 ---
 
+## Stellar Federation Types
+
+Exported from `@wraith-protocol/sdk/chains/stellar`:
+
+```typescript
+import type {
+  FederationRecord,
+  FederationCache,
+  FederationError,
+  FederationErrorCode,
+} from "@wraith-protocol/sdk/chains/stellar";
+```
+
+### `FederationRecord`
+
+The resolved result of a `name*domain.com` lookup.
+
+```typescript
+interface FederationRecord {
+  federationAddress: string;       // "alice*example.com" — the address that was queried
+  accountId: string;               // "GABC..." or "st:xlm:..." — resolved destination
+  memoType?: "text" | "id" | "hash";
+  memoValue?: string;              // required for exchange deposit addresses
+}
+```
+
+When `accountId` starts with `st:xlm:` it is a Wraith stealth meta-address and should be decoded with `decodeStealthMetaAddress()` before sending. Otherwise it is a plain `G...` public key.
+
+### `FederationCache`
+
+Pluggable cache interface accepted by `resolveStellarFederation()`. Implement this with any backend (in-memory, Redis, etc.).
+
+```typescript
+interface FederationCache {
+  get(key: string): Promise<FederationRecord | undefined>;
+  set(key: string, record: FederationRecord, ttlMs: number): Promise<void>;
+}
+```
+
+### `FederationErrorCode`
+
+```typescript
+type FederationErrorCode =
+  | "NOT_FOUND"            // federation server returned 404 / unknown address
+  | "DNS_FAILURE"          // could not fetch stellar.toml (network or DNS error)
+  | "NO_FEDERATION_SERVER" // stellar.toml exists but has no FEDERATION_SERVER field
+  | "INVALID_TOML"         // stellar.toml content is malformed
+  | "MALFORMED_RESPONSE"   // federation server response is missing required fields
+  | "TIMEOUT"              // request exceeded options.timeoutMs
+  | "NETWORK_ERROR";       // fetch failed for any other reason
+```
+
+### `FederationError`
+
+Thrown by `resolveStellarFederation()` on any failure. Always check `err.code` rather than `err.message` for programmatic handling.
+
+```typescript
+interface FederationError extends Error {
+  code: FederationErrorCode;
+  message: string;
+  cause?: unknown;    // the underlying network error or parse error, if any
+}
+```
+
+---
+
 ## Chain Connector Types
 
 Internal types used by the TEE server. Documented here for developers building custom chain connectors.

architecture/chain-connectors.mdx

@@ -347,7 +347,7 @@ class ChainRegistry {
 
 ### Usage in Agent Service
 
-```typescript
+```typescript no-check
 async sendPayment(agentId: string, recipient: string, amount: string) {
   const agent = await this.db.agents.findOneBy({ id: agentId });
   const connector = this.chainRegistry.get(agent.chain);

architecture/overview.mdx

@@ -72,7 +72,7 @@ The AI can call multiple tools in one response. A cap (10 iterations) prevents i
 
 Each tool call routes to the appropriate chain connector:
 
-```typescript
+```typescript no-check
 import { Chain } from "@wraith-protocol/sdk";
 
 // The agent service resolves the connector automatically

architecture/stellar-cryptography.mdx

@@ -0,0 +1,98 @@
+---
+title: "Stellar Cryptography"
+description: "Design rationale, view tag derivation, and RFC-compatible cryptography for Stellar stealth payments."
+---
+
+Wraith Protocol implements a non-interactive stealth payment scheme on Stellar. This page documents the cryptography decisions behind the implementation and exactly where each concept is realized in the SDK.
+
+## Why ed25519?
+
+Unlike EVM environments, which rely on `secp256k1`, the Stellar network uses the **ed25519** curve for all account addressing and signatures. 
+To ensure that stealth accounts are valid Stellar accounts that can sign transactions, the protocol's stealth derivations must perform point addition on the ed25519 curve.
+
+- **Curve definition**: `scalar.ts:1` (via [@noble/curves/ed25519](https://github.com/paulmillr/noble-curves))
+
+## X25519 ECDH and Edwards-to-Montgomery Conversion
+
+Standard ed25519 points (in Edwards form) are optimized for signing, not for Diffie-Hellman key exchange. To securely establish a shared secret between sender and receiver without interaction, we must use **X25519** ECDH.
+This requires converting the public and private ed25519 keys from Edwards coordinates to Montgomery coordinates, as specified in [RFC 7748](https://datatracker.ietf.org/doc/html/rfc7748).
+
+- **Edwards-to-Montgomery conversion**: `stealth.ts:91-92`
+- **X25519 shared secret**: `stealth.ts:20` and `stealth.ts:93`
+
+## Domain Separation Prefixes
+
+We use domain-separation prefixes in SHA-256 hashes to prevent cryptographic collisions between different key derivation phases.
+
+- `wraith:spending:`: Separates the derivation of the spending seed (`keys.ts:25`).
+- `wraith:viewing:`: Separates the derivation of the viewing seed (`keys.ts:26`).
+- `wraith:scalar:`: Prevents the hash scalar from colliding with the base shared secret before it's reduced modulo L (`scalar.ts:202`, `scalar.ts:220`).
+- `wraith:stellar:view-tag:v2:`: Domains the derivation for the 1-byte view tag (`stealth.ts:8`).
+- `wraith:tag:`: The legacy v1 view tag prefix (`stealth.ts:9`).
+
+## View Tag Derivation
+
+To avoid performing an expensive X25519 ECDH operation for every incoming transaction, the sender derives a 1-byte **view tag** and publishes it alongside their ephemeral public key.
+
+**Derivation:**
+```
+view_tag = SHA-256("wraith:stellar:view-tag:v2:" || R_ephemeral || V_recipient)[0]
+```
+
+- **Implementation**: `stealth.ts:99`
+- **Performance impact**: This creates a cheap public prefilter before the X25519 shared secret computation (`scan.ts:12`).
+- **False-positive rate**: A 1-byte tag produces a false-positive rate of `1/256` (~0.39%). For non-matching announcements, the protocol skips the expensive elliptic curve operations 99.61% of the time.
+
+```mermaid
+sequenceDiagram
+    participant Network
+    participant Scanner
+    Network->>Scanner: Fetch Announcements (R, view_tag)
+    Note over Scanner: Compare cheap view_tag first
+    alt Match view_tag
+        Scanner->>Scanner: X25519(v, R) -> shared_secret
+        Scanner->>Scanner: Derive expected stealth address
+        alt Match Address
+            Scanner->>Network: Recovered match!
+        end
+    else Mismatch view_tag
+        Note over Scanner: Skip (99.61% of non-matches)
+    end
+```
+
+## Private Scalar vs. Seeds and RFC 8032
+
+Standard ed25519 signing libraries expect a 32-byte seed as the private key, which they hash (via SHA-512) to produce both the private scalar and a deterministic nonce.
+
+In our non-interactive stealth scheme, the stealth private key is a *derived scalar*, not a raw seed:
+```
+stealth_scalar = (spending_scalar + hash_scalar) mod L
+```
+
+Because we only hold the resulting scalar, we cannot use off-the-shelf seed-based signing APIs. Instead, the SDK exposes a custom `signWithScalar` function to deterministically sign transactions using a raw scalar directly, while maintaining strict [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032) compatibility for ed25519 signatures.
+
+- **`signWithScalar` implementation**: `scalar.ts:251`
+
+## Meta-Address Encoding
+
+To accept stealth payments, users publish a single "meta-address" that encapsulates both their spending and viewing public keys.
+
+- **Prefix**: `st:xlm:` (`constants.ts:43`).
+- **Encoding**: Consists of the prefix concatenated with the hex-encoded 32-byte spending public key and the 32-byte viewing public key (`meta-address.ts:10`).
+- **Stellar StrKey compatibility**: To turn the final derived public stealth key into a standard Stellar address format (`G...`), we utilize Stellar's `StrKey` encoding logic (`scalar.ts:171`).
+
+## Key Derivation Overview
+
+```mermaid
+flowchart TD
+    S(Sender) -->|Generates| r(Ephemeral Private Key 'r')
+    r --> R(Ephemeral Public Key 'R')
+    S --> |Recipient's| V(Viewing Public Key 'V')
+    S --> |Recipient's| K(Spending Public Key 'K')
+    r & V --> X25519(X25519 ECDH)
+    X25519 --> SS(Shared Secret)
+    R & V --> VT(View Tag)
+    SS --> |Hash mod L| HS(Hash Scalar)
+    HS & K --> |Point Addition| SP(Stealth Public Key)
+    SP --> |StrKey Encoding| SA(Stellar Address 'G...')
+```

architecture/tee.mdx

@@ -58,7 +58,7 @@ The chain connector determines how the raw seed becomes usable keys:
 
 Every time an operation needs agent keys (sending a payment, scanning, withdrawing), the keys are re-derived from the TEE root secret. No private key material touches disk.
 
-```typescript
+```typescript no-check
 // Every chat message re-derives keys
 async chat(agentId: string, message: string) {
   const agent = await this.db.agents.findOneBy({ id: agentId });