npm package: @protocol-01/anon0mesh-sdk
Description: TypeScript SDK for anon0mesh — mesh-first Solana RPC relay. Works in Node.js, React Native, and browser.
Latest version: 0.2.1

# @protocol-01/anon0mesh-sdk

TypeScript SDK for [anon0mesh](https://github.com/anonmesh/anon0mesh_cli) — mesh-first Solana RPC relay. Works in **Node.js**, **React Native**, and **browser**.

Replaces the Python CLI + Node.js shim (~2000 lines) with a single importable package.

## Install

```bash
npm install @protocol-01/anon0mesh-sdk
```

## Quick Start

```typescript
import {
  Anon0meshClient,
  WebSocketTransport,
  Keypair,
  PublicKey,
} from "@protocol-01/anon0mesh-sdk";

// Connect to a beacon via WebSocket
const client = new Anon0meshClient({
  transport: new WebSocketTransport("ws://your-beacon:8765"),
  keypair: Keypair.generate(),
});

await client.connect();

// Check balance
const { sol } = await client.getBalance();
console.log(`Balance: ${sol} SOL`);

// Send SOL via durable nonce (no expiry — ideal for mesh relay)
const sig = await client.sendSol(
  new PublicKey("recipient..."),
  0.1,
  new PublicKey("nonceAccount..."),
);
console.log(`Sent: ${sig}`);
```

## Why This SDK?

The original anon0mesh CLI is Python + Node.js — it cannot run on mobile. This SDK solves that:

| Problem | Original CLI | This SDK |
|---------|-------------|----------|
| **Runtime** | Python 3 + Node.js subprocess | TypeScript (any JS runtime) |
| **Mobile support** | None | React Native, Expo, browser |
| **Mesh transport** | Reticulum only (desktop) | WebSocket + pluggable transports |
| **Arcium encryption** | Spawns `node rescue_shim.mjs` | Direct imports, no subprocess |
| **Wallet management** | JSON files on disk | In-memory Keypair, secure storage ready |
| **Integration** | CLI flags + REPL | `import` and call functions |

## Architecture

```
Mobile / Browser App
  │
  │  import { Anon0meshClient } from "@protocol-01/anon0mesh-sdk"
  │
  ├─► WebSocketTransport ──► Beacon (ws_bridge.py) ──► Solana RPC
  │                              │
  │                              ├─► Reticulum mesh (existing clients)
  │                              └─► Arcium MPC (payment stats)
  │
  └─► DirectRpcTransport ──► Solana RPC (fallback, no beacon)
```

## Transports

### WebSocket (recommended for mobile)

Connects to a beacon running `ws_bridge.py`. The beacon handles Solana RPC forwarding and transaction co-signing.

```typescript
import { WebSocketTransport } from "@protocol-01/anon0mesh-sdk";

const transport = new WebSocketTransport("ws://beacon-host:8765", 30_000);
```

### Direct RPC (fallback)

Bypasses the beacon and hits Solana RPC directly. No mesh relay, no co-signing.

```typescript
import { DirectRpcTransport } from "@protocol-01/anon0mesh-sdk";

const transport = new DirectRpcTransport("https://api.devnet.solana.com");
```

### Beacon Pool (multi-beacon)

Race or fallback across multiple transports — mirrors the Python `BeaconPool`.

```typescript
import { BeaconPool, WebSocketTransport } from "@protocol-01/anon0mesh-sdk";

const pool = new BeaconPool({ strategy: "race" });
pool.addTransport(new WebSocketTransport("ws://beacon-1:8765"));
pool.addTransport(new WebSocketTransport("ws://beacon-2:8765"));
await pool.connect();
```

## Wallet Operations

### Keypair Management

```typescript
import { generateKeypair, importKeypair, exportKeypair } from "@protocol-01/anon0mesh-sdk";

const kp = generateKeypair();
const exported = exportKeypair(kp); // number[] — standard Solana JSON format
const imported = importKeypair(exported);
```

### Durable Nonce Transactions

Transactions sent over mesh networks can be delayed by minutes or hours. Durable nonces replace the expiring blockhash so signed transactions stay valid indefinitely.

```typescript
// Create a nonce account
const { noncePubkey, signature } = await client.createNonceAccount();

// Send SOL with durable nonce (never expires)
const sig = await client.sendSol(recipient, 0.5, noncePubkey);
```

### Offline Signing (low-level)

```typescript
import { signNonceTransfer } from "@protocol-01/anon0mesh-sdk";

const txBase64 = signNonceTransfer(
  payerKeypair,
  nonceAccountPubkey,
  nonceAuthorityKeypair,
  recipientPubkey,
  500_000_000, // lamports
  nonceValue,
);
// txBase64 can be relayed later — it won't expire
```

## Arcium MPC Payments

Send encrypted payments through the beacon with Arcium MPC revenue-share logging.

```typescript
const client = new Anon0meshClient({
  transport: new WebSocketTransport("ws://beacon:8765"),
  keypair: myKeypair,
  mxePublicKeyHex: "your_mxe_pubkey_hex",
  clusterOffset: 456, // devnet
});

await client.connect();

await client.sendArciumPayment({
  recipient: new PublicKey("recipient..."),
  mint: new PublicKey("token_mint..."),
  amount: 1_000_000, // token amount in smallest unit
  nonceAccount: new PublicKey("nonce..."),
});
```

### Low-Level Arcium Functions

```typescript
import {
  x25519Keygen,
  rescueEncrypt,
  rescueDecrypt,
  getArciumAccounts,
  buildExecutePaymentIx,
} from "@protocol-01/anon0mesh-sdk";

// x25519 key generation
const { privateKey, publicKey } = x25519Keygen();

// Encrypt a value with RescueCipher
const encrypted = rescueEncrypt(mxePublicKeyHex, [BigInt(amount)]);

// Get all Arcium PDA addresses
const accounts = getArciumAccounts(programId, clusterOffset);

// Build the execute_payment instruction
const { instruction } = buildExecutePaymentIx({ ... });
```

## Beacon Setup (ws_bridge.py)

The SDK connects to beacons via WebSocket. Add `ws_bridge.py` to your beacon:

```bash
# Install dependency
pip install websockets

# Run standalone
python ws_bridge.py --port 8765 --rpc https://api.devnet.solana.com

# Or with beacon keypair for co-signing
python ws_bridge.py --port 8765 --keypair ~/.config/solana/id.json
```

To integrate into your existing `beacon.py`:

```python
from ws_bridge import start_ws_bridge

# Start WS bridge in background alongside Reticulum
start_ws_bridge(port=8765, rpc_url=rpc_url, beacon_keypair=keypair)
```

## React Native Integration

```typescript
// App.tsx
import { Anon0meshClient, WebSocketTransport, Keypair } from "@protocol-01/anon0mesh-sdk";
import { useEffect, useState } from "react";

function App() {
  const [client] = useState(() => new Anon0meshClient({
    transport: new WebSocketTransport("ws://your-beacon:8765"),
    keypair: Keypair.generate(),
  }));

  useEffect(() => {
    client.connect();
    return () => { client.disconnect(); };
  }, []);

  const sendPayment = async () => {
    const sig = await client.sendSol(recipientPubkey, 0.1, nonceAccount);
    console.log("Sent:", sig);
  };
}
```

## API Reference

### `Anon0meshClient`

| Method | Description |
|--------|-------------|
| `connect()` | Connect to the beacon transport |
| `disconnect()` | Disconnect |
| `getBalance(address?)` | SOL balance (defaults to own wallet) |
| `getTokenAccounts(owner?)` | SPL token accounts |
| `getSlot()` | Current Solana slot |
| `getBlockHeight()` | Current block height |
| `createNonceAccount()` | Create a durable nonce account |
| `getNonceAccount(pubkey)` | Fetch nonce account state |
| `sendSol(to, amount, nonceAccount)` | Send SOL via durable nonce |
| `sendSolOnline(to, amount)` | Send SOL with regular blockhash |
| `sendArciumPayment(options)` | Encrypted payment via Arcium MPC |

### Transports

| Class | Use Case |
|-------|----------|
| `WebSocketTransport` | Mobile/browser → beacon |
| `DirectRpcTransport` | Direct Solana RPC (no beacon) |
| `BeaconPool` | Multi-beacon with race/fallback |

## Part of Protocol 01

This SDK is built and maintained by [Protocol 01](https://protocol-01.dev) — privacy infrastructure for Solana.

Other packages in the `@protocol-01` ecosystem:

- [`@protocol-01/zk-sdk`](https://www.npmjs.com/package/@protocol-01/zk-sdk) — ZK-SNARK privacy toolkit
- [`@protocol-01/privacy-sdk`](https://www.npmjs.com/package/@protocol-01/privacy-sdk) — High-level privacy API

## License

MIT