agentwallet-sdk 5.0.2 → 5.0.3

package/README.md

@@ -204,9 +204,45 @@ await escrow.verify(escrowId);
 
 Premium access: [github.com/up2itnow/AgentNexus2](https://github.com/up2itnow/AgentNexus2)
 
+## x402 Protocol: Supported Chains and Payment Rails
+
+x402 (HTTP 402 Payment Required) is the native payment protocol for agent-to-service transactions. The agent encounters a 402 response, signs a payment proof, and re-sends the request. One round trip. No accounts, no API keys, no invoices.
+
+As of March 2026, x402 is live on 3 chains/rails:
+
+| Chain / Rail | Status | Settlement Token | Gas Cost | Notes |
+|---|---|---|---|---|
+| **Base** (Coinbase L2) | Live | USDC | Sub-cent | Primary x402 chain. 15M+ transactions in Jan 2026. |
+| **Etherlink** (Tezos L2) | Live (Mar 2026) | USDC | Sub-cent | EVM-compatible. Same x402 integration, different RPC + chain ID. |
+| **Stripe** (Fiat offramp) | Live (Feb 2026) | USDC -> USD | N/A | Vendors receive USD in Stripe dashboard. Agents pay USDC. |
+
+### x402 + Etherlink Quick Start
+
+```typescript
+import { createWallet, agentExecute } from 'agentwallet-sdk';
+
+const wallet = createWallet({
+  accountAddress: '0xYourAgent',
+  chain: 'etherlink',  // new: Tezos L2 support
+  walletClient,
+});
+
+// x402 payment flow is identical across chains
+const response = await fetch('https://api.vendor.com/data');
+if (response.status === 402) {
+  const details = await response.json();
+  const proof = await wallet.createX402Proof(details);
+  const paid = await fetch('https://api.vendor.com/data', {
+    headers: { 'X-Payment': proof }
+  });
+}
+```
+
+The SDK handles chain-specific RPC endpoints, gas estimation, and USDC contract addresses automatically. Swap `chain: 'base'` to `chain: 'etherlink'` and the x402 flow works identically.
+
 ## Supported Chains
 
-Mainnet: Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC, Celo, Gnosis, Linea, Mantle, Scroll, and more.
+Mainnet: Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC, Celo, Gnosis, Linea, Mantle, Scroll, Etherlink, and more.
 
 Testnet: Base Sepolia, Arbitrum Sepolia, and corresponding testnets.
 

package/dist/verifiable-intent/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Mastercard Verifiable Intent module for agentwallet-sdk.
+ * @module verifiable-intent
+ */
+
+export interface AgentIdentity {
+  agentId: string;
+  principalId: string;
+  agenticToken: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export interface ScopeConstraints {
+  maxAmountPerTx: number;
+  maxAmountPerDay: number;
+  maxTxPerDay: number;
+  allowedMerchantCategories?: string[];
+  allowedCurrencies?: string[];
+  windowStartUtc?: number;
+  windowEndUtc?: number;
+}
+
+export interface IntentDeclaration {
+  intentId: string;
+  agentId: string;
+  action: 'pay' | 'subscribe' | 'escrow' | 'refund';
+  amount: number;
+  currency: string;
+  recipientId: string;
+  description: string;
+  createdAt: number;
+  expiresAt: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SignedIntent {
+  intent: IntentDeclaration;
+  signature: string;
+  agenticToken: string;
+  signatureAlgorithm: string;
+}
+
+export interface VerificationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export interface VerifiableIntentConfig {
+  agentId: string;
+  principalId: string;
+  signingSecret: string;
+  scope: ScopeConstraints;
+  tokenTtlSeconds?: number;
+  intentTtlSeconds?: number;
+}
+
+export declare class VerifiableIntentClient {
+  identity: AgentIdentity;
+  constructor(config: VerifiableIntentConfig);
+  createIntent(params: {
+    action: 'pay' | 'subscribe' | 'escrow' | 'refund';
+    amount: number;
+    currency: string;
+    recipientId: string;
+    description: string;
+    metadata?: Record<string, unknown>;
+  }): SignedIntent;
+  verify(signedIntent: SignedIntent): VerificationResult;
+  recordExecution(signedIntent: SignedIntent): void;
+  getDailyUsage(): {
+    spentToday: number;
+    txToday: number;
+    remainingBudget: number;
+    remainingTx: number;
+  };
+  static serialize(signedIntent: SignedIntent): string;
+  static deserialize(json: string): SignedIntent;
+}
+
+export declare class VerifiableIntentError extends Error {
+  context?: unknown;
+  constructor(message: string, context?: unknown);
+}

package/dist/verifiable-intent/index.js

@@ -0,0 +1,385 @@
+/**
+ * VerifiableIntent — Mastercard Verifiable Intent implementation for agentwallet-sdk
+ *
+ * Implements the Mastercard Verifiable Intent open standard (March 2026):
+ *   - Create signed intent declarations for agent transactions
+ *   - Verify intent signatures and scope constraints
+ *   - Enforce spending caps, time windows, and merchant category limits
+ *   - Compatible with Google AP2 (Agent Payments Protocol)
+ *
+ * The spec defines four pillars:
+ *   1. Agent Identity — unique Agentic Token per agent
+ *   2. Intent Declaration — structured payload describing the transaction
+ *   3. Authorization Chain — proof of human/system delegation
+ *   4. Scope Limits — spending caps, time windows, merchant categories
+ *
+ * @module verifiable-intent
+ */
+
+import { createHash, createHmac, randomUUID } from 'crypto';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} AgentIdentity
+ * @property {string} agentId - Unique agent identifier (UUID or DID)
+ * @property {string} principalId - Human/system that delegated authority
+ * @property {string} agenticToken - Signed token proving agent registration
+ * @property {number} issuedAt - Unix timestamp of token issuance
+ * @property {number} expiresAt - Unix timestamp of token expiry
+ */
+
+/**
+ * @typedef {Object} ScopeConstraints
+ * @property {number} maxAmountPerTx - Maximum amount per single transaction (in minor units)
+ * @property {number} maxAmountPerDay - Maximum cumulative daily spend (in minor units)
+ * @property {number} maxTxPerDay - Maximum number of transactions per day
+ * @property {string[]} [allowedMerchantCategories] - MCC codes the agent can transact with
+ * @property {string[]} [allowedCurrencies] - ISO 4217 currency codes permitted
+ * @property {number} [windowStartUtc] - Unix timestamp: scope validity start
+ * @property {number} [windowEndUtc] - Unix timestamp: scope validity end
+ */
+
+/**
+ * @typedef {Object} IntentDeclaration
+ * @property {string} intentId - Unique ID for this intent (UUID v4)
+ * @property {string} agentId - Agent making the request
+ * @property {string} action - What the agent wants to do ('pay', 'subscribe', 'escrow', 'refund')
+ * @property {number} amount - Transaction amount in minor units
+ * @property {string} currency - ISO 4217 currency code
+ * @property {string} recipientId - Merchant/service/agent receiving payment
+ * @property {string} description - Human-readable purpose
+ * @property {number} createdAt - Unix timestamp
+ * @property {number} expiresAt - Unix timestamp when intent becomes invalid
+ * @property {Object} [metadata] - Additional key-value pairs
+ */
+
+/**
+ * @typedef {Object} SignedIntent
+ * @property {IntentDeclaration} intent - The intent payload
+ * @property {string} signature - HMAC-SHA256 signature of the canonical intent
+ * @property {string} agenticToken - The agent's identity token
+ * @property {string} signatureAlgorithm - Always 'HMAC-SHA256' in this implementation
+ */
+
+/**
+ * @typedef {Object} VerificationResult
+ * @property {boolean} valid - Whether the intent passes all checks
+ * @property {string[]} errors - List of validation failures (empty if valid)
+ */
+
+// ---------------------------------------------------------------------------
+// Core Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * VerifiableIntentClient — Create, sign, and verify Mastercard Verifiable Intent payloads.
+ *
+ * @example
+ * ```typescript
+ * const vi = new VerifiableIntentClient({
+ *   agentId: 'agent-001',
+ *   principalId: 'user-bill',
+ *   signingSecret: process.env.AGENT_SIGNING_SECRET,
+ *   scope: {
+ *     maxAmountPerTx: 10000,    // $100.00
+ *     maxAmountPerDay: 50000,   // $500.00
+ *     maxTxPerDay: 20,
+ *     allowedCurrencies: ['USD', 'EUR'],
+ *   }
+ * });
+ *
+ * const signed = vi.createIntent({
+ *   action: 'pay',
+ *   amount: 5000,
+ *   currency: 'USD',
+ *   recipientId: 'merchant-xyz',
+ *   description: 'API compute credits',
+ * });
+ *
+ * const result = vi.verify(signed);
+ * // { valid: true, errors: [] }
+ * ```
+ */
+export class VerifiableIntentClient {
+  /**
+   * @param {Object} config
+   * @param {string} config.agentId - Unique agent identifier
+   * @param {string} config.principalId - Human/system principal who delegated authority
+   * @param {string} config.signingSecret - Secret key for HMAC signing (min 32 chars)
+   * @param {ScopeConstraints} config.scope - Spending and authorization constraints
+   * @param {number} [config.tokenTtlSeconds=86400] - Agentic token lifetime (default 24h)
+   * @param {number} [config.intentTtlSeconds=300] - Intent validity window (default 5 min)
+   */
+  constructor(config) {
+    if (!config.signingSecret || config.signingSecret.length < 32) {
+      throw new VerifiableIntentError('signingSecret must be at least 32 characters');
+    }
+    this.agentId = config.agentId;
+    this.principalId = config.principalId;
+    this.signingSecret = config.signingSecret;
+    this.scope = config.scope;
+    this.tokenTtlSeconds = config.tokenTtlSeconds ?? 86400;
+    this.intentTtlSeconds = config.intentTtlSeconds ?? 300;
+
+    // Daily tracking for scope enforcement
+    this._dailySpend = 0;
+    this._dailyTxCount = 0;
+    this._dailyResetDate = this._todayUtc();
+
+    // Generate agentic token on initialization
+    this.identity = this._issueAgenticToken();
+  }
+
+  /**
+   * Create and sign a Verifiable Intent declaration.
+   *
+   * @param {Object} params
+   * @param {string} params.action - 'pay' | 'subscribe' | 'escrow' | 'refund'
+   * @param {number} params.amount - Amount in minor units (cents)
+   * @param {string} params.currency - ISO 4217 currency code
+   * @param {string} params.recipientId - Recipient identifier
+   * @param {string} params.description - Human-readable purpose
+   * @param {Object} [params.metadata] - Additional context
+   * @returns {SignedIntent}
+   */
+  createIntent(params) {
+    const now = Math.floor(Date.now() / 1000);
+
+    // Check token validity
+    if (now >= this.identity.expiresAt) {
+      this.identity = this._issueAgenticToken();
+    }
+
+    const intent = {
+      intentId: randomUUID(),
+      agentId: this.agentId,
+      action: params.action,
+      amount: params.amount,
+      currency: params.currency,
+      recipientId: params.recipientId,
+      description: params.description,
+      createdAt: now,
+      expiresAt: now + this.intentTtlSeconds,
+      metadata: params.metadata ?? {},
+    };
+
+    // Pre-sign scope validation
+    const scopeCheck = this._checkScope(intent);
+    if (!scopeCheck.valid) {
+      throw new VerifiableIntentError(
+        `Intent blocked by scope constraints: ${scopeCheck.errors.join(', ')}`
+      );
+    }
+
+    const canonical = this._canonicalize(intent);
+    const signature = this._sign(canonical);
+
+    return {
+      intent,
+      signature,
+      agenticToken: this.identity.agenticToken,
+      signatureAlgorithm: 'HMAC-SHA256',
+    };
+  }
+
+  /**
+   * Verify a signed intent declaration.
+   *
+   * Checks:
+   *   1. Signature validity (HMAC-SHA256)
+   *   2. Intent not expired
+   *   3. Agent identity matches
+   *   4. Scope constraints satisfied
+   *
+   * @param {SignedIntent} signedIntent
+   * @returns {VerificationResult}
+   */
+  verify(signedIntent) {
+    const errors = [];
+    const { intent, signature, agenticToken } = signedIntent;
+    const now = Math.floor(Date.now() / 1000);
+
+    // 1. Signature check
+    const canonical = this._canonicalize(intent);
+    const expectedSig = this._sign(canonical);
+    if (signature !== expectedSig) {
+      errors.push('Invalid signature');
+    }
+
+    // 2. Expiry check
+    if (now >= intent.expiresAt) {
+      errors.push(`Intent expired at ${new Date(intent.expiresAt * 1000).toISOString()}`);
+    }
+
+    // 3. Agent identity check
+    if (intent.agentId !== this.agentId) {
+      errors.push(`Agent ID mismatch: expected ${this.agentId}, got ${intent.agentId}`);
+    }
+
+    // 4. Agentic token check
+    if (agenticToken !== this.identity.agenticToken) {
+      errors.push('Agentic token mismatch or expired');
+    }
+
+    // 5. Scope constraints
+    const scopeResult = this._checkScope(intent);
+    errors.push(...scopeResult.errors);
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Record a completed transaction against daily limits.
+   * Call this after a verified intent is successfully executed.
+   *
+   * @param {SignedIntent} signedIntent - The executed intent
+   */
+  recordExecution(signedIntent) {
+    this._resetDailyIfNeeded();
+    this._dailySpend += signedIntent.intent.amount;
+    this._dailyTxCount += 1;
+  }
+
+  /**
+   * Get current daily usage against scope limits.
+   *
+   * @returns {{ spentToday: number, txToday: number, remainingBudget: number, remainingTx: number }}
+   */
+  getDailyUsage() {
+    this._resetDailyIfNeeded();
+    return {
+      spentToday: this._dailySpend,
+      txToday: this._dailyTxCount,
+      remainingBudget: Math.max(0, this.scope.maxAmountPerDay - this._dailySpend),
+      remainingTx: Math.max(0, this.scope.maxTxPerDay - this._dailyTxCount),
+    };
+  }
+
+  /**
+   * Serialize a signed intent to a portable JSON string for transmission.
+   *
+   * @param {SignedIntent} signedIntent
+   * @returns {string} JSON string
+   */
+  static serialize(signedIntent) {
+    return JSON.stringify(signedIntent);
+  }
+
+  /**
+   * Deserialize a JSON string back to a SignedIntent object.
+   *
+   * @param {string} json
+   * @returns {SignedIntent}
+   */
+  static deserialize(json) {
+    const parsed = JSON.parse(json);
+    if (!parsed.intent || !parsed.signature || !parsed.agenticToken) {
+      throw new VerifiableIntentError('Invalid SignedIntent structure');
+    }
+    return parsed;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private methods
+  // -------------------------------------------------------------------------
+
+  _issueAgenticToken() {
+    const now = Math.floor(Date.now() / 1000);
+    const payload = `${this.agentId}:${this.principalId}:${now}`;
+    const token = createHmac('sha256', this.signingSecret)
+      .update(payload)
+      .digest('hex');
+    return {
+      agentId: this.agentId,
+      principalId: this.principalId,
+      agenticToken: token,
+      issuedAt: now,
+      expiresAt: now + this.tokenTtlSeconds,
+    };
+  }
+
+  _canonicalize(intent) {
+    // Deterministic JSON serialization: sorted keys, no whitespace
+    const ordered = {
+      action: intent.action,
+      agentId: intent.agentId,
+      amount: intent.amount,
+      createdAt: intent.createdAt,
+      currency: intent.currency,
+      description: intent.description,
+      expiresAt: intent.expiresAt,
+      intentId: intent.intentId,
+      metadata: intent.metadata,
+      recipientId: intent.recipientId,
+    };
+    return JSON.stringify(ordered);
+  }
+
+  _sign(canonical) {
+    return createHmac('sha256', this.signingSecret)
+      .update(canonical)
+      .digest('hex');
+  }
+
+  _checkScope(intent) {
+    const errors = [];
+    this._resetDailyIfNeeded();
+
+    if (intent.amount > this.scope.maxAmountPerTx) {
+      errors.push(`Amount ${intent.amount} exceeds per-tx limit ${this.scope.maxAmountPerTx}`);
+    }
+
+    if (this._dailySpend + intent.amount > this.scope.maxAmountPerDay) {
+      errors.push(
+        `Daily spend would be ${this._dailySpend + intent.amount}, exceeds limit ${this.scope.maxAmountPerDay}`
+      );
+    }
+
+    if (this._dailyTxCount + 1 > this.scope.maxTxPerDay) {
+      errors.push(`Daily tx count would exceed limit ${this.scope.maxTxPerDay}`);
+    }
+
+    if (this.scope.allowedCurrencies && !this.scope.allowedCurrencies.includes(intent.currency)) {
+      errors.push(`Currency ${intent.currency} not in allowed list: ${this.scope.allowedCurrencies.join(', ')}`);
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    if (this.scope.windowStartUtc && now < this.scope.windowStartUtc) {
+      errors.push('Current time is before scope validity window');
+    }
+    if (this.scope.windowEndUtc && now >= this.scope.windowEndUtc) {
+      errors.push('Current time is past scope validity window');
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  _todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+  }
+
+  _resetDailyIfNeeded() {
+    const today = this._todayUtc();
+    if (today !== this._dailyResetDate) {
+      this._dailySpend = 0;
+      this._dailyTxCount = 0;
+      this._dailyResetDate = today;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class VerifiableIntentError extends Error {
+  constructor(message, context) {
+    super(message);
+    this.context = context;
+    this.name = 'VerifiableIntentError';
+  }
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwallet-sdk",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "Non-custodial AI agent wallet SDK. ERC-8004 identity & reputation registries, mutual stake escrow, x402 payments, 17-chain CCTP bridging, ERC-6551 TBA, SpendingPolicy guardrails, Uniswap V3 swap. The agent holds the keys.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,4 +48,4 @@
     "typescript": "5.3.3",
     "vitest": "4.0.18"
   }
-}
+}