@alleyboss/micropay-solana-x402-paywall 2.3.0 → 2.3.1

package/README.md

@@ -54,7 +54,7 @@ if (result.valid) {
 
 ## 🔧 Modules
 
-9 tree-shakeable entry points for minimal bundle size:
+10 tree-shakeable entry points for minimal bundle size:
 
 ```typescript
 // Core verification
@@ -80,8 +80,42 @@ import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/mi
 
 // Retry utilities
 import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
+
+// 🆕 AI Agent Payments (v2.3.0)
+import { executeAgentPayment, getAgentBalance } from '@alleyboss/micropay-solana-x402-paywall/agent';
 ```
 
+## 🤖 AI Agent Payments (NEW in v2.3.0)
+
+Enable autonomous AI agents to pay for premium API access without user intervention:
+
+```typescript
+import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
+import { Keypair, Connection } from '@solana/web3.js';
+
+// Server-side: Load agent keypair from environment
+const agentKeypair = Keypair.fromSecretKey(
+  Uint8Array.from(process.env.AGENT_SECRET.split(',').map(Number))
+);
+
+// Execute autonomous payment
+const result = await executeAgentPayment({
+  connection: new Connection('https://api.devnet.solana.com'),
+  agentKeypair,
+  recipientAddress: 'CREATOR_WALLET',
+  amountLamports: BigInt(2_000_000), // 0.002 SOL
+  priorityFee: { enabled: true, microLamports: 5000 },
+});
+
+if (result.success) {
+  console.log('Payment confirmed:', result.signature);
+  // Deliver premium content to AI agent
+}
+```
+
+**Live Demo:** [solana-x402-paywall.vercel.app/agent-chat](https://solana-x402-paywall.vercel.app/agent-chat)
+
+
 ## 🔥 New in v2.2.0
 
 ### x402 Protocol Compliance

package/dist/agent/index.cjs

@@ -0,0 +1,359 @@
+'use strict';
+
+var web3_js = require('@solana/web3.js');
+var jose = require('jose');
+var uuid = require('uuid');
+
+// src/agent/agentPayment.ts
+var DEFAULT_COMPUTE_UNITS = 2e5;
+var DEFAULT_MICRO_LAMPORTS = 1e3;
+function createPriorityFeeInstructions(config = {}) {
+  const { enabled = false, microLamports, computeUnits } = config;
+  if (!enabled) {
+    return [];
+  }
+  const instructions = [];
+  const units = computeUnits ?? DEFAULT_COMPUTE_UNITS;
+  instructions.push(web3_js.ComputeBudgetProgram.setComputeUnitLimit({ units }));
+  const price = microLamports ?? DEFAULT_MICRO_LAMPORTS;
+  instructions.push(web3_js.ComputeBudgetProgram.setComputeUnitPrice({ microLamports: price }));
+  return instructions;
+}
+async function buildVersionedTransaction(config) {
+  const {
+    connection,
+    payer,
+    instructions,
+    lookupTables = [],
+    priorityFee,
+    recentBlockhash
+  } = config;
+  const priorityIxs = createPriorityFeeInstructions(priorityFee);
+  const allInstructions = [...priorityIxs, ...instructions];
+  let blockhash;
+  let lastValidBlockHeight;
+  if (recentBlockhash) {
+    blockhash = recentBlockhash;
+    const slot = await connection.getSlot();
+    lastValidBlockHeight = slot + 150;
+  } else {
+    const latestBlockhash = await connection.getLatestBlockhash("confirmed");
+    blockhash = latestBlockhash.blockhash;
+    lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;
+  }
+  const message = new web3_js.TransactionMessage({
+    payerKey: payer,
+    recentBlockhash: blockhash,
+    instructions: allInstructions
+  }).compileToV0Message(lookupTables);
+  const transaction = new web3_js.VersionedTransaction(message);
+  return {
+    transaction,
+    blockhash,
+    lastValidBlockHeight
+  };
+}
+
+// src/agent/agentPayment.ts
+var WALLET_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+function isValidWalletAddress(address) {
+  if (!address || typeof address !== "string") return false;
+  return WALLET_REGEX.test(address);
+}
+async function executeAgentPayment(params) {
+  const {
+    connection,
+    agentKeypair,
+    recipientAddress,
+    amountLamports,
+    priorityFee,
+    confirmationTimeout = 6e4
+  } = params;
+  if (!isValidWalletAddress(recipientAddress)) {
+    return {
+      success: false,
+      error: "Invalid recipient address format"
+    };
+  }
+  if (amountLamports <= 0n) {
+    return {
+      success: false,
+      error: "Amount must be greater than 0"
+    };
+  }
+  try {
+    const recipientPubkey = new web3_js.PublicKey(recipientAddress);
+    const transferInstruction = web3_js.SystemProgram.transfer({
+      fromPubkey: agentKeypair.publicKey,
+      toPubkey: recipientPubkey,
+      lamports: amountLamports
+    });
+    const { transaction, lastValidBlockHeight } = await buildVersionedTransaction({
+      connection,
+      payer: agentKeypair.publicKey,
+      instructions: [transferInstruction],
+      priorityFee
+    });
+    transaction.sign([agentKeypair]);
+    const signature = await connection.sendTransaction(transaction, {
+      maxRetries: 3,
+      skipPreflight: false
+    });
+    const confirmationPromise = connection.confirmTransaction(
+      {
+        signature,
+        lastValidBlockHeight,
+        blockhash: transaction.message.recentBlockhash
+      },
+      "confirmed"
+    );
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("Confirmation timeout")), confirmationTimeout);
+    });
+    const confirmation = await Promise.race([confirmationPromise, timeoutPromise]);
+    if (confirmation.value.err) {
+      return {
+        success: false,
+        signature,
+        error: "Transaction failed on-chain"
+      };
+    }
+    const txDetails = await connection.getTransaction(signature, {
+      commitment: "confirmed",
+      maxSupportedTransactionVersion: 0
+    });
+    return {
+      success: true,
+      signature,
+      confirmedAt: txDetails?.blockTime ?? Math.floor(Date.now() / 1e3),
+      slot: txDetails?.slot ?? confirmation.context.slot,
+      amountLamports,
+      amountSol: Number(amountLamports) / web3_js.LAMPORTS_PER_SOL
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    return {
+      success: false,
+      error: errorMessage
+    };
+  }
+}
+async function getAgentBalance(connection, agentKeypair) {
+  const balance = await connection.getBalance(agentKeypair.publicKey);
+  return {
+    balance: BigInt(balance),
+    balanceSol: balance / web3_js.LAMPORTS_PER_SOL
+  };
+}
+async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports) {
+  const { balance } = await getAgentBalance(connection, agentKeypair);
+  const totalRequired = requiredLamports + 10000n;
+  return {
+    sufficient: balance >= totalRequired,
+    balance,
+    required: totalRequired
+  };
+}
+function keypairFromBase58(base58Secret) {
+  const bytes = Buffer.from(base58Secret, "base64");
+  if (bytes.length !== 64) {
+    const parts = base58Secret.split(",").map((n) => parseInt(n.trim(), 10));
+    if (parts.length === 64) {
+      return web3_js.Keypair.fromSecretKey(Uint8Array.from(parts));
+    }
+    throw new Error("Invalid secret key format. Expected base58 string or comma-separated bytes.");
+  }
+  return web3_js.Keypair.fromSecretKey(bytes);
+}
+function generateAgentKeypair() {
+  const keypair = web3_js.Keypair.generate();
+  const secretBytes = Array.from(keypair.secretKey);
+  return {
+    keypair,
+    secretBase58: secretBytes.join(","),
+    // Comma-separated for easy storage
+    publicKey: keypair.publicKey.toBase58()
+  };
+}
+var MAX_CREDITS = 1e3;
+var MIN_SECRET_LENGTH = 32;
+function getSecretKey(secret) {
+  if (!secret || typeof secret !== "string") {
+    throw new Error("Session secret is required");
+  }
+  if (secret.length < MIN_SECRET_LENGTH) {
+    throw new Error(`Session secret must be at least ${MIN_SECRET_LENGTH} characters`);
+  }
+  return new TextEncoder().encode(secret);
+}
+function validateWalletAddress(address) {
+  if (!address || typeof address !== "string") return false;
+  const base58Regex = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+  return base58Regex.test(address);
+}
+async function createCreditSession(walletAddress, purchaseId, config) {
+  if (!validateWalletAddress(walletAddress)) {
+    throw new Error("Invalid wallet address format");
+  }
+  if (config.initialCredits <= 0 || config.initialCredits > MAX_CREDITS) {
+    throw new Error(`Credits must be between 1 and ${MAX_CREDITS}`);
+  }
+  if (!config.durationHours || config.durationHours <= 0 || config.durationHours > 8760) {
+    throw new Error("Session duration must be between 1 and 8760 hours (1 year)");
+  }
+  const sessionId = uuid.v4();
+  const now = Math.floor(Date.now() / 1e3);
+  const expiresAt = now + config.durationHours * 3600;
+  const bundleExpiry = config.bundleExpiryHours ? now + config.bundleExpiryHours * 3600 : expiresAt;
+  const session = {
+    id: sessionId,
+    walletAddress,
+    unlockedArticles: [purchaseId],
+    siteWideUnlock: false,
+    createdAt: now,
+    expiresAt,
+    credits: config.initialCredits,
+    bundleExpiry,
+    bundleType: config.bundleType
+  };
+  const payload = {
+    sub: walletAddress,
+    sid: sessionId,
+    articles: session.unlockedArticles,
+    siteWide: false,
+    credits: config.initialCredits,
+    bundleExpiry,
+    bundleType: config.bundleType,
+    iat: now,
+    exp: expiresAt
+  };
+  const token = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(`${config.durationHours}h`).sign(getSecretKey(config.secret));
+  return { token, session };
+}
+async function validateCreditSession(token, secret) {
+  if (!token || typeof token !== "string") {
+    return { valid: false, reason: "Invalid token format" };
+  }
+  try {
+    const { payload } = await jose.jwtVerify(token, getSecretKey(secret));
+    const creditPayload = payload;
+    if (!creditPayload.sub || !creditPayload.sid || !creditPayload.exp) {
+      return { valid: false, reason: "Malformed session payload" };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (creditPayload.exp < now) {
+      return { valid: false, reason: "Session expired" };
+    }
+    if (creditPayload.bundleExpiry && creditPayload.bundleExpiry < now) {
+      return { valid: false, reason: "Bundle expired" };
+    }
+    if (!validateWalletAddress(creditPayload.sub)) {
+      return { valid: false, reason: "Invalid session data" };
+    }
+    const session = {
+      id: creditPayload.sid,
+      walletAddress: creditPayload.sub,
+      unlockedArticles: Array.isArray(creditPayload.articles) ? creditPayload.articles : [],
+      siteWideUnlock: Boolean(creditPayload.siteWide),
+      createdAt: creditPayload.iat ?? 0,
+      expiresAt: creditPayload.exp,
+      credits: creditPayload.credits ?? 0,
+      bundleExpiry: creditPayload.bundleExpiry,
+      bundleType: creditPayload.bundleType
+    };
+    return { valid: true, session };
+  } catch {
+    return { valid: false, reason: "Invalid session" };
+  }
+}
+async function useCredit(token, secret, creditsToUse = 1) {
+  if (creditsToUse <= 0) {
+    return { success: false, remainingCredits: 0, error: "Invalid credit amount" };
+  }
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return {
+      success: false,
+      remainingCredits: 0,
+      error: validation.reason || "Invalid session"
+    };
+  }
+  const session = validation.session;
+  if (session.credits < creditsToUse) {
+    return {
+      success: false,
+      remainingCredits: session.credits,
+      error: "Insufficient credits"
+    };
+  }
+  const newCredits = session.credits - creditsToUse;
+  const payload = {
+    sub: session.walletAddress,
+    sid: session.id,
+    articles: session.unlockedArticles,
+    siteWide: session.siteWideUnlock,
+    credits: newCredits,
+    bundleExpiry: session.bundleExpiry,
+    bundleType: session.bundleType,
+    iat: session.createdAt,
+    exp: session.expiresAt
+  };
+  const newToken = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(getSecretKey(secret));
+  return {
+    success: true,
+    remainingCredits: newCredits,
+    newToken
+  };
+}
+async function addCredits(token, secret, creditsToAdd) {
+  if (creditsToAdd <= 0 || creditsToAdd > MAX_CREDITS) {
+    return { success: false, error: "Invalid credit amount" };
+  }
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return { success: false, error: validation.reason || "Invalid session" };
+  }
+  const session = validation.session;
+  const newCredits = Math.min(session.credits + creditsToAdd, MAX_CREDITS);
+  const payload = {
+    sub: session.walletAddress,
+    sid: session.id,
+    articles: session.unlockedArticles,
+    siteWide: session.siteWideUnlock,
+    credits: newCredits,
+    bundleExpiry: session.bundleExpiry,
+    bundleType: session.bundleType,
+    iat: session.createdAt,
+    exp: session.expiresAt
+  };
+  const newToken = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).sign(getSecretKey(secret));
+  return {
+    success: true,
+    newToken,
+    totalCredits: newCredits
+  };
+}
+async function getRemainingCredits(token, secret) {
+  const validation = await validateCreditSession(token, secret);
+  if (!validation.valid || !validation.session) {
+    return { credits: 0, valid: false };
+  }
+  return {
+    credits: validation.session.credits,
+    valid: true,
+    bundleExpiry: validation.session.bundleExpiry
+  };
+}
+
+exports.addCredits = addCredits;
+exports.createCreditSession = createCreditSession;
+exports.executeAgentPayment = executeAgentPayment;
+exports.generateAgentKeypair = generateAgentKeypair;
+exports.getAgentBalance = getAgentBalance;
+exports.getRemainingCredits = getRemainingCredits;
+exports.hasAgentSufficientBalance = hasAgentSufficientBalance;
+exports.keypairFromBase58 = keypairFromBase58;
+exports.useCredit = useCredit;
+exports.validateCreditSession = validateCreditSession;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/agent/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/solana/priority-fees.ts","../../src/solana/versioned.ts","../../src/agent/agentPayment.ts","../../src/agent/credits.ts"],"names":["ComputeBudgetProgram","TransactionMessage","VersionedTransaction","PublicKey","SystemProgram","LAMPORTS_PER_SOL","Keypair","uuidv4","SignJWT","jwtVerify"],"mappings":";;;;;;;AAqBA,IAAM,qBAAA,GAAwB,GAAA;AAC9B,IAAM,sBAAA,GAAyB,GAAA;AAiBxB,SAAS,6BAAA,CACZ,MAAA,GAA4B,EAAC,EACL;AACxB,EAAA,MAAM,EAAE,OAAA,GAAU,KAAA,EAAO,aAAA,EAAe,cAAa,GAAI,MAAA;AAEzD,EAAA,IAAI,CAAC,OAAA,EAAS;AACV,IAAA,OAAO,EAAC;AAAA,EACZ;AAEA,EAAA,MAAM,eAAyC,EAAC;AAGhD,EAAA,MAAM,QAAQ,YAAA,IAAgB,qBAAA;AAC9B,EAAA,YAAA,CAAa,KAAKA,4BAAA,CAAqB,mBAAA,CAAoB,EAAE,KAAA,EAAO,CAAC,CAAA;AAGrE,EAAA,MAAM,QAAQ,aAAA,IAAiB,sBAAA;AAC/B,EAAA,YAAA,CAAa,KAAKA,4BAAA,CAAqB,mBAAA,CAAoB,EAAE,aAAA,EAAe,KAAA,EAAO,CAAC,CAAA;AAEpF,EAAA,OAAO,YAAA;AACX;ACHA,eAAsB,0BAClB,MAAA,EACmC;AACnC,EAAA,MAAM;AAAA,IACF,UAAA;AAAA,IACA,KAAA;AAAA,IACA,YAAA;AAAA,IACA,eAAe,EAAC;AAAA,IAChB,WAAA;AAAA,IACA;AAAA,GACJ,GAAI,MAAA;AAGJ,EAAA,MAAM,WAAA,GAAc,8BAA8B,WAAW,CAAA;AAC7D,EAAA,MAAM,eAAA,GAAkB,CAAC,GAAG,WAAA,EAAa,GAAG,YAAY,CAAA;AAGxD,EAAA,IAAI,SAAA;AACJ,EAAA,IAAI,oBAAA;AAEJ,EAAA,IAAI,eAAA,EAAiB;AACjB,IAAA,SAAA,GAAY,eAAA;AAEZ,IAAA,MAAM,IAAA,GAAO,MAAM,UAAA,CAAW,OAAA,EAAQ;AACtC,IAAA,oBAAA,GAAuB,IAAA,GAAO,GAAA;AAAA,EAClC,CAAA,MAAO;AACH,IAAA,MAAM,eAAA,GAAkB,MAAM,UAAA,CAAW,kBAAA,CAAmB,WAAW,CAAA;AACvE,IAAA,SAAA,GAAY,eAAA,CAAgB,SAAA;AAC5B,IAAA,oBAAA,GAAuB,eAAA,CAAgB,oBAAA;AAAA,EAC3C;AAGA,EAAA,MAAM,OAAA,GAAU,IAAIC,0BAAA,CAAmB;AAAA,IACnC,QAAA,EAAU,KAAA;AAAA,IACV,eAAA,EAAiB,SAAA;AAAA,IACjB,YAAA,EAAc;AAAA,GACjB,CAAA,CAAE,kBAAA,CAAmB,YAAY,CAAA;AAGlC,EAAA,MAAM,WAAA,GAAc,IAAIC,4BAAA,CAAqB,OAAO,CAAA;AAEpD,EAAA,OAAO;AAAA,IACH,WAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACJ;AACJ;;;ACpDA,IAAM,YAAA,GAAe,+BAAA;AAKrB,SAAS,qBAAqB,OAAA,EAA0B;AACpD,EAAA,IAAI,CAAC,OAAA,IAAW,OAAO,OAAA,KAAY,UAAU,OAAO,KAAA;AACpD,EAAA,OAAO,YAAA,CAAa,KAAK,OAAO,CAAA;AACpC;AAkCA,eAAsB,oBAClB,MAAA,EAC2B;AAC3B,EAAA,MAAM;AAAA,IACF,UAAA;AAAA,IACA,YAAA;AAAA,IACA,gBAAA;AAAA,IACA,cAAA;AAAA,IACA,WAAA;AAAA,IACA,mBAAA,GAAsB;AAAA,GAC1B,GAAI,MAAA;AAGJ,EAAA,IAAI,CAAC,oBAAA,CAAqB,gBAAgB,CAAA,EAAG;AACzC,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,KAAA;AAAA,MACT,KAAA,EAAO;AAAA,KACX;AAAA,EACJ;AAGA,EAAA,IAAI,kBAAkB,EAAA,EAAI;AACtB,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,KAAA;AAAA,MACT,KAAA,EAAO;AAAA,KACX;AAAA,EACJ;AAEA,EAAA,IAAI;AACA,IAAA,MAAM,eAAA,GAAkB,IAAIC,iBAAAA,CAAU,gBAAgB,CAAA;AAGtD,IAAA,MAAM,mBAAA,GAAsBC,sBAAc,QAAA,CAAS;AAAA,MAC/C,YAAY,YAAA,CAAa,SAAA;AAAA,MACzB,QAAA,EAAU,eAAA;AAAA,MACV,QAAA,EAAU;AAAA,KACb,CAAA;AAGD,IAAA,MAAM,EAAE,WAAA,EAAa,oBAAA,EAAqB,GAAI,MAAM,yBAAA,CAA0B;AAAA,MAC1E,UAAA;AAAA,MACA,OAAO,YAAA,CAAa,SAAA;AAAA,MACpB,YAAA,EAAc,CAAC,mBAAmB,CAAA;AAAA,MAClC;AAAA,KACH,CAAA;AAGD,IAAA,WAAA,CAAY,IAAA,CAAK,CAAC,YAAY,CAAC,CAAA;AAG/B,IAAA,MAAM,SAAA,GAAY,MAAM,UAAA,CAAW,eAAA,CAAgB,WAAA,EAAa;AAAA,MAC5D,UAAA,EAAY,CAAA;AAAA,MACZ,aAAA,EAAe;AAAA,KAClB,CAAA;AAGD,IAAA,MAAM,sBAAsB,UAAA,CAAW,kBAAA;AAAA,MACnC;AAAA,QACI,SAAA;AAAA,QACA,oBAAA;AAAA,QACA,SAAA,EAAW,YAAY,OAAA,CAAQ;AAAA,OACnC;AAAA,MACA;AAAA,KACJ;AAEA,IAAA,MAAM,cAAA,GAAiB,IAAI,OAAA,CAAe,CAAC,GAAG,MAAA,KAAW;AACrD,MAAA,UAAA,CAAW,MAAM,MAAA,CAAO,IAAI,MAAM,sBAAsB,CAAC,GAAG,mBAAmB,CAAA;AAAA,IACnF,CAAC,CAAA;AAED,IAAA,MAAM,eAAe,MAAM,OAAA,CAAQ,KAAK,CAAC,mBAAA,EAAqB,cAAc,CAAC,CAAA;AAE7E,IAAA,IAAI,YAAA,CAAa,MAAM,GAAA,EAAK;AACxB,MAAA,OAAO;AAAA,QACH,OAAA,EAAS,KAAA;AAAA,QACT,SAAA;AAAA,QACA,KAAA,EAAO;AAAA,OACX;AAAA,IACJ;AAGA,IAAA,MAAM,SAAA,GAAY,MAAM,UAAA,CAAW,cAAA,CAAe,SAAA,EAAW;AAAA,MACzD,UAAA,EAAY,WAAA;AAAA,MACZ,8BAAA,EAAgC;AAAA,KACnC,CAAA;AAED,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,IAAA;AAAA,MACT,SAAA;AAAA,MACA,WAAA,EAAa,WAAW,SAAA,IAAa,IAAA,CAAK,MAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AAAA,MACjE,IAAA,EAAM,SAAA,EAAW,IAAA,IAAQ,YAAA,CAAa,OAAA,CAAQ,IAAA;AAAA,MAC9C,cAAA;AAAA,MACA,SAAA,EAAW,MAAA,CAAO,cAAc,CAAA,GAAIC;AAAA,KACxC;AAAA,EACJ,SAAS,KAAA,EAAO;AACZ,IAAA,MAAM,YAAA,GAAe,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,eAAA;AAC9D,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,KAAA;AAAA,MACT,KAAA,EAAO;AAAA,KACX;AAAA,EACJ;AACJ;AAKA,eAAsB,eAAA,CAClB,YACA,YAAA,EACgD;AAChD,EAAA,MAAM,OAAA,GAAU,MAAM,UAAA,CAAW,UAAA,CAAW,aAAa,SAAS,CAAA;AAClE,EAAA,OAAO;AAAA,IACH,OAAA,EAAS,OAAO,OAAO,CAAA;AAAA,IACvB,YAAY,OAAA,GAAUA;AAAA,GAC1B;AACJ;AAKA,eAAsB,yBAAA,CAClB,UAAA,EACA,YAAA,EACA,gBAAA,EACmE;AACnE,EAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAM,eAAA,CAAgB,YAAY,YAAY,CAAA;AAElE,EAAA,MAAM,gBAAgB,gBAAA,GAAmB,MAAA;AACzC,EAAA,OAAO;AAAA,IACH,YAAY,OAAA,IAAW,aAAA;AAAA,IACvB,OAAA;AAAA,IACA,QAAA,EAAU;AAAA,GACd;AACJ;AAUO,SAAS,kBAAkB,YAAA,EAA+B;AAG7D,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,IAAA,CAAK,YAAA,EAAc,QAAQ,CAAA;AAGhD,EAAA,IAAI,KAAA,CAAM,WAAW,EAAA,EAAI;AAErB,IAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,KAAA,CAAM,GAAG,CAAA,CAAE,GAAA,CAAI,CAAA,CAAA,KAAK,QAAA,CAAS,CAAA,CAAE,IAAA,EAAK,EAAG,EAAE,CAAC,CAAA;AACrE,IAAA,IAAI,KAAA,CAAM,WAAW,EAAA,EAAI;AACrB,MAAA,OAAOC,eAAA,CAAQ,aAAA,CAAc,UAAA,CAAW,IAAA,CAAK,KAAK,CAAC,CAAA;AAAA,IACvD;AACA,IAAA,MAAM,IAAI,MAAM,6EAA6E,CAAA;AAAA,EACjG;AAEA,EAAA,OAAOA,eAAA,CAAQ,cAAc,KAAK,CAAA;AACtC;AAMO,SAAS,oBAAA,GAAsF;AAClG,EAAA,MAAM,OAAA,GAAUA,gBAAQ,QAAA,EAAS;AACjC,EAAA,MAAM,WAAA,GAAc,KAAA,CAAM,IAAA,CAAK,OAAA,CAAQ,SAAS,CAAA;AAChD,EAAA,OAAO;AAAA,IACH,OAAA;AAAA,IACA,YAAA,EAAc,WAAA,CAAY,IAAA,CAAK,GAAG,CAAA;AAAA;AAAA,IAClC,SAAA,EAAW,OAAA,CAAQ,SAAA,CAAU,QAAA;AAAS,GAC1C;AACJ;AC5NA,IAAM,WAAA,GAAc,GAAA;AACpB,IAAM,iBAAA,GAAoB,EAAA;AAK1B,SAAS,aAAa,MAAA,EAA4B;AAC9C,EAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,KAAW,QAAA,EAAU;AACvC,IAAA,MAAM,IAAI,MAAM,4BAA4B,CAAA;AAAA,EAChD;AACA,EAAA,IAAI,MAAA,CAAO,SAAS,iBAAA,EAAmB;AACnC,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,gCAAA,EAAmC,iBAAiB,CAAA,WAAA,CAAa,CAAA;AAAA,EACrF;AACA,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,CAAA;AAC1C;AAKA,SAAS,sBAAsB,OAAA,EAA0B;AACrD,EAAA,IAAI,CAAC,OAAA,IAAW,OAAO,OAAA,KAAY,UAAU,OAAO,KAAA;AACpD,EAAA,MAAM,WAAA,GAAc,+BAAA;AACpB,EAAA,OAAO,WAAA,CAAY,KAAK,OAAO,CAAA;AACnC;AAwBA,eAAsB,mBAAA,CAClB,aAAA,EACA,UAAA,EACA,MAAA,EACsD;AAEtD,EAAA,IAAI,CAAC,qBAAA,CAAsB,aAAa,CAAA,EAAG;AACvC,IAAA,MAAM,IAAI,MAAM,+BAA+B,CAAA;AAAA,EACnD;AACA,EAAA,IAAI,MAAA,CAAO,cAAA,IAAkB,CAAA,IAAK,MAAA,CAAO,iBAAiB,WAAA,EAAa;AACnE,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,8BAAA,EAAiC,WAAW,CAAA,CAAE,CAAA;AAAA,EAClE;AACA,EAAA,IAAI,CAAC,OAAO,aAAA,IAAiB,MAAA,CAAO,iBAAiB,CAAA,IAAK,MAAA,CAAO,gBAAgB,IAAA,EAAM;AACnF,IAAA,MAAM,IAAI,MAAM,4DAA4D,CAAA;AAAA,EAChF;AAEA,EAAA,MAAM,YAAYC,OAAA,EAAO;AACzB,EAAA,MAAM,MAAM,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AACxC,EAAA,MAAM,SAAA,GAAY,GAAA,GAAO,MAAA,CAAO,aAAA,GAAgB,IAAA;AAChD,EAAA,MAAM,eAAe,MAAA,CAAO,iBAAA,GACtB,GAAA,GAAO,MAAA,CAAO,oBAAoB,IAAA,GAClC,SAAA;AAEN,EAAA,MAAM,OAAA,GAA6B;AAAA,IAC/B,EAAA,EAAI,SAAA;AAAA,IACJ,aAAA;AAAA,IACA,gBAAA,EAAkB,CAAC,UAAU,CAAA;AAAA,IAC7B,cAAA,EAAgB,KAAA;AAAA,IAChB,SAAA,EAAW,GAAA;AAAA,IACX,SAAA;AAAA,IACA,SAAS,MAAA,CAAO,cAAA;AAAA,IAChB,YAAA;AAAA,IACA,YAAY,MAAA,CAAO;AAAA,GACvB;AAEA,EAAA,MAAM,OAAA,GAA4B;AAAA,IAC9B,GAAA,EAAK,aAAA;AAAA,IACL,GAAA,EAAK,SAAA;AAAA,IACL,UAAU,OAAA,CAAQ,gBAAA;AAAA,IAClB,QAAA,EAAU,KAAA;AAAA,IACV,SAAS,MAAA,CAAO,cAAA;AAAA,IAChB,YAAA;AAAA,IACA,YAAY,MAAA,CAAO,UAAA;AAAA,IACnB,GAAA,EAAK,GAAA;AAAA,IACL,GAAA,EAAK;AAAA,GACT;AAEA,EAAA,MAAM,KAAA,GAAQ,MAAM,IAAIC,YAAA,CAAQ,OAA6C,EACxE,kBAAA,CAAmB,EAAE,GAAA,EAAK,OAAA,EAAS,CAAA,CACnC,aAAY,CACZ,iBAAA,CAAkB,CAAA,EAAG,MAAA,CAAO,aAAa,CAAA,CAAA,CAAG,EAC5C,IAAA,CAAK,YAAA,CAAa,MAAA,CAAO,MAAM,CAAC,CAAA;AAErC,EAAA,OAAO,EAAE,OAAO,OAAA,EAAQ;AAC5B;AAYA,eAAsB,qBAAA,CAClB,OACA,MAAA,EACyB;AACzB,EAAA,IAAI,CAAC,KAAA,IAAS,OAAO,KAAA,KAAU,QAAA,EAAU;AACrC,IAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,sBAAA,EAAuB;AAAA,EAC1D;AAEA,EAAA,IAAI;AACA,IAAA,MAAM,EAAE,SAAQ,GAAI,MAAMC,eAAU,KAAA,EAAO,YAAA,CAAa,MAAM,CAAC,CAAA;AAC/D,IAAA,MAAM,aAAA,GAAgB,OAAA;AAGtB,IAAA,IAAI,CAAC,cAAc,GAAA,IAAO,CAAC,cAAc,GAAA,IAAO,CAAC,cAAc,GAAA,EAAK;AAChE,MAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,2BAAA,EAA4B;AAAA,IAC/D;AAGA,IAAA,MAAM,MAAM,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AACxC,IAAA,IAAI,aAAA,CAAc,MAAM,GAAA,EAAK;AACzB,MAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,iBAAA,EAAkB;AAAA,IACrD;AAGA,IAAA,IAAI,aAAA,CAAc,YAAA,IAAgB,aAAA,CAAc,YAAA,GAAe,GAAA,EAAK;AAChE,MAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,gBAAA,EAAiB;AAAA,IACpD;AAGA,IAAA,IAAI,CAAC,qBAAA,CAAsB,aAAA,CAAc,GAAG,CAAA,EAAG;AAC3C,MAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,sBAAA,EAAuB;AAAA,IAC1D;AAEA,IAAA,MAAM,OAAA,GAA6B;AAAA,MAC/B,IAAI,aAAA,CAAc,GAAA;AAAA,MAClB,eAAe,aAAA,CAAc,GAAA;AAAA,MAC7B,gBAAA,EAAkB,MAAM,OAAA,CAAQ,aAAA,CAAc,QAAQ,CAAA,GAAI,aAAA,CAAc,WAAW,EAAC;AAAA,MACpF,cAAA,EAAgB,OAAA,CAAQ,aAAA,CAAc,QAAQ,CAAA;AAAA,MAC9C,SAAA,EAAW,cAAc,GAAA,IAAO,CAAA;AAAA,MAChC,WAAW,aAAA,CAAc,GAAA;AAAA,MACzB,OAAA,EAAS,cAAc,OAAA,IAAW,CAAA;AAAA,MAClC,cAAc,aAAA,CAAc,YAAA;AAAA,MAC5B,YAAY,aAAA,CAAc;AAAA,KAC9B;AAEA,IAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,OAAA,EAAQ;AAAA,EAClC,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,iBAAA,EAAkB;AAAA,EACrD;AACJ;AAiCA,eAAsB,SAAA,CAClB,KAAA,EACA,MAAA,EACA,YAAA,GAAuB,CAAA,EACC;AACxB,EAAA,IAAI,gBAAgB,CAAA,EAAG;AACnB,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,gBAAA,EAAkB,CAAA,EAAG,OAAO,uBAAA,EAAwB;AAAA,EACjF;AAEA,EAAA,MAAM,UAAA,GAAa,MAAM,qBAAA,CAAsB,KAAA,EAAO,MAAM,CAAA;AAE5D,EAAA,IAAI,CAAC,UAAA,CAAW,KAAA,IAAS,CAAC,WAAW,OAAA,EAAS;AAC1C,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,KAAA;AAAA,MACT,gBAAA,EAAkB,CAAA;AAAA,MAClB,KAAA,EAAO,WAAW,MAAA,IAAU;AAAA,KAChC;AAAA,EACJ;AAEA,EAAA,MAAM,UAAU,UAAA,CAAW,OAAA;AAG3B,EAAA,IAAI,OAAA,CAAQ,UAAU,YAAA,EAAc;AAChC,IAAA,OAAO;AAAA,MACH,OAAA,EAAS,KAAA;AAAA,MACT,kBAAkB,OAAA,CAAQ,OAAA;AAAA,MAC1B,KAAA,EAAO;AAAA,KACX;AAAA,EACJ;AAGA,EAAA,MAAM,UAAA,GAAa,QAAQ,OAAA,GAAU,YAAA;AAErC,EAAA,MAAM,OAAA,GAA4B;AAAA,IAC9B,KAAK,OAAA,CAAQ,aAAA;AAAA,IACb,KAAK,OAAA,CAAQ,EAAA;AAAA,IACb,UAAU,OAAA,CAAQ,gBAAA;AAAA,IAClB,UAAU,OAAA,CAAQ,cAAA;AAAA,IAClB,OAAA,EAAS,UAAA;AAAA,IACT,cAAc,OAAA,CAAQ,YAAA;AAAA,IACtB,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,KAAK,OAAA,CAAQ,SAAA;AAAA,IACb,KAAK,OAAA,CAAQ;AAAA,GACjB;AAEA,EAAA,MAAM,QAAA,GAAW,MAAM,IAAID,YAAA,CAAQ,OAA6C,CAAA,CAC3E,kBAAA,CAAmB,EAAE,GAAA,EAAK,SAAS,CAAA,CACnC,IAAA,CAAK,YAAA,CAAa,MAAM,CAAC,CAAA;AAE9B,EAAA,OAAO;AAAA,IACH,OAAA,EAAS,IAAA;AAAA,IACT,gBAAA,EAAkB,UAAA;AAAA,IAClB;AAAA,GACJ;AACJ;AAMA,eAAsB,UAAA,CAClB,KAAA,EACA,MAAA,EACA,YAAA,EACuF;AACvF,EAAA,IAAI,YAAA,IAAgB,CAAA,IAAK,YAAA,GAAe,WAAA,EAAa;AACjD,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,KAAA,EAAO,uBAAA,EAAwB;AAAA,EAC5D;AAEA,EAAA,MAAM,UAAA,GAAa,MAAM,qBAAA,CAAsB,KAAA,EAAO,MAAM,CAAA;AAE5D,EAAA,IAAI,CAAC,UAAA,CAAW,KAAA,IAAS,CAAC,WAAW,OAAA,EAAS;AAC1C,IAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,KAAA,EAAO,UAAA,CAAW,UAAU,iBAAA,EAAkB;AAAA,EAC3E;AAEA,EAAA,MAAM,UAAU,UAAA,CAAW,OAAA;AAC3B,EAAA,MAAM,aAAa,IAAA,CAAK,GAAA,CAAI,OAAA,CAAQ,OAAA,GAAU,cAAc,WAAW,CAAA;AAEvE,EAAA,MAAM,OAAA,GAA4B;AAAA,IAC9B,KAAK,OAAA,CAAQ,aAAA;AAAA,IACb,KAAK,OAAA,CAAQ,EAAA;AAAA,IACb,UAAU,OAAA,CAAQ,gBAAA;AAAA,IAClB,UAAU,OAAA,CAAQ,cAAA;AAAA,IAClB,OAAA,EAAS,UAAA;AAAA,IACT,cAAc,OAAA,CAAQ,YAAA;AAAA,IACtB,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,KAAK,OAAA,CAAQ,SAAA;AAAA,IACb,KAAK,OAAA,CAAQ;AAAA,GACjB;AAEA,EAAA,MAAM,QAAA,GAAW,MAAM,IAAIA,YAAA,CAAQ,OAA6C,CAAA,CAC3E,kBAAA,CAAmB,EAAE,GAAA,EAAK,SAAS,CAAA,CACnC,IAAA,CAAK,YAAA,CAAa,MAAM,CAAC,CAAA;AAE9B,EAAA,OAAO;AAAA,IACH,OAAA,EAAS,IAAA;AAAA,IACT,QAAA;AAAA,IACA,YAAA,EAAc;AAAA,GAClB;AACJ;AAKA,eAAsB,mBAAA,CAClB,OACA,MAAA,EACmE;AACnE,EAAA,MAAM,UAAA,GAAa,MAAM,qBAAA,CAAsB,KAAA,EAAO,MAAM,CAAA;AAE5D,EAAA,IAAI,CAAC,UAAA,CAAW,KAAA,IAAS,CAAC,WAAW,OAAA,EAAS;AAC1C,IAAA,OAAO,EAAE,OAAA,EAAS,CAAA,EAAG,KAAA,EAAO,KAAA,EAAM;AAAA,EACtC;AAEA,EAAA,OAAO;AAAA,IACH,OAAA,EAAS,WAAW,OAAA,CAAQ,OAAA;AAAA,IAC5B,KAAA,EAAO,IAAA;AAAA,IACP,YAAA,EAAc,WAAW,OAAA,CAAQ;AAAA,GACrC;AACJ","file":"index.cjs","sourcesContent":["// Priority Fee Utilities for Solana Transactions\n// Adds compute budget instructions for landing transactions faster\n\nimport {\n    ComputeBudgetProgram,\n    type Connection,\n    type PublicKey,\n    type TransactionInstruction,\n} from '@solana/web3.js';\n\n/** Configuration for priority fees */\nexport interface PriorityFeeConfig {\n    /** Enable priority fees (default: false) */\n    enabled?: boolean;\n    /** Price per compute unit in micro-lamports (default: auto-estimate) */\n    microLamports?: number;\n    /** Maximum compute units for transaction (default: 200_000) */\n    computeUnits?: number;\n}\n\n/** Default priority fee settings */\nconst DEFAULT_COMPUTE_UNITS = 200_000;\nconst DEFAULT_MICRO_LAMPORTS = 1_000; // 0.001 lamports per CU\n\n/**\n * Create compute budget instructions for priority fees\n * \n * @example\n * ```typescript\n * const priorityIxs = createPriorityFeeInstructions({\n *   enabled: true,\n *   microLamports: 5000,\n *   computeUnits: 150_000,\n * });\n * \n * // Add to transaction\n * transaction.add(...priorityIxs, ...yourInstructions);\n * ```\n */\nexport function createPriorityFeeInstructions(\n    config: PriorityFeeConfig = {}\n): TransactionInstruction[] {\n    const { enabled = false, microLamports, computeUnits } = config;\n\n    if (!enabled) {\n        return [];\n    }\n\n    const instructions: TransactionInstruction[] = [];\n\n    // Set compute unit limit\n    const units = computeUnits ?? DEFAULT_COMPUTE_UNITS;\n    instructions.push(ComputeBudgetProgram.setComputeUnitLimit({ units }));\n\n    // Set compute unit price\n    const price = microLamports ?? DEFAULT_MICRO_LAMPORTS;\n    instructions.push(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: price }));\n\n    return instructions;\n}\n\n/**\n * Estimate priority fee based on recent network activity\n * Returns micro-lamports per compute unit\n * \n * @example\n * ```typescript\n * const fee = await estimatePriorityFee(connection, [recipientPubkey]);\n * console.log(`Recommended fee: ${fee} micro-lamports/CU`);\n * ```\n */\nexport async function estimatePriorityFee(\n    connection: Connection,\n    accounts: PublicKey[] = []\n): Promise<number> {\n    try {\n        const fees = await connection.getRecentPrioritizationFees({\n            lockedWritableAccounts: accounts,\n        });\n\n        if (fees.length === 0) {\n            return DEFAULT_MICRO_LAMPORTS;\n        }\n\n        // Get median of recent fees (more stable than mean)\n        const sortedFees = fees\n            .map((f) => f.prioritizationFee)\n            .filter((f) => f > 0)\n            .sort((a, b) => a - b);\n\n        if (sortedFees.length === 0) {\n            return DEFAULT_MICRO_LAMPORTS;\n        }\n\n        const medianIndex = Math.floor(sortedFees.length / 2);\n        return sortedFees[medianIndex];\n    } catch {\n        // Fallback on RPC errors\n        return DEFAULT_MICRO_LAMPORTS;\n    }\n}\n\n/**\n * Calculate total priority fee cost in lamports\n * \n * @example\n * ```typescript\n * const cost = calculatePriorityFeeCost(5000, 200_000);\n * console.log(`Priority fee: ${cost} lamports`);\n * ```\n */\nexport function calculatePriorityFeeCost(\n    microLamportsPerCU: number,\n    computeUnits: number\n): number {\n    return Math.ceil((microLamportsPerCU * computeUnits) / 1_000_000);\n}\n","// Versioned Transaction Support\n// Utilities for building and working with versioned transactions\n\nimport {\n    TransactionMessage,\n    VersionedTransaction,\n    type AddressLookupTableAccount,\n    type Connection,\n    type PublicKey,\n    type TransactionInstruction,\n} from '@solana/web3.js';\nimport { createPriorityFeeInstructions, type PriorityFeeConfig } from './priority-fees';\n\n/** Configuration for building versioned transactions */\nexport interface VersionedTransactionConfig {\n    /** Solana connection */\n    connection: Connection;\n    /** Fee payer public key */\n    payer: PublicKey;\n    /** Transaction instructions */\n    instructions: TransactionInstruction[];\n    /** Address lookup tables for compression (optional) */\n    lookupTables?: AddressLookupTableAccount[];\n    /** Priority fee configuration (optional, default: disabled) */\n    priorityFee?: PriorityFeeConfig;\n    /** Recent blockhash (optional, will fetch if not provided) */\n    recentBlockhash?: string;\n}\n\n/** Result of building a versioned transaction */\nexport interface VersionedTransactionResult {\n    /** The built versioned transaction */\n    transaction: VersionedTransaction;\n    /** The blockhash used */\n    blockhash: string;\n    /** Last valid block height for the transaction */\n    lastValidBlockHeight: number;\n}\n\n/**\n * Build a versioned transaction (v0) with optional priority fees and lookup tables\n * \n * @example\n * ```typescript\n * const { transaction, blockhash, lastValidBlockHeight } = await buildVersionedTransaction({\n *   connection,\n *   payer: wallet.publicKey,\n *   instructions: [transferIx],\n *   priorityFee: { enabled: true, microLamports: 5000 },\n * });\n * \n * // Sign and send\n * transaction.sign([wallet]);\n * const sig = await connection.sendTransaction(transaction);\n * ```\n */\nexport async function buildVersionedTransaction(\n    config: VersionedTransactionConfig\n): Promise<VersionedTransactionResult> {\n    const {\n        connection,\n        payer,\n        instructions,\n        lookupTables = [],\n        priorityFee,\n        recentBlockhash,\n    } = config;\n\n    // Prepend priority fee instructions if configured\n    const priorityIxs = createPriorityFeeInstructions(priorityFee);\n    const allInstructions = [...priorityIxs, ...instructions];\n\n    // Get recent blockhash if not provided\n    let blockhash: string;\n    let lastValidBlockHeight: number;\n\n    if (recentBlockhash) {\n        blockhash = recentBlockhash;\n        // Estimate last valid block height (typically ~150 blocks)\n        const slot = await connection.getSlot();\n        lastValidBlockHeight = slot + 150;\n    } else {\n        const latestBlockhash = await connection.getLatestBlockhash('confirmed');\n        blockhash = latestBlockhash.blockhash;\n        lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;\n    }\n\n    // Build message\n    const message = new TransactionMessage({\n        payerKey: payer,\n        recentBlockhash: blockhash,\n        instructions: allInstructions,\n    }).compileToV0Message(lookupTables);\n\n    // Create versioned transaction\n    const transaction = new VersionedTransaction(message);\n\n    return {\n        transaction,\n        blockhash,\n        lastValidBlockHeight,\n    };\n}\n\n/**\n * Fetch address lookup table accounts\n * \n * @example\n * ```typescript\n * const tables = await fetchLookupTables(connection, [tableAddress1, tableAddress2]);\n * const { transaction } = await buildVersionedTransaction({\n *   connection,\n *   payer,\n *   instructions,\n *   lookupTables: tables,\n * });\n * ```\n */\nexport async function fetchLookupTables(\n    connection: Connection,\n    addresses: PublicKey[]\n): Promise<AddressLookupTableAccount[]> {\n    const tables: AddressLookupTableAccount[] = [];\n\n    for (const address of addresses) {\n        const result = await connection.getAddressLookupTable(address);\n        if (result.value) {\n            tables.push(result.value);\n        }\n    }\n\n    return tables;\n}\n\n/**\n * Check if a transaction version is supported\n */\nexport function isVersionedTransaction(\n    tx: unknown\n): tx is VersionedTransaction {\n    return tx instanceof VersionedTransaction;\n}\n","// Agent Payment Utilities\n// Server-side autonomous payment execution for AI agents\n// SECURITY: Keypair must only be loaded server-side\n\nimport {\n    Connection,\n    Keypair,\n    PublicKey,\n    SystemProgram,\n    LAMPORTS_PER_SOL,\n} from '@solana/web3.js';\nimport { buildVersionedTransaction, type PriorityFeeConfig } from '../solana';\n\n/** Parameters for executing an agent payment */\nexport interface ExecuteAgentPaymentParams {\n    /** Solana connection */\n    connection: Connection;\n    /** Agent's keypair (server-side only!) */\n    agentKeypair: Keypair;\n    /** Recipient wallet address (base58) */\n    recipientAddress: string;\n    /** Amount to send in lamports */\n    amountLamports: bigint;\n    /** Optional memo for the transaction */\n    memo?: string;\n    /** Optional priority fee configuration */\n    priorityFee?: PriorityFeeConfig;\n    /** Timeout for confirmation in ms (default: 60000) */\n    confirmationTimeout?: number;\n}\n\n/** Result of an agent payment execution */\nexport interface AgentPaymentResult {\n    /** Whether the payment was successful */\n    success: boolean;\n    /** Transaction signature (if successful) */\n    signature?: string;\n    /** Error message (if failed) */\n    error?: string;\n    /** Block time when confirmed (Unix timestamp) */\n    confirmedAt?: number;\n    /** Slot number */\n    slot?: number;\n    /** Amount sent in lamports */\n    amountLamports?: bigint;\n    /** Amount sent in SOL */\n    amountSol?: number;\n}\n\n// Wallet address validation regex\nconst WALLET_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;\n\n/**\n * Validate wallet address format\n */\nfunction isValidWalletAddress(address: string): boolean {\n    if (!address || typeof address !== 'string') return false;\n    return WALLET_REGEX.test(address);\n}\n\n/**\n * Execute an autonomous SOL payment from the agent's wallet\n * \n * This is the core utility for AI agents to pay for x402-protected resources.\n * The agent keypair must be loaded server-side only (never exposed to client).\n * \n * @example\n * ```typescript\n * import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';\n * import { Keypair, Connection } from '@solana/web3.js';\n * import bs58 from 'bs58';\n * \n * // Load agent keypair from environment (server-side only!)\n * const agentKeypair = Keypair.fromSecretKey(\n *   bs58.decode(process.env.AGENT_KEYPAIR_SECRET!)\n * );\n * \n * const connection = new Connection('https://api.devnet.solana.com');\n * \n * const result = await executeAgentPayment({\n *   connection,\n *   agentKeypair,\n *   recipientAddress: 'RecipientWallet...',\n *   amountLamports: 20_000_000n, // 0.02 SOL\n *   priorityFee: { enabled: true, microLamports: 5000 },\n * });\n * \n * if (result.success) {\n *   console.log('Payment sent:', result.signature);\n * }\n * ```\n */\nexport async function executeAgentPayment(\n    params: ExecuteAgentPaymentParams\n): Promise<AgentPaymentResult> {\n    const {\n        connection,\n        agentKeypair,\n        recipientAddress,\n        amountLamports,\n        priorityFee,\n        confirmationTimeout = 60000,\n    } = params;\n\n    // Validate recipient address\n    if (!isValidWalletAddress(recipientAddress)) {\n        return {\n            success: false,\n            error: 'Invalid recipient address format',\n        };\n    }\n\n    // Validate amount\n    if (amountLamports <= 0n) {\n        return {\n            success: false,\n            error: 'Amount must be greater than 0',\n        };\n    }\n\n    try {\n        const recipientPubkey = new PublicKey(recipientAddress);\n\n        // Create transfer instruction\n        const transferInstruction = SystemProgram.transfer({\n            fromPubkey: agentKeypair.publicKey,\n            toPubkey: recipientPubkey,\n            lamports: amountLamports,\n        });\n\n        // Build versioned transaction with optional priority fee\n        const { transaction, lastValidBlockHeight } = await buildVersionedTransaction({\n            connection,\n            payer: agentKeypair.publicKey,\n            instructions: [transferInstruction],\n            priorityFee,\n        });\n\n        // Sign transaction\n        transaction.sign([agentKeypair]);\n\n        // Send transaction\n        const signature = await connection.sendTransaction(transaction, {\n            maxRetries: 3,\n            skipPreflight: false,\n        });\n\n        // Wait for confirmation with timeout\n        const confirmationPromise = connection.confirmTransaction(\n            {\n                signature,\n                lastValidBlockHeight,\n                blockhash: transaction.message.recentBlockhash,\n            },\n            'confirmed'\n        );\n\n        const timeoutPromise = new Promise<never>((_, reject) => {\n            setTimeout(() => reject(new Error('Confirmation timeout')), confirmationTimeout);\n        });\n\n        const confirmation = await Promise.race([confirmationPromise, timeoutPromise]);\n\n        if (confirmation.value.err) {\n            return {\n                success: false,\n                signature,\n                error: 'Transaction failed on-chain',\n            };\n        }\n\n        // Get transaction details for confirmed time\n        const txDetails = await connection.getTransaction(signature, {\n            commitment: 'confirmed',\n            maxSupportedTransactionVersion: 0,\n        });\n\n        return {\n            success: true,\n            signature,\n            confirmedAt: txDetails?.blockTime ?? Math.floor(Date.now() / 1000),\n            slot: txDetails?.slot ?? confirmation.context.slot,\n            amountLamports,\n            amountSol: Number(amountLamports) / LAMPORTS_PER_SOL,\n        };\n    } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : 'Unknown error';\n        return {\n            success: false,\n            error: errorMessage,\n        };\n    }\n}\n\n/**\n * Get the agent wallet's SOL balance\n */\nexport async function getAgentBalance(\n    connection: Connection,\n    agentKeypair: Keypair\n): Promise<{ balance: bigint; balanceSol: number }> {\n    const balance = await connection.getBalance(agentKeypair.publicKey);\n    return {\n        balance: BigInt(balance),\n        balanceSol: balance / LAMPORTS_PER_SOL,\n    };\n}\n\n/**\n * Check if agent has sufficient balance for a payment\n */\nexport async function hasAgentSufficientBalance(\n    connection: Connection,\n    agentKeypair: Keypair,\n    requiredLamports: bigint\n): Promise<{ sufficient: boolean; balance: bigint; required: bigint }> {\n    const { balance } = await getAgentBalance(connection, agentKeypair);\n    // Add buffer for transaction fees (~5000 lamports)\n    const totalRequired = requiredLamports + 10000n;\n    return {\n        sufficient: balance >= totalRequired,\n        balance,\n        required: totalRequired,\n    };\n}\n\n/**\n * Create a Keypair from a base58-encoded secret key string\n * \n * @example\n * ```typescript\n * const keypair = keypairFromBase58(process.env.AGENT_KEYPAIR_SECRET!);\n * ```\n */\nexport function keypairFromBase58(base58Secret: string): Keypair {\n    // Dynamic import to avoid bundling bs58 in client code\n    // For server-side use, install bs58 as a dependency\n    const bytes = Buffer.from(base58Secret, 'base64');\n\n    // Try base58 decode if base64 fails\n    if (bytes.length !== 64) {\n        // Fallback: assume it's a comma-separated array of numbers\n        const parts = base58Secret.split(',').map(n => parseInt(n.trim(), 10));\n        if (parts.length === 64) {\n            return Keypair.fromSecretKey(Uint8Array.from(parts));\n        }\n        throw new Error('Invalid secret key format. Expected base58 string or comma-separated bytes.');\n    }\n\n    return Keypair.fromSecretKey(bytes);\n}\n\n/**\n * Create a new random Keypair for agent use\n * Returns both the keypair and its base58-encoded secret for storage\n */\nexport function generateAgentKeypair(): { keypair: Keypair; secretBase58: string; publicKey: string } {\n    const keypair = Keypair.generate();\n    const secretBytes = Array.from(keypair.secretKey);\n    return {\n        keypair,\n        secretBase58: secretBytes.join(','), // Comma-separated for easy storage\n        publicKey: keypair.publicKey.toBase58(),\n    };\n}\n","// Bundle Credits System\n// Optional credit-based session management for agent payments\n\nimport { SignJWT, jwtVerify } from 'jose';\nimport { v4 as uuidv4 } from 'uuid';\nimport type { SessionConfig, SessionData } from '../types';\n\n/** Credit claims stored in session JWT */\nexport interface CreditSessionClaims {\n    /** Number of remaining credits */\n    credits: number;\n    /** Unix timestamp when bundle expires (optional) */\n    bundleExpiry?: number;\n    /** Bundle type identifier (e.g., 'starter', 'pro') */\n    bundleType?: string;\n}\n\n/** Extended session data with credit information */\nexport type CreditSessionData = SessionData & CreditSessionClaims;\n\n/** Configuration for credit sessions */\nexport interface CreditSessionConfig extends SessionConfig {\n    /** Initial number of credits */\n    initialCredits: number;\n    /** Bundle expiry in hours (optional, defaults to session duration) */\n    bundleExpiryHours?: number;\n    /** Bundle type identifier */\n    bundleType?: string;\n}\n\n/** JWT payload for credit sessions */\ninterface CreditJWTPayload {\n    sub: string;\n    sid: string;\n    articles: string[];\n    siteWide: boolean;\n    credits: number;\n    bundleExpiry?: number;\n    bundleType?: string;\n    iat: number;\n    exp: number;\n}\n\n// Constants\nconst MAX_CREDITS = 1000;\nconst MIN_SECRET_LENGTH = 32;\n\n/**\n * Get the secret key for JWT signing\n */\nfunction getSecretKey(secret: string): Uint8Array {\n    if (!secret || typeof secret !== 'string') {\n        throw new Error('Session secret is required');\n    }\n    if (secret.length < MIN_SECRET_LENGTH) {\n        throw new Error(`Session secret must be at least ${MIN_SECRET_LENGTH} characters`);\n    }\n    return new TextEncoder().encode(secret);\n}\n\n/**\n * Validate wallet address format\n */\nfunction validateWalletAddress(address: string): boolean {\n    if (!address || typeof address !== 'string') return false;\n    const base58Regex = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;\n    return base58Regex.test(address);\n}\n\n/**\n * Create a new credit session after bundle purchase\n * \n * @example\n * ```typescript\n * import { createCreditSession } from '@alleyboss/micropay-solana-x402-paywall/agent';\n * \n * const { token, session } = await createCreditSession(\n *   walletAddress,\n *   'bundle-purchase',\n *   {\n *     secret: process.env.SESSION_SECRET!,\n *     durationHours: 24 * 30, // 30 days\n *     initialCredits: 10,\n *     bundleType: 'starter',\n *   }\n * );\n * \n * // Set as cookie\n * response.cookies.set('x402_credits', token, { httpOnly: true });\n * ```\n */\nexport async function createCreditSession(\n    walletAddress: string,\n    purchaseId: string,\n    config: CreditSessionConfig\n): Promise<{ token: string; session: CreditSessionData }> {\n    // Input validation\n    if (!validateWalletAddress(walletAddress)) {\n        throw new Error('Invalid wallet address format');\n    }\n    if (config.initialCredits <= 0 || config.initialCredits > MAX_CREDITS) {\n        throw new Error(`Credits must be between 1 and ${MAX_CREDITS}`);\n    }\n    if (!config.durationHours || config.durationHours <= 0 || config.durationHours > 8760) {\n        throw new Error('Session duration must be between 1 and 8760 hours (1 year)');\n    }\n\n    const sessionId = uuidv4();\n    const now = Math.floor(Date.now() / 1000);\n    const expiresAt = now + (config.durationHours * 3600);\n    const bundleExpiry = config.bundleExpiryHours\n        ? now + (config.bundleExpiryHours * 3600)\n        : expiresAt;\n\n    const session: CreditSessionData = {\n        id: sessionId,\n        walletAddress,\n        unlockedArticles: [purchaseId],\n        siteWideUnlock: false,\n        createdAt: now,\n        expiresAt,\n        credits: config.initialCredits,\n        bundleExpiry,\n        bundleType: config.bundleType,\n    };\n\n    const payload: CreditJWTPayload = {\n        sub: walletAddress,\n        sid: sessionId,\n        articles: session.unlockedArticles,\n        siteWide: false,\n        credits: config.initialCredits,\n        bundleExpiry,\n        bundleType: config.bundleType,\n        iat: now,\n        exp: expiresAt,\n    };\n\n    const token = await new SignJWT(payload as unknown as Record<string, unknown>)\n        .setProtectedHeader({ alg: 'HS256' })\n        .setIssuedAt()\n        .setExpirationTime(`${config.durationHours}h`)\n        .sign(getSecretKey(config.secret));\n\n    return { token, session };\n}\n\n/** Result of validating a credit session */\nexport interface CreditValidation {\n    valid: boolean;\n    session?: CreditSessionData;\n    reason?: string;\n}\n\n/**\n * Validate a credit session token\n */\nexport async function validateCreditSession(\n    token: string,\n    secret: string\n): Promise<CreditValidation> {\n    if (!token || typeof token !== 'string') {\n        return { valid: false, reason: 'Invalid token format' };\n    }\n\n    try {\n        const { payload } = await jwtVerify(token, getSecretKey(secret));\n        const creditPayload = payload as unknown as CreditJWTPayload;\n\n        // Validate required fields\n        if (!creditPayload.sub || !creditPayload.sid || !creditPayload.exp) {\n            return { valid: false, reason: 'Malformed session payload' };\n        }\n\n        // Check expiration\n        const now = Math.floor(Date.now() / 1000);\n        if (creditPayload.exp < now) {\n            return { valid: false, reason: 'Session expired' };\n        }\n\n        // Check bundle expiry if set\n        if (creditPayload.bundleExpiry && creditPayload.bundleExpiry < now) {\n            return { valid: false, reason: 'Bundle expired' };\n        }\n\n        // Validate wallet format\n        if (!validateWalletAddress(creditPayload.sub)) {\n            return { valid: false, reason: 'Invalid session data' };\n        }\n\n        const session: CreditSessionData = {\n            id: creditPayload.sid,\n            walletAddress: creditPayload.sub,\n            unlockedArticles: Array.isArray(creditPayload.articles) ? creditPayload.articles : [],\n            siteWideUnlock: Boolean(creditPayload.siteWide),\n            createdAt: creditPayload.iat ?? 0,\n            expiresAt: creditPayload.exp,\n            credits: creditPayload.credits ?? 0,\n            bundleExpiry: creditPayload.bundleExpiry,\n            bundleType: creditPayload.bundleType,\n        };\n\n        return { valid: true, session };\n    } catch {\n        return { valid: false, reason: 'Invalid session' };\n    }\n}\n\n/** Result of using a credit */\nexport interface UseCreditResult {\n    /** Whether the credit was successfully used */\n    success: boolean;\n    /** Remaining credits after use */\n    remainingCredits: number;\n    /** New token with decremented credits (if successful) */\n    newToken?: string;\n    /** Error message (if failed) */\n    error?: string;\n}\n\n/**\n * Use one credit from the session\n * Returns a new token with decremented credit count\n * \n * @example\n * ```typescript\n * import { useCredit } from '@alleyboss/micropay-solana-x402-paywall/agent';\n * \n * const result = await useCredit(token, process.env.SESSION_SECRET!);\n * \n * if (result.success) {\n *   console.log(`Credit used. ${result.remainingCredits} remaining`);\n *   // Update cookie with new token\n *   response.cookies.set('x402_credits', result.newToken!);\n * } else {\n *   console.log('No credits:', result.error);\n * }\n * ```\n */\nexport async function useCredit(\n    token: string,\n    secret: string,\n    creditsToUse: number = 1\n): Promise<UseCreditResult> {\n    if (creditsToUse <= 0) {\n        return { success: false, remainingCredits: 0, error: 'Invalid credit amount' };\n    }\n\n    const validation = await validateCreditSession(token, secret);\n\n    if (!validation.valid || !validation.session) {\n        return {\n            success: false,\n            remainingCredits: 0,\n            error: validation.reason || 'Invalid session'\n        };\n    }\n\n    const session = validation.session;\n\n    // Check if enough credits\n    if (session.credits < creditsToUse) {\n        return {\n            success: false,\n            remainingCredits: session.credits,\n            error: 'Insufficient credits'\n        };\n    }\n\n    // Decrement credits and create new token\n    const newCredits = session.credits - creditsToUse;\n\n    const payload: CreditJWTPayload = {\n        sub: session.walletAddress,\n        sid: session.id,\n        articles: session.unlockedArticles,\n        siteWide: session.siteWideUnlock,\n        credits: newCredits,\n        bundleExpiry: session.bundleExpiry,\n        bundleType: session.bundleType,\n        iat: session.createdAt,\n        exp: session.expiresAt,\n    };\n\n    const newToken = await new SignJWT(payload as unknown as Record<string, unknown>)\n        .setProtectedHeader({ alg: 'HS256' })\n        .sign(getSecretKey(secret));\n\n    return {\n        success: true,\n        remainingCredits: newCredits,\n        newToken,\n    };\n}\n\n/**\n * Add credits to an existing session\n * Useful for top-ups or rewards\n */\nexport async function addCredits(\n    token: string,\n    secret: string,\n    creditsToAdd: number\n): Promise<{ success: boolean; newToken?: string; totalCredits?: number; error?: string }> {\n    if (creditsToAdd <= 0 || creditsToAdd > MAX_CREDITS) {\n        return { success: false, error: 'Invalid credit amount' };\n    }\n\n    const validation = await validateCreditSession(token, secret);\n\n    if (!validation.valid || !validation.session) {\n        return { success: false, error: validation.reason || 'Invalid session' };\n    }\n\n    const session = validation.session;\n    const newCredits = Math.min(session.credits + creditsToAdd, MAX_CREDITS);\n\n    const payload: CreditJWTPayload = {\n        sub: session.walletAddress,\n        sid: session.id,\n        articles: session.unlockedArticles,\n        siteWide: session.siteWideUnlock,\n        credits: newCredits,\n        bundleExpiry: session.bundleExpiry,\n        bundleType: session.bundleType,\n        iat: session.createdAt,\n        exp: session.expiresAt,\n    };\n\n    const newToken = await new SignJWT(payload as unknown as Record<string, unknown>)\n        .setProtectedHeader({ alg: 'HS256' })\n        .sign(getSecretKey(secret));\n\n    return {\n        success: true,\n        newToken,\n        totalCredits: newCredits,\n    };\n}\n\n/**\n * Get remaining credits from a session token (quick check without full validation)\n */\nexport async function getRemainingCredits(\n    token: string,\n    secret: string\n): Promise<{ credits: number; valid: boolean; bundleExpiry?: number }> {\n    const validation = await validateCreditSession(token, secret);\n\n    if (!validation.valid || !validation.session) {\n        return { credits: 0, valid: false };\n    }\n\n    return {\n        credits: validation.session.credits,\n        valid: true,\n        bundleExpiry: validation.session.bundleExpiry,\n    };\n}\n"]}