@absol-labs/agent 0.4.0 → 0.6.0

package/src/wallet/lifecycle.ts

@@ -0,0 +1,158 @@
+import { erc20Abi, type Address } from "viem";
+
+/**
+ * Agent wallet lifecycle helpers (metrik-agent#65).
+ *
+ * `../wallet/provider.ts` already resolves a wallet (injected key or a
+ * Coinbase CDP Server Wallet v2 account) and hands back a viem `Account` that
+ * can sign directly — `resolveAgentWallet()`'s CDP path is create-OR-restore
+ * by construction (`cdp.evm.getOrCreateAccount({ name })` is idempotent: the
+ * same `ownerName` always resolves to the same on-chain address, so a second
+ * run with the same env "restores" rather than creates a new wallet).
+ *
+ * This module adds the remaining thin, non-custodial lifecycle pieces the
+ * issue asks for: reading balances, a testnet faucet hint, and requesting
+ * funds from the CDP faucet. It deliberately does NOT wrap signing — a
+ * `ResolvedAgentWallet.account` is already a plain viem `Account`
+ * (`signMessage` / `signTypedData` / `signTransaction` all work as-is), and
+ * adding a second signing surface here would be exactly the "second wallet
+ * system" AGENTS.md warns against.
+ */
+
+/** Native gas balance + USDC balance for one address. */
+export interface WalletBalances {
+  /** Native token balance (ETH on Base/Base Sepolia), in wei. */
+  readonly nativeWei: bigint;
+  /** USDC balance, in atomic units (6 decimals). */
+  readonly usdcAtomic: bigint;
+}
+
+/** The subset of a viem `PublicClient` balance reads need. Duck-typed so any real client satisfies it. */
+export interface BalanceReader {
+  getBalance(args: { readonly address: Address }): Promise<bigint>;
+  readContract(args: {
+    readonly address: Address;
+    readonly abi: typeof erc20Abi;
+    readonly functionName: "balanceOf";
+    readonly args: readonly [Address];
+  }): Promise<unknown>;
+}
+
+export interface GetWalletBalancesOptions {
+  readonly publicClient: BalanceReader;
+  readonly address: Address;
+  /** The USDC token contract to read the ERC-20 balance from. */
+  readonly usdc: Address;
+}
+
+/** Reads a wallet's native gas balance and USDC balance in one call. Read-only — no signing, no writes. */
+export async function getWalletBalances(
+  options: GetWalletBalancesOptions,
+): Promise<WalletBalances> {
+  const [nativeWei, usdcAtomic] = await Promise.all([
+    options.publicClient.getBalance({ address: options.address }),
+    options.publicClient.readContract({
+      address: options.usdc,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [options.address],
+    }),
+  ]);
+  return { nativeWei, usdcAtomic: usdcAtomic as bigint };
+}
+
+/** Human-facing pointers to fund a freshly created/restored testnet wallet. */
+export interface FaucetHint {
+  readonly network: string;
+  /** Coinbase CDP faucet — funds native ETH (and, on some networks, USDC) for a CDP-managed address. */
+  readonly cdpFaucetUrl: string;
+  /** Circle's own Base Sepolia USDC faucet — an alternative USDC source that doesn't require a CDP account. */
+  readonly usdcFaucetUrl: string;
+  /** How to request the same funds programmatically from a CDP wallet — see {@link requestCdpFaucet}. */
+  readonly programmaticHint: string;
+}
+
+export class UnsupportedFaucetChainError extends Error {
+  constructor(chainId: number) {
+    super(
+      `no known testnet faucet for chainId ${chainId} (Metrik is Base Sepolia (84532) only)`,
+    );
+    this.name = "UnsupportedFaucetChainError";
+  }
+}
+
+const BASE_SEPOLIA_CHAIN_ID = 84532;
+
+const BASE_SEPOLIA_FAUCET_HINT: FaucetHint = {
+  network: "base-sepolia",
+  cdpFaucetUrl: "https://portal.cdp.coinbase.com/products/faucet",
+  usdcFaucetUrl: "https://faucet.circle.com",
+  programmaticHint:
+    "requestCdpFaucet({ cdp, address, token: 'eth' | 'usdc' }) — subject to a 24h per-address rate limit",
+};
+
+/** A faucet hint for the given chain. Only Base Sepolia (84532) is supported — Metrik is testnet-only, single-chain. */
+export function faucetHint(chainId: number): FaucetHint {
+  if (chainId !== BASE_SEPOLIA_CHAIN_ID) {
+    throw new UnsupportedFaucetChainError(chainId);
+  }
+  return BASE_SEPOLIA_FAUCET_HINT;
+}
+
+export type FaucetToken = "eth" | "usdc";
+
+/** The subset of the Coinbase CDP client the faucet request needs. Duck-typed for testability. */
+export interface CdpFaucetClientLike {
+  readonly evm: {
+    requestFaucet(options: {
+      readonly address: Address;
+      readonly network: string;
+      readonly token: FaucetToken;
+    }): Promise<{ readonly transactionHash: string }>;
+  };
+}
+
+export interface RequestCdpFaucetOptions {
+  readonly cdp: CdpFaucetClientLike;
+  readonly address: Address;
+  readonly token: FaucetToken;
+  /** Default `"base-sepolia"`. */
+  readonly network?: string;
+}
+
+export interface FaucetRequestResult {
+  /** `true` iff the faucet accepted the request (a tx hash was returned). */
+  readonly requested: boolean;
+  readonly txHash?: string;
+  /**
+   * Set when `requested` is `false`. The CDP faucet enforces a 24h per-address
+   * rate limit, so a failure here is an EXPECTED, non-fatal outcome — never
+   * thrown. Callers should log this and fall back to checking whether the
+   * balance is already sufficient.
+   */
+  readonly error?: string;
+}
+
+/**
+ * Requests testnet funds from the Coinbase CDP faucet for a CDP-managed
+ * address. Tolerates the faucet's 24h rate limit and any other request
+ * failure by returning `{ requested: false, error }` — it never throws, so a
+ * caller can always fall through to reading the current balance instead.
+ */
+export async function requestCdpFaucet(
+  options: RequestCdpFaucetOptions,
+): Promise<FaucetRequestResult> {
+  try {
+    const result = await options.cdp.evm.requestFaucet({
+      address: options.address,
+      network: options.network ?? "base-sepolia",
+      token: options.token,
+    });
+    return { requested: true, txHash: result.transactionHash };
+  } catch (error) {
+    return {
+      requested: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}