@absol-labs/agent 0.10.0 → 0.11.0

package/src/cli/deps.ts

@@ -8,7 +8,7 @@ import {
   type StreamV2,
   type StreamProofTransactionResult,
 } from "@absol-labs/sdk";
-import { erc20Abi, getAbiItem, http, type LocalAccount } from "viem";
+import { erc20Abi, getAbiItem, http, type Transport } from "viem";
 
 import {
   discoverServicesDetailed,
@@ -30,8 +30,10 @@ import {
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamResult,
 } from "../sdk/client.js";
+import type { SignedSpendMandate } from "../mandates/mandate.js";
 
 import type { CliConfig } from "./config.js";
+import type { CliSignerAccount } from "./wallet.js";
 import { RPC_RETRY_COUNT, RPC_TIMEOUT_MS, withReadTimeout } from "./timeout.js";
 
 /**
@@ -149,17 +151,39 @@ export interface OpenedStream {
   readonly blockNumber: bigint;
 }
 
+/**
+ * A fund-moving call, with the mandate made EXPLICITLY optional.
+ *
+ * `null` is not "no authorization" — it is "this wallet's ceiling is enforced
+ * by a broker policy the client cannot reach or raise, so a locally self-signed
+ * mandate would be the agent attesting to its own limits on top of a stronger
+ * limit". The CLI substitutes the real ceiling instead; see
+ * `./spend-policy.ts`, which also explains why re-adding the mandate here would
+ * be a regression rather than a tidy-up.
+ *
+ * A key-holding wallet (private key, CDP) always passes a real mandate, and its
+ * path through `VerifiedStreamAgentClient` is unchanged.
+ */
+type MandateOptional<T extends { readonly signedMandate: SignedSpendMandate }> =
+  Omit<T, "signedMandate"> & {
+    readonly signedMandate: SignedSpendMandate | null;
+  };
+
+export type CliOpenStreamInput = MandateOptional<OpenVerifiedStreamInput>;
+export type CliStreamActionInput =
+  MandateOptional<MandateAuthorizedStreamActionInput>;
+export type CliReclaimStreamInput =
+  MandateOptional<ReclaimAuthorizedStreamInput>;
+
 export interface CliWriteClient {
   /** Build + best-effort simulate the hire WITHOUT broadcasting (`--dry-run`). */
   buildHireTx(input: HireComputeInput): Promise<HireTxPreview>;
-  openVerifiedStream(
-    input: OpenVerifiedStreamInput,
-  ): Promise<HireComputeResult>;
+  openVerifiedStream(input: CliOpenStreamInput): Promise<HireComputeResult>;
   closeStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
   reclaimStream(
-    input: ReclaimAuthorizedStreamInput,
+    input: CliReclaimStreamInput,
   ): Promise<ReclaimVerifiedStreamResult>;
   /**
    * The no-proof escape hatch. Separate from {@link reclaimStream} because it is
@@ -167,14 +191,27 @@ export interface CliWriteClient {
    * — see `VerifiedStreamAgentClient.reclaimUnverifiedStream`.
    */
   reclaimUnverifiedStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
   /** Operator-only: redeem the verified-earned balance for a stream. */
   claimStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
 }
 
+/**
+ * Per-wallet write-path overrides.
+ *
+ * `transport` exists for exactly one reason: a Privy wallet has no local
+ * `signTransaction`. Its EIP-1193 provider performs `eth_sendTransaction`
+ * itself, so the provider must BE the wallet client's transport rather than the
+ * plain `http(--rpc-url)` every local signer uses. Left unset — which is every
+ * private-key and CDP run — the transport is unchanged, byte for byte.
+ */
+export interface CreateWriteClientOptions {
+  readonly transport?: Transport;
+}
+
 export interface CliDependencies {
   readonly createReadClient: (config: CliConfig) => CliReadClient;
   /**
@@ -185,7 +222,8 @@ export interface CliDependencies {
    */
   readonly createWriteClient: (
     config: CliConfig,
-    account: LocalAccount | null,
+    account: CliSignerAccount | null,
+    options?: CreateWriteClientOptions,
   ) => CliWriteClient;
   readonly discover: (
     options: DiscoverServicesOptions,
@@ -228,11 +266,12 @@ function rpcTransport(config: CliConfig) {
 /** Shared `MetrikClient` construction: one escrow, declared as V2 on both keys. */
 function createMetrikClient(
   config: CliConfig,
-  account?: LocalAccount,
+  account?: CliSignerAccount,
+  transport?: Transport,
 ): MetrikClient {
   return new MetrikClient({
     chain: config.chain,
-    transport: rpcTransport(config),
+    transport: transport ?? rpcTransport(config),
     escrow: config.escrow,
     // Declared on BOTH keys: without `escrowV2` the SDK routes reads and
     // settlement through the legacy V1 ABI, which reverts against
@@ -365,10 +404,13 @@ export const defaultCliDependencies: CliDependencies = {
       },
     };
   },
-  createWriteClient(config, account) {
+  createWriteClient(config, account, options) {
+    // A Privy wallet's provider IS the transport (see CreateWriteClientOptions);
+    // every other wallet keeps the plain bounded HTTP transport.
+    const transport = options?.transport ?? rpcTransport(config);
     const clientConfig = {
       chain: config.chain,
-      transport: rpcTransport(config),
+      transport,
       escrow: config.escrow,
       escrowV2: config.escrow,
       usdc: config.usdc,
@@ -382,26 +424,61 @@ export const defaultCliDependencies: CliDependencies = {
     const agentClient = new VerifiedStreamAgentClient(clientConfig);
     const metrik = createMetrikClient(
       config,
-      ...(account === null ? [] : ([account] as const)),
+      account === null ? undefined : account,
+      transport,
     );
     return {
       async buildHireTx(input) {
         return await metrik.buildHireTx(input);
       },
-      async openVerifiedStream(input) {
-        return await agentClient.openVerifiedStream(input);
+      async openVerifiedStream({ signedMandate, ...input }) {
+        // No mandate means a policy-enforced wallet: the ceiling was already
+        // checked against the broker's own `/v1/config` before we got here, and
+        // the broker checks it AGAIN server-side on the transaction it signs.
+        // Going straight at the SDK client is the same path the SDK-driven
+        // (non-CLI) flow has always used.
+        if (signedMandate === null) {
+          return await metrik.hireVerifiedService({
+            operator: input.operator,
+            serviceRef: input.serviceRef,
+            budgetUsdc: input.budgetUsdc,
+            ratePerSecond: input.ratePerSecondUsdc,
+            maxDurationSeconds: input.maxDurationSeconds,
+          });
+        }
+        return await agentClient.openVerifiedStream({
+          ...input,
+          signedMandate,
+        });
       },
-      async closeStream(input) {
-        return await agentClient.closeStream(input);
+      async closeStream({ signedMandate, ...input }) {
+        if (signedMandate === null) return await metrik.close(input.streamId);
+        return await agentClient.closeStream({ ...input, signedMandate });
       },
-      async reclaimStream(input) {
-        return await agentClient.reclaimStream(input);
+      async reclaimStream({ signedMandate, ...input }) {
+        if (signedMandate === null) {
+          const closeResult = input.closeFirst
+            ? await metrik.close(input.streamId)
+            : null;
+          return {
+            closeResult,
+            reclaimResult: await metrik.reclaim(input.streamId),
+          };
+        }
+        return await agentClient.reclaimStream({ ...input, signedMandate });
       },
-      async reclaimUnverifiedStream(input) {
-        return await agentClient.reclaimUnverifiedStream(input);
+      async reclaimUnverifiedStream({ signedMandate, ...input }) {
+        if (signedMandate === null) {
+          return await metrik.reclaimUnverified(input.streamId);
+        }
+        return await agentClient.reclaimUnverifiedStream({
+          ...input,
+          signedMandate,
+        });
       },
-      async claimStream(input) {
-        return await agentClient.claimStream(input);
+      async claimStream({ signedMandate, ...input }) {
+        if (signedMandate === null) return await metrik.claim(input.streamId);
+        return await agentClient.claimStream({ ...input, signedMandate });
       },
     };
   },
@@ -434,4 +511,18 @@ export const defaultCliDependencies: CliDependencies = {
   },
 };
 
+/**
+ * The write-client options a resolved wallet implies.
+ *
+ * Kept next to {@link CreateWriteClientOptions} so every fund-moving command
+ * spells the transport decision the same way, and so a wallet that needs a
+ * provider transport cannot be broadcast through a plain RPC by a command that
+ * simply forgot to pass it.
+ */
+export function writeClientOptions(
+  wallet: { readonly transport?: Transport } | null,
+): CreateWriteClientOptions {
+  return wallet?.transport === undefined ? {} : { transport: wallet.transport };
+}
+
 export type { DiscoverResult, ServiceListing };

package/src/cli/privy.ts

@@ -0,0 +1,396 @@
+import {
+  custom,
+  isAddress,
+  getAddress,
+  type Account,
+  type Transport,
+} from "viem";
+
+import {
+  AutonomousWalletError,
+  EncryptedFileCredentialStore,
+  HttpAutonomousWalletBroker,
+  METRIK_AUTONOMOUS_WALLET_BROKER_URL,
+  METRIK_WALLET_ENCRYPTION_KEY_ENV,
+  createAutonomousWalletProvider,
+  createDefaultAutonomousWalletStore,
+  type AutonomousWalletCredentialStore,
+  type AutonomousWalletRecord,
+} from "../wallet/autonomous-wallet.js";
+import { createPrivySessionProvider } from "../wallet/privy-session-provider.js";
+import {
+  createPrivyEmbeddedAccount,
+  type PrivyEip1193Provider,
+} from "../wallet/provider.js";
+import { configError } from "./errors.js";
+
+/**
+ * The CLI's two Privy wallet shapes.
+ *
+ * Privy differs from the private-key and CDP paths in ONE structural way: the
+ * account it yields has no local `signTransaction`. It signs and broadcasts by
+ * sending `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so the
+ * viem wallet client's TRANSPORT must be that provider rather than a plain HTTP
+ * RPC. That is the whole difference, and it is what `transport` below carries.
+ *
+ * Neither shape puts a wallet key on this machine. The signing key lives at
+ * Privy; the broker holds the Privy authorization key. What the CLI holds is
+ * either a short-lived session token (`session`) or a P-256 authorization key
+ * in the host credential store (`autonomous`) — a key that authorizes a
+ * policy-bounded request, not a key that can move funds by itself.
+ */
+export type PrivyCliWalletSource = "privy-autonomous" | "privy-session";
+
+/** The store key naming the agent-owned wallet in the host credential store. */
+export const PRIVY_WALLET_KEY_ENV = "METRIK_AGENT_PRIVY_WALLET_KEY";
+/** Broker base URL. Optional for `autonomous`, REQUIRED for `session`. */
+export const PRIVY_BROKER_URL_ENV = "METRIK_AGENT_PRIVY_BROKER_URL";
+/** A scoped session token minted by the broker's `POST /v1/sessions`. */
+export const PRIVY_SESSION_TOKEN_ENV = "METRIK_AGENT_PRIVY_SESSION_TOKEN";
+/** The embedded wallet address the session is bound to. */
+export const PRIVY_ADDRESS_ENV = "METRIK_AGENT_PRIVY_ADDRESS";
+/** The PUBLIC Privy app id. Not a secret — the broker serves it at `/v1/config`. */
+export const PRIVY_APP_ID_ENV = "METRIK_AGENT_PRIVY_APP_ID";
+
+/** Every variable either Privy shape reads. Named in errors, never printed. */
+export const PRIVY_ENV_VARS = [
+  PRIVY_WALLET_KEY_ENV,
+  PRIVY_BROKER_URL_ENV,
+  PRIVY_SESSION_TOKEN_ENV,
+  PRIVY_ADDRESS_ENV,
+  PRIVY_APP_ID_ENV,
+] as const;
+
+/** The variables the user-owned session shape needs, all of them. */
+export const PRIVY_SESSION_ENV_VARS = [
+  PRIVY_BROKER_URL_ENV,
+  PRIVY_SESSION_TOKEN_ENV,
+  PRIVY_ADDRESS_ENV,
+  PRIVY_APP_ID_ENV,
+] as const;
+
+/**
+ * The spend ceiling a broker enforces server-side, read from `GET /v1/config`.
+ *
+ * These are the SAME numbers the broker checks `openStream` against
+ * (`deposit <= maxTotalUsdc`, `ratePerSecond <= maxRatePerSecondUsdc`,
+ * `duration <= maxDurationSeconds`), which is why the CLI can use them to
+ * refuse an over-ceiling hire locally instead of paying gas to learn a knowable
+ * fact. It reads them rather than hardcoding them: the ceiling belongs to the
+ * broker, and a copy in this file would be a second source of truth that goes
+ * stale silently.
+ */
+export interface PrivySpendPolicy {
+  readonly brokerUrl: string;
+  readonly chainId: number;
+  readonly maxTotalUsdc: bigint;
+  readonly maxRatePerSecondUsdc: bigint;
+  readonly maxDurationSeconds: number;
+}
+
+/** Reads a broker's public policy. No credential is sent; nothing secret is served. */
+export async function fetchPrivySpendPolicy(
+  brokerUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<PrivySpendPolicy> {
+  const base = brokerUrl.replace(/\/$/, "");
+  const response = await fetchImpl(`${base}/v1/config`, {
+    headers: { accept: "application/json" },
+  }).catch((error: unknown) => {
+    throw configError(
+      `the Privy broker at ${base} did not answer its public policy`,
+      `${describe(error)} The CLI reads GET /v1/config to know the ceiling your wallet is capped at; without it, it cannot tell you before broadcasting whether a hire fits.`,
+    );
+  });
+  const body = (await response.json().catch(() => null)) as Record<
+    string,
+    unknown
+  > | null;
+  if (!response.ok || body === null) {
+    throw configError(
+      `the Privy broker at ${base} rejected the public policy read (${response.status})`,
+    );
+  }
+  const chainId = Number(body.chainId);
+  const maxTotalUsdc = asBigint(body.maxTotalUsdcAtomic);
+  const maxRatePerSecondUsdc = asBigint(body.maxRatePerSecondAtomic);
+  const maxDurationSeconds = Number(body.maxDurationSeconds);
+  if (
+    !Number.isSafeInteger(chainId) ||
+    maxTotalUsdc === null ||
+    maxRatePerSecondUsdc === null ||
+    !Number.isSafeInteger(maxDurationSeconds)
+  ) {
+    throw configError(
+      `the Privy broker at ${base} returned a policy this CLI cannot read`,
+      "expected chainId, maxTotalUsdcAtomic, maxRatePerSecondAtomic and maxDurationSeconds.",
+    );
+  }
+  return {
+    brokerUrl: base,
+    chainId,
+    maxTotalUsdc,
+    maxRatePerSecondUsdc,
+    maxDurationSeconds,
+  };
+}
+
+function asBigint(value: unknown): bigint | null {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value))
+    return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return null;
+}
+
+export interface ResolvedPrivyCliWallet {
+  readonly source: PrivyCliWalletSource;
+  /** A JSON-RPC account: `signTypedData` works, `signTransaction` does not exist. */
+  readonly account: Account;
+  /** The provider-as-transport. Without this every write goes to a plain RPC and fails. */
+  readonly transport: Transport;
+  /** One line naming the wallet's origin. Safe to print: no credential in it. */
+  readonly description: string;
+  /** Reads the broker ceiling this wallet is capped at. Bound to its broker URL. */
+  readonly readSpendPolicy: () => Promise<PrivySpendPolicy>;
+}
+
+export interface ResolvePrivyCliWalletOptions {
+  /** `--rpc-url`, so a Privy wallet's READS use the same endpoint as everything else. */
+  readonly rpcUrl?: string;
+  readonly note?: (line: string) => void;
+  /** Test seam. Defaults to the real credential store selected from `env`. */
+  readonly store?: AutonomousWalletCredentialStore;
+  /** Test seam for the broker HTTP contract. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+/**
+ * Resolves a Privy wallet from the environment, or `null` when no Privy
+ * variable is set at all.
+ *
+ * A PARTIALLY configured Privy setup is an error, not a `null` — "you set the
+ * session token but not the address" and "you configured no Privy wallet" are
+ * different facts, and rendering the first as the second sends the reader
+ * looking in the wrong place. This mirrors the CDP path exactly.
+ */
+export async function resolvePrivyCliWallet(
+  env: NodeJS.ProcessEnv,
+  options: ResolvePrivyCliWalletOptions = {},
+): Promise<ResolvedPrivyCliWallet | null> {
+  const walletKey = read(env, PRIVY_WALLET_KEY_ENV);
+  const brokerUrl = read(env, PRIVY_BROKER_URL_ENV);
+  const sessionToken = read(env, PRIVY_SESSION_TOKEN_ENV);
+  const address = read(env, PRIVY_ADDRESS_ENV);
+  const appId = read(env, PRIVY_APP_ID_ENV);
+
+  if (
+    walletKey === null &&
+    brokerUrl === null &&
+    sessionToken === null &&
+    address === null &&
+    appId === null
+  ) {
+    return null;
+  }
+
+  if (walletKey !== null) {
+    if (sessionToken !== null) {
+      options.note?.(
+        `warning: both ${PRIVY_WALLET_KEY_ENV} and ${PRIVY_SESSION_TOKEN_ENV} are set; using the agent-owned wallet named by ${PRIVY_WALLET_KEY_ENV}. Unset it to sign with the session token.`,
+      );
+    }
+    return await resolveAutonomous(walletKey, brokerUrl, env, options);
+  }
+
+  const missing = PRIVY_SESSION_ENV_VARS.filter(
+    (name) => read(env, name) === null,
+  );
+  if (missing.length > 0) {
+    throw configError(
+      `the Privy wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`,
+      `a Privy wallet is configured one of two ways: set ${PRIVY_WALLET_KEY_ENV} to the store key of an agent-owned wallet you provisioned with provisionMetrikAutonomousWallet(), or set all of ${PRIVY_SESSION_ENV_VARS.join(", ")} for a broker session. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others to use a different wallet.`,
+    );
+  }
+
+  return resolveSession({
+    brokerUrl: brokerUrl as string,
+    sessionToken: sessionToken as string,
+    address: address as string,
+    appId: appId as string,
+    ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+    ...(options.fetchImpl === undefined
+      ? {}
+      : { fetchImpl: options.fetchImpl }),
+  });
+}
+
+async function resolveAutonomous(
+  walletKey: string,
+  brokerUrlOverride: string | null,
+  env: NodeJS.ProcessEnv,
+  options: ResolvePrivyCliWalletOptions,
+): Promise<ResolvedPrivyCliWallet> {
+  const store = options.store ?? selectCredentialStore(env);
+  let record: AutonomousWalletRecord | null;
+  try {
+    record = await store.load(walletKey);
+  } catch (error) {
+    throw configError(
+      `could not read the agent-owned Privy wallet "${walletKey}" from the credential store`,
+      `${describe(error)} On a headless host the OS credential store is often unavailable; set ${METRIK_WALLET_ENCRYPTION_KEY_ENV} to use the encrypted-file store instead.`,
+    );
+  }
+  if (record === null) {
+    throw configError(
+      `no agent-owned Privy wallet is stored under the key "${walletKey}"`,
+      `the CLI never provisions a wallet on your behalf — a fund-moving command is the wrong place to mint one. Provision it once with provisionMetrikAutonomousWallet({ storeKey: "${walletKey}" }) (see docs/autonomous-privy-wallet.md), then re-run this command.`,
+    );
+  }
+  if (record.walletId === undefined || record.address === undefined) {
+    throw configError(
+      `the agent-owned Privy wallet "${walletKey}" was never finished provisioning`,
+      "the local key exists but the broker never returned a wallet id and address. Re-run provisionMetrikAutonomousWallet() with the same store key — it retries with the same key and idempotency nonce.",
+    );
+  }
+
+  const brokerUrl = brokerUrlOverride ?? record.brokerUrl;
+  if (brokerUrlOverride !== null && brokerUrlOverride !== record.brokerUrl) {
+    options.note?.(
+      `note: ${PRIVY_BROKER_URL_ENV} (${brokerUrlOverride}) overrides the broker this wallet was provisioned against (${record.brokerUrl}); only a broker holding this wallet's Privy authorization key can authorize it.`,
+    );
+  }
+
+  let broker: HttpAutonomousWalletBroker;
+  try {
+    broker = new HttpAutonomousWalletBroker(brokerUrl, {
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+    });
+  } catch (error) {
+    throw configError(
+      `the autonomous wallet broker URL is not usable: ${describe(error)}`,
+      `set ${PRIVY_BROKER_URL_ENV} to an HTTPS broker you control (the default is ${METRIK_AUTONOMOUS_WALLET_BROKER_URL}).`,
+    );
+  }
+
+  const provider = createAutonomousWalletProvider({
+    wallet: record,
+    broker,
+    ...(options.rpcUrl === undefined ? {} : { rpcUrl: options.rpcUrl }),
+    ...(options.fetchImpl === undefined
+      ? {}
+      : { fetchImpl: options.fetchImpl }),
+  });
+  const account = await embeddedAccount(provider, record.appId, record.address);
+
+  return {
+    source: "privy-autonomous",
+    account,
+    transport: custom(provider),
+    description: `${record.address} (agent-owned Privy wallet "${walletKey}" via ${brokerUrl})`,
+    readSpendPolicy: async () =>
+      await fetchPrivySpendPolicy(
+        brokerUrl,
+        options.fetchImpl ?? globalThis.fetch.bind(globalThis),
+      ),
+  };
+}
+
+function resolveSession(input: {
+  readonly brokerUrl: string;
+  readonly sessionToken: string;
+  readonly address: string;
+  readonly appId: string;
+  readonly rpcUrl?: string;
+  readonly fetchImpl?: typeof fetch;
+}): Promise<ResolvedPrivyCliWallet> {
+  if (!isAddress(input.address)) {
+    throw configError(
+      `${PRIVY_ADDRESS_ENV} must be a 0x-prefixed 20-byte address`,
+    );
+  }
+  const address = getAddress(input.address);
+  let provider: PrivyEip1193Provider;
+  try {
+    provider = createPrivySessionProvider({
+      brokerUrl: input.brokerUrl,
+      sessionToken: input.sessionToken,
+      address,
+      ...(input.rpcUrl === undefined ? {} : { rpcUrl: input.rpcUrl }),
+      ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+    });
+  } catch (error) {
+    throw configError(
+      `the Privy session broker URL is not usable: ${describe(error)}`,
+      `set ${PRIVY_BROKER_URL_ENV} to the HTTPS broker that minted ${PRIVY_SESSION_TOKEN_ENV}. A session token is only valid against the broker that issued it.`,
+    );
+  }
+  return embeddedAccount(provider, input.appId, address).then((account) => ({
+    source: "privy-session" as const,
+    account,
+    transport: custom(provider),
+    description: `${address} (Privy broker session via ${input.brokerUrl})`,
+    readSpendPolicy: async () =>
+      await fetchPrivySpendPolicy(
+        input.brokerUrl,
+        input.fetchImpl ?? globalThis.fetch.bind(globalThis),
+      ),
+  }));
+}
+
+/**
+ * Wraps a provider in the package's existing Privy EOA adapter.
+ *
+ * Both CLI providers answer `eth_chainId` and `eth_accounts` locally, so the
+ * adapter's session assertion is a pure local consistency check here — no
+ * network call happens while the wallet is being resolved.
+ */
+async function embeddedAccount(
+  provider: PrivyEip1193Provider,
+  appId: string,
+  address: `0x${string}`,
+): Promise<Account> {
+  try {
+    return await createPrivyEmbeddedAccount({
+      appId,
+      address,
+      provider,
+      chainId: 84532,
+    });
+  } catch (error) {
+    throw configError(
+      `the Privy wallet could not be prepared: ${describe(error)}`,
+      `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are Base Sepolia (84532) only.`,
+    );
+  }
+}
+
+/**
+ * The credential store the autonomous wallet was provisioned into.
+ *
+ * Selection mirrors `provisionMetrikAutonomousWallet`'s documented options:
+ * setting `METRIK_WALLET_ENCRYPTION_KEY` means the encrypted-file store (the
+ * durable option for a headless host), otherwise the host OS store. Picking a
+ * different store than provisioning used simply finds no record, and the
+ * "no wallet is stored under this key" error above says so.
+ */
+function selectCredentialStore(
+  env: NodeJS.ProcessEnv,
+): AutonomousWalletCredentialStore {
+  if (read(env, METRIK_WALLET_ENCRYPTION_KEY_ENV) !== null) {
+    return new EncryptedFileCredentialStore({ env });
+  }
+  return createDefaultAutonomousWalletStore();
+}
+
+function read(env: NodeJS.ProcessEnv, name: string): string | null {
+  const value = env[name];
+  return value === undefined || value.length === 0 ? null : value;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof AutonomousWalletError) return error.message;
+  return error instanceof Error ? error.message : String(error);
+}