@absol-labs/agent 0.5.0 → 0.7.0

package/src/wallet/autonomous-wallet.ts

@@ -0,0 +1,779 @@
+import { createPrivateKey, createPublicKey } from "node:crypto";
+
+import {
+  generateAuthorizationSignature,
+  generateP256KeyPair,
+} from "@privy-io/node";
+import { getAddress, type Address, type Hex } from "viem";
+
+import {
+  createPrivyEmbeddedAccount,
+  type PrivyEip1193Provider,
+  type PrivyEmbeddedWalletConfig,
+} from "./provider.js";
+import {
+  AUTONOMOUS_WALLET_CHAIN_ID,
+  AUTONOMOUS_WALLET_VERSION,
+  autonomousProofBytes,
+  type AutonomousWalletBroker,
+  type AutonomousWalletProof,
+  type PreparedPrivyRequest,
+} from "./autonomous-wallet-protocol.js";
+
+export {
+  AUTONOMOUS_WALLET_CAIP2,
+  AUTONOMOUS_WALLET_CHAIN_ID,
+  AUTONOMOUS_WALLET_VERSION,
+  autonomousProofBytes,
+  type AutonomousWalletBroker,
+  type AutonomousWalletProof,
+  type PreparedPrivyRequest,
+} from "./autonomous-wallet-protocol.js";
+const KEYCHAIN_SERVICE = "com.absol-labs.metrik.autonomous-wallet";
+export const METRIK_AUTONOMOUS_WALLET_BROKER_URL =
+  "https://wallet.137.23.50.249.sslip.io";
+
+export interface AutonomousWalletRecord {
+  readonly version: typeof AUTONOMOUS_WALLET_VERSION;
+  readonly appId: string;
+  readonly brokerUrl: string;
+  readonly publicKey: string;
+  /** Base64 PKCS8 P-256 key. This field must only be stored in a secure store. */
+  readonly privateKey: string;
+  readonly provisioningNonce: string;
+  readonly walletId?: string;
+  readonly address?: Address;
+  readonly policyId?: string;
+  readonly createdAt: number;
+}
+
+export interface AutonomousWalletCredentialStore {
+  load(key: string): Promise<AutonomousWalletRecord | null>;
+  save(key: string, record: AutonomousWalletRecord): Promise<void>;
+}
+
+export class AutonomousWalletError extends Error {
+  constructor(
+    readonly code:
+      | "invalid-config"
+      | "store-failure"
+      | "broker-failure"
+      | "proof-failure"
+      | "invalid-response",
+    message: string,
+    options?: { readonly cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "AutonomousWalletError";
+  }
+}
+
+/**
+ * Wire adapter for the broker HTTP contract. The only credential sent by this
+ * client is the P-256 proof/signature; the PKCS8 private key never enters a
+ * request body or header.
+ */
+export class HttpAutonomousWalletBroker implements AutonomousWalletBroker {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(
+    brokerUrl: string,
+    options: { readonly fetchImpl?: typeof fetch } = {},
+  ) {
+    const url = new URL(brokerUrl);
+    if (url.protocol !== "https:" && url.hostname !== "localhost") {
+      throw new AutonomousWalletError(
+        "invalid-config",
+        "autonomous wallet broker URL must use HTTPS (except localhost development)",
+      );
+    }
+    url.search = "";
+    url.hash = "";
+    this.baseUrl = url.toString().replace(/\/$/, "");
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async provision(input: Parameters<AutonomousWalletBroker["provision"]>[0]) {
+    return validateProvisionResponse(
+      await this.post("/v1/autonomous-wallets", input),
+    );
+  }
+
+  async prepare(input: Parameters<AutonomousWalletBroker["prepare"]>[0]) {
+    return validatePreparedResponse(
+      await this.post("/v1/autonomous-wallets/prepare", input),
+    );
+  }
+
+  async execute(input: Parameters<AutonomousWalletBroker["execute"]>[0]) {
+    const response = await this.post("/v1/autonomous-wallets/execute", input);
+    if (
+      !isRecord(response) ||
+      typeof response.result !== "string" ||
+      !/^0x[0-9a-fA-F]+$/.test(response.result)
+    ) {
+      throw new AutonomousWalletError(
+        "invalid-response",
+        "autonomous wallet broker returned an invalid execution result",
+      );
+    }
+    return response.result as Hex;
+  }
+
+  private async post(path: string, body: unknown): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body, bigintJson),
+      });
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "broker-failure",
+        "autonomous wallet broker request failed",
+        { cause: error },
+      );
+    }
+    const payload = (await response.json().catch(() => null)) as {
+      readonly error?: unknown;
+    } | null;
+    if (!response.ok) {
+      const detail =
+        typeof payload?.error === "string" ? `: ${payload.error}` : "";
+      throw new AutonomousWalletError(
+        "broker-failure",
+        `autonomous wallet broker rejected request (${response.status})${detail}`,
+      );
+    }
+    if (payload === null || typeof payload !== "object") {
+      throw new AutonomousWalletError(
+        "invalid-response",
+        "autonomous wallet broker returned invalid JSON",
+      );
+    }
+    return payload;
+  }
+}
+
+export interface ProvisionAutonomousWalletOptions {
+  readonly appId: string;
+  readonly policyId: string;
+  readonly brokerUrl: string;
+  readonly storeKey: string;
+  readonly broker: AutonomousWalletBroker;
+  readonly store?: AutonomousWalletCredentialStore;
+  readonly nowSeconds?: number;
+  readonly nonce?: string;
+}
+
+export interface ProvisionMetrikAutonomousWalletOptions {
+  readonly storeKey: string;
+  readonly brokerUrl?: string;
+  readonly store?: AutonomousWalletCredentialStore;
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Zero-secret Metrik entry point. Public app/policy configuration is fetched
+ * from the trusted HTTPS broker; the authorization key is generated and kept
+ * in the local OS credential store.
+ */
+export async function provisionMetrikAutonomousWallet(
+  options: ProvisionMetrikAutonomousWalletOptions,
+): Promise<AutonomousWalletRecord> {
+  const brokerUrl = options.brokerUrl ?? METRIK_AUTONOMOUS_WALLET_BROKER_URL;
+  const base = normalizeBrokerUrl(brokerUrl);
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  const response = await fetchImpl(`${base}/v1/config`, {
+    headers: { accept: "application/json" },
+  }).catch((error: unknown) => {
+    throw new AutonomousWalletError(
+      "broker-failure",
+      "autonomous wallet broker configuration is unreachable",
+      { cause: error },
+    );
+  });
+  const raw = (await response.json().catch(() => null)) as unknown;
+  if (!response.ok || !isRecord(raw))
+    throw new AutonomousWalletError(
+      "broker-failure",
+      `autonomous wallet broker rejected configuration (${response.status})`,
+    );
+  const appId = raw.appId;
+  const policyId = raw.policyId;
+  if (
+    typeof appId !== "string" ||
+    appId.trim() === "" ||
+    typeof policyId !== "string" ||
+    policyId.trim() === "" ||
+    raw.chainId !== AUTONOMOUS_WALLET_CHAIN_ID
+  ) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "autonomous wallet broker returned invalid public configuration",
+    );
+  }
+  const broker = new HttpAutonomousWalletBroker(base, { fetchImpl });
+  return provisionAutonomousWallet({
+    appId,
+    policyId,
+    brokerUrl: base,
+    storeKey: options.storeKey,
+    broker,
+    ...(options.store === undefined ? {} : { store: options.store }),
+  });
+}
+
+/**
+ * Creates or restores an agent-owned Privy wallet. A pending record is saved
+ * before the broker call so a network failure can retry with the same key and
+ * idempotency key. If secure storage fails, provisioning stops before any
+ * broker request is made.
+ */
+export async function provisionAutonomousWallet(
+  options: ProvisionAutonomousWalletOptions,
+): Promise<AutonomousWalletRecord> {
+  validateProvisionOptions(options);
+  const store = options.store ?? createDefaultAutonomousWalletStore();
+  const existingRaw = await loadRecord(store, options.storeKey);
+  if (existingRaw !== null) {
+    const existing = validateStoredRecord(existingRaw);
+    validateExistingRecord(existing, options);
+    if (existing.walletId === undefined || existing.address === undefined) {
+      return provisionPendingRecord(existing, options, store);
+    }
+    return existing;
+  }
+
+  const keyPair = await generateP256KeyPair();
+  const now = options.nowSeconds ?? Math.floor(Date.now() / 1_000);
+  const nonce = options.nonce ?? cryptoRandomNonce();
+  const pending: AutonomousWalletRecord = {
+    version: AUTONOMOUS_WALLET_VERSION,
+    appId: options.appId,
+    brokerUrl: normalizeBrokerUrl(options.brokerUrl),
+    publicKey: keyPair.publicKey,
+    privateKey: keyPair.privateKey,
+    provisioningNonce: nonce,
+    createdAt: now,
+  };
+  await saveRecord(store, options.storeKey, pending);
+  return provisionPendingRecord(pending, options, store);
+}
+
+async function provisionPendingRecord(
+  pending: AutonomousWalletRecord,
+  options: ProvisionAutonomousWalletOptions,
+  store: AutonomousWalletCredentialStore,
+): Promise<AutonomousWalletRecord> {
+  const proofInput = {
+    version: pending.version,
+    appId: pending.appId,
+    chainId: AUTONOMOUS_WALLET_CHAIN_ID,
+    publicKey: pending.publicKey,
+    nonce: pending.provisioningNonce,
+    // A retry gets a fresh proof timestamp while retaining the original key
+    // and idempotency nonce. This permits recovery after a transient outage.
+    issuedAt: options.nowSeconds ?? Math.floor(Date.now() / 1_000),
+  } as const;
+  const proof: AutonomousWalletProof = {
+    ...proofInput,
+    signature: generateAuthorizationSignature({
+      authorizationPrivateKey: pending.privateKey,
+      input: autonomousProofBytes(proofInput),
+    }),
+  };
+  let response: Awaited<ReturnType<AutonomousWalletBroker["provision"]>>;
+  try {
+    response = await options.broker.provision({
+      appId: options.appId,
+      chainId: AUTONOMOUS_WALLET_CHAIN_ID,
+      publicKey: pending.publicKey,
+      proof,
+      idempotencyKey: pending.provisioningNonce,
+    });
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "broker-failure",
+      "autonomous wallet broker rejected provisioning; the pending key remains for safe retry",
+      { cause: error },
+    );
+  }
+  const validated = validateProvisionResponse(response);
+  if (validated.policyId !== options.policyId) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "autonomous wallet broker returned an unexpected policy id",
+    );
+  }
+  const ready: AutonomousWalletRecord = {
+    ...pending,
+    walletId: validated.walletId,
+    address: getAddress(validated.address),
+    policyId: validated.policyId,
+  };
+  await saveRecord(store, options.storeKey, ready);
+  return ready;
+}
+
+export interface CreateAutonomousWalletProviderOptions {
+  readonly wallet: AutonomousWalletRecord;
+  readonly broker: AutonomousWalletBroker;
+  readonly rpcUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Builds the provider used by the existing Privy EOA adapter. Reads use the
+ * public Base Sepolia RPC; writes are prepared by the broker, signed locally
+ * with the agent key, and then executed once by the broker.
+ */
+export function createAutonomousWalletProvider(
+  options: CreateAutonomousWalletProviderOptions,
+): PrivyEip1193Provider {
+  if (
+    options.wallet.walletId === undefined ||
+    options.wallet.address === undefined
+  ) {
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "cannot create a provider before autonomous wallet provisioning completes",
+    );
+  }
+  const address = options.wallet.address;
+  let rpcId = 0;
+  return {
+    async request({ method, params = [] }) {
+      if (method === "eth_chainId") return "0x14a34";
+      if (method === "eth_accounts" || method === "eth_requestAccounts")
+        return [address];
+      if (
+        method === "eth_sendTransaction" ||
+        method === "eth_signTypedData_v4"
+      ) {
+        const prepared = await options.broker.prepare({
+          walletId: options.wallet.walletId!,
+          publicKey: options.wallet.publicKey,
+          method,
+          params,
+        });
+        if (
+          prepared.walletId !== options.wallet.walletId ||
+          prepared.method !== method
+        ) {
+          throw new AutonomousWalletError(
+            "invalid-response",
+            "autonomous broker returned a mismatched prepared request",
+          );
+        }
+        if (Math.floor(Date.now() / 1_000) >= prepared.expiresAt) {
+          throw new AutonomousWalletError(
+            "broker-failure",
+            "autonomous broker returned an expired prepared request",
+          );
+        }
+        const signature = generateAuthorizationSignature({
+          authorizationPrivateKey: options.wallet.privateKey,
+          input: decodeBase64(prepared.payload),
+        });
+        return options.broker.execute({
+          requestId: prepared.requestId,
+          publicKey: options.wallet.publicKey,
+          signature,
+        });
+      }
+      const response = await (
+        options.fetchImpl ?? globalThis.fetch.bind(globalThis)
+      )(options.rpcUrl ?? "https://base-sepolia-rpc.publicnode.com", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(
+          {
+            jsonrpc: "2.0",
+            id: ++rpcId,
+            method,
+            params,
+          },
+          bigintJson,
+        ),
+      });
+      const body = (await response.json()) as {
+        readonly result?: unknown;
+        readonly error?: { readonly message?: string };
+      };
+      if (!response.ok || body.error !== undefined) {
+        throw new AutonomousWalletError(
+          "broker-failure",
+          body.error?.message ?? `Base Sepolia RPC rejected ${method}`,
+        );
+      }
+      return body.result;
+    },
+  };
+}
+
+export async function createAutonomousWalletAccount(
+  options: CreateAutonomousWalletProviderOptions,
+) {
+  const provider = createAutonomousWalletProvider(options);
+  const config: PrivyEmbeddedWalletConfig = {
+    appId: options.wallet.appId,
+    address: options.wallet.address!,
+    provider,
+    chainId: AUTONOMOUS_WALLET_CHAIN_ID,
+  };
+  return createPrivyEmbeddedAccount(config);
+}
+
+export class InMemoryAutonomousWalletStore implements AutonomousWalletCredentialStore {
+  private readonly records = new Map<string, AutonomousWalletRecord>();
+
+  async load(key: string): Promise<AutonomousWalletRecord | null> {
+    return this.records.get(key) ?? null;
+  }
+
+  async save(key: string, record: AutonomousWalletRecord): Promise<void> {
+    this.records.set(key, record);
+  }
+}
+
+/**
+ * Uses the host OS credential manager. There is intentionally no plaintext
+ * file fallback: unsupported hosts receive an actionable error instead.
+ */
+export class OsCredentialStore implements AutonomousWalletCredentialStore {
+  async load(key: string): Promise<AutonomousWalletRecord | null> {
+    const raw = await this.readSecret(key);
+    if (raw === null) return null;
+    try {
+      return validateStoredRecord(JSON.parse(raw));
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        "OS credential contains invalid wallet data",
+        { cause: error },
+      );
+    }
+  }
+
+  async save(key: string, record: AutonomousWalletRecord): Promise<void> {
+    const raw = JSON.stringify(record);
+    try {
+      const { AsyncEntry } = await import("@napi-rs/keyring");
+      await new AsyncEntry(KEYCHAIN_SERVICE, key).setPassword(raw);
+      return;
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        "OS credential store rejected the autonomous wallet record; no plaintext fallback is allowed",
+        { cause: error },
+      );
+    }
+  }
+
+  private async readSecret(key: string): Promise<string | null> {
+    try {
+      const { AsyncEntry } = await import("@napi-rs/keyring");
+      return (
+        (await new AsyncEntry(KEYCHAIN_SERVICE, key).getPassword()) ?? null
+      );
+    } catch (error) {
+      throw new AutonomousWalletError(
+        "store-failure",
+        "OS credential store could not read the autonomous wallet record",
+        { cause: error },
+      );
+    }
+  }
+}
+
+export function createDefaultAutonomousWalletStore(): AutonomousWalletCredentialStore {
+  return new OsCredentialStore();
+}
+
+async function loadRecord(
+  store: AutonomousWalletCredentialStore,
+  key: string,
+): Promise<AutonomousWalletRecord | null> {
+  try {
+    return await store.load(key);
+  } catch (error) {
+    if (error instanceof AutonomousWalletError) throw error;
+    throw new AutonomousWalletError(
+      "store-failure",
+      "secure credential store could not be read",
+      { cause: error },
+    );
+  }
+}
+
+async function saveRecord(
+  store: AutonomousWalletCredentialStore,
+  key: string,
+  record: AutonomousWalletRecord,
+): Promise<void> {
+  try {
+    await store.save(key, record);
+  } catch (error) {
+    if (error instanceof AutonomousWalletError) throw error;
+    throw new AutonomousWalletError(
+      "store-failure",
+      "secure credential store could not persist the autonomous wallet key",
+      { cause: error },
+    );
+  }
+}
+
+function validateProvisionOptions(
+  options: ProvisionAutonomousWalletOptions,
+): void {
+  if (options.appId.trim() === "")
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "Privy public app id is required",
+    );
+  if (options.policyId.trim() === "")
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "Metrik autonomous wallet policy id is required",
+    );
+  let broker: URL;
+  try {
+    broker = new URL(options.brokerUrl);
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "autonomous wallet broker URL is invalid",
+      { cause: error },
+    );
+  }
+  if (broker.protocol !== "https:" && broker.hostname !== "localhost")
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "autonomous wallet broker URL must use HTTPS (except localhost development)",
+    );
+  if (options.storeKey.trim() === "")
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "secure store key is required",
+    );
+}
+
+function validateExistingRecord(
+  record: AutonomousWalletRecord,
+  options: ProvisionAutonomousWalletOptions,
+): void {
+  if (
+    record.version !== AUTONOMOUS_WALLET_VERSION ||
+    record.appId !== options.appId ||
+    record.brokerUrl !== normalizeBrokerUrl(options.brokerUrl) ||
+    (record.policyId !== undefined && record.policyId !== options.policyId)
+  ) {
+    throw new AutonomousWalletError(
+      "invalid-config",
+      "stored autonomous wallet belongs to a different app or broker",
+    );
+  }
+}
+
+function validateStoredRecord(value: unknown): AutonomousWalletRecord {
+  if (
+    !isRecord(value) ||
+    value.version !== AUTONOMOUS_WALLET_VERSION ||
+    typeof value.appId !== "string" ||
+    value.appId.trim() === "" ||
+    typeof value.brokerUrl !== "string" ||
+    typeof value.publicKey !== "string" ||
+    value.publicKey.trim() === "" ||
+    typeof value.privateKey !== "string" ||
+    value.privateKey.trim() === "" ||
+    typeof value.provisioningNonce !== "string" ||
+    value.provisioningNonce.trim() === "" ||
+    typeof value.createdAt !== "number" ||
+    !Number.isSafeInteger(value.createdAt)
+  ) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "OS credential contains an invalid autonomous wallet record",
+    );
+  }
+  if (
+    value.walletId !== undefined &&
+    (typeof value.walletId !== "string" || value.walletId.trim() === "")
+  ) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "OS credential contains an invalid wallet id",
+    );
+  }
+  if (
+    value.policyId !== undefined &&
+    (typeof value.policyId !== "string" || value.policyId.trim() === "")
+  ) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "OS credential contains an invalid policy id",
+    );
+  }
+  if (
+    value.address !== undefined &&
+    (typeof value.address !== "string" ||
+      !/^0x[0-9a-fA-F]{40}$/.test(value.address))
+  ) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "OS credential contains an invalid wallet address",
+    );
+  }
+  try {
+    validateP256KeyPair(value.publicKey, value.privateKey);
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "store-failure",
+      "OS credential contains invalid P-256 key material",
+      { cause: error },
+    );
+  }
+  return {
+    version: AUTONOMOUS_WALLET_VERSION,
+    appId: value.appId,
+    brokerUrl: value.brokerUrl,
+    publicKey: value.publicKey,
+    privateKey: value.privateKey,
+    provisioningNonce: value.provisioningNonce,
+    ...(value.walletId === undefined ? {} : { walletId: value.walletId }),
+    ...(value.address === undefined
+      ? {}
+      : { address: getAddress(value.address) }),
+    ...(value.policyId === undefined ? {} : { policyId: value.policyId }),
+    createdAt: value.createdAt,
+  };
+}
+
+function normalizeBrokerUrl(value: string): string {
+  const url = new URL(value);
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+function cryptoRandomNonce(): string {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64url");
+}
+
+function decodeBase64(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 === 1) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "broker returned invalid proof payload encoding",
+    );
+  }
+  const decoded = Buffer.from(value, "base64");
+  if (decoded.length === 0 || decoded.toString("base64") !== value) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "broker returned an empty proof payload",
+    );
+  }
+  return new Uint8Array(decoded);
+}
+
+function validateP256KeyPair(publicKey: string, privateKey: string): void {
+  const publicObject = createPublicKey({
+    key: Buffer.from(decodeBase64(publicKey)),
+    format: "der",
+    type: "spki",
+  });
+  const privateObject = createPrivateKey({
+    key: Buffer.from(decodeBase64(privateKey)),
+    format: "der",
+    type: "pkcs8",
+  });
+  if (
+    publicObject.asymmetricKeyType !== "ec" ||
+    publicObject.asymmetricKeyDetails?.namedCurve !== "prime256v1" ||
+    privateObject.asymmetricKeyType !== "ec" ||
+    privateObject.asymmetricKeyDetails?.namedCurve !== "prime256v1"
+  ) {
+    throw new Error("key material is not P-256");
+  }
+  const derived = createPublicKey(privateObject)
+    .export({ format: "der", type: "spki" })
+    .toString("base64");
+  if (derived !== publicKey)
+    throw new Error("public key does not match private key");
+}
+
+function validateProvisionResponse(value: unknown): {
+  readonly walletId: string;
+  readonly address: Address;
+  readonly policyId: string;
+} {
+  if (
+    !isRecord(value) ||
+    typeof value.walletId !== "string" ||
+    value.walletId.trim() === "" ||
+    typeof value.address !== "string" ||
+    typeof value.policyId !== "string" ||
+    value.policyId.trim() === ""
+  ) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "autonomous wallet broker returned an invalid wallet record",
+    );
+  }
+  try {
+    return {
+      walletId: value.walletId,
+      address: getAddress(value.address),
+      policyId: value.policyId,
+    };
+  } catch (error) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "autonomous wallet broker returned an invalid wallet address",
+      { cause: error },
+    );
+  }
+}
+
+function validatePreparedResponse(value: unknown): PreparedPrivyRequest {
+  if (
+    !isRecord(value) ||
+    typeof value.requestId !== "string" ||
+    value.requestId.trim() === "" ||
+    typeof value.walletId !== "string" ||
+    value.walletId.trim() === "" ||
+    (value.method !== "eth_sendTransaction" &&
+      value.method !== "eth_signTypedData_v4") ||
+    typeof value.payload !== "string" ||
+    value.payload.length === 0 ||
+    typeof value.expiresAt !== "number" ||
+    !Number.isSafeInteger(value.expiresAt)
+  ) {
+    throw new AutonomousWalletError(
+      "invalid-response",
+      "autonomous wallet broker returned an invalid prepared request",
+    );
+  }
+  decodeBase64(value.payload);
+  return {
+    requestId: value.requestId,
+    walletId: value.walletId,
+    method: value.method,
+    payload: value.payload,
+    expiresAt: value.expiresAt,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function bigintJson(_key: string, value: unknown): unknown {
+  return typeof value === "bigint" ? `0x${value.toString(16)}` : value;
+}