@x1scroll/agent-sdk 1.2.0 → 1.2.2

package/package.json

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

package/src/index.js

@@ -52,7 +52,7 @@ 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.
@@ -326,25 +326,26 @@ class AgentClient {
    *   X1 RPC endpoint (default: https://rpc.x1.xyz).
    *   Use https://rpc.x1scroll.io for our dedicated node.
    */
-  constructor({ wallet = null, rpcUrl = DEFAULT_RPC_URL } = {}) {
-    // ── resolve wallet ──
-    if (wallet === null || wallet === undefined) {
+  constructor({ wallet = null, keypair = null, rpcUrl = DEFAULT_RPC_URL } = {}) {
+    // ── resolve wallet — accept both `wallet` and `keypair` param names ──
+    const resolvedWallet = wallet || keypair;
+    if (resolvedWallet === null || resolvedWallet === undefined) {
       this.keypair       = null;
       this.walletAddress = null;
-    } else if (wallet instanceof Keypair) {
-      this.keypair       = wallet;
-      this.walletAddress = wallet.publicKey.toBase58();
-    } else if (typeof wallet === 'string') {
-      const secretKey    = bs58decode(wallet);
+    } else if (resolvedWallet instanceof Keypair) {
+      this.keypair       = resolvedWallet;
+      this.walletAddress = resolvedWallet.publicKey.toBase58();
+    } else if (typeof resolvedWallet === 'string') {
+      const secretKey    = bs58decode(resolvedWallet);
       this.keypair       = Keypair.fromSecretKey(secretKey);
       this.walletAddress = this.keypair.publicKey.toBase58();
-    } else if (wallet && wallet.secretKey && wallet.publicKey) {
+    } else if (resolvedWallet && resolvedWallet.secretKey && resolvedWallet.publicKey) {
       // Keypair-like object
-      this.keypair       = wallet;
-      this.walletAddress = wallet.publicKey.toBase58();
+      this.keypair       = resolvedWallet;
+      this.walletAddress = resolvedWallet.publicKey.toBase58();
     } else {
       throw new AgentSDKError(
-        'wallet must be a Keypair, a base58 secret key string, or null',
+        'wallet (or keypair) must be a Keypair, a base58 secret key string, or null',
         'INVALID_WALLET'
       );
     }
@@ -355,6 +356,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} */
@@ -518,6 +567,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
@@ -940,16 +993,42 @@ class AgentClient {
    * @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) {
+  async decisionWrite(agentKeypair, branchLabelOrMessage, cidOrOpts, outcome, confidence, parentHash = null) {
     assertIsSigner(agentKeypair, 'agentKeypair');
+
+    // ── Simple overload: decisionWrite(keypair, type, message) ──
+    // Allows: client.decisionWrite(kp, 'trade', 'bought XNT at 0.34')
+    // Internally maps to branchLabel=type, cid=sha256(message), outcome=1, confidence=9000
+    let branchLabel, cid;
+    if (typeof cidOrOpts === 'string' && cidOrOpts.length < 64 && !cidOrOpts.startsWith('Qm') && outcome === undefined) {
+      branchLabel = branchLabelOrMessage;
+      // Hash the message string into a pseudo-CID for on-chain storage
+      cid         = 'msg:' + crypto.createHash('sha256').update(cidOrOpts).digest('hex').slice(0, 44);
+      outcome     = 1;    // executed
+      confidence  = 9000; // 90%
+    } else {
+      branchLabel = branchLabelOrMessage;
+      cid         = cidOrOpts;
+    }
+
     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');
+      throw new AgentSDKError(
+        `outcome must be 0 (pending), 1 (executed), or 2 (rejected) — got: ${JSON.stringify(outcome)}. ` +
+        'Tip: use the simple form decisionWrite(keypair, type, message) to skip outcome/confidence.',
+        'INVALID_INPUT'
+      );
     }
     if (typeof confidence !== 'number' || confidence < 0 || confidence > 10000) {
-      throw new AgentSDKError('confidence must be 0-10000 basis points', 'INVALID_INPUT');
+      throw new AgentSDKError(
+        `confidence must be 0-10000 basis points — got: ${JSON.stringify(confidence)}`,
+        'INVALID_INPUT'
+      );
     }
 
     // Derive decision_hash: sha256(JSON.stringify({cid, branchLabel, timestamp}))
@@ -1124,8 +1203,17 @@ class AgentClient {
       throw new AgentSDKError('limit must be a positive integer', 'INVALID_INPUT');
     }
 
-    const agentPdaPubkey = new PublicKey(agentPda);
-    const connection     = this._getConnection();
+    let agentPdaPubkey;
+    try {
+      agentPdaPubkey = new PublicKey(agentPda);
+    } catch (err) {
+      throw new AgentSDKError(
+        `contextGet: invalid agentPda — expected a base58 public key, got: ${JSON.stringify(agentPda)}`,
+        'INVALID_INPUT', err
+      );
+    }
+
+    const connection = this._getConnection();
 
     // Fetch recent signatures for this address
     const sigs = await connection.getSignaturesForAddress(agentPdaPubkey, { limit });
@@ -1167,8 +1255,15 @@ class AgentClient {
           });
           break; // one entry per tx
         }
-      } catch (_) {
-        // skip transactions we can't parse
+      } catch (err) {
+        // Log parse failures but don't block — one bad tx shouldn't kill the whole query
+        entries.push({
+          slot:        sigInfo.slot,
+          sig:         sigInfo.signature,
+          instruction: 'ParseError',
+          error:       err.message || String(err),
+          blockTime:   sigInfo.blockTime || null,
+        });
       }
     }));