v0.2.11: sync from monorepo 2026-06-03

Author: azeth-sync[bot]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/sdk",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "type": "module",
   "description": "TypeScript SDK for the Azeth trust infrastructure — smart accounts, x402 payments, reputation, and service discovery",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "test:mutation": "npx stryker run"
   },
   "dependencies": {
-    "@azeth/common": "^0.2.10",
+    "@azeth/common": "^0.2.11",
     "@x402/core": "^2.14.0",
     "@x402/extensions": "^2.14.0",
     "@xmtp/agent-sdk": "^2.2.0",

src/account/history.ts

@@ -24,6 +24,19 @@ export interface TransactionRecord {
   timestamp: number;
 }
 
+/** Shape of a single record returned by the server's GET /api/v1/history.
+ *  The server wraps records in `{ data, meta }` and serializes the bigint
+ *  fields (value, blockNumber) as JSON-safe strings. */
+interface ServerHistoryRecord {
+  hash: `0x${string}`;
+  from: `0x${string}`;
+  to: `0x${string}` | null;
+  value: string;
+  token: `0x${string}` | null;
+  blockNumber: string;
+  timestamp: number;
+}
+
 /** Pad an address to a 32-byte hex topic for event log filtering */
 function addressToTopic(addr: `0x${string}`): `0x${string}` {
   return `0x000000000000000000000000${addr.slice(2).toLowerCase()}` as `0x${string}`;
@@ -51,7 +64,20 @@ export async function getHistory(
     try {
       const response = await withRetry(() => fetch(`${serverUrl}/api/v1/history?${queryParams}`));
       if (response.ok) {
-        return await response.json() as TransactionRecord[];
+        // The server returns { data, meta } (not a bare array) and serializes
+        // bigint fields as strings. Unwrap the envelope and restore the bigint
+        // types declared by TransactionRecord so callers (e.g. the MCP tool's
+        // formatTokenAmount) receive the contract they expect.
+        const body = await response.json() as { data?: ServerHistoryRecord[] };
+        return (body.data ?? []).map((r) => ({
+          hash: r.hash,
+          from: r.from,
+          to: r.to,
+          value: BigInt(r.value),
+          token: r.token,
+          blockNumber: BigInt(r.blockNumber),
+          timestamp: r.timestamp,
+        }));
       }
       // Non-OK response — fall through to on-chain fallback
     } catch {

src/payments/smart-fetch.ts

@@ -101,7 +101,9 @@ export async function smartFetch402(
   const resolvedChain = chainName ?? chainIdToName(publicClient.chain?.id ?? 0) ?? 'baseSepolia' as SupportedChainName;
   const discoveryResult = await discoverServicesWithFallback(serverUrl, discoveryParams, publicClient, resolvedChain);
   const services = discoveryResult.entries
-    .filter(s => !!s.endpoint)
+    // Reject empty AND whitespace-only endpoints — registry entries with " "
+    // are truthy but produce `fetch(" ")` → "Invalid URL", aborting the fallback (S-3).
+    .filter(s => !!s.endpoint?.trim())
     .slice(0, maxRetries);
 
   if (services.length === 0) {
@@ -126,8 +128,8 @@ export async function smartFetch402(
   for (let i = 0; i < services.length; i++) {
     const service = services[i]!;
 
-    // Skip services without an endpoint
-    if (!service.endpoint) {
+    // Skip services without a usable endpoint (empty or whitespace-only)
+    if (!service.endpoint?.trim()) {
       failedServices.push({ service, error: 'No endpoint URL' });
       continue;
     }

src/payments/x402.ts

@@ -311,8 +311,8 @@ export async function fetch402(
   // Check budget (default cap: 10 USDC if not specified)
   const effectiveMaxAmount = options?.maxAmount ?? DEFAULT_MAX_AMOUNT;
   if (amount > effectiveMaxAmount) {
-    const requiredFmt = formatTokenAmount(amount, 6, 2);
-    const maxFmt = formatTokenAmount(effectiveMaxAmount, 6, 2);
+    const requiredFmt = formatTokenAmount(amount, 6);
+    const maxFmt = formatTokenAmount(effectiveMaxAmount, 6);
     throw new AzethError(
       `Payment of ${requiredFmt} USDC exceeds maximum of ${maxFmt} USDC`,
       'BUDGET_EXCEEDED',
@@ -683,8 +683,8 @@ async function attemptSmartAccountPayment(
     // Budget check
     const effectiveMaxAmount = options.maxAmount ?? DEFAULT_MAX_AMOUNT;
     if (amount > effectiveMaxAmount) {
-      const requiredFmt = formatTokenAmount(amount, 6, 2);
-      const maxFmt = formatTokenAmount(effectiveMaxAmount, 6, 2);
+      const requiredFmt = formatTokenAmount(amount, 6);
+      const maxFmt = formatTokenAmount(effectiveMaxAmount, 6);
       throw new AzethError(
         `Payment of ${requiredFmt} USDC exceeds maximum of ${maxFmt} USDC`,
         'BUDGET_EXCEEDED',

src/utils/userop.ts

@@ -16,6 +16,7 @@ import {
   entryPoint07Abi,
   entryPoint07Address,
   getUserOperationHash,
+  prepareUserOperation,
 } from 'viem/account-abstraction';
 import { createSmartAccountClient, type SmartAccountClient as PermissionlessSmartAccountClient } from 'permissionless';
 import { AzethAccountAbi } from '@azeth/common/abis';
@@ -194,6 +195,30 @@ export async function createAzethSmartAccount(
   });
 }
 
+/**
+ * Multiplier (numerator / denominator) applied to the bundler's estimated
+ * `verificationGasLimit`.
+ *
+ * GuardianModule.validateUserOp burns a STATE-DEPENDENT amount of verification
+ * gas: oracle staticcalls, a daily-spend SSTORE (cold ~20k / warm ~5k), and a
+ * conditional epoch reset. The bundler estimates against on-chain state at
+ * estimation time, but that slot can be cold (or the epoch can roll over) by
+ * execution time, so the real verification cost can exceed a tight point
+ * estimate — deterministically reverting with `AA26 over verificationGasLimit`.
+ * A 1.5x buffer absorbs that variance; unused gas is refunded by the EntryPoint,
+ * so over-provisioning is safe. This restores the headroom lost when the flat
+ * 300K override was removed alongside the v22 GuardianModule estimation fix, but
+ * as a proportional multiplier rather than a magic constant.
+ */
+const VERIFICATION_GAS_BUFFER_NUMERATOR = 3n;
+const VERIFICATION_GAS_BUFFER_DENOMINATOR = 2n;
+
+/** Apply the verification-gas safety buffer to a bundler estimate.
+ *  See {@link VERIFICATION_GAS_BUFFER_NUMERATOR} for why this is needed. */
+export function applyVerificationGasBuffer(verificationGasLimit: bigint): bigint {
+  return (verificationGasLimit * VERIFICATION_GAS_BUFFER_NUMERATOR) / VERIFICATION_GAS_BUFFER_DENOMINATOR;
+}
+
 /**
  * Create a permissionless SmartAccountClient for an AzethAccount.
  *
@@ -273,6 +298,20 @@ export async function createAzethSmartAccountClient(
     chain: publicClient.chain,
     bundlerTransport: http(resolvedBundlerUrl),
     client: publicClient,
+    // Absorb state-dependent GuardianModule verification-gas variance (see
+    // applyVerificationGasBuffer). Wrapping prepareUserOperation applies the
+    // buffer to EVERY UserOp submitted through this client — value transfers,
+    // agreement executions, x402 settlement — so a cold daily-spend slot can't
+    // deterministically AA26 a funded account's first value-spend.
+    userOperation: {
+      prepareUserOperation: async (client, parameters) => {
+        const prepared = await prepareUserOperation(client, parameters);
+        return {
+          ...prepared,
+          verificationGasLimit: applyVerificationGasBuffer(prepared.verificationGasLimit),
+        };
+      },
+    },
   };
 
   // Wire paymaster middleware when URL is available.

test/account/history.test.ts

@@ -16,25 +16,47 @@ describe('account/history', () => {
   });
 
   describe('server-based history (with serverUrl)', () => {
-    it('should fetch history from the server API', async () => {
-      const mockRecords = [
-        {
-          hash: '0xabc' as `0x${string}`,
-          from: TEST_ACCOUNT,
-          to: '0x1234' as `0x${string}`,
-          value: 100n,
-          blockNumber: 50n,
-          timestamp: 1700000000,
-        },
-      ];
+    it('parses the { data, meta } envelope and restores bigint fields (F-5)', async () => {
+      // The real server wraps records in { data, meta } and serializes the
+      // bigint fields (value, blockNumber) as JSON strings. The SDK previously
+      // cast the whole body to TransactionRecord[], so it returned the wrapper
+      // object instead of the records (and string-typed values).
+      const serverBody = {
+        data: [
+          {
+            hash: '0xabc' as `0x${string}`,
+            from: TEST_ACCOUNT,
+            to: '0x1234' as `0x${string}`,
+            value: '100',
+            token: null,
+            type: 'transfer',
+            timestamp: 1700000000,
+            blockNumber: '50',
+          },
+        ],
+        meta: { count: 1, nextCursor: undefined },
+      };
 
       globalThis.fetch = vi.fn().mockResolvedValue(
-        createMockResponse(200, mockRecords),
+        createMockResponse(200, serverBody),
       );
 
       const result = await getHistory(publicClient, TEST_ACCOUNT, 'https://api.azeth.ai');
 
-      expect(result).toEqual(mockRecords);
+      expect(result).toEqual([
+        {
+          hash: '0xabc',
+          from: TEST_ACCOUNT,
+          to: '0x1234',
+          value: 100n,
+          token: null,
+          blockNumber: 50n,
+          timestamp: 1700000000,
+        },
+      ]);
+      // bigint fields restored from JSON strings
+      expect(result[0]?.value).toBe(100n);
+      expect(result[0]?.blockNumber).toBe(50n);
       expect(globalThis.fetch).toHaveBeenCalledWith(
         expect.stringContaining('https://api.azeth.ai/api/v1/history'),
       );

test/payments/smart-fetch.test.ts

@@ -202,6 +202,29 @@ describe('smartFetch402 (standalone routing layer)', () => {
     expect(result.failedServices).toBeUndefined();
   });
 
+  it('should filter out whitespace-only endpoints before attempting (S-3)', async () => {
+    const spaceEndpoint = makeService({ tokenId: 1n, name: 'SpaceEndpoint', endpoint: ' ' });
+    const blankEndpoint = makeService({ tokenId: 2n, name: 'BlankEndpoint', endpoint: '   ' });
+    const withEndpoint = makeService({ tokenId: 3n, name: 'HasEndpoint', endpoint: 'https://good.example.com' });
+    mockedDiscover.mockResolvedValueOnce({ entries: [spaceEndpoint, blankEndpoint, withEndpoint], source: 'server' });
+    mockedFetch402.mockResolvedValueOnce(makeFetch402Result());
+
+    const result = await smartFetch402(
+      publicClient as any, walletClient as any, TEST_OWNER, SERVER_URL,
+      'price-feed',
+    );
+
+    // The whitespace endpoints are truthy but would make fetch(" ") throw "Invalid
+    // URL"; they must be skipped so the valid service is the one attempted.
+    expect(result.service.name).toBe('HasEndpoint');
+    expect(result.attemptsCount).toBe(1);
+    expect(mockedFetch402).toHaveBeenCalledTimes(1);
+    expect(mockedFetch402).toHaveBeenCalledWith(
+      expect.anything(), expect.anything(), TEST_OWNER, 'https://good.example.com',
+      expect.anything(),
+    );
+  });
+
   it('should move preferredService to the front', async () => {
     const service1 = makeService({ tokenId: 1n, name: 'First', reputation: 95 });
     const service2 = makeService({ tokenId: 2n, name: 'Preferred', reputation: 80, endpoint: 'https://preferred.example.com' });

test/payments/x402.test.ts

@@ -180,7 +180,23 @@ describe('payments/x402', () => {
         fetch402(publicClient, walletClient, TEST_ACCOUNT, testUrl, {
           maxAmount: 500000n, // 0.5 USDC, less than the 1 USDC required
         }),
-      ).rejects.toThrow('Payment of 1 USDC exceeds maximum of 0.50 USDC');
+      ).rejects.toThrow('Payment of 1 USDC exceeds maximum of 0.5 USDC');
+    });
+
+    it('shows sub-cent maxAmount at full precision in the error (F-8)', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue(
+        createMockResponse(402, null, {
+          'X-Payment-Required': JSON.stringify(paymentRequirement),
+        }),
+      );
+
+      // 0.009 USDC used to round to "0.01" (self-contradictory: "0.01 exceeds 0.01"),
+      // and 0.001 USDC rounded to "0". Full precision shows the real cap.
+      await expect(
+        fetch402(publicClient, walletClient, TEST_ACCOUNT, testUrl, {
+          maxAmount: 9000n, // 0.009 USDC
+        }),
+      ).rejects.toThrow('Payment of 1 USDC exceeds maximum of 0.009 USDC');
     });
 
     it('should not throw when payment is within maxAmount budget', async () => {
@@ -595,7 +611,8 @@ describe('payments/x402', () => {
           smartAccountTransfer: mockSmartAccountTransfer,
           maxAmount: 500000n, // 0.5 USDC, less than the 1 USDC required
         }),
-      ).rejects.toThrow('Payment of 1 USDC exceeds maximum of 0.50 USDC');
+      ).rejects.toThrow('Payment of 1 USDC exceeds maximum of 0.5 USDC');
     });
+
   });
 });

test/utils/userop.test.ts

@@ -6,6 +6,7 @@ const {
   mockToSmartAccount,
   mockGetPaymasterData,
   mockGetPaymasterStubData,
+  mockPrepareUserOperation,
 } = vi.hoisted(() => ({
   mockCreateSmartAccountClient: vi.fn().mockReturnValue({
     sendTransaction: vi.fn(),
@@ -19,6 +20,7 @@ const {
   }),
   mockGetPaymasterData: vi.fn().mockResolvedValue({ paymaster: '0xPaymaster', paymasterData: '0xdata' }),
   mockGetPaymasterStubData: vi.fn().mockResolvedValue({ paymaster: '0xPaymaster', paymasterData: '0xstubdata' }),
+  mockPrepareUserOperation: vi.fn(),
 }));
 
 vi.mock('permissionless', () => ({
@@ -30,6 +32,7 @@ vi.mock('viem/account-abstraction', () => ({
   entryPoint07Abi: [],
   entryPoint07Address: '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
   getUserOperationHash: vi.fn().mockReturnValue('0x' + '00'.repeat(32)),
+  prepareUserOperation: mockPrepareUserOperation,
 }));
 
 vi.mock('viem', async (importOriginal) => {
@@ -53,7 +56,7 @@ vi.mock('@azeth/common/abis', () => ({
   AzethAccountAbi: [],
 }));
 
-import { createAzethSmartAccountClient } from '../../src/utils/userop.js';
+import { createAzethSmartAccountClient, applyVerificationGasBuffer } from '../../src/utils/userop.js';
 import type { PublicClient, WalletClient, Transport, Chain, Account } from 'viem';
 
 function mockPublicClient(overrides: Record<string, unknown> = {}): PublicClient<Transport, Chain> {
@@ -212,4 +215,63 @@ describe('createAzethSmartAccountClient', () => {
       }),
     ).rejects.toThrow('bundlerUrl is required');
   });
+
+  // F-2: native value-spends deterministically AA26'd because the SDK took the
+  // bundler's verificationGasLimit estimate verbatim, leaving no headroom for
+  // GuardianModule's state-dependent validation gas (cold daily-spend SSTORE,
+  // epoch reset). The client must install a prepareUserOperation hook that
+  // buffers verificationGasLimit for EVERY UserOp.
+  it('installs a prepareUserOperation hook that buffers verificationGasLimit (F-2)', async () => {
+    mockPrepareUserOperation.mockResolvedValue({
+      sender: TEST_SMART_ACCOUNT,
+      nonce: 1n,
+      callData: '0x',
+      callGasLimit: 50_000n,
+      verificationGasLimit: 100_000n,
+      preVerificationGas: 40_000n,
+      maxFeePerGas: 1n,
+      maxPriorityFeePerGas: 1n,
+      signature: '0x',
+    });
+
+    await createAzethSmartAccountClient({
+      publicClient: mockPublicClient(),
+      walletClient: mockWalletClient(),
+      smartAccountAddress: TEST_SMART_ACCOUNT,
+      bundlerUrl: TEST_BUNDLER_URL,
+    });
+
+    const callArgs = mockCreateSmartAccountClient.mock.calls[0][0];
+    expect(callArgs.userOperation).toBeDefined();
+    expect(callArgs.userOperation.prepareUserOperation).toBeTypeOf('function');
+
+    // Invoke the installed hook: it must delegate to viem's prepareUserOperation
+    // and return the SAME op with only verificationGasLimit scaled up 1.5x.
+    const fakeClient = {} as never;
+    const fakeParams = {} as never;
+    const prepared = await callArgs.userOperation.prepareUserOperation(fakeClient, fakeParams);
+
+    expect(mockPrepareUserOperation).toHaveBeenCalledWith(fakeClient, fakeParams);
+    expect(prepared.verificationGasLimit).toBe(150_000n); // 100k * 3/2
+    // Every other field passes through untouched.
+    expect(prepared.callGasLimit).toBe(50_000n);
+    expect(prepared.preVerificationGas).toBe(40_000n);
+    expect(prepared.nonce).toBe(1n);
+  });
+});
+
+describe('applyVerificationGasBuffer', () => {
+  it('scales the estimate by 1.5x (the AA26 fix for F-2)', () => {
+    // The exact verificationGasLimit (101136) the bundler returned for the
+    // transfer that deterministically reverted with AA26 in the MCP test.
+    expect(applyVerificationGasBuffer(101_136n)).toBe(151_704n);
+    expect(applyVerificationGasBuffer(100_000n)).toBe(150_000n);
+    expect(applyVerificationGasBuffer(0n)).toBe(0n);
+  });
+
+  it('always returns at least the input (headroom is never negative)', () => {
+    for (const estimate of [1n, 12_345n, 80_000n, 101_136n, 500_000n]) {
+      expect(applyVerificationGasBuffer(estimate)).toBeGreaterThanOrEqual(estimate);
+    }
+  });
 });