@wafermapxyz/cli 0.0.0-stage → 0.4.2

package/dist/types/shared/solana.d.ts

@@ -0,0 +1,36 @@
+export declare const SOLANA_CAIP = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export declare const SOLANA_USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+/** Signs as one Solana address. `blockhash` returns a recent blockhash from any mainnet RPC. */
+export type SolanaPayer = {
+    address: string;
+    sign: (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    blockhash: () => Promise<string>;
+};
+export declare function isSolanaAddress(v: string): boolean;
+/** The agent's Solana keypair, derived from its EVM private key. */
+export declare function solanaKeyFromEvm(privateKey: string): {
+    address: string;
+    /** seed ‖ public key, base58: the format Phantom and Solflare import. */
+    secretKey: string;
+    sign: (message: Uint8Array) => Uint8Array<ArrayBufferLike>;
+};
+/** The associated token account of `owner` for `mint` (classic SPL Token program). */
+export declare function ataOf(owner: string, mint?: string): string;
+export type SolanaQuote = {
+    amount: string;
+    payTo: string;
+    asset: string;
+    feePayer: string;
+    memo?: string;
+};
+/** The base64 wire transaction for an x402 `exact` payment on Solana, signed by `payer` only. */
+export declare function solanaPayment(payer: SolanaPayer, q: SolanaQuote): Promise<string>;
+export declare function solanaRpc(url: string, method: string, params: unknown[], f?: typeof fetch): Promise<any>;
+export declare const latestBlockhash: (url: string, f?: typeof fetch) => Promise<string>;
+/** USDC (6 decimals) and SOL balances of a wallet. A wallet that never held USDC has no token
+ *  account: 0. Read with getAccountInfo, which free public RPCs serve (getTokenAccountBalance is
+ *  an "indexed" call some of them reserve for paid keys). */
+export declare function solanaBalances(url: string, owner: string, f?: typeof fetch): Promise<{
+    usdc: string;
+    sol: string;
+}>;

package/dist/types/shared/swap.d.ts

@@ -0,0 +1,78 @@
+import { type Address, type Hex, type PublicClient, type WalletClient } from "viem";
+export type Net = "robinhood" | "base";
+export type Token = {
+    symbol: string;
+    name: string;
+    address: Address;
+    decimals: number | null;
+    kind?: "native" | "stable" | "wrapped" | "stock";
+};
+export declare const NATIVE: Address;
+export declare const TOKENS: Record<Net, Token[]>;
+/** KyberSwap's MetaAggregationRouterV2, the only contract a swap may approve or call. The API's answer
+ *  is checked against it, and the swap calldata is decoded and checked too (see executeSwap). */
+export declare const KYBER_ROUTER: Record<Net, Address>;
+export declare class SwapError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Resolve "ETH", "USDC", "TSLA" or a 0x address to a token with decimals.
+ * `lookup` finds symbols outside the built-in list (e.g. Robinhood stock tokens).
+ */
+export declare function resolveToken(net: Net, ref: string, client: PublicClient, lookup?: (net: Net, symbol: string) => Promise<Token | null>): Promise<Token>;
+export type SwapQuote = {
+    network: Net;
+    tokenIn: Token;
+    tokenOut: Token;
+    amountIn: string;
+    amountOut: string;
+    amountInUsd: number | null;
+    amountOutUsd: number | null;
+    gasUsd: number | null;
+    /** Percent lost between USD in and USD out (route fees + impact), when both are known. */
+    impactPct: number | null;
+    routerAddress: Address;
+    route: unknown;
+    at: number;
+};
+/** Ask Kyber for the best route. `amount` is human units of tokenIn ("0.5"). */
+export declare function quoteSwap(o: {
+    network: Net;
+    tokenIn: Token;
+    tokenOut: Token;
+    amount: string;
+    fetch?: typeof fetch;
+}): Promise<SwapQuote>;
+/**
+ * What the calldata will make the router do, read from the bytes themselves rather than from what the
+ * API says about them: which tokens, how much in, who receives the output, the minimum out, any fees.
+ */
+export declare function decodeSwap(data: Hex): {
+    fn: "swap" | "swapSimpleMode";
+    srcToken: `0x${string}`;
+    dstToken: `0x${string}`;
+    receiver: `0x${string}`;
+    amount: bigint;
+    minReturn: bigint;
+    feeReceivers: readonly `0x${string}`[];
+    feeAmounts: readonly bigint[];
+};
+/**
+ * Build, check, approve (exact amount, only if needed) and send the swap from the wallet's account.
+ * The built transaction is checked before anything is signed: KyberSwap's router, the quoted tokens and
+ * amount, the output to this wallet, no fees, and a minimum output within the slippage of the quote.
+ * Every step is reported through `step` so a UI can show progress.
+ */
+export declare function executeSwap(o: {
+    quote: SwapQuote;
+    wallet: WalletClient;
+    client: PublicClient;
+    slippageBps?: number;
+    fetch?: typeof fetch;
+    step?: (s: string, tx?: Hex) => void;
+}): Promise<{
+    approveTx: `0x${string}` | undefined;
+    tx: `0x${string}`;
+    amountOutMin: string;
+}>;

package/dist/types/shared/x402client.d.ts

@@ -0,0 +1,116 @@
+import { type SolanaPayer } from "./solana";
+export type Hex = `0x${string}`;
+/** Anything that can sign EIP-712 typed data for one address (a viem account works). */
+export type Signer = {
+    address: Hex;
+    signTypedData: (args: {
+        domain: any;
+        types: any;
+        primaryType: string;
+        message: any;
+    }) => Promise<Hex>;
+};
+export type ChainKey = "robinhood" | "base" | "arbitrum" | "polygon" | "solana";
+export type Chain = {
+    key: ChainKey;
+    vm: "evm" | "svm";
+    id: number;
+    caip: string;
+    v1: string;
+    stable: string;
+    symbol: string;
+    name: string;
+    domain?: {
+        name: string;
+        version: string;
+    };
+};
+export declare const PAY_CHAINS: Chain[];
+export declare const EVM_CHAINS: Chain[];
+export declare const CHAIN_KEYS: ChainKey[];
+export type Requirement = {
+    version: 1 | 2;
+    chain: Chain;
+    /** Base units, 6 decimals. */
+    amount: string;
+    usd: number;
+    payTo: string;
+    asset: string;
+    maxTimeoutSeconds: number;
+    /** EVM: the token's EIP-712 domain. Solana: the facilitator's fee payer and an optional memo. */
+    extra: {
+        name?: string;
+        version?: string;
+        feePayer?: string;
+        memo?: string;
+    };
+    /** The requirement exactly as the server sent it (echoed back in the payment). */
+    raw: any;
+};
+export type Quote = {
+    version: 1 | 2;
+    resource: any;
+    accepts: Requirement[];
+    offered: string[];
+    inputError?: {
+        code: string;
+        message: string;
+    };
+};
+export declare class X402Error extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** Read a 402 response into a quote. Only payable requirements are kept in `accepts`. */
+export declare function readQuote(res: Response): Promise<Quote>;
+/** Pick the requirement to pay: the first preferred chain that is offered. */
+export declare function choose(q: Quote, prefer?: ChainKey[]): Requirement;
+/** The longest an EVM payment authorization stays valid, whatever the server allows. Whoever receives
+ *  a signed payment can execute it until then, so this bounds how long "failed calls cost $0" rests on
+ *  the server's word. Long enough for a slow resource plus settlement (Wafermap needs at least 60 s). */
+export declare const MAX_VALIDITY_SECONDS = 90;
+/** Sign the payment for the exact amount and return the header to send: an EIP-3009 transfer on
+ *  EVM chains, a partially signed USDC transfer transaction on Solana. */
+export declare function signPayment(signer: Signer, req: Requirement, resource: any, solana?: SolanaPayer): Promise<{
+    name: string;
+    value: string;
+    auth?: SignedAuth;
+}>;
+/** Settlement details a server returns after a paid call, when it sends them. */
+export declare function readSettlement(res: Response): {
+    tx?: string;
+    network?: string;
+    success?: boolean;
+} | null;
+/** What an EVM payment authorized on-chain: anyone holding it can execute it until `validBefore`
+ *  (unix seconds), once. `authorizationState(from, nonce)` on the token says whether it was used. */
+export type SignedAuth = {
+    nonce: Hex;
+    validBefore: number;
+};
+export type Signed = {
+    req: Requirement;
+    from: string;
+    auth?: SignedAuth;
+};
+export type PaidCall = {
+    res: Response;
+    paid: (Signed & {
+        tx: string | null;
+    }) | null;
+};
+/**
+ * Fetch an x402 resource, paying once when it answers 402.
+ * `approve` sees the chosen requirement before anything is signed; throw to stop.
+ * `onSigned` runs once the payment is signed and before it is sent: from then on the payment
+ * can be executed whatever the server answers (or if it never answers), so a spend limit has to
+ * count it here, at its full amount, not from what the server reports back.
+ */
+export declare function x402fetch(url: string, init: RequestInit, opts: {
+    signer: Signer | (() => Promise<Signer>);
+    solana?: SolanaPayer;
+    prefer?: ChainKey[];
+    approve?: (req: Requirement) => Promise<void> | void;
+    onSigned?: (s: Signed) => void;
+    fetch?: typeof fetch;
+}): Promise<PaidCall>;

package/dist/types/src/core.d.ts

@@ -0,0 +1,184 @@
+import { type Hex, type LocalAccount, type PublicClient } from "viem";
+import { type SwapQuote, type Token } from "../shared/swap";
+import { type SolanaPayer } from "../shared/solana";
+import { type ChainKey } from "../shared/x402client";
+/** A payment network. Swaps run on Robinhood Chain and Base only. */
+export type Net = ChainKey;
+type EvmNet = Exclude<Net, "solana">;
+export declare const NETS: Net[];
+export declare const isNet: (v: unknown) => v is Net;
+export type Limits = {
+    perPayment: number;
+    perDay: number;
+    perSwap: number;
+};
+/**
+ * One line of the spend log. A payment writes two lines: the signed amount the moment it is
+ * signed (`status: "signed"`, counted by the daily cap), then the outcome with `usd: 0` and
+ * `of` pointing back to it. Older logs have single lines without `id`; `mergeLog` joins them.
+ */
+export type SpendEntry = {
+    at: number;
+    kind: "resource" | "service" | "swap";
+    what: string;
+    usd: number;
+    network: Net;
+    tx: string | null;
+    payer: string;
+    id?: string;
+    of?: string;
+    status?: PaymentStatus;
+    /** EVM payments: the EIP-3009 nonce and expiry, to check on-chain whether it was ever used. */
+    nonce?: string;
+    validBefore?: number;
+    /** What the server said it charged, for the record only. */
+    reported?: number | null;
+};
+/** signed: sent, outcome not known (or the request died) · ok: the server answered 2xx ·
+ *  failed: it answered with an error · refused: it refused the payment itself ·
+ *  aborted: signed but never sent, because another process had used the budget meanwhile. */
+export type PaymentStatus = "signed" | "ok" | "failed" | "refused" | "aborted";
+export type Approval = {
+    kind: SpendEntry["kind"];
+    what: string;
+    usd: number;
+    network: Net;
+    detail?: string;
+};
+export type WafermapOptions = {
+    /** A 0x private key, or pass `account` (any viem LocalAccount). A private key also gives the
+     *  wallet its Solana side (derived from it); with `account`, pass `solana` to pay on Solana. */
+    privateKey?: Hex;
+    account?: LocalAccount;
+    /** Signs Solana payments. Derived from `privateKey` when not given. */
+    solana?: Omit<SolanaPayer, "blockhash">;
+    /** Read-only: a Solana address for balances when there is no key. */
+    solanaAddress?: string;
+    /** Default https://wafermap.xyz */
+    baseUrl?: string;
+    /** Preferred payment network. Default robinhood (USDG); base, arbitrum, polygon and solana pay in USDC. */
+    network?: Net;
+    limits?: Partial<Limits>;
+    /** Where spending is remembered for the daily cap. Default: in memory. */
+    ledger?: {
+        entries(): SpendEntry[];
+        record(e: SpendEntry): void;
+    };
+    /** Called before every payment or swap. Return false to refuse. Default: allow within caps. */
+    approve?: (a: Approval) => boolean | Promise<boolean>;
+    /** RPC URLs per network. Solana defaults to `${baseUrl}/api/solana`. */
+    rpc?: Partial<Record<Net, string>>;
+    /** Give up on any HTTP request (quote, paid call, discovery, swap API) after this long. Default 60000 ms.
+     *  A paid call that times out after signing stays counted until its authorization expires. */
+    timeoutMs?: number;
+};
+export declare class WafermapError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** One row per payment: the signed line joined with its outcome line. Old single lines pass through. */
+export declare function mergeLog(entries: SpendEntry[]): SpendEntry[];
+/**
+ * Was a signed payment ever executed? Reads the token contract (EIP-3009 authorizationState),
+ * so the answer does not depend on any server and needs no key. "unused" after expiry means it
+ * can never be charged. Solana payments and old log lines without a nonce come back "unknown"; an RPC
+ * failure comes back "error".
+ */
+export declare function checkPayment(e: Pick<SpendEntry, "network" | "payer" | "nonce" | "validBefore">, rpc?: string): Promise<"used" | "unused" | "pending" | "unknown" | "error">;
+export declare const DEFAULT_LIMITS: Limits;
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare class Wafermap {
+    readonly account: LocalAccount;
+    readonly baseUrl: string;
+    network: Net;
+    limits: Limits;
+    private ledger;
+    private approveFn?;
+    private rpc;
+    private clients;
+    readonly solana: SolanaPayer | null;
+    readonly solanaAddress: string | null;
+    readonly timeoutMs: number;
+    /** fetch with this wallet's time limit: a server that never answers cannot hold a call forever. */
+    readonly fetch: typeof fetch;
+    constructor(o: WafermapOptions);
+    get address(): `0x${string}`;
+    client(n: EvmNet): PublicClient;
+    /** USD signed today (local midnight) on payments, not counting swaps. Every signed payment
+     *  counts at its full amount, whatever the server answered, because a signed payment can be
+     *  executed until it expires. `checkPayment` shows on-chain which ones were never used. */
+    spentToday(): number;
+    private gate;
+    private prefer;
+    /** A second 402 means the payment itself was refused (usually: not enough balance). */
+    private rejected;
+    /** Write the signed payment to the ledger before it leaves the machine. */
+    private booked;
+    /** The outcome line for a booked payment. It adds nothing to the daily total. */
+    private outcome;
+    /** The timeout error for `host`, saying whether a payment was signed and until when it can be executed. */
+    private timeoutError;
+    /** Read a JSON body; a time-out while reading is reported, anything else gives `fallback`. */
+    private body;
+    private queue;
+    private acquire;
+    private paidFetch;
+    resources(): Promise<any[]>;
+    call(id: string, input?: Record<string, unknown>, o?: {
+        network?: Net;
+    }): Promise<{
+        resource: string;
+        result: any;
+        receipt: {
+            network: string;
+            asset: string;
+            amountUsd: number;
+            payer: string;
+            tx: string;
+            ms: number;
+        } | null;
+    }>;
+    discover(query: string, limit?: number): Promise<{
+        url: string;
+        method: string;
+        name: string | null;
+        description: string;
+        priceUsd: number | null;
+        networks: string[];
+        payable: boolean;
+        input: unknown;
+        outputExample: unknown;
+    }[]>;
+    /** Call any x402 URL and pay it if it asks. GET sends `input` as the query string, POST as JSON. */
+    pay(url: string, o?: {
+        method?: "GET" | "POST";
+        input?: Record<string, unknown>;
+        network?: Net;
+    }): Promise<{
+        status: number;
+        result: any;
+        paid: {
+            usd: number;
+            network: ChainKey;
+            tx: string | null;
+        } | null;
+    }>;
+    balances(): Promise<Record<ChainKey, {
+        eth: string;
+        gas: string;
+        stable: string;
+        symbol: string;
+    } | null>>;
+    private tokenCache;
+    private lookup;
+    swapQuote(from: string, to: string, amount: string, network?: Net): Promise<SwapQuote>;
+    swap(quote: SwapQuote, o?: {
+        slippageBps?: number;
+        step?: (s: string) => void;
+    }): Promise<{
+        approveTx: `0x${string}` | undefined;
+        tx: `0x${string}`;
+        amountOutMin: string;
+    }>;
+}
+export type { SwapQuote, Token };

package/dist/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export { Wafermap, WafermapError, DEFAULT_LIMITS, DEFAULT_TIMEOUT_MS, checkPayment, mergeLog } from "./core.js";
+export type { Approval, Limits, Net, PaymentStatus, SpendEntry, SwapQuote, Token, WafermapOptions } from "./core.js";
+export { x402fetch, readQuote, choose, signPayment, PAY_CHAINS, MAX_VALIDITY_SECONDS, X402Error } from "../shared/x402client";
+export { quoteSwap, executeSwap, decodeSwap, KYBER_ROUTER, SwapError } from "../shared/swap";
+export type { Requirement, Quote, Signed, SignedAuth, Signer } from "../shared/x402client";

package/package.json

@@ -1,6 +1,68 @@
-{
-  "name": "@wafermapxyz/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@wafermapxyz/cli",
+  "version": "0.4.2",
+  "description": "Wafermap for agents: an encrypted local wallet that pays x402 resources, discovers and pays third-party x402 services (USDG on Robinhood Chain; USDC on Solana, Base, Arbitrum, Polygon), and swaps on Robinhood Chain and Base. CLI, SDK and MCP server.",
+  "type": "module",
+  "bin": {
+    "wafermap": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test"
+  },
+  "keywords": [
+    "x402",
+    "agents",
+    "mcp",
+    "wallet",
+    "robinhood-chain",
+    "base",
+    "arbitrum",
+    "polygon",
+    "solana",
+    "usdg",
+    "usdc"
+  ],
+  "homepage": "https://wafermap.xyz/docs#cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wafermap/wafermap-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wafermap/wafermap-cli/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@noble/curves": "^1.9.1",
+    "@noble/hashes": "^1.8.0",
+    "@scure/base": "^1.2.6",
+    "viem": "^2.56.8",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2"
+  }
+}