@cofhe/sdk 0.6.0 → 0.7.0

package/acps/types.ts

@@ -0,0 +1,252 @@
+import { type EthEncryptedData } from './sealing.js';
+import { type Hex } from 'viem';
+
+/**
+ * EIP712 related types
+ */
+export type EIP712Type = { name: string; type: string };
+export type EIP712Types = Record<string, EIP712Type[]>;
+export type EIP712Message = Record<string, string>;
+export type EIP712Domain = {
+  chainId: number;
+  name: string;
+  verifyingContract: Hex;
+  version: string;
+};
+
+/**
+ * Re-export EthEncryptedData from sealing module
+ */
+export type { EthEncryptedData };
+
+// Viem client types will be imported from viem package
+
+/**
+ * The client-side-only component of an ACP — never leaves the client.
+ */
+export interface ACPPrivate {
+  /**
+   * Stable hash of relevant acp data, used as key in storage
+   */
+  hash: string;
+  /**
+   * Name for this acp, for organization and UI usage, not included in signature.
+   */
+  name: string;
+  /**
+   * The type of the ACP (self / sharing / recipient)
+   * (self) ACP that will be signed and used by the issuer
+   * (sharing) ACP that is signed by the issuer, but intended to be shared with recipient
+   * (recipient) ACP that has been received, and signed by the recipient
+   */
+  type: 'self' | 'sharing' | 'recipient';
+  /**
+   * The private half of the sealing keypair — used to unseal returned data.
+   * `sealingKey` (in the public component) is the corresponding public key.
+   * Never leaves the client.
+   */
+  sealingPrivateKey: Hex;
+  /**
+   * EIP712 domain used to sign this acp.
+   * Should not be set manually, included in metadata as part of serialization flows.
+   */
+  _signedDomain?: EIP712Domain;
+}
+
+/**
+ * The public component of an ACP — the signed struct passed on-chain / to the
+ * decryption backend to grant encrypted data access. Produced by `getPublic()`.
+ */
+export interface ACPPublic {
+  /**
+   * (base) User that initially created the permission, target of data fetching
+   */
+  issuer: Hex;
+  /**
+   * (base) Expiration timestamp
+   */
+  expiration: number;
+  /**
+   * (sharing) The user that this permission will be shared with
+   * ** optional, use `address(0)` to disable **
+   */
+  recipient: Hex;
+  /**
+   * (revocation) Opaque data interpreted by `revokerContract` — the default
+   * revoker interprets it as the acp's creation timestamp.
+   * ** optional, use `0` to disable **
+   */
+  revokerData: number;
+  /**
+   * (revocation) The contract to query to determine permission validity
+   * ** optional, use `address(0)` to disable **
+   */
+  revokerContract: Hex;
+  /**
+   * (scope) Scope discriminator — exactly one scope mode per ACP (see ACPScope).
+   * Global: all of `issuer`s values (arrays empty). Contract: values readable by
+   * `contracts`. Handles: the listed `handles` only.
+   */
+  scope: number;
+  /**
+   * (scope) Grants access to `issuer`s values readable by any of these contracts.
+   * Checked on-chain as an intersection with the ACL's persisted allowances.
+   */
+  contracts: Hex[];
+  /**
+   * (scope) Grants access to these specific ciphertext handles (bytes32 hex)
+   */
+  handles: Hex[];
+  /**
+   * (base) The public half of the sealing keypair — used to re-encrypt `issuer`s confidential data
+   *   (non-sharing) Populated by `issuer`
+   *   (sharing)     Populated by `recipient`
+   */
+  sealingKey: Hex;
+  /**
+   * (base) `signTypedData` signature created by `issuer`.
+   * (base) Shared- and Self- permissions differ in signature format: (`sealingKey` absent in shared signature)
+   */
+  issuerSignature: Hex;
+  /**
+   * (sharing) `signTypedData` signature created by `recipient`
+   * ** required for shared acps **
+   */
+  recipientSignature: Hex;
+}
+
+/**
+ * Core ACP (Access Control Permission) type — immutable design for React compatibility.
+ * The union of the private (client-only) and public (signed) components.
+ */
+export type ACP = Expand<ACPPrivate & ACPPublic>;
+
+/**
+ * ACP discriminant helpers
+ */
+export type ACPType = ACP['type'];
+
+/**
+ * Utility type to narrow an ACP to a specific discriminant.
+ *
+ * Note: this only narrows the `type` field. Runtime/validation constraints
+ * (e.g. recipient == zeroAddress for self acps) are enforced elsewhere.
+ */
+export type ACPOf<T extends ACPType> = Expand<Omit<ACP, 'type'> & { type: T }>;
+
+export type SelfACP = ACPOf<'self'>;
+export type SharingACP = ACPOf<'sharing'>;
+export type RecipientACP = ACPOf<'recipient'>;
+
+/**
+ * Optional additional metadata of an ACP
+ * Can be passed into the constructor, but not necessary
+ * Useful for deserialization
+ */
+export interface ACPMetadata {
+  /**
+   * EIP712 domain used to sign this acp.
+   * Should not be set manually, included in metadata as part of serialization flows.
+   */
+  _signedDomain?: EIP712Domain;
+}
+
+/**
+ * Utility types for acp creation
+ */
+
+/**
+ * Scope fields shared by all acp creation options.
+ * When any scope array is populated and `global` is not explicitly set,
+ * `global` defaults to false (narrowest matching scope); with no scope
+ * arrays it defaults to true (V2 behavior).
+ */
+export const ACPScope = {
+  Global: 0,
+  Contract: 1,
+  Handles: 2,
+} as const;
+
+export type ACPScopeOptions = {
+  scope?: number;
+  contracts?: Hex[];
+  handles?: Hex[];
+};
+
+// Specific option types for each acp creation method
+export type CreateSelfACPOptions = ACPScopeOptions & {
+  type?: 'self';
+  issuer: string;
+  name?: string;
+  expiration?: number;
+  revokerData?: number;
+  revokerContract?: string;
+};
+
+export type CreateSharingACPOptions = ACPScopeOptions & {
+  type?: 'sharing';
+  issuer: string;
+  recipient: string;
+  name?: string;
+  expiration?: number;
+  revokerData?: number;
+  revokerContract?: string;
+};
+
+export type ImportSharedACPOptions = ACPScopeOptions & {
+  type?: 'sharing';
+  issuer: string;
+  recipient: string;
+  issuerSignature: string;
+  name?: string;
+  expiration: number;
+  revokerData?: number;
+  revokerContract?: string;
+};
+
+/** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
+export type SerializedACP = ACP;
+
+/**
+ * The share payload produced by `ACPUtils.export()` — the full public component
+ * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
+ * the display name and acp type. Fixed shape: every field is always present
+ * (zero-values instead of omissions), so importers can parse a single schema.
+ * Mirrors the on-chain sharing payload struct field-for-field.
+ */
+export type SharedACP = Expand<
+  Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
+    name: string;
+    type: 'sharing';
+  }
+>;
+
+/**
+ * A share read back from the on-chain ACPShareRegistry: the posted payload
+ * (SharedACP minus the client-side name/type) plus its registry id.
+ */
+export type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & { shareId: Hex }>;
+
+/**
+ * A type representing the acp fields that are used to generate the hash
+ */
+export type ACPHashFields = Pick<
+  ACP,
+  'type' | 'issuer' | 'expiration' | 'recipient' | 'revokerData' | 'revokerContract' | 'scope' | 'contracts' | 'handles'
+>;
+
+/**
+ * Validation result type
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error: 'invalid-schema' | 'expired' | 'not-signed' | null;
+}
+
+/**
+ * Signature types for EIP712 signing
+ */
+export type ACPSignaturePrimaryType = 'ACPIssuerSelf' | 'ACPIssuerShared' | 'ACPRecipient';
+
+// Utils
+export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;

package/acps/validation.ts

@@ -0,0 +1,392 @@
+import { z } from 'zod';
+import { getAddress, isAddress, isHex, zeroAddress, type Hex } from 'viem';
+import type { ACP, ValidationResult } from './types.js';
+
+export const addressSchema = z
+  .string()
+  .refine((val) => isAddress(val), {
+    error: 'Invalid address',
+  })
+  .transform((val): Hex => getAddress(val));
+
+export const addressNotZeroSchema = addressSchema.refine((val) => val !== zeroAddress, {
+  error: 'Must not be zeroAddress',
+});
+
+export const bytesSchema = z.custom<Hex>(
+  (val) => {
+    return typeof val === 'string' && isHex(val);
+  },
+  {
+    message: 'Invalid hex value',
+  }
+);
+
+export const bytesNotEmptySchema = bytesSchema.refine((val) => val !== '0x', {
+  error: 'Must not be empty',
+});
+
+const DEFAULT_EXPIRATION_FN = () => Math.round(Date.now() / 1000) + 7 * 24 * 60 * 60; // 7 days from now
+
+/** (scope) ciphertext handles — bytes32 hex strings */
+export const handlesSchema = z
+  .array(z.string().regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid handle: expected 32-byte hex') as z.ZodType<Hex>)
+  .optional()
+  .default([]);
+
+/** (scope) contract addresses */
+export const contractsSchema = z.array(addressSchema).optional().default([]);
+
+/**
+ * Context-sensitive `global` default: with no scope arrays it defaults to true
+ * (V2 behavior); when contracts/handles are provided it defaults to false
+ * (narrowest matching scope).
+ */
+/**
+ * Scope derivation + per-scope array rules (client-side validation, per review):
+ *  - explicit `scope` wins; otherwise derived: contracts -> Contract, handles -> Handles, else Global
+ *  - Global   => contracts and handles must be empty
+ *  - Contract => contracts non-empty, handles empty
+ *  - Handles  => handles non-empty, contracts empty
+ * Exactly one scope mode per ACP — no overlapping scopes.
+ */
+const SCOPE_GLOBAL = 0;
+const SCOPE_CONTRACT = 1;
+const SCOPE_HANDLES = 2;
+
+const ScopeConsistencyRefinement = [
+  (data: { scope: number; contracts: Hex[]; handles: Hex[] }) =>
+    (data.scope === SCOPE_GLOBAL && data.contracts.length === 0 && data.handles.length === 0) ||
+    (data.scope === SCOPE_CONTRACT && data.contracts.length > 0 && data.handles.length === 0) ||
+    (data.scope === SCOPE_HANDLES && data.handles.length > 0 && data.contracts.length === 0),
+  {
+    error:
+      'ACP scope :: arrays must match the scope mode (Global: both empty; Contract: contracts only; Handles: handles only)',
+    path: ['scope'] as string[],
+  },
+] as const;
+
+const withDerivedScope = <T extends { scope?: number; contracts: Hex[]; handles: Hex[] }>(data: T) => ({
+  ...data,
+  scope:
+    data.scope ?? (data.contracts.length > 0 ? SCOPE_CONTRACT : data.handles.length > 0 ? SCOPE_HANDLES : SCOPE_GLOBAL),
+});
+
+const zACPWithDefaults = z.object({
+  name: z.string().optional().default('Unnamed ACP'),
+  type: z.enum(['self', 'sharing', 'recipient']),
+  issuer: addressNotZeroSchema,
+  expiration: z.int().optional().default(DEFAULT_EXPIRATION_FN),
+  recipient: addressSchema.optional().default(zeroAddress),
+  revokerData: z.int().optional().default(0),
+  revokerContract: addressSchema.optional().default(zeroAddress),
+  scope: z.int().min(0).max(2).optional().default(0),
+  contracts: contractsSchema,
+  handles: handlesSchema,
+  issuerSignature: bytesSchema.optional().default('0x'),
+  recipientSignature: bytesSchema.optional().default('0x'),
+});
+
+const zACPWithSealingKeys = zACPWithDefaults.extend({
+  /** X25519 private key, 0x-prefixed 32-byte hex; never leaves the client */
+  sealingPrivateKey: z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid sealing private key')
+    .optional(),
+  sealingKey: z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid sealing key')
+    .optional(),
+});
+
+type zACPType = z.infer<typeof zACPWithDefaults>;
+
+/**
+ * ACPs allow a hook into an optional external revoker contract,
+ * this check ensures that IF an external revoker is applied, that both `revokerData` and `revokerContract` are populated,
+ * ELSE ensures that both `revokerData` and `revokerContract` are empty
+ */
+const ExternalValidatorRefinement = [
+  (data: Pick<zACPType, 'revokerData' | 'revokerContract'>) =>
+    (data.revokerData !== 0 && data.revokerContract !== zeroAddress) ||
+    (data.revokerData === 0 && data.revokerContract === zeroAddress),
+  {
+    error: 'ACP external revoker :: revokerData and revokerContract must either both be set or both be unset.',
+    path: ['revokerData', 'revokerContract'] as string[],
+  },
+] as const;
+
+/**
+ * Prevents sharable acp from having the same issuer and recipient
+ */
+const RecipientRefinement = [
+  (data: Pick<zACPType, 'issuer' | 'recipient'>) => data.issuer !== data.recipient,
+  {
+    error: 'Sharing acp :: issuer and recipient must not be the same',
+    path: ['issuer', 'recipient'] as string[],
+  },
+] as const;
+
+// ============================================================================
+// SELF ACP VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for self acp creation options
+ */
+export const SelfACPOptionsValidator = z
+  .object({
+    type: z.literal('self').optional().default('self'),
+    issuer: addressNotZeroSchema,
+    name: z.string().optional().default('Unnamed ACP'),
+    expiration: z.int().optional().default(DEFAULT_EXPIRATION_FN),
+    recipient: addressSchema.optional().default(zeroAddress),
+    revokerData: z.int().optional().default(0),
+    revokerContract: addressSchema.optional().default(zeroAddress),
+    scope: z.int().min(0).max(2).optional(),
+    contracts: contractsSchema,
+    handles: handlesSchema,
+    issuerSignature: bytesSchema.optional().default('0x'),
+    recipientSignature: bytesSchema.optional().default('0x'),
+  })
+  .refine(...ExternalValidatorRefinement)
+  .transform(withDerivedScope)
+  .refine(...ScopeConsistencyRefinement);
+
+/**
+ * Validator for fully formed self acps
+ */
+export const SelfACPValidator = zACPWithSealingKeys
+  .refine((data) => data.type === 'self', {
+    error: "Type must be 'self'",
+  })
+  .refine((data) => data.recipient === zeroAddress, {
+    error: 'Recipient must be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    error: 'IssuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature === '0x', {
+    error: 'RecipientSignature must be empty',
+  })
+  .refine(...ExternalValidatorRefinement);
+
+// ============================================================================
+// SHARING ACP VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for sharing acp creation options
+ */
+export const SharingACPOptionsValidator = z
+  .object({
+    type: z.literal('sharing').optional().default('sharing'),
+    issuer: addressNotZeroSchema,
+    recipient: addressNotZeroSchema,
+    name: z.string().optional().default('Unnamed ACP'),
+    expiration: z.int().optional().default(DEFAULT_EXPIRATION_FN),
+    revokerData: z.int().optional().default(0),
+    revokerContract: addressSchema.optional().default(zeroAddress),
+    scope: z.int().min(0).max(2).optional(),
+    contracts: contractsSchema,
+    handles: handlesSchema,
+    issuerSignature: bytesSchema.optional().default('0x'),
+    recipientSignature: bytesSchema.optional().default('0x'),
+  })
+  .refine(...RecipientRefinement)
+  .refine(...ExternalValidatorRefinement)
+  .transform(withDerivedScope)
+  .refine(...ScopeConsistencyRefinement);
+
+/**
+ * Validator for fully formed sharing acps
+ */
+export const SharingACPValidator = zACPWithSealingKeys
+  .refine((data) => data.type === 'sharing', {
+    error: "Type must be 'sharing'",
+  })
+  .refine((data) => data.recipient !== zeroAddress, {
+    error: 'Recipient must not be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    error: 'IssuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature === '0x', {
+    error: 'RecipientSignature must be empty',
+  })
+  .refine(...ExternalValidatorRefinement);
+
+// ============================================================================
+// IMPORT/RECIPIENT ACP VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for import acp creation options (recipient receiving shared acp)
+ */
+export const ImportACPOptionsValidator = z
+  .object({
+    type: z.literal('recipient').optional().default('recipient'),
+    issuer: addressNotZeroSchema,
+    recipient: addressNotZeroSchema,
+    name: z.string().optional().default('Unnamed ACP'),
+    expiration: z.int(),
+    revokerData: z.int().optional().default(0),
+    revokerContract: addressSchema.optional().default(zeroAddress),
+    scope: z.int().min(0).max(2).optional(),
+    contracts: contractsSchema,
+    handles: handlesSchema,
+    issuerSignature: bytesNotEmptySchema,
+    recipientSignature: bytesSchema.optional().default('0x'),
+  })
+  .refine(...ExternalValidatorRefinement)
+  .transform(withDerivedScope)
+  .refine(...ScopeConsistencyRefinement);
+
+/**
+ * Validator for fully formed import/recipient acps
+ */
+export const ImportACPValidator = zACPWithSealingKeys
+  .refine((data) => data.type === 'recipient', {
+    error: "Type must be 'recipient'",
+  })
+  .refine((data) => data.recipient !== zeroAddress, {
+    error: 'Recipient must not be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    error: 'IssuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature !== '0x', {
+    error: 'RecipientSignature must be populated',
+  })
+  .refine(...ExternalValidatorRefinement);
+
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+
+const safeParseAndThrowFormatted = <T extends z.ZodTypeAny>(schema: T, data: unknown, message: string): z.output<T> => {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    throw new Error(`${message}: ${z.prettifyError(result.error)}`, { cause: result.error });
+  }
+  return result.data;
+};
+
+/**
+ * Validates self acp creation options
+ */
+export const validateSelfACPOptions = (options: any) => {
+  return safeParseAndThrowFormatted(SelfACPOptionsValidator, options, 'Invalid self acp options');
+};
+/**
+ * Validates sharing acp creation options
+ */
+export const validateSharingACPOptions = (options: any) => {
+  return safeParseAndThrowFormatted(SharingACPOptionsValidator, options, 'Invalid sharing acp options');
+};
+
+/**
+ * Validates import acp creation options
+ */
+export const validateImportACPOptions = (options: any) => {
+  return safeParseAndThrowFormatted(ImportACPOptionsValidator, options, 'Invalid import acp options');
+};
+
+/**
+ * Validates a fully formed self acp
+ */
+export const validateSelfACP = (acp: any) => {
+  return safeParseAndThrowFormatted(SelfACPValidator, acp, 'Invalid self acp');
+};
+
+/**
+ * Validates a fully formed sharing acp
+ */
+export const validateSharingACP = (acp: any) => {
+  return safeParseAndThrowFormatted(SharingACPValidator, acp, 'Invalid sharing acp');
+};
+
+/**
+ * Validates a fully formed import/recipient acp
+ */
+export const validateImportACP = (acp: any) => {
+  return safeParseAndThrowFormatted(ImportACPValidator, acp, 'Invalid import acp');
+};
+
+/**
+ * Simple validation functions for common checks
+ */
+export const ValidationUtils = {
+  /**
+   * Check if acp is expired
+   */
+  isExpired: (acp: ACP): boolean => {
+    return acp.expiration < Math.floor(Date.now() / 1000);
+  },
+
+  /**
+   * Check if acp is signed by the active party
+   */
+  isSigned: (acp: ACP): boolean => {
+    if (acp.type === 'self' || acp.type === 'sharing') {
+      return acp.issuerSignature !== '0x';
+    }
+    if (acp.type === 'recipient') {
+      return acp.recipientSignature !== '0x';
+    }
+    return false;
+  },
+
+  /**
+   * Checks that an ACP is signed and not expired.
+   */
+  isSignedAndNotExpired: (acp: ACP): ValidationResult => {
+    if (ValidationUtils.isExpired(acp)) {
+      return { valid: false, error: 'expired' };
+    }
+    if (!ValidationUtils.isSigned(acp)) {
+      return { valid: false, error: 'not-signed' };
+    }
+    return { valid: true, error: null };
+  },
+
+  /**
+   * Asserts that an ACP is signed and not expired.
+   *
+   * Throws `Error` with message:
+   * - `ACP is expired`
+   * - `ACP is not signed`
+   */
+  assertSignedAndNotExpired: (acp: ACP): void => {
+    const result = ValidationUtils.isSignedAndNotExpired(acp);
+    if (result.valid) return;
+
+    if (result.error === 'expired') {
+      throw new Error('ACP is expired');
+    }
+    if (result.error === 'not-signed') {
+      throw new Error('ACP is not signed');
+    }
+
+    // Should be unreachable, but keeps this future-proof.
+    throw new Error('ACP is invalid');
+  },
+
+  isValid: (acp: ACP): ValidationResult => {
+    const schema =
+      acp.type === 'self'
+        ? SelfACPValidator
+        : acp.type === 'sharing'
+          ? SharingACPValidator
+          : acp.type === 'recipient'
+            ? ImportACPValidator
+            : null;
+
+    if (schema == null) return { valid: false, error: 'invalid-schema' };
+
+    const schemaResult = schema.safeParse(acp);
+    if (!schemaResult.success) return { valid: false, error: 'invalid-schema' };
+
+    return ValidationUtils.isSignedAndNotExpired(acp);
+  },
+};

package/adapters/test/ethers5.test.ts

@@ -13,7 +13,10 @@ describe('Ethers5Adapter', () => {
   beforeEach(() => {
     // Create common setup for all tests
     provider = new ethers5.providers.JsonRpcProvider(testRpcUrl);
-    wallet = new ethers5.Wallet('0x' + '1'.repeat(64), provider);
+    // Fresh random key each run → a guaranteed-empty account (0 balance, nonce 0), so the
+    // sendTransaction test deterministically fails with "insufficient funds". The old shared
+    // 0x11…11 key is funded and heavily used on Sepolia, so its tx failed with other errors.
+    wallet = new ethers5.Wallet(ethers5.Wallet.createRandom().privateKey, provider);
   });
 
   it('should work with real JsonRpcProvider and Wallet', async () => {

package/adapters/test/ethers6.test.ts

@@ -13,7 +13,10 @@ describe('Ethers6Adapter', () => {
   beforeEach(() => {
     // Create common setup for all tests
     provider = new ethers6.JsonRpcProvider(testRpcUrl);
-    wallet = new ethers6.Wallet('0x' + '1'.repeat(64), provider);
+    // Fresh random key each run → a guaranteed-empty account (0 balance, nonce 0), so the
+    // sendTransaction test deterministically fails with "insufficient funds". The old shared
+    // 0x11…11 key is funded and heavily used on Sepolia, so its tx failed with other errors.
+    wallet = new ethers6.Wallet(ethers6.Wallet.createRandom().privateKey, provider);
   });
 
   it('should work with real JsonRpcProvider and Wallet', async () => {

package/adapters/test/wagmi.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { parseEther, createPublicClient, createWalletClient, http, type PublicClient, type WalletClient } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { WagmiAdapter } from '../wagmi.js';
 
 describe('WagmiAdapter', () => {
@@ -12,7 +12,10 @@ describe('WagmiAdapter', () => {
 
   beforeEach(() => {
     // Create common setup for all tests - no chain needed
-    account = privateKeyToAccount(('0x' + '1'.repeat(64)) as `0x${string}`);
+    // Fresh random key each run → a guaranteed-empty account (0 balance, nonce 0), so the
+    // sendTransaction test deterministically fails with "insufficient funds". The old shared
+    // 0x11…11 key is funded and heavily used on Sepolia, so its tx failed with other errors.
+    account = privateKeyToAccount(generatePrivateKey());
 
     publicClient = createPublicClient({
       transport: http(testRpcUrl),