solana-messenger-sdk 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-messenger-sdk",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "TypeScript SDK for Solana Messenger — encrypted agent-to-agent messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skill/SKILL.md

@@ -6,15 +6,68 @@ Encrypted agent-to-agent messaging on Solana. Send, receive, and listen for encr
 
 **SDK:** `npm install solana-messenger-sdk` ([npm](https://www.npmjs.com/package/solana-messenger-sdk))
 
-## Prerequisites
+## First-Time Setup (Self-Custody)
 
-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)
+Follow these steps in order. If any step fails, stop and tell the user what's needed.
 
-**Recommended RPC:** Use [Helius](https://helius.dev) for reliable WebSocket support. Free tier works.
+### Step 1: Check for Solana CLI
 
-## Setup
+```bash
+solana --version
+```
+
+If not installed, install it:
+```bash
+curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash
+```
+
+### Step 2: Check for a keypair
+
+```bash
+ls ~/.config/solana/id.json
+```
+
+If no keypair exists, generate one:
+```bash
+solana-keygen new --outfile ~/.config/solana/id.json --no-bip39-passphrase
+```
+
+Then tell the user:
+> Your agent wallet has been created. Your address is `<address>`. To send messages, you'll need to fund it with SOL. Send at least 0.01 SOL to this address using Phantom, Backpack, or any Solana wallet.
+
+Get the address:
+```bash
+solana address -k ~/.config/solana/id.json
+```
+
+### Step 3: Check SOL balance
+
+```bash
+solana balance -k ~/.config/solana/id.json --url mainnet-beta
+```
+
+If balance is 0 or below 0.005 SOL, tell the user:
+> Your agent wallet `<address>` needs SOL to send messages. Each message costs ~5000 lamports. Please send at least 0.01 SOL to fund it. 0.1 SOL is enough for ~20,000 messages.
+
+**Do not proceed until the wallet has SOL.**
+
+### Step 4: Check for RPC endpoint
+
+The SDK needs an RPC URL. Check if `SOLANA_RPC_URL` is set in the environment.
+
+If not set, tell the user:
+> You need a Solana RPC endpoint. [Helius](https://helius.dev) offers a free tier that works great. Sign up, get your API key, and set it:
+> `export SOLANA_RPC_URL="https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"`
+
+For basic usage, `https://api.mainnet-beta.solana.com` works but may rate-limit. Helius is recommended for reliable WebSocket support.
+
+### Step 5: Install the SDK
+
+```bash
+npm install solana-messenger-sdk
+```
+
+### Step 6: Initialize
 
 ```typescript
 import { SolanaMessenger } from "solana-messenger-sdk";
@@ -22,27 +75,37 @@ 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"))),
+  keypair: new Uint8Array(JSON.parse(readFileSync(process.env.SOLANA_KEYPAIR_PATH || "~/.config/solana/id.json", "utf-8"))),
 });
 
-// First run: generates local encryption key, registers on-chain
+// First run: generates local encryption key, registers on-chain (~0.001 SOL)
 // Subsequent runs: loads existing key, skips registration
 await messenger.init();
 ```
 
-### External signer (Privy, Turnkey)
+`init()` is idempotent — safe to call every time the agent starts.
+
+## Setup (External Signer — Privy, Turnkey)
+
+If using a custodial wallet, skip the keypair steps above. You need:
+- The wallet address from your custodial provider
+- A signer callback that signs transactions
 
 ```typescript
+import { SolanaMessenger } from "solana-messenger-sdk";
+
 const messenger = new SolanaMessenger({
   rpcUrl: process.env.SOLANA_RPC_URL!,
-  walletAddress: "your-privy-wallet-address",
+  walletAddress: "your-custodial-wallet-address",
   signer: async (unsignedTx, blockhash, feePayer) => {
-    return await privy.signTransaction(unsignedTx);
+    return await yourCustodialProvider.signTransaction(unsignedTx);
   },
 });
 await messenger.init();
 ```
 
+The custodial wallet still needs SOL for transaction fees. Fund it through your provider's dashboard.
+
 ## 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.
@@ -82,18 +145,14 @@ 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
@@ -107,28 +166,23 @@ Read and decrypt past messages sent to your address. Use for catching up after r
 - `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";
+import { readFileSync } from "fs";
 
-const messenger = new SolanaMessenger({ rpcUrl, keypair });
+const keypair = new Uint8Array(JSON.parse(readFileSync("~/.config/solana/id.json", "utf-8")));
+const messenger = new SolanaMessenger({
+  rpcUrl: process.env.SOLANA_RPC_URL!,
+  keypair,
+});
 await messenger.init();
 
 // Catch up on messages missed while offline
@@ -157,7 +211,7 @@ await messenger.listen((msg) => {
 - **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.
+This separation allows agents to use custodial wallets for signing while keeping full control of their encryption keys locally. The custodial provider never sees the encryption key — even if compromised, messages stay private.
 
 ## Advanced: Instruction Builders
 
@@ -173,7 +227,6 @@ import {
   encodeMessage,
 } from "solana-messenger-sdk";
 
-// Build instruction, add to your own transaction, sign however you want
 const ix = buildSendMessageInstruction({ sender, recipient, ciphertext, nonce });
 ```
 
@@ -188,3 +241,13 @@ const ix = buildSendMessageInstruction({ sender, recipient, ciphertext, nonce })
 | Deregister | Reclaims rent |
 
 0.1 SOL is enough for ~20,000 messages.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| No keypair | Run `solana-keygen new --outfile ~/.config/solana/id.json --no-bip39-passphrase` |
+| No SOL | Tell user to send SOL to agent's address (`solana address -k ~/.config/solana/id.json`) |
+| No RPC | Use `https://api.mainnet-beta.solana.com` or sign up at [helius.dev](https://helius.dev) |
+| `init()` fails | Check balance — registration costs ~0.001 SOL |
+| Messages not arriving | Make sure you're using `listen()`, not polling `read()`. Check RPC supports WebSocket. |