@x1scroll/agent-sdk 1.0.0 → 1.0.1

package/README.md

@@ -116,6 +116,44 @@ const { txSig, memoryEntryPDA } = await client.storeMemory(
 
 ---
 
+### `client.uploadMemory(agentKeypair, agentRecordHuman, topic, content, options?)`
+
+**The easy path** — handles IPFS upload, pinning, and on-chain storage in one call. No IPFS knowledge required.
+
+**Fee:** 0.001 XNT (same as `storeMemory`)
+
+```js
+// Using x1scroll.io IPFS (free, rate-limited — good for dev/testing)
+const { txSig, cid } = await client.uploadMemory(
+  agentKeypair,
+  humanWallet.publicKey.toBase58(),
+  'session-2026-04-06',
+  { summary: 'Discussed SDK launch', decisions: ['publish to npm', 'BSL license'] }
+);
+
+// Using Pinata (production — persistent pinning guaranteed)
+const { txSig, cid } = await client.uploadMemory(
+  agentKeypair,
+  humanWallet.publicKey.toBase58(),
+  'session-2026-04-06',
+  { summary: 'Discussed SDK launch' },
+  { provider: 'pinata', pinataJwt: process.env.PINATA_JWT, tags: ['session', 'daily'] }
+);
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | `string` | `'x1scroll'` | `'pinata'` or `'x1scroll'` |
+| `pinataJwt` | `string` | — | Required if provider is `'pinata'` |
+| `tags` | `string[]` | `[]` | Up to 5 tags |
+| `encrypted` | `boolean` | `false` | Whether content is encrypted |
+
+**Returns:** `Promise<{ txSig: string, memoryEntryPDA: string, cid: string }>`
+
+> **Use `uploadMemory()` if you want zero IPFS configuration.** Use `storeMemory()` directly if you manage your own pinning infrastructure.
+
+---
+
 ### `client.updateAgent(humanKeypair, agentPubkey, name, metadataUri)`
 
 Update an agent's name and metadata URI. Only the human owner can call this.
@@ -313,6 +351,44 @@ Your agent gets smarter. Every session.
 
 ---
 
+## ⚠️ IPFS Pinning — Read This First
+
+`storeMemory()` stores a **pointer** (CID) on-chain — not the content itself. The on-chain record is permanent. The content is only as permanent as your IPFS pin.
+
+**If you don't pin the CID, your content can disappear. The on-chain record will still exist, but it will point to nothing.**
+
+### Pin your CIDs (pick one):
+
+**Pinata (easiest):**
+```js
+const pinata = new PinataSDK({ pinataJwt: process.env.PINATA_JWT });
+const { IpfsHash } = await pinata.upload.json(memoryObject);
+// IpfsHash is your CID — it's already pinned
+await client.storeMemory(agentKeypair, human, topic, IpfsHash, tags);
+```
+
+**Filebase (S3-compatible, cheap):**
+```js
+// Upload to Filebase bucket → get CID → pin is automatic
+```
+
+**Self-hosted (advanced):**
+```bash
+ipfs pin add <CID>
+```
+
+**What the chain gives you:**
+- Immutable, ordered index of memory events
+- Ownership + transferability
+- XNT-gated writes (spam resistance)
+- No single point of failure for the *record*
+
+**What you must provide:**
+- IPFS content pinning (Pinata, Filebase, or your own node)
+- x1scroll.io indexes pinned memories for semantic search — use our RPC for full retrieval stack
+
+---
+
 ## Fee Structure
 
 | Action | XNT Cost | Why |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1scroll/agent-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Agent identity and on-chain memory protocol for X1 blockchain",
   "license": "BSL-1.1",
   "main": "src/index.js",

package/src/index.js

@@ -526,6 +526,98 @@ class AgentClient {
     };
   }
 
+  /**
+   * Upload memory content to IPFS (with auto-pinning) and store the CID on-chain.
+   *
+   * This is the one-stop method for developers who don't want to manage IPFS manually.
+   * It handles: JSON serialization → IPFS upload → pinning → on-chain storeMemory().
+   *
+   * Supported pinning providers:
+   *   - 'pinata'   — requires { pinataJwt } in options
+   *   - 'x1scroll' — uses x1scroll.io IPFS node (free, rate-limited). Default.
+   *
+   * Fee: 0.001 XNT (same as storeMemory — automatic).
+   *
+   * @param {Keypair}  agentKeypair        The agent's keypair — must be a real Signer
+   * @param {string}   agentRecordHuman    The human wallet address that owns this agent
+   * @param {string}   topic               Memory topic label (max 64 chars)
+   * @param {object|string} content        Memory content — object (auto-serialized) or string
+   * @param {object}   [options={}]
+   * @param {string}   [options.provider='x1scroll']  Pinning provider: 'pinata' | 'x1scroll'
+   * @param {string}   [options.pinataJwt]             Required if provider='pinata'
+   * @param {string[]} [options.tags=[]]               Tags (max 5)
+   * @param {boolean}  [options.encrypted=false]       Whether content is encrypted before upload
+   * @returns {Promise<{ txSig: string, memoryEntryPDA: string, cid: string }>}
+   */
+  async uploadMemory(agentKeypair, agentRecordHuman, topic, content, options = {}) {
+    const {
+      provider  = 'x1scroll',
+      pinataJwt = null,
+      tags      = [],
+      encrypted = false,
+    } = options;
+
+    // Serialize content
+    const body = (typeof content === 'string') ? content : JSON.stringify(content);
+
+    let cid;
+
+    if (provider === 'pinata') {
+      if (!pinataJwt) {
+        throw new AgentSDKError(
+          'pinataJwt is required when provider is "pinata". Get one at https://pinata.cloud',
+          'MISSING_PINATA_JWT'
+        );
+      }
+      // Upload to Pinata — returns IpfsHash
+      const res = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
+        method:  'POST',
+        headers: {
+          'Content-Type':  'application/json',
+          'Authorization': `Bearer ${pinataJwt}`,
+        },
+        body: JSON.stringify({ pinataContent: body, pinataMetadata: { name: topic } }),
+      });
+      if (!res.ok) {
+        const err = await res.text();
+        throw new AgentSDKError(`Pinata upload failed: ${err}`, 'PINATA_ERROR');
+      }
+      const json = await res.json();
+      cid = json.IpfsHash;
+
+    } else if (provider === 'x1scroll') {
+      // Upload to x1scroll.io IPFS node (free, rate-limited)
+      const res = await fetch('https://ipfs.x1scroll.io/upload', {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body:    JSON.stringify({ content: body, topic, agentPubkey: agentKeypair.publicKey.toBase58() }),
+      });
+      if (!res.ok) {
+        throw new AgentSDKError(
+          `x1scroll IPFS upload failed (${res.status}). Use provider='pinata' for production workloads.`,
+          'X1SCROLL_IPFS_ERROR'
+        );
+      }
+      const json = await res.json();
+      cid = json.cid;
+
+    } else {
+      throw new AgentSDKError(
+        `Unknown provider "${provider}". Supported: 'pinata', 'x1scroll'`,
+        'INVALID_PROVIDER'
+      );
+    }
+
+    if (!cid) {
+      throw new AgentSDKError('IPFS upload returned no CID', 'NO_CID');
+    }
+
+    // Store CID on-chain
+    const result = await this.storeMemory(agentKeypair, agentRecordHuman, topic, cid, tags, encrypted);
+
+    return { ...result, cid };
+  }
+
   /**
    * Update an agent's name and metadata URI.
    * Only the human owner can call this. Free (network tx fee only).