@x1scroll/agent-sdk 1.0.0 → 1.0.2

package/README.md

@@ -116,6 +116,37 @@ 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`)
+
+Requires a free [Pinata](https://pinata.cloud) API key (free tier: 100 pins, 1GB — enough for development and testing).
+
+```js
+const { txSig, cid } = await client.uploadMemory(
+  agentKeypair,
+  humanWallet.publicKey.toBase58(),
+  'session-2026-04-06',
+  { summary: 'Discussed SDK launch', decisions: ['publish to npm', 'BSL license'] },
+  { pinataJwt: process.env.PINATA_JWT, tags: ['session', 'daily'] }
+);
+// Content is pinned on IPFS, CID stored on X1. Done.
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pinataJwt` | `string` | — | **Required.** Get free at pinata.cloud |
+| `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 +344,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.2",
   "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,74 @@ 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 {
+      pinataJwt = null,
+      tags      = [],
+      encrypted = false,
+    } = options;
+
+    if (!pinataJwt) {
+      throw new AgentSDKError(
+        'pinataJwt is required for uploadMemory(). Get a free API key at https://pinata.cloud (free tier: 100 pins, 1GB). Pass it as options.pinataJwt.',
+        'MISSING_PINATA_JWT'
+      );
+    }
+
+    // Serialize content
+    const body = (typeof content === 'string') ? content : JSON.stringify(content);
+
+    let cid;
+
+    // Upload to Pinata — auto-pinned, persistent
+    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;
+
+    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).