moneyos 0.2.1 → 0.3.2

package/dist/index.d.ts

@@ -1,13 +1,5 @@
-import { Hex, Address } from 'viem';
+import { Address, Hex, Account } from 'viem';
 
-interface MoneyOSConfig {
-    /** Default chain ID (e.g. 42161 for Arbitrum) */
-    chainId: number;
-    /** RPC URL override. Uses public RPC if not set. */
-    rpcUrl?: string;
-    /** Private key for signing transactions (hex string) */
-    privateKey?: Hex;
-}
 interface Balance {
     token: string;
     symbol: string;
@@ -68,14 +60,190 @@ interface Chain {
     blockExplorer: string;
 }
 
+interface Token {
+    symbol: string;
+    name: string;
+    decimals: number;
+    addresses: Record<number, Address>;
+}
+declare const NATIVE_TOKEN_ADDRESS: Address;
+declare const tokens: Record<string, Token>;
+declare function getToken(symbol: string): Token | undefined;
+declare function getTokenAddress(symbol: string, chainId: number): Address | undefined;
+
+declare const chains: Record<string, Chain>;
+declare const defaultChain: Chain;
+declare function getChain(idOrName: number | string): Chain | undefined;
+
+interface CallRequest {
+    to: Address;
+    data?: Hex;
+    value?: bigint;
+    chainId: number;
+}
+interface ExecutionResult {
+    hash: Hex;
+    chainId: number;
+}
+interface ExecutionClient {
+    mode: "eoa" | "smart-account" | "delegated";
+    getAddress(): Address;
+    send(call: CallRequest): Promise<ExecutionResult>;
+    sendBatch?(calls: CallRequest[]): Promise<ExecutionResult>;
+    capabilities(): {
+        sponsoredGas: boolean;
+        batching: boolean;
+        simulation: boolean;
+    };
+}
+interface ReadClient {
+    getBalance(params: {
+        address: Address;
+        chainId: number;
+    }): Promise<bigint>;
+    readContract<T = unknown>(params: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+        chainId: number;
+    }): Promise<T>;
+}
+interface AccessAdapter {
+    name: string;
+    openSession(ctx: SessionContext): Promise<AccessSession>;
+}
+interface AccessSession {
+    kind: "local" | "social" | "hardware";
+    getAddress(): Address;
+}
+interface SessionContext {
+    chainId: number;
+    rpcUrl?: string;
+}
+interface MoneyOSAction<I = unknown, O = unknown> {
+    name: string;
+    description: string;
+    run(input: I, ctx: ActionContext): Promise<O>;
+}
+interface ActionContext {
+    read: ReadClient;
+    execute: ExecutionClient;
+    assets: AssetRegistry;
+}
+interface AssetRegistry {
+    getToken(symbol: string): Token | undefined;
+    getTokenAddress(symbol: string, chainId: number): Address | undefined;
+    getChain(idOrName: number | string): Chain | undefined;
+    nativeTokenAddress: Address;
+}
+interface MoneyOSRuntime {
+    read: ReadClient;
+    execute: ExecutionClient;
+    assets: AssetRegistry;
+    config: RuntimeConfig;
+}
+interface RuntimeConfig {
+    defaultChainId: number;
+    rpcUrl?: string;
+}
+/**
+ * Configuration for a MoneyOS instance.
+ *
+ * Three construction modes, mutually exclusive:
+ *
+ * 1. Default EOA from private key: pass `privateKey`. A default
+ *    `EOAExecutor` and `ViemReadClient` are created for you. Legacy shortcut
+ *    for the common "I have a hex key" case.
+ *
+ * 2. Pre-loaded signer: pass `signer` — a viem `Account` resolved elsewhere
+ *    (typically from a `KeyStore`: file, 1Password, hardware, KMS, MPC). A
+ *    default `EOAExecutor` is built around it. This is the preferred path
+ *    when key loading is async, because the keystore boundary stays async
+ *    while `MoneyOS` construction remains synchronous.
+ *
+ * 3. Injected runtime: pass `execute` (and optionally `read` / `assets`) to
+ *    plug in custom implementations — e.g. a gasless smart-account executor
+ *    or a custom read client. Any part you do not inject falls back to the
+ *    default.
+ *
+ * `privateKey`, `signer`, and `execute` are mutually exclusive — passing
+ * more than one throws.
+ */
+interface MoneyOSConfig {
+    /** Default chain ID (e.g. 42161 for Arbitrum). */
+    chainId: number;
+    /** RPC URL override. Uses public RPC if not set. */
+    rpcUrl?: string;
+    /** Private key for signing transactions (hex string). Creates a default EOAExecutor. Mutually exclusive with `signer` and `execute`. */
+    privateKey?: Hex;
+    /** Pre-loaded viem `Account`, typically resolved from a `KeyStore`. Creates a default EOAExecutor. Mutually exclusive with `privateKey` and `execute`. */
+    signer?: Account;
+    /** Inject a custom ExecutionClient (e.g. a gasless smart-account executor). Mutually exclusive with `privateKey` and `signer`. */
+    execute?: ExecutionClient;
+    /** Inject a custom ReadClient. Defaults to ViemReadClient. */
+    read?: ReadClient;
+    /** Inject a custom AssetRegistry. Defaults to the built-in registry. */
+    assets?: AssetRegistry;
+}
+
+/**
+ * KeyStore — pluggable backend for loading an EOA signer.
+ *
+ * A KeyStore decides *how* a signer is obtained. It does not decide how
+ * transactions are sent — that remains the responsibility of
+ * `ExecutionClient`.
+ *
+ * The interface is deliberately narrow:
+ *   - `loadSigner()` returns a viem `Account`, not a raw private key.
+ *     There is intentionally no `getPrivateKey()` method. Future
+ *     hardware-, KMS-, or MPC-backed stores must fit the same shape.
+ *   - `metadata()` is async because some stores may need I/O even to answer
+ *     questions about the stored key.
+ *   - `hasKey()` lets callers probe the store without triggering a full
+ *     `loadSigner()` (which may prompt the user for biometric auth).
+ */
+/**
+ * Identifies the backend kind of a `KeyStore`. `"custom"` is reserved for
+ * stores that don't fit any of the built-in kinds and is not expected to be
+ * used in v1.
+ */
+type KeyStoreKind = "file" | "hardware" | "kms" | "custom";
+/**
+ * Non-secret descriptive information about a stored key. Safe to log or
+ * display.
+ */
+interface KeyStoreMetadata {
+    kind: KeyStoreKind;
+    /** Derived EOA address, if the store can produce it without loading the signer. */
+    address?: Address;
+    /** Optional human-readable label for diagnostics. */
+    label?: string;
+}
+interface KeyStore {
+    readonly kind: KeyStoreKind;
+    metadata(): Promise<KeyStoreMetadata>;
+    hasKey(): Promise<boolean>;
+    /**
+     * Load a viem `Account` that can sign transactions and messages.
+     *
+     * Returns viem's `Account` type (not the narrower `LocalAccount`) so that
+     * future stores backed by hardware wallets, remote KMS, or MPC can return
+     * a `toAccount({ signMessage, signTransaction, signTypedData })` wrapper
+     * without changing this interface.
+     */
+    loadSigner(): Promise<Account>;
+}
+
 declare class MoneyOS {
-    private config;
-    private publicClients;
-    private walletClient;
+    private read;
+    private executor;
+    private assets;
+    private runtimeConfig;
     constructor(config: MoneyOSConfig);
-    private getPublicClient;
-    private getWalletClient;
+    get runtime(): MoneyOSRuntime;
     get address(): Address;
+    private requireExecutor;
     balance(token: string, options?: {
         address?: Address;
         chainId?: number;
@@ -89,21 +257,6 @@ declare class MoneyOS {
     }): Promise<SwapResult>;
 }
 
-declare const chains: Record<string, Chain>;
-declare const defaultChain: Chain;
-declare function getChain(idOrName: number | string): Chain | undefined;
-
-interface Token {
-    symbol: string;
-    name: string;
-    decimals: number;
-    addresses: Record<number, Address>;
-}
-declare const NATIVE_TOKEN_ADDRESS: Address;
-declare const tokens: Record<string, Token>;
-declare function getToken(symbol: string): Token | undefined;
-declare function getTokenAddress(symbol: string, chainId: number): Address | undefined;
-
 declare class OdosProvider implements SwapProvider {
     name: string;
     private apiKey?;
@@ -132,4 +285,121 @@ declare class OdosProvider implements SwapProvider {
     }>;
 }
 
-export { type Balance, type Chain, MoneyOS, type MoneyOSConfig, NATIVE_TOKEN_ADDRESS, OdosProvider, type SendResult, type SwapProvider, type SwapQuote, type SwapResult, type Token, chains, defaultChain, getChain, getToken, getTokenAddress, tokens };
+declare class ViemReadClient implements ReadClient {
+    private clients;
+    private config;
+    constructor(config: RuntimeConfig);
+    private getClient;
+    getBalance(params: {
+        address: Address;
+        chainId: number;
+    }): Promise<bigint>;
+    readContract<T = unknown>(params: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+        chainId: number;
+    }): Promise<T>;
+}
+declare class EOAExecutor implements ExecutionClient {
+    readonly mode: "eoa";
+    private signer;
+    private walletClients;
+    private publicClients;
+    private config;
+    constructor(signer: Account, config: RuntimeConfig);
+    /**
+     * Convenience factory: build an EOAExecutor from a raw private key.
+     * Equivalent to `new EOAExecutor(privateKeyToAccount(privateKey), config)`.
+     * Kept as a helper so the common "I have a hex key" path stays one line
+     * while the constructor itself takes a viem `Account` to accommodate
+     * future keystore-backed signers (hardware, KMS, MPC).
+     *
+     * Attach viem's nonce manager so back-to-back live transactions use a
+     * pending-aware nonce source instead of relying on RPC fill behavior.
+     */
+    static fromPrivateKey(privateKey: Hex, config: RuntimeConfig): EOAExecutor;
+    private getWalletClient;
+    private getPublicClient;
+    getAddress(): Address;
+    send(call: CallRequest): Promise<ExecutionResult>;
+    capabilities(): {
+        sponsoredGas: boolean;
+        batching: boolean;
+        simulation: boolean;
+    };
+}
+
+declare class LocalAccessAdapter implements AccessAdapter {
+    readonly name = "local";
+    private privateKey;
+    constructor(privateKey: Hex);
+    openSession(_ctx: SessionContext): Promise<AccessSession>;
+}
+
+/**
+ * FileKeyStore — raw-key JSON helper for library consumers.
+ *
+ * Reads a raw private key from a JSON file on disk (by default
+ * `~/.moneyos/config.json`) and derives a viem `Account` from it.
+ *
+ * MoneyOS CLI no longer uses plaintext `config.json` wallet storage as its
+ * default path. The CLI now uses an encrypted wallet file plus a local unlock
+ * session. This helper remains available for advanced SDK use cases and
+ * explicit raw-key compatibility paths outside the default CLI flow.
+ */
+interface FileKeyStoreOptions {
+    /**
+     * Absolute path to the JSON config file that holds the private key.
+     * Defaults to `~/.moneyos/config.json` for compatibility with earlier
+     * raw-key layouts and explicit SDK usage.
+     */
+    configPath?: string;
+}
+declare class FileKeyStore implements KeyStore {
+    readonly kind: "file";
+    private configPath;
+    constructor(options?: FileKeyStoreOptions);
+    hasKey(): Promise<boolean>;
+    metadata(): Promise<KeyStoreMetadata>;
+    loadSigner(): Promise<Account>;
+    /**
+     * Read and validate the config file. Returns `undefined` if the file does
+     * not exist. Throws with context for any other failure mode (malformed
+     * JSON, wrong top-level type, wrong `privateKey` type). The hex format of
+     * the key itself is validated later by viem's `privateKeyToAccount`.
+     */
+    private readConfig;
+}
+
+/**
+ * Create a MoneyOS instance.
+ *
+ * Default EOA usage:
+ * ```ts
+ *   const moneyos = createMoneyOS({ chainId: 42161, privateKey: "0x..." });
+ *   await moneyos.send("USDC", "0x...", "10");
+ * ```
+ *
+ * Custom execution (e.g. gasless smart-account):
+ * ```ts
+ *   import { ParticleExecutor } from "@moneyos/executor-particle";
+ *   const moneyos = createMoneyOS({
+ *     chainId: 42161,
+ *     execute: new ParticleExecutor({ ... }),
+ *   });
+ *   // moneyos.send / moneyos.swap transparently use the injected executor
+ * ```
+ *
+ * You can also inject `read` or `assets` if you need custom implementations.
+ * `privateKey` and `execute` are mutually exclusive.
+ *
+ * Future (with tools):
+ * ```ts
+ *   const moneyos = createMoneyOS(config).use(swapTool());
+ * ```
+ */
+declare function createMoneyOS(config: MoneyOSConfig): MoneyOS;
+
+export { type AccessAdapter, type AccessSession, type ActionContext, type AssetRegistry, type Balance, type CallRequest, type Chain, EOAExecutor, type ExecutionClient, type ExecutionResult, FileKeyStore, type FileKeyStoreOptions, type KeyStore, type KeyStoreKind, type KeyStoreMetadata, LocalAccessAdapter, MoneyOS, type MoneyOSAction, type MoneyOSConfig, type MoneyOSRuntime, NATIVE_TOKEN_ADDRESS, OdosProvider, type ReadClient, type RuntimeConfig, type SendResult, type SessionContext, type SwapProvider, type SwapQuote, type SwapResult, type Token, ViemReadClient, chains, createMoneyOS, defaultChain, getChain, getToken, getTokenAddress, tokens };