@elisym/mcp 0.2.4 → 0.3.0

package/README.md

@@ -12,33 +12,6 @@ Enables AI assistants (Claude, Cursor, Windsurf, any MCP-compatible client) to d
 
 Currently customer-mode only. To run a provider agent, use [`@elisym/cli`](../cli).
 
-## Flow
-
-```mermaid
-sequenceDiagram
-    participant AI as AI Assistant
-    participant MCP as elisym MCP
-    participant Nostr as Nostr relays
-    participant Prov as Provider agent
-    participant Chain as Settlement layer
-
-    AI->>MCP: find agents by capability
-    MCP->>Nostr: NIP-89 discovery query
-    Nostr-->>MCP: capability cards
-    MCP-->>AI: matching providers
-
-    AI->>MCP: submit job to npub
-    MCP->>Nostr: NIP-90 job request
-    Nostr->>Prov: delivered
-    Prov->>Nostr: NIP-90 feedback payment-required
-    Nostr-->>MCP: feedback
-    MCP->>Chain: pay provider
-    Chain-->>Prov: settled
-    Prov->>Nostr: NIP-90 result
-    Nostr-->>MCP: result
-    MCP-->>AI: job complete
-```
-
 ## Install
 
 ```bash
@@ -165,6 +138,10 @@ Check my wallet balance
 
 The assistant will use elisym MCP tools automatically to discover agents, submit jobs, handle payments, and receive results.
 
+### Agent Skill (Claude Code, Hermes, OpenClaw)
+
+Alongside the MCP server, elisym ships an [agentskills.io](https://agentskills.io)-compatible skill at [`skills/elisym/SKILL.md`](../../skills/elisym/SKILL.md) in the monorepo root. Any agent runtime that reads the agentskills format (Claude Code, Hermes by Nous Research, OpenClaw by Bankr) can drop the file into its skills directory - the skill teaches the agent when to reach for elisym and walks it through discovery, job submission, payment, and result handling on top of this MCP server.
+
 ## Security
 
 `withdraw` and `switch_agent` are gated behind opt-in flags that must be explicitly enabled per-agent:

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { LIMITS, DEFAULT_KIND_OFFSET, ElisymIdentity, ElisymClient, RELAYS, validateAgentName, serializeConfig, toDTag, SolanaPaymentStrategy } from '@elisym/sdk';
-import { Keypair, Connection, PublicKey, sendAndConfirmTransaction, Transaction, SystemProgram } from '@solana/web3.js';
+import { LIMITS, DEFAULT_KIND_OFFSET, SolanaPaymentStrategy, ElisymIdentity, ElisymClient, RELAYS, validateAgentName, serializeConfig, toDTag, getProtocolProgramId, getProtocolConfig } from '@elisym/sdk';
+import { generateKeyPairSigner, createKeyPairSignerFromBytes, createSolanaRpc, address, createSolanaRpcSubscriptions, sendAndConfirmTransactionFactory, getSignatureFromTransaction, pipe, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, isAddress } from '@solana/kit';
 import bs58 from 'bs58';
 import { Command } from 'commander';
 import { nip19, generateSecretKey, getPublicKey } from 'nostr-tools';
@@ -16,6 +16,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSche
 import { z, ZodError } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { randomBytes } from 'node:crypto';
+import { getTransferSolInstruction } from '@solana-program/system';
 
 async function writeFileAtomic(path, content, mode = 384) {
   const tmpPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
@@ -159,11 +160,16 @@ async function listAgentNames() {
     return [];
   }
 }
-
-// src/context.ts
 function rpcUrlFor(network) {
   return network === "mainnet" ? "https://api.mainnet-beta.solana.com" : "https://api.devnet.solana.com";
 }
+async function fetchProtocolConfig(network) {
+  const cluster = network === "mainnet" ? "mainnet" : "devnet";
+  const programId = getProtocolProgramId(cluster);
+  const rpc = createSolanaRpc(rpcUrlFor(cluster));
+  const config = await getProtocolConfig(rpc, programId, { forceRefresh: true });
+  return { feeBps: config.feeBps, treasury: config.treasury };
+}
 function explorerClusterFor(network) {
   return network === "mainnet" ? "mainnet-beta" : "devnet";
 }
@@ -606,6 +612,19 @@ function errorResult(text) {
 }
 
 // src/tools/agent.ts
+async function exportKeyPairBytes(signer) {
+  const { privateKey, publicKey } = signer.keyPair;
+  const [pkcs8, rawPub] = await Promise.all([
+    crypto.subtle.exportKey("pkcs8", privateKey),
+    crypto.subtle.exportKey("raw", publicKey)
+  ]);
+  const privateBytes = new Uint8Array(pkcs8).slice(16);
+  const publicBytes = new Uint8Array(rawPub);
+  const bytes = new Uint8Array(64);
+  bytes.set(privateBytes, 0);
+  bytes.set(publicBytes, 32);
+  return bytes;
+}
 var CreateAgentSchema = z.object({
   name: z.string().min(1).max(64),
   description: z.string().default("Elisym MCP agent"),
@@ -624,7 +643,7 @@ var ListAgentsSchema = z.object({});
 var StopAgentSchema = z.object({
   name: z.string()
 });
-function buildAgentInstance(name, config) {
+async function buildAgentInstance(name, config) {
   let identity;
   if (config.nostrSecretKey.startsWith("nsec")) {
     const decoded = nip19.decode(config.nostrSecretKey);
@@ -639,10 +658,11 @@ function buildAgentInstance(name, config) {
   let solanaKeypair;
   if (config.solanaSecretKey) {
     try {
-      const kp = Keypair.fromSecretKey(bs58.decode(config.solanaSecretKey));
+      const decoded = bs58.decode(config.solanaSecretKey);
+      const signer = await createKeyPairSignerFromBytes(decoded);
       solanaKeypair = {
-        publicKey: kp.publicKey.toBase58(),
-        secretKey: kp.secretKey
+        publicKey: signer.address,
+        secretKey: decoded
       };
     } catch {
       console.error(`[mcp:warn] Invalid Solana key for agent "${name}" - payments disabled`);
@@ -693,21 +713,22 @@ var agentTools = [
         }
       }
       const nostrSecretKey = generateSecretKey();
-      const solanaKeypair = Keypair.generate();
+      const solanaSigner = await generateKeyPairSigner(true);
+      const solanaSecretBytes = await exportKeyPairBytes(solanaSigner);
       const nostrSecretHex = Buffer.from(nostrSecretKey).toString("hex");
-      const solanaSecretBase58 = bs58.encode(solanaKeypair.secretKey);
+      const solanaSecretBase58 = bs58.encode(solanaSecretBytes);
       await saveAgentConfig(input.name, {
         name: input.name,
         description: input.description,
         relays: [...RELAYS],
         nostrSecretKey: nostrSecretHex,
         solanaSecretKey: solanaSecretBase58,
-        solanaAddress: solanaKeypair.publicKey.toBase58(),
+        solanaAddress: solanaSigner.address,
         network: input.network,
         security: { withdrawals_enabled: false, agent_switch_enabled: false },
         passphrase: input.passphrase
       });
-      const instance = buildAgentInstance(input.name, {
+      const instance = await buildAgentInstance(input.name, {
         nostrSecretKey: nostrSecretHex,
         solanaSecretKey: solanaSecretBase58,
         network: input.network,
@@ -717,7 +738,7 @@ var agentTools = [
       return textResult(
         `Agent "${input.name}" created.
 Nostr: ${instance.identity.npub}
-Solana: ${solanaKeypair.publicKey.toBase58()}
+Solana: ${solanaSigner.address}
 ` + (input.activate ? "Activated as current agent." : "")
       );
     }
@@ -762,7 +783,7 @@ Solana: ${solanaKeypair.publicKey.toBase58()}
       }
       try {
         const config = await loadAgentConfig(input.name);
-        const instance = buildAgentInstance(input.name, config);
+        const instance = await buildAgentInstance(input.name, config);
         ctx.register(instance, true);
         const npub = instance.identity.npub;
         return textResult(`Loaded and switched to agent "${input.name}" (${npub}).`);
@@ -1102,6 +1123,10 @@ function providerSolanaAddress(provider, dTag) {
   }
   return void 0;
 }
+function wsUrlFor(httpUrl) {
+  return httpUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
+}
+var paymentStrategy = new SolanaPaymentStrategy();
 async function executePaymentFlow(agent, paymentRequest, jobId, providerPubkey, expectedRecipient) {
   let requestData;
   try {
@@ -1109,25 +1134,30 @@ async function executePaymentFlow(agent, paymentRequest, jobId, providerPubkey,
   } catch {
     throw new Error("Provider sent a malformed payment_request (not valid JSON).");
   }
-  const validation = payment().validatePaymentRequest(paymentRequest, expectedRecipient);
+  const protocolConfig = await fetchProtocolConfig(agent.network);
+  const validation = payment().validatePaymentRequest(
+    paymentRequest,
+    protocolConfig,
+    expectedRecipient
+  );
   if (validation !== null) {
     throw new Error(`Payment validation failed: ${validation.message}`);
   }
   if (!agent.solanaKeypair) {
     throw new Error("Solana payments not configured for this agent.");
   }
-  const keypair = Keypair.fromSecretKey(agent.solanaKeypair.secretKey);
-  const connection = new Connection(rpcUrlFor(agent.network));
-  const tx = await payment().buildTransaction(
-    keypair.publicKey.toBase58(),
-    requestData
-  );
-  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
-  tx.feePayer = keypair.publicKey;
-  const signature = await sendAndConfirmTransaction(connection, tx, [keypair], {
-    commitment: "confirmed",
-    preflightCommitment: "confirmed"
+  const signer = await createKeyPairSignerFromBytes(agent.solanaKeypair.secretKey);
+  const httpUrl = rpcUrlFor(agent.network);
+  const rpc = createSolanaRpc(httpUrl);
+  const signedTx = await paymentStrategy.buildTransaction(requestData, signer, rpc, protocolConfig);
+  const rpcSubscriptions = createSolanaRpcSubscriptions(wsUrlFor(httpUrl));
+  const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
+  await sendAndConfirm(signedTx, {
+    commitment: "confirmed"
   });
+  const signature = getSignatureFromTransaction(
+    signedTx
+  );
   try {
     await agent.client.marketplace.submitPaymentConfirmation(
       agent.identity,
@@ -1930,26 +1960,28 @@ var SendPaymentSchema = z.object({
   expected_solana_recipient: z.string().describe("Base58 Solana address you expect to receive the payment (from the provider card).")
 });
 var WithdrawSchema = z.object({
-  address: z.string().describe("Destination Solana address (base58). Must be a valid PublicKey."),
+  address: z.string().describe("Destination Solana address (base58). Must be a valid address."),
   amount_sol: z.string().describe('Amount in SOL as a decimal string (e.g. "0.5"), or the literal "all".'),
   nonce: z.string().optional().describe("Confirmation nonce from a previous preview call. Omit to request a preview.")
 });
-function agentKeypair(secretKey) {
-  return Keypair.fromSecretKey(secretKey);
+async function agentSigner(secretKey) {
+  return createKeyPairSignerFromBytes(secretKey);
+}
+function rpcFor(agent) {
+  return createSolanaRpc(rpcUrlFor(agent.network));
 }
-function connectionFor(agent) {
-  return new Connection(rpcUrlFor(agent.network));
+function wsUrlFor2(httpUrl) {
+  return httpUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
 }
 function explorerUrl(agent, signature) {
   return `https://explorer.solana.com/tx/${signature}?cluster=${explorerClusterFor(agent.network)}`;
 }
 function assertSolanaAddress(field, value) {
-  try {
-    return new PublicKey(value);
-  } catch {
-    throw new Error(`${field} is not a valid Solana address (base58 PublicKey).`);
+  if (!isAddress(value)) {
+    throw new Error(`${field} is not a valid Solana address.`);
   }
 }
+var paymentStrategy2 = new SolanaPaymentStrategy();
 var walletTools = [
   defineTool({
     name: "get_balance",
@@ -1961,9 +1993,10 @@ var walletTools = [
       if (!agent.solanaKeypair) {
         return errorResult("Solana payments not configured for this agent.");
       }
-      const connection = connectionFor(agent);
-      const pubkey = new PublicKey(agent.solanaKeypair.publicKey);
-      const balance = await connection.getBalance(pubkey);
+      const rpc = rpcFor(agent);
+      const walletAddress = address(agent.solanaKeypair.publicKey);
+      const { value: balanceLamports } = await rpc.getBalance(walletAddress).send();
+      const balance = Number(balanceLamports);
       return textResult(
         `Address: ${agent.solanaKeypair.publicKey}
 Network: ${agent.network}
@@ -1994,32 +2027,39 @@ Balance: ${formatSol(BigInt(balance))} (${balance} lamports)`
       } catch {
         return errorResult("Malformed payment_request: not valid JSON.");
       }
+      const protocolConfig = await fetchProtocolConfig(agent.network);
       const validation = payment().validatePaymentRequest(
         input.payment_request,
+        protocolConfig,
         input.expected_solana_recipient
       );
       if (validation !== null) {
         return errorResult(`Payment validation failed: ${validation.message}`);
       }
-      const keypair = agentKeypair(agent.solanaKeypair.secretKey);
-      const connection = connectionFor(agent);
-      const tx = await payment().buildTransaction(
-        keypair.publicKey.toBase58(),
-        requestData
+      const signer = await agentSigner(agent.solanaKeypair.secretKey);
+      const rpc = rpcFor(agent);
+      const signedTx = await paymentStrategy2.buildTransaction(
+        requestData,
+        signer,
+        rpc,
+        protocolConfig
       );
-      tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
-      tx.feePayer = keypair.publicKey;
-      const signature = await sendAndConfirmTransaction(connection, tx, [keypair], {
-        commitment: "confirmed",
-        preflightCommitment: "confirmed"
+      const httpUrl = rpcUrlFor(agent.network);
+      const rpcSubscriptions = createSolanaRpcSubscriptions(wsUrlFor2(httpUrl));
+      const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
+      await sendAndConfirm(signedTx, {
+        commitment: "confirmed"
       });
-      const balance = await connection.getBalance(keypair.publicKey);
+      const signature = getSignatureFromTransaction(
+        signedTx
+      );
+      const { value: balanceLamports } = await rpc.getBalance(address(agent.solanaKeypair.publicKey)).send();
       return textResult(
         `Payment sent.
   Signature: ${signature}
   Amount: ${formatSol(BigInt(requestData.amount))}
   Recipient: ${requestData.recipient}
-  Remaining balance: ${formatSol(BigInt(balance))}
+  Remaining balance: ${formatSol(balanceLamports)}
   Explorer: ${explorerUrl(agent, signature)}`
       );
     }
@@ -2055,15 +2095,15 @@ Balance: ${formatSol(BigInt(balance))} (${balance} lamports)`
           `Withdrawals are disabled for agent "${agent.name}". Enable with: elisym-mcp enable-withdrawals ${agent.name}`
         );
       }
-      let destination;
       try {
-        destination = assertSolanaAddress("address", input.address);
+        assertSolanaAddress("address", input.address);
       } catch (e) {
         return errorResult(e instanceof Error ? e.message : String(e));
       }
-      const keypair = agentKeypair(agent.solanaKeypair.secretKey);
-      const connection = connectionFor(agent);
-      const balance = BigInt(await connection.getBalance(keypair.publicKey));
+      const signer = await agentSigner(agent.solanaKeypair.secretKey);
+      const rpc = rpcFor(agent);
+      const { value: balanceLamports } = await rpc.getBalance(address(agent.solanaKeypair.publicKey)).send();
+      const balance = balanceLamports;
       const TX_FEE_RESERVE = 5000n;
       let lamports;
       try {
@@ -2115,26 +2155,36 @@ To execute, call withdraw again with the SAME address and amount_sol, plus nonce
           "Nonce does not match the current {agent, address, amount}. Re-run the preview step."
         );
       }
-      const tx = new Transaction().add(
-        SystemProgram.transfer({
-          fromPubkey: keypair.publicKey,
-          toPubkey: destination,
-          lamports
-        })
+      const destination = address(input.address);
+      const transferIx = getTransferSolInstruction({
+        source: signer,
+        destination,
+        amount: lamports
+      });
+      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+      const message = pipe(
+        createTransactionMessage({ version: 0 }),
+        (msg) => setTransactionMessageFeePayerSigner(signer, msg),
+        (msg) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg),
+        (msg) => appendTransactionMessageInstructions([transferIx], msg)
       );
-      tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
-      tx.feePayer = keypair.publicKey;
-      const signature = await sendAndConfirmTransaction(connection, tx, [keypair], {
-        commitment: "confirmed",
-        preflightCommitment: "confirmed"
+      const signedTx = await signTransactionMessageWithSigners(message);
+      const httpUrl = rpcUrlFor(agent.network);
+      const rpcSubscriptions = createSolanaRpcSubscriptions(wsUrlFor2(httpUrl));
+      const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
+      await sendAndConfirm(signedTx, {
+        commitment: "confirmed"
       });
-      const newBalance = BigInt(await connection.getBalance(keypair.publicKey));
+      const signature = getSignatureFromTransaction(
+        signedTx
+      );
+      const { value: newBalanceLamports } = await rpc.getBalance(address(agent.solanaKeypair.publicKey)).send();
       return textResult(
         `Withdrawal complete.
   Signature: ${signature}
   Amount: ${formatSol(lamports)}
   Destination: ${input.address}
-  New balance: ${formatSol(newBalance)}
+  New balance: ${formatSol(newBalanceLamports)}
   Explorer: ${explorerUrl(agent, signature)}`
       );
     }
@@ -2270,8 +2320,9 @@ async function startServer(ctx) {
       if (!agent.solanaKeypair) {
         throw new Error("Solana payments not configured");
       }
-      const connection = new Connection(rpcUrlFor(agent.network));
-      const balance = await connection.getBalance(new PublicKey(agent.solanaKeypair.publicKey));
+      const rpc = createSolanaRpc(rpcUrlFor(agent.network));
+      const { value: balanceLamports } = await rpc.getBalance(address(agent.solanaKeypair.publicKey)).send();
+      const balance = Number(balanceLamports);
       return {
         contents: [
           {
@@ -2343,7 +2394,7 @@ program.action(async () => {
   if (agentName) {
     try {
       const config = await loadAgentConfig(agentName);
-      const instance = buildAgentInstance(agentName, config);
+      const instance = await buildAgentInstance(agentName, config);
       ctx.register(instance);
       console.error(`Loaded agent: ${agentName}`);
     } catch (e) {
@@ -2373,7 +2424,7 @@ program.action(async () => {
       const name = names[0];
       try {
         const config = await loadAgentConfig(name);
-        const instance = buildAgentInstance(name, config);
+        const instance = await buildAgentInstance(name, config);
         ctx.register(instance);
         console.error(`Loaded default agent: ${name} (${instance.network})`);
       } catch (e) {
@@ -2432,14 +2483,15 @@ program.command("init [name]").description("Create a new agent identity").option
   ]);
   const nostrSecretKey = generateSecretKey();
   const nostrPubkey = getPublicKey(nostrSecretKey);
-  const solanaKeypair = Keypair.generate();
+  const solanaSigner = await generateKeyPairSigner(true);
+  const solanaSecretBytes = await exportKeyPairBytes(solanaSigner);
   await saveAgentConfig(name, {
     name,
     description: options.description,
     relays: [...RELAYS],
     nostrSecretKey: Buffer.from(nostrSecretKey).toString("hex"),
-    solanaSecretKey: bs58.encode(solanaKeypair.secretKey),
-    solanaAddress: solanaKeypair.publicKey.toBase58(),
+    solanaSecretKey: bs58.encode(solanaSecretBytes),
+    solanaAddress: solanaSigner.address,
     network: options.network,
     security: { withdrawals_enabled: false, agent_switch_enabled: false },
     passphrase: passphrase || void 0
@@ -2447,7 +2499,7 @@ program.command("init [name]").description("Create a new agent identity").option
   const npub = nip19.npubEncode(nostrPubkey);
   console.log(`Agent "${name}" created.`);
   console.log(`  Nostr: ${npub}`);
-  console.log(`  Solana: ${solanaKeypair.publicKey.toBase58()}`);
+  console.log(`  Solana: ${solanaSigner.address}`);
   console.log(`  Network: ${options.network}`);
   console.log(`  Encrypted: ${passphrase ? "yes" : "no"}`);
   console.log(`  Config: ~/.elisym/agents/${name}/config.json`);