@x1scroll/agent-sdk 1.1.2 → 1.2.1

package/package.json

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

package/src/index.js

@@ -21,7 +21,8 @@ const {
   SystemProgram,
   LAMPORTS_PER_SOL,
 } = require('@solana/web3.js');
-const bs58 = require('bs58');
+const bs58   = require('bs58');
+const crypto = require('crypto');
 
 // ── bs58 compat (v4 vs v5 API shape) ─────────────────────────────────────────
 const bs58encode = (typeof bs58.encode === 'function') ? bs58.encode : bs58.default.encode;
@@ -51,15 +52,19 @@ const PROGRAM_ID = new PublicKey('ECgaMEwH4KLSz3awDo1vz84mSrx5n6h1ZCrbmunB5UxB')
  */
 const TREASURY = new PublicKey('GmvrL1ymC9ENuQCUqymC9robGa9t9L59AbFiwhDDd4Ld');
 
-const DEFAULT_RPC_URL = 'https://rpc.x1.xyz';
+const DEFAULT_RPC_URL = 'https://x1scroll.io/rpc';
 
 // ── Anchor instruction discriminators (sha256("global:<name>")[0..8]) ─────────
 // Pre-computed from the IDL. These are fixed for the deployed program version.
 const DISCRIMINATORS = {
-  register_agent:  Buffer.from([135, 157, 66, 55, 116, 253, 50, 45]),
-  store_memory:    Buffer.from([31, 139, 69, 89, 102, 57, 218, 246]),
-  update_agent:    Buffer.from([220, 76, 168, 212, 224, 211, 185, 76]),
-  transfer_agent:  Buffer.from([39, 202, 189, 195, 254, 40, 59, 198]),
+  register_agent:       Buffer.from([135, 157, 66, 55, 116, 253, 50, 45]),
+  store_memory:         Buffer.from([31, 139, 69, 89, 102, 57, 218, 246]),
+  update_agent:         Buffer.from([220, 76, 168, 212, 224, 211, 185, 76]),
+  transfer_agent:       Buffer.from([39, 202, 189, 195, 254, 40, 59, 198]),
+  // v2 discriminators — sha256("global:<name>")[0:8]
+  decision_write:         crypto.createHash('sha256').update('global:decision_write').digest().slice(0, 8),
+  strategy_branch_open:   crypto.createHash('sha256').update('global:strategy_branch_open').digest().slice(0, 8),
+  strategy_branch_close:  crypto.createHash('sha256').update('global:strategy_branch_close').digest().slice(0, 8),
 };
 
 // ── Anchor account discriminators (sha256("account:<Name>")[0..8]) ─────────────
@@ -134,6 +139,27 @@ function encodeU64(n) {
   return buf;
 }
 
+/**
+ * Pad or truncate a label string to exactly 32 bytes (for branch PDA seeds).
+ * @param {string} label
+ * @returns {Buffer}  32-byte buffer
+ */
+function padLabel(label) {
+  const src = Buffer.from(label, 'utf8');
+  const out = Buffer.alloc(32);
+  src.copy(out, 0, 0, Math.min(src.length, 32));
+  return out;
+}
+
+/**
+ * Compute sha256 of a string and return a 32-byte Buffer.
+ * @param {string} s
+ * @returns {Buffer}
+ */
+function sha256Str(s) {
+  return crypto.createHash('sha256').update(s).digest();
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Borsh decoding helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -329,6 +355,54 @@ class AgentClient {
     this._registryCacheExpiry = 0;
   }
 
+  /**
+   * Check RPC connectivity. Throws AgentSDKError with fallback suggestion if unreachable.
+   * @returns {Promise<{ ok: boolean, slot: number, rpcUrl: string }>}
+   */
+  async healthCheck() {
+    const conn = this._getConnection();
+    try {
+      const slot = await Promise.race([
+        conn.getSlot(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 8000)),
+      ]);
+      return { ok: true, slot, rpcUrl: this.rpcUrl };
+    } catch (err) {
+      throw new AgentSDKError(
+        `RPC endpoint unreachable: ${this.rpcUrl}. ` +
+        `Try the public fallback: https://x1scroll.io/rpc\n` +
+        `Original error: ${err.message}`,
+        'RPC_UNREACHABLE',
+        err
+      );
+    }
+  }
+
+  /**
+   * Check that a keypair has sufficient XNT balance for an operation.
+   * Throws AgentSDKError with current balance and required amount if insufficient.
+   * @param {Keypair} keypair
+   * @param {number}  requiredLamports
+   * @param {string}  [operationName]
+   */
+  async _assertSufficientBalance(keypair, requiredLamports, operationName = 'operation') {
+    const conn = this._getConnection();
+    const balance = await conn.getBalance(keypair.publicKey);
+    // Add 5000 lamports buffer for network tx fee
+    const totalRequired = requiredLamports + 5000;
+    if (balance < totalRequired) {
+      const balanceXNT  = (balance / 1e9).toFixed(6);
+      const requiredXNT = (totalRequired / 1e9).toFixed(6);
+      throw new AgentSDKError(
+        `Insufficient balance for ${operationName}. ` +
+        `Have: ${balanceXNT} XNT, Need: ${requiredXNT} XNT. ` +
+        `Fund wallet: ${keypair.publicKey.toBase58()}`,
+        'INSUFFICIENT_BALANCE'
+      );
+    }
+    return balance;
+  }
+
   // ── Internal ────────────────────────────────────────────────────────────────
 
   /** @returns {Connection} */
@@ -492,6 +566,10 @@ class AgentClient {
 
     const humanKeypair = this.keypair;
     const agentPubkey  = agentKeypair.publicKey;
+
+    // ── Pre-flight balance check (0.05 XNT registration fee) ──
+    await this._assertSufficientBalance(humanKeypair, 50_000_000, 'register_agent (0.05 XNT)');
+
     const { pda: agentRecordPDA } = AgentClient.deriveAgentRecord(agentPubkey);
 
     // Borsh-encode instruction data: discriminator + name + metadata_uri
@@ -900,15 +978,299 @@ class AgentClient {
     // Most recent first
     return results.reverse();
   }
+
+  // ── v2 Methods ──────────────────────────────────────────────────────────────
+
+  /**
+   * Write a decision to the on-chain decision tree.
+   *
+   * @param {Keypair}       agentKeypair  The agent keypair (signer + fee payer)
+   * @param {string}        branchLabel   Strategy branch this decision belongs to
+   * @param {string}        cid           IPFS CID of the decision payload
+   * @param {number}        outcome       0=pending, 1=executed, 2=rejected
+   * @param {number}        confidence    0-10000 basis points (8200 = 82%)
+   * @param {Buffer|null}   [parentHash]  32-byte parent decision hash; zeros for root
+   * @returns {Promise<{ sig: string, decisionHash: string, pda: string }>}
+   */
+  async decisionWrite(agentKeypair, branchLabel, cid, outcome, confidence, parentHash = null) {
+    assertIsSigner(agentKeypair, 'agentKeypair');
+    validateString(branchLabel, 'branchLabel', 64);
+    validateString(cid, 'cid', 64);
+
+    // ── Pre-flight balance check (0.001 XNT decision write fee) ──
+    await this._assertSufficientBalance(agentKeypair, 1_000_000, 'decision_write (0.001 XNT)');
+
+    if (typeof outcome !== 'number' || ![0, 1, 2].includes(outcome)) {
+      throw new AgentSDKError('outcome must be 0 (pending), 1 (executed), or 2 (rejected)', 'INVALID_INPUT');
+    }
+    if (typeof confidence !== 'number' || confidence < 0 || confidence > 10000) {
+      throw new AgentSDKError('confidence must be 0-10000 basis points', 'INVALID_INPUT');
+    }
+
+    // Derive decision_hash: sha256(JSON.stringify({cid, branchLabel, timestamp}))
+    const timestamp    = Date.now();
+    const decisionHash = sha256Str(JSON.stringify({ cid, branchLabel, timestamp }));
+
+    // parent_hash: provided Buffer(32) or zeros
+    const parentHashBuf = (parentHash instanceof Buffer && parentHash.length === 32)
+      ? parentHash
+      : Buffer.alloc(32);
+
+    // Derive AgentRecord PDA
+    const { pda: agentRecordPDA } = AgentClient.deriveAgentRecord(agentKeypair.publicKey);
+
+    // Derive DecisionRecord PDA: [b"decision", agentRecord, decision_hash]
+    const [decisionRecordPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('decision'), agentRecordPDA.toBuffer(), decisionHash],
+      PROGRAM_ID
+    );
+
+    // Encode confidence as u32 LE
+    const confidenceBuf = Buffer.alloc(4);
+    confidenceBuf.writeUInt32LE(confidence, 0);
+
+    const data = Buffer.concat([
+      DISCRIMINATORS.decision_write,
+      decisionHash,                  // [u8;32]
+      parentHashBuf,                 // [u8;32]
+      encodeString(branchLabel),     // string (4-byte LE len + utf8)
+      encodeString(cid),             // string
+      Buffer.from([outcome]),        // u8
+      confidenceBuf,                 // u32 LE
+    ]);
+
+    const ix = new TransactionInstruction({
+      programId: PROGRAM_ID,
+      keys: [
+        { pubkey: agentKeypair.publicKey, isSigner: true,  isWritable: true  }, // agent_authority
+        { pubkey: agentRecordPDA,         isSigner: false, isWritable: true  }, // agent_record
+        { pubkey: decisionRecordPDA,      isSigner: false, isWritable: true  }, // decision_record (init)
+        { pubkey: TREASURY,               isSigner: false, isWritable: true  }, // treasury
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false }, // system_program
+      ],
+      data,
+    });
+
+    const tx  = new Transaction().add(ix);
+    const sig = await this._sendAndConfirm(tx, [agentKeypair]);
+
+    return {
+      sig,
+      decisionHash: decisionHash.toString('hex'),
+      pda:          decisionRecordPDA.toBase58(),
+    };
+  }
+
+  /**
+   * Open a new strategy branch on-chain.
+   *
+   * @param {Keypair} agentKeypair   The agent keypair (signer + fee payer)
+   * @param {string}  label          Branch label (max 32 chars — also used for PDA seed)
+   * @param {string}  hypothesis     Branch hypothesis description (max 256 chars)
+   * @param {string}  [parentBranch] Parent branch label, or '' for top-level
+   * @returns {Promise<{ sig: string, branchPda: string }>}
+   */
+  async branchOpen(agentKeypair, label, hypothesis, parentBranch = '') {
+    assertIsSigner(agentKeypair, 'agentKeypair');
+    validateString(label, 'label', 32);
+    validateString(hypothesis, 'hypothesis', 256);
+    if (parentBranch !== '') {
+      validateString(parentBranch, 'parentBranch', 32);
+    }
+
+    const { pda: agentRecordPDA } = AgentClient.deriveAgentRecord(agentKeypair.publicKey);
+
+    // Derive BranchRecord PDA: [b"branch", agentRecord, padLabel(label)]
+    const [branchRecordPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('branch'), agentRecordPDA.toBuffer(), padLabel(label)],
+      PROGRAM_ID
+    );
+
+    const data = Buffer.concat([
+      DISCRIMINATORS.strategy_branch_open,
+      encodeString(label),
+      encodeString(parentBranch),
+      encodeString(hypothesis),
+    ]);
+
+    const ix = new TransactionInstruction({
+      programId: PROGRAM_ID,
+      keys: [
+        { pubkey: agentKeypair.publicKey, isSigner: true,  isWritable: true  }, // agent_authority
+        { pubkey: agentRecordPDA,         isSigner: false, isWritable: true  }, // agent_record
+        { pubkey: branchRecordPDA,        isSigner: false, isWritable: true  }, // branch_record (init)
+        { pubkey: TREASURY,               isSigner: false, isWritable: true  }, // treasury
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false }, // system_program
+      ],
+      data,
+    });
+
+    const tx  = new Transaction().add(ix);
+    const sig = await this._sendAndConfirm(tx, [agentKeypair]);
+
+    return {
+      sig,
+      branchPda: branchRecordPDA.toBase58(),
+    };
+  }
+
+  /**
+   * Close a strategy branch on-chain.
+   *
+   * @param {Keypair} agentKeypair  The agent keypair (signer + fee payer)
+   * @param {string}  label         Branch label to close (must match opened label)
+   * @param {number}  outcome       1=success, 2=failure, 3=abandoned
+   * @param {string}  summaryCid    IPFS CID of the closing summary
+   * @returns {Promise<{ sig: string }>}
+   */
+  async branchClose(agentKeypair, label, outcome, summaryCid) {
+    assertIsSigner(agentKeypair, 'agentKeypair');
+    validateString(label, 'label', 32);
+    validateString(summaryCid, 'summaryCid', 64);
+
+    if (typeof outcome !== 'number' || ![1, 2, 3].includes(outcome)) {
+      throw new AgentSDKError('outcome must be 1 (success), 2 (failure), or 3 (abandoned)', 'INVALID_INPUT');
+    }
+
+    const { pda: agentRecordPDA } = AgentClient.deriveAgentRecord(agentKeypair.publicKey);
+
+    // Derive BranchRecord PDA: [b"branch", agentRecord, padLabel(label)]
+    const [branchRecordPDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from('branch'), agentRecordPDA.toBuffer(), padLabel(label)],
+      PROGRAM_ID
+    );
+
+    const data = Buffer.concat([
+      DISCRIMINATORS.strategy_branch_close,
+      encodeString(label),
+      Buffer.from([outcome]),        // u8
+      encodeString(summaryCid),
+    ]);
+
+    const ix = new TransactionInstruction({
+      programId: PROGRAM_ID,
+      keys: [
+        { pubkey: agentKeypair.publicKey, isSigner: true,  isWritable: true  }, // agent_authority
+        { pubkey: agentRecordPDA,         isSigner: false, isWritable: false }, // agent_record (NOT writable for close)
+        { pubkey: branchRecordPDA,        isSigner: false, isWritable: true  }, // branch_record
+        { pubkey: TREASURY,               isSigner: false, isWritable: true  }, // treasury
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false }, // system_program
+      ],
+      data,
+    });
+
+    const tx  = new Transaction().add(ix);
+    const sig = await this._sendAndConfirm(tx, [agentKeypair]);
+
+    return { sig };
+  }
+
+  /**
+   * Fetch last N decisions/memories from chain for an agent by reading transaction history.
+   * Does NOT call serve_context on-chain (requires validator signature).
+   * Reads transactions directly from RPC and filters for program instructions.
+   *
+   * @param {PublicKey|string} agentPda  The AgentRecord PDA address
+   * @param {number}           [limit]   Max number of entries to return (default 10)
+   * @returns {Promise<{ entries: Array<{slot: number, sig: string, instruction: string, blockTime: number|null}>, count: number }>}
+   */
+  async contextGet(agentPda, limit = 10) {
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new AgentSDKError('limit must be a positive integer', 'INVALID_INPUT');
+    }
+
+    const agentPdaPubkey = new PublicKey(agentPda);
+    const connection     = this._getConnection();
+
+    // Fetch recent signatures for this address
+    const sigs = await connection.getSignaturesForAddress(agentPdaPubkey, { limit });
+
+    const entries = [];
+
+    // Fetch and parse each transaction
+    await Promise.all(sigs.map(async (sigInfo) => {
+      try {
+        const tx = await connection.getParsedTransaction(sigInfo.signature, {
+          maxSupportedTransactionVersion: 0,
+        });
+        if (!tx || !tx.transaction) return;
+
+        const instructions = tx.transaction.message.instructions || [];
+        for (const ix of instructions) {
+          const programId = ix.programId ? ix.programId.toBase58() : null;
+          if (programId !== PROGRAM_ID.toBase58()) continue;
+
+          // Classify instruction type from data discriminator if available
+          let instructionType = 'Unknown';
+          if (ix.data) {
+            try {
+              const rawData = Buffer.from(bs58decode(ix.data));
+              const disc    = rawData.slice(0, 8);
+              if (disc.equals(DISCRIMINATORS.store_memory))          instructionType = 'StoreMemory';
+              else if (disc.equals(DISCRIMINATORS.decision_write))   instructionType = 'DecisionWrite';
+              else if (disc.equals(DISCRIMINATORS.strategy_branch_open))  instructionType = 'BranchOpen';
+              else if (disc.equals(DISCRIMINATORS.strategy_branch_close)) instructionType = 'BranchClose';
+              else if (disc.equals(DISCRIMINATORS.register_agent))   instructionType = 'RegisterAgent';
+            } catch (_) { /* unparseable — leave as Unknown */ }
+          }
+
+          entries.push({
+            slot:        sigInfo.slot,
+            sig:         sigInfo.signature,
+            instruction: instructionType,
+            blockTime:   sigInfo.blockTime || null,
+          });
+          break; // one entry per tx
+        }
+      } catch (_) {
+        // skip transactions we can't parse
+      }
+    }));
+
+    // Sort by slot descending (most recent first)
+    entries.sort((a, b) => b.slot - a.slot);
+
+    return { entries, count: entries.length };
+  }
+
+  /**
+   * Utility: derive the AgentRecord PDA for any public key.
+   *
+   * @param {PublicKey|string} agentPublicKey
+   * @returns {{ pda: PublicKey, bump: number }}
+   */
+  getAgentPda(agentPublicKey) {
+    const [pda, bump] = PublicKey.findProgramAddressSync(
+      [Buffer.from('agent'), new PublicKey(agentPublicKey).toBuffer()],
+      PROGRAM_ID
+    );
+    return { pda, bump };
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Exports
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Standalone utility: derive the AgentRecord PDA for any public key.
+ * Mirrors AgentClient#getAgentPda but available without instantiating a client.
+ *
+ * @param {PublicKey|string} agentPublicKey
+ * @returns {{ pda: PublicKey, bump: number }}
+ */
+function getAgentPda(agentPublicKey) {
+  const [pda, bump] = PublicKey.findProgramAddressSync(
+    [Buffer.from('agent'), new PublicKey(agentPublicKey).toBuffer()],
+    PROGRAM_ID
+  );
+  return { pda, bump };
+}
+
 module.exports = {
   AgentClient,
   AgentSDKError,
+  getAgentPda,
   PROGRAM_ID,
   TREASURY,
   DEFAULT_RPC_URL,