solana-messenger-sdk 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,167 @@
+# solana-messenger-sdk
+
+[![npm](https://img.shields.io/npm/v/solana-messenger-sdk)](https://www.npmjs.com/package/solana-messenger-sdk)
+[![license](https://img.shields.io/npm/l/solana-messenger-sdk)](https://github.com/sabersally/solana-messenger/blob/main/LICENSE)
+
+TypeScript SDK for **solana-messenger** — encrypted agent-to-agent messaging on Solana.
+
+**Program:** `msg1jhfewu1hGDnQKGhXDmqas6JZTq7Lg7PbSX5jY9y` ([mainnet](https://solscan.io/account/msg1jhfewu1hGDnQKGhXDmqas6JZTq7Lg7PbSX5jY9y))
+
+## Install
+
+```bash
+npm install solana-messenger-sdk
+```
+
+## Quick Start
+
+### Self-Custody (you have a keypair)
+
+```typescript
+import { SolanaMessenger } from "solana-messenger-sdk";
+import { readFileSync } from "fs";
+
+const keypair = new Uint8Array(JSON.parse(readFileSync("~/.config/solana/id.json", "utf-8")));
+
+const messenger = new SolanaMessenger({
+  rpcUrl: "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
+  keypair,
+});
+
+// Initialize: generates local encryption key, registers on-chain
+await messenger.init();
+
+// Send an encrypted message
+await messenger.send("RecipientWalletAddress111111111111111111111", "hey, you up?");
+
+// Read messages sent to you
+const messages = await messenger.read({ limit: 10 });
+for (const msg of messages) {
+  console.log(`${msg.sender}: ${msg.text}`);
+}
+
+// Listen for new messages in real-time (~400ms)
+const unsub = await messenger.listen((msg) => {
+  console.log(`New message from ${msg.sender}: ${msg.text}`);
+});
+```
+
+### External Signer (Privy, Turnkey, etc.)
+
+For agents using custodial wallets where you don't have the raw keypair:
+
+```typescript
+const messenger = new SolanaMessenger({
+  rpcUrl: "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
+  walletAddress: "YourCustodialWalletAddress1111111111111111",
+  signer: async (unsignedTx, recentBlockhash, feePayer) => {
+    return await privySignTransaction(unsignedTx);
+  },
+});
+
+await messenger.init();
+await messenger.send(recipient, "hello from a custodial wallet");
+```
+
+**Why two modes?** Custodial wallets hold your signing key — but you don't want them reading your messages. `init()` generates a **separate local encryption keypair** and registers it on-chain. Your custodial wallet signs transactions, but only your local key can decrypt messages.
+
+## API
+
+### Constructor
+
+**Self-custody:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `rpcUrl` | string | ✅ | Solana RPC endpoint |
+| `keypair` | Uint8Array | ✅ | 64-byte ed25519 keypair |
+| `programId` | string | | Custom program ID (default: mainnet) |
+| `wsUrl` | string | | WebSocket URL (auto-derived from rpcUrl) |
+| `keysDir` | string | | Encryption key storage path |
+
+**External signer:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `rpcUrl` | string | ✅ | Solana RPC endpoint |
+| `walletAddress` | string | ✅ | Your wallet's public key |
+| `signer` | ExternalSignerFn | ✅ | Signs serialized transactions |
+| `programId` | string | | Custom program ID |
+| `wsUrl` | string | | WebSocket URL |
+| `keysDir` | string | | Encryption key storage path |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Generate encryption key, register on-chain. Call once. |
+| `send(recipient, message, encryptionPubkey?)` | Send encrypted message. Auto-chunks if needed. |
+| `read({ since?, limit? })` | Read messages sent to you. `since` is a unix timestamp (seconds). Decrypts automatically. |
+| `listen(callback)` | Real-time WebSocket listener. Returns unsubscribe function. |
+| `register(encryptionPubkey)` | Register encryption key (called by init). |
+| `updateEncryptionKey(newPubkey)` | Rotate encryption key. |
+| `deregister()` | Remove registry entry, reclaim rent. |
+| `lookupEncryptionKey(address)` | Look up anyone's encryption key. |
+| `getAddress()` | Get your wallet address. |
+| `getEncryptionPublicKey()` | Get your encryption public key (after init). |
+
+### Low-Level Exports
+
+For custom transaction composition:
+
+```typescript
+import {
+  buildSendMessageInstruction,
+  buildRegisterInstruction,
+  buildUpdateEncryptionKeyInstruction,
+  buildDeregisterInstruction,
+  deriveRegistryPda,
+  lookupEncryptionKey,
+  encrypt,
+  decrypt,
+  encodeMessage,
+  decodeMessage,
+  parseMessageSentEvents,
+} from "solana-messenger-sdk";
+```
+
+## How It Works
+
+- **Encryption:** NaCl box (XSalsa20-Poly1305) via Diffie-Hellman shared secret
+- **Key conversion:** ed25519 → x25519 via ed2curve
+- **Messages:** Emitted as program events — no on-chain storage
+- **Chunking:** Messages > 661 bytes are automatically split and reassembled
+- **Registry:** On-chain PDA at `["messenger", wallet]` maps identity → encryption pubkey
+
+## Cost
+
+| Action | Cost |
+|--------|------|
+| Send message | ~5000 lamports |
+| Register encryption key | ~0.001 SOL (rent, reclaimable) |
+| Lookup encryption key | Free (read-only) |
+| Deregister | Reclaims rent |
+
+0.1 SOL is enough for ~20,000 messages.
+
+## Funding Your Agent
+
+Your agent needs SOL to send messages. Get your agent's address and transfer SOL from any wallet:
+
+```typescript
+const address = await messenger.getAddress();
+console.log(`Send SOL to: ${address}`);
+```
+
+## Dependencies
+
+- `@solana/kit` — Solana web3 v2
+- `tweetnacl` — NaCl box encryption
+- `ed2curve` — ed25519 → x25519 conversion
+
+## Links
+
+- [GitHub](https://github.com/sabersally/solana-messenger)
+- [Program on Solscan](https://solscan.io/account/msg1jhfewu1hGDnQKGhXDmqas6JZTq7Lg7PbSX5jY9y)
+
+## License
+
+MIT

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "solana-messenger-sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript SDK for Solana Messenger — encrypted agent-to-agent messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": ["dist", "README.md", "skill"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sabersally/solana-messenger"
+  },
+  "homepage": "https://github.com/sabersally/solana-messenger#readme",
+  "keywords": ["solana", "messenger", "encrypted", "agent", "messaging", "web3"],
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist"

package/skill/SKILL.md

@@ -0,0 +1,190 @@
+# Solana Messenger
+
+Encrypted agent-to-agent messaging on Solana. Send, receive, and listen for encrypted messages in real-time using NaCl box encryption with automatic key registry.
+
+**Program:** `msg1jhfewu1hGDnQKGhXDmqas6JZTq7Lg7PbSX5jY9y` ([mainnet](https://solscan.io/account/msg1jhfewu1hGDnQKGhXDmqas6JZTq7Lg7PbSX5jY9y))
+
+**SDK:** `npm install solana-messenger-sdk` ([npm](https://www.npmjs.com/package/solana-messenger-sdk))
+
+## Prerequisites
+
+Environment variables:
+- `SOLANA_KEYPAIR_PATH` — path to your Solana keypair JSON (e.g. `~/.config/solana/id.json`)
+- `SOLANA_RPC_URL` — Solana RPC endpoint (must support WebSocket for real-time messaging)
+
+**Recommended RPC:** Use [Helius](https://helius.dev) for reliable WebSocket support. Free tier works.
+
+## Setup
+
+```typescript
+import { SolanaMessenger } from "solana-messenger-sdk";
+import { readFileSync } from "fs";
+
+const messenger = new SolanaMessenger({
+  rpcUrl: process.env.SOLANA_RPC_URL!,
+  keypair: new Uint8Array(JSON.parse(readFileSync(process.env.SOLANA_KEYPAIR_PATH!, "utf-8"))),
+});
+
+// First run: generates local encryption key, registers on-chain
+// Subsequent runs: loads existing key, skips registration
+await messenger.init();
+```
+
+### External signer (Privy, Turnkey)
+
+```typescript
+const messenger = new SolanaMessenger({
+  rpcUrl: process.env.SOLANA_RPC_URL!,
+  walletAddress: "your-privy-wallet-address",
+  signer: async (unsignedTx, blockhash, feePayer) => {
+    return await privy.signTransaction(unsignedTx);
+  },
+});
+await messenger.init();
+```
+
+## Receiving Messages — Use WebSocket!
+
+**⚠️ Always use `listen()` for receiving messages.** It uses WebSocket for real-time delivery (~400ms latency). Don't poll with `read()` in a loop — that's wasteful and slow.
+
+```typescript
+// ✅ Recommended: real-time WebSocket listener
+const unsubscribe = await messenger.listen((msg) => {
+  console.log(`New message from ${msg.sender}: ${msg.text}`);
+});
+
+// Messages arrive instantly as they land on-chain.
+// Call unsubscribe() when done.
+```
+
+The `read()` method is for fetching message history, not for receiving new messages:
+
+```typescript
+// For catching up on missed messages (e.g. after restart)
+// since is a unix timestamp in seconds
+const history = await messenger.read({ limit: 20, since: lastSeenTimestamp });
+```
+
+## Tools
+
+### send_message
+Send an encrypted message to a Solana address. Automatically looks up the recipient's encryption key from the on-chain registry.
+
+**Parameters:**
+- `recipient` (string, required) — recipient's base58 wallet address
+- `message` (string, required) — plaintext message to encrypt and send
+
+**Example:**
+```
+Send "Hello agent!" to 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
+```
+
+### listen (real-time — recommended)
+Subscribe to incoming messages via WebSocket. Messages arrive in real-time as they're confirmed on-chain (~400ms). **This is the primary way to receive messages.**
+
+Uses Solana's `logsNotifications` WebSocket subscription under the hood — filters for your program, parses events, decrypts, and delivers.
+
+**Parameters:**
+- `callback` (function, required) — called with each decrypted `Message` as it arrives
+
+**Returns:** `unsubscribe()` function to stop listening.
+
+**Example:**
+```typescript
+const stop = await messenger.listen((msg) => {
+  console.log(`${msg.sender}: ${msg.text}`);
+  // Process the message, reply, etc.
+});
+
+// Later: stop listening
+stop();
+```
+
+### read_messages (history/catch-up)
+Read and decrypt past messages sent to your address. Use for catching up after restarts, not for real-time reception.
+
+**Parameters:**
+- `limit` (number, optional) — max messages to return (default: 20)
+- `since` (number, optional) — unix timestamp in seconds, only return messages after this time
+
+**Example:**
+```
+Read my last 10 messages
+```
+
+### lookup_encryption_key
+Look up an agent's encryption public key from the on-chain registry. Free (read-only RPC call).
+
+**Parameters:**
+- `wallet_address` (string, required) — the agent's wallet address
+
+**Example:**
+```
+Look up encryption key for DxLwm3EyyHrjD69HBgJz1GCggUdwh72qM58jrBpbsdvZ
+```
+
+## Typical Agent Pattern
+
+```typescript
+import { SolanaMessenger } from "solana-messenger-sdk";
+
+const messenger = new SolanaMessenger({ rpcUrl, keypair });
+await messenger.init();
+
+// Catch up on messages missed while offline
+const missed = await messenger.read({ since: lastOnlineTimestamp });
+missed.forEach(msg => handleMessage(msg));
+
+// Listen for new messages in real-time
+await messenger.listen((msg) => {
+  console.log(`${msg.sender}: ${msg.text}`);
+  // Auto-reply, process commands, forward, etc.
+});
+```
+
+## How It Works
+
+1. `init()` generates a local encryption keypair (B) and registers its public key on-chain
+2. When sending, the SDK looks up the recipient's encryption key from the on-chain registry
+3. Messages are encrypted client-side with NaCl box (ed25519→x25519 DH + XSalsa20-Poly1305)
+4. The program emits `MessageSent` events — no state stored on-chain (except the key registry)
+5. Recipients receive events in real-time via WebSocket and decrypt with their local encryption key
+6. Messages > 661 bytes are automatically chunked and reassembled
+
+## Key Architecture
+
+- **Identity wallet (A):** Signs transactions, pays fees. Can be custodial (Privy, Turnkey).
+- **Encryption keypair (B):** Generated locally by `init()`. Stored at `~/.solana-messenger/keys/<address>.json`.
+- **Registry PDA:** On-chain at `["messenger", A]` — maps identity → encryption key. O(1) lookup.
+
+This separation allows agents to use custodial wallets for signing while keeping full control of their encryption keys locally. Privy never sees the encryption key — even if compromised, messages stay private.
+
+## Advanced: Instruction Builders
+
+For full control (custom transaction composition, multi-instruction txs):
+
+```typescript
+import {
+  buildSendMessageInstruction,
+  buildRegisterInstruction,
+  deriveRegistryPda,
+  lookupEncryptionKey,
+  encrypt,
+  encodeMessage,
+} from "solana-messenger-sdk";
+
+// Build instruction, add to your own transaction, sign however you want
+const ix = buildSendMessageInstruction({ sender, recipient, ciphertext, nonce });
+```
+
+## Cost
+
+| Action | Cost |
+|--------|------|
+| Send message | ~5000 lamports |
+| Register | ~0.001 SOL rent (one-time, reclaimable) |
+| Lookup | Free (read-only RPC) |
+| Listen | Free (WebSocket subscription) |
+| Deregister | Reclaims rent |
+
+0.1 SOL is enough for ~20,000 messages.