moltspay 0.1.2 → 0.2.0

package/dist/wallet/index.d.mts

@@ -102,4 +102,191 @@ declare class SecureWallet {
     private updateDailyTotal;
 }
 
-export { SecureWallet, Wallet, type WalletConfig };
+/**
+ * createWallet - 为 Agent 创建新钱包
+ *
+ * 功能：
+ * - 生成新的以太坊钱包
+ * - 安全存储私钥（加密或明文，取决于配置）
+ * - 返回钱包地址（不返回私钥）
+ */
+interface CreateWalletOptions {
+    /** 存储路径，默认 ~/.moltspay/wallet.json */
+    storagePath?: string;
+    /** 加密密码（可选，不提供则明文存储） */
+    password?: string;
+    /** 钱包标签/名称 */
+    label?: string;
+    /** 如果钱包已存在，是否覆盖 */
+    overwrite?: boolean;
+}
+interface WalletData {
+    address: string;
+    label?: string;
+    createdAt: string;
+    encrypted: boolean;
+    /** 加密后的私钥或明文私钥 */
+    privateKey: string;
+    /** 加密用的 IV */
+    iv?: string;
+    /** 加密用的 salt */
+    salt?: string;
+}
+interface CreateWalletResult {
+    success: boolean;
+    address?: string;
+    storagePath?: string;
+    error?: string;
+    /** 是否是新创建的（false 表示加载了已有钱包） */
+    isNew?: boolean;
+}
+/**
+ * 创建新钱包
+ *
+ * @example
+ * ```typescript
+ * // 创建未加密钱包
+ * const result = await createWallet();
+ * console.log('钱包地址:', result.address);
+ *
+ * // 创建加密钱包
+ * const result = await createWallet({ password: 'mySecurePassword' });
+ *
+ * // 指定存储路径
+ * const result = await createWallet({ storagePath: './my-wallet.json' });
+ * ```
+ */
+declare function createWallet(options?: CreateWalletOptions): CreateWalletResult;
+/**
+ * 加载已有钱包
+ */
+declare function loadWallet(options?: {
+    storagePath?: string;
+    password?: string;
+}): {
+    success: boolean;
+    address?: string;
+    privateKey?: string;
+    error?: string;
+};
+/**
+ * 获取钱包地址（不需要密码）
+ */
+declare function getWalletAddress(storagePath?: string): string | null;
+/**
+ * 检查钱包是否存在
+ */
+declare function walletExists(storagePath?: string): boolean;
+
+/**
+ * PermitWallet - 使用 Boss 授权的 Permit 进行支付
+ *
+ * 场景：
+ * - Agent 没有自己的 USDC，但 Boss 给了 Permit 授权
+ * - Agent 使用 Permit 签名 + 自己的钱包执行 transferFrom
+ * - Agent 只需要少量 ETH 付 gas，USDC 从 Boss 钱包扣除
+ */
+
+interface PermitData {
+    /** Boss 的钱包地址（USDC 持有者） */
+    owner: string;
+    /** Agent 的钱包地址（被授权者） */
+    spender: string;
+    /** 授权金额（USDC，6位小数的原始值） */
+    value: string;
+    /** 过期时间戳 */
+    deadline: number;
+    /** 签名 v */
+    v: number;
+    /** 签名 r */
+    r: string;
+    /** 签名 s */
+    s: string;
+}
+interface PermitWalletConfig {
+    chain?: ChainName;
+    /** Agent 的私钥（用于执行交易） */
+    privateKey?: string;
+    /** 从文件加载私钥 */
+    walletPath?: string;
+    /** 解密密码 */
+    walletPassword?: string;
+    rpcUrl?: string;
+}
+interface TransferWithPermitParams {
+    /** 收款地址 */
+    to: string;
+    /** 金额（USDC） */
+    amount: number;
+    /** Boss 签署的 Permit 数据 */
+    permit: PermitData;
+}
+interface TransferWithPermitResult extends TransferResult {
+    /** Permit 交易 hash */
+    permitTxHash?: string;
+    /** Transfer 交易 hash */
+    transferTxHash?: string;
+}
+declare class PermitWallet {
+    readonly chain: ChainName;
+    readonly chainConfig: ChainConfig;
+    readonly address: string;
+    private wallet;
+    private provider;
+    private usdcContract;
+    constructor(config?: PermitWalletConfig);
+    /**
+     * 检查 Permit 是否有效
+     */
+    checkPermitAllowance(owner: string): Promise<string>;
+    /**
+     * 使用 Permit 授权进行支付
+     *
+     * 流程：
+     * 1. 调用 permit() 让合约记录 Boss 的授权
+     * 2. 调用 transferFrom() 从 Boss 钱包转账到收款方
+     *
+     * @example
+     * ```typescript
+     * const wallet = new PermitWallet({ chain: 'base' });
+     *
+     * // Boss 签署的 permit 数据
+     * const permit = {
+     *   owner: '0xBOSS...',
+     *   spender: wallet.address,
+     *   value: '10000000', // 10 USDC
+     *   deadline: 1234567890,
+     *   v: 27,
+     *   r: '0x...',
+     *   s: '0x...'
+     * };
+     *
+     * const result = await wallet.transferWithPermit({
+     *   to: '0xSELLER...',
+     *   amount: 3.99,
+     *   permit
+     * });
+     * ```
+     */
+    transferWithPermit(params: TransferWithPermitParams): Promise<TransferWithPermitResult>;
+    /**
+     * 获取 ETH 余额（用于支付 gas）
+     */
+    getGasBalance(): Promise<string>;
+    /**
+     * 检查是否有足够的 gas
+     */
+    hasEnoughGas(minEth?: number): Promise<boolean>;
+}
+/**
+ * 格式化 Permit 请求消息（发给 Boss）
+ */
+declare function formatPermitRequest(params: {
+    agentAddress: string;
+    amount: number;
+    deadlineHours?: number;
+    chain?: ChainName;
+    reason?: string;
+}): string;
+
+export { type CreateWalletOptions, type CreateWalletResult, type PermitData, PermitWallet, type PermitWalletConfig, SecureWallet, type TransferWithPermitParams, type TransferWithPermitResult, Wallet, type WalletConfig, type WalletData, createWallet, formatPermitRequest, getWalletAddress, loadWallet, walletExists };

package/dist/wallet/index.d.ts

@@ -102,4 +102,191 @@ declare class SecureWallet {
     private updateDailyTotal;
 }
 
-export { SecureWallet, Wallet, type WalletConfig };
+/**
+ * createWallet - 为 Agent 创建新钱包
+ *
+ * 功能：
+ * - 生成新的以太坊钱包
+ * - 安全存储私钥（加密或明文，取决于配置）
+ * - 返回钱包地址（不返回私钥）
+ */
+interface CreateWalletOptions {
+    /** 存储路径，默认 ~/.moltspay/wallet.json */
+    storagePath?: string;
+    /** 加密密码（可选，不提供则明文存储） */
+    password?: string;
+    /** 钱包标签/名称 */
+    label?: string;
+    /** 如果钱包已存在，是否覆盖 */
+    overwrite?: boolean;
+}
+interface WalletData {
+    address: string;
+    label?: string;
+    createdAt: string;
+    encrypted: boolean;
+    /** 加密后的私钥或明文私钥 */
+    privateKey: string;
+    /** 加密用的 IV */
+    iv?: string;
+    /** 加密用的 salt */
+    salt?: string;
+}
+interface CreateWalletResult {
+    success: boolean;
+    address?: string;
+    storagePath?: string;
+    error?: string;
+    /** 是否是新创建的（false 表示加载了已有钱包） */
+    isNew?: boolean;
+}
+/**
+ * 创建新钱包
+ *
+ * @example
+ * ```typescript
+ * // 创建未加密钱包
+ * const result = await createWallet();
+ * console.log('钱包地址:', result.address);
+ *
+ * // 创建加密钱包
+ * const result = await createWallet({ password: 'mySecurePassword' });
+ *
+ * // 指定存储路径
+ * const result = await createWallet({ storagePath: './my-wallet.json' });
+ * ```
+ */
+declare function createWallet(options?: CreateWalletOptions): CreateWalletResult;
+/**
+ * 加载已有钱包
+ */
+declare function loadWallet(options?: {
+    storagePath?: string;
+    password?: string;
+}): {
+    success: boolean;
+    address?: string;
+    privateKey?: string;
+    error?: string;
+};
+/**
+ * 获取钱包地址（不需要密码）
+ */
+declare function getWalletAddress(storagePath?: string): string | null;
+/**
+ * 检查钱包是否存在
+ */
+declare function walletExists(storagePath?: string): boolean;
+
+/**
+ * PermitWallet - 使用 Boss 授权的 Permit 进行支付
+ *
+ * 场景：
+ * - Agent 没有自己的 USDC，但 Boss 给了 Permit 授权
+ * - Agent 使用 Permit 签名 + 自己的钱包执行 transferFrom
+ * - Agent 只需要少量 ETH 付 gas，USDC 从 Boss 钱包扣除
+ */
+
+interface PermitData {
+    /** Boss 的钱包地址（USDC 持有者） */
+    owner: string;
+    /** Agent 的钱包地址（被授权者） */
+    spender: string;
+    /** 授权金额（USDC，6位小数的原始值） */
+    value: string;
+    /** 过期时间戳 */
+    deadline: number;
+    /** 签名 v */
+    v: number;
+    /** 签名 r */
+    r: string;
+    /** 签名 s */
+    s: string;
+}
+interface PermitWalletConfig {
+    chain?: ChainName;
+    /** Agent 的私钥（用于执行交易） */
+    privateKey?: string;
+    /** 从文件加载私钥 */
+    walletPath?: string;
+    /** 解密密码 */
+    walletPassword?: string;
+    rpcUrl?: string;
+}
+interface TransferWithPermitParams {
+    /** 收款地址 */
+    to: string;
+    /** 金额（USDC） */
+    amount: number;
+    /** Boss 签署的 Permit 数据 */
+    permit: PermitData;
+}
+interface TransferWithPermitResult extends TransferResult {
+    /** Permit 交易 hash */
+    permitTxHash?: string;
+    /** Transfer 交易 hash */
+    transferTxHash?: string;
+}
+declare class PermitWallet {
+    readonly chain: ChainName;
+    readonly chainConfig: ChainConfig;
+    readonly address: string;
+    private wallet;
+    private provider;
+    private usdcContract;
+    constructor(config?: PermitWalletConfig);
+    /**
+     * 检查 Permit 是否有效
+     */
+    checkPermitAllowance(owner: string): Promise<string>;
+    /**
+     * 使用 Permit 授权进行支付
+     *
+     * 流程：
+     * 1. 调用 permit() 让合约记录 Boss 的授权
+     * 2. 调用 transferFrom() 从 Boss 钱包转账到收款方
+     *
+     * @example
+     * ```typescript
+     * const wallet = new PermitWallet({ chain: 'base' });
+     *
+     * // Boss 签署的 permit 数据
+     * const permit = {
+     *   owner: '0xBOSS...',
+     *   spender: wallet.address,
+     *   value: '10000000', // 10 USDC
+     *   deadline: 1234567890,
+     *   v: 27,
+     *   r: '0x...',
+     *   s: '0x...'
+     * };
+     *
+     * const result = await wallet.transferWithPermit({
+     *   to: '0xSELLER...',
+     *   amount: 3.99,
+     *   permit
+     * });
+     * ```
+     */
+    transferWithPermit(params: TransferWithPermitParams): Promise<TransferWithPermitResult>;
+    /**
+     * 获取 ETH 余额（用于支付 gas）
+     */
+    getGasBalance(): Promise<string>;
+    /**
+     * 检查是否有足够的 gas
+     */
+    hasEnoughGas(minEth?: number): Promise<boolean>;
+}
+/**
+ * 格式化 Permit 请求消息（发给 Boss）
+ */
+declare function formatPermitRequest(params: {
+    agentAddress: string;
+    amount: number;
+    deadlineHours?: number;
+    chain?: ChainName;
+    reason?: string;
+}): string;
+
+export { type CreateWalletOptions, type CreateWalletResult, type PermitData, PermitWallet, type PermitWalletConfig, SecureWallet, type TransferWithPermitParams, type TransferWithPermitResult, Wallet, type WalletConfig, type WalletData, createWallet, formatPermitRequest, getWalletAddress, loadWallet, walletExists };