moltspay 0.2.2 → 0.2.4

package/dist/wallet/index.d.mts

@@ -289,4 +289,203 @@ declare function formatPermitRequest(params: {
     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 };
+/**
+ * signPermit - Agent signs EIP-2612 Permit to authorize another address to spend USDC
+ *
+ * Used for Agent-to-Agent payments where the client agent authorizes
+ * the service provider to pull payment.
+ */
+
+interface SignPermitParams {
+    /** Spender address (service provider's wallet) */
+    spender: string;
+    /** Amount in USDC (e.g., 0.99) */
+    amount: number;
+    /** Deadline timestamp (Unix seconds) or minutes from now if < 1000000 */
+    deadline?: number;
+}
+interface SignPermitResult {
+    /** Permit owner (signer's address) */
+    owner: string;
+    /** Authorized spender */
+    spender: string;
+    /** Authorized amount (raw, 6 decimals) */
+    value: string;
+    /** Expiration timestamp */
+    deadline: number;
+    /** Nonce used */
+    nonce: number;
+    /** Signature v */
+    v: number;
+    /** Signature r */
+    r: string;
+    /** Signature s */
+    s: string;
+}
+interface SignPermitConfig {
+    chain?: ChainName;
+    privateKey?: string;
+    rpcUrl?: string;
+}
+/**
+ * Sign an EIP-2612 Permit
+ *
+ * @example
+ * ```typescript
+ * import { signPermit } from 'moltspay';
+ *
+ * const permit = await signPermit(
+ *   { chain: 'base', privateKey: process.env.WALLET_KEY },
+ *   {
+ *     spender: '0xZen7Wallet...',
+ *     amount: 0.99,
+ *     deadline: 30  // 30 minutes from now
+ *   }
+ * );
+ *
+ * // Send permit to service provider
+ * await fetch('https://service/api/pay', {
+ *   body: JSON.stringify({ permit })
+ * });
+ * ```
+ */
+declare function signPermit(config: SignPermitConfig, params: SignPermitParams): Promise<SignPermitResult>;
+/**
+ * Convenient class method version
+ */
+declare class PermitSigner {
+    private config;
+    constructor(config: SignPermitConfig);
+    sign(params: SignPermitParams): Promise<SignPermitResult>;
+}
+
+/**
+ * AllowanceWallet - Agent spends from Owner's wallet using Permit allowance
+ *
+ * This is the recommended pattern for AI Agents:
+ * 1. Owner signs EIP-2612 Permit in MetaMask (off-chain, no gas)
+ * 2. Owner sends Permit data to Agent
+ * 3. Agent stores Permit and spends within the allowance
+ * 4. Agent only needs minimal ETH for gas, USDC stays in Owner's wallet
+ *
+ * Benefits:
+ * - Agent never holds significant funds
+ * - Owner maintains custody of USDC
+ * - Owner can revoke by spending/transferring USDC
+ * - Clear audit trail of Agent spending
+ */
+
+interface OwnerPermit {
+    /** Owner's wallet address (USDC holder, e.g., MetaMask) */
+    owner: string;
+    /** Authorized amount (raw, 6 decimals for USDC) */
+    value: string;
+    /** Expiration timestamp (Unix seconds) */
+    deadline: number;
+    /** Nonce used when signing */
+    nonce: number;
+    /** Signature components */
+    v: number;
+    r: string;
+    s: string;
+}
+interface AllowanceWalletConfig {
+    chain?: ChainName;
+    /** Agent's private key (only for gas, not for USDC) */
+    privateKey: string;
+    rpcUrl?: string;
+}
+interface SpendParams {
+    /** Recipient address (e.g., service provider) */
+    to: string;
+    /** Amount in USDC */
+    amount: number;
+    /** Owner's Permit (if not yet submitted on-chain) */
+    permit?: OwnerPermit;
+}
+interface SpendResult {
+    success: boolean;
+    txHash?: string;
+    error?: string;
+    from: string;
+    to: string;
+    amount: number;
+    remainingAllowance?: string;
+    explorerUrl?: string;
+}
+interface AllowanceStatus {
+    owner: string;
+    agent: string;
+    allowance: string;
+    ownerBalance: string;
+    agentGasBalance: string;
+    canSpend: boolean;
+    chain: string;
+}
+declare class AllowanceWallet {
+    readonly chain: ChainName;
+    readonly chainConfig: ChainConfig;
+    readonly address: string;
+    private wallet;
+    private provider;
+    private usdcContract;
+    /** Stored permits from owners */
+    private permits;
+    constructor(config: AllowanceWalletConfig);
+    /**
+     * Store a Permit received from Owner
+     * Call this when Owner sends you a signed Permit
+     */
+    storePermit(permit: OwnerPermit): void;
+    /**
+     * Get stored Permit for an owner
+     */
+    getPermit(owner: string): OwnerPermit | undefined;
+    /**
+     * Check allowance status with an owner
+     */
+    checkAllowance(owner: string): Promise<AllowanceStatus>;
+    /**
+     * Spend from Owner's wallet using Permit allowance
+     *
+     * @example
+     * ```typescript
+     * const agent = new AllowanceWallet({
+     *   chain: 'base',
+     *   privateKey: process.env.AGENT_KEY  // Only needs gas
+     * });
+     *
+     * // Owner gave us a Permit
+     * agent.storePermit(ownerPermit);
+     *
+     * // Spend to pay for a service
+     * const result = await agent.spend({
+     *   to: '0xServiceProvider...',
+     *   amount: 2.99,
+     * });
+     * ```
+     */
+    spend(params: SpendParams): Promise<SpendResult>;
+    /**
+     * Get Agent's gas balance (ETH)
+     */
+    getGasBalance(): Promise<string>;
+}
+/**
+ * Generate instructions for Owner to sign a Permit in MetaMask
+ *
+ * Owner can use this with eth_signTypedData_v4 in any web3 wallet
+ */
+declare function generatePermitInstructions(params: {
+    ownerAddress: string;
+    agentAddress: string;
+    amount: number;
+    deadlineHours?: number;
+    chain?: ChainName;
+}): {
+    instructions: string;
+    typedData: object;
+    eip712Domain: object;
+};
+
+export { type AllowanceStatus, AllowanceWallet, type AllowanceWalletConfig, type CreateWalletOptions, type CreateWalletResult, type OwnerPermit, type PermitData, PermitSigner, PermitWallet, type PermitWalletConfig, SecureWallet, type SignPermitConfig, type SignPermitParams, type SignPermitResult, type SpendParams, type SpendResult, type TransferWithPermitParams, type TransferWithPermitResult, Wallet, type WalletConfig, type WalletData, createWallet, formatPermitRequest, generatePermitInstructions, getWalletAddress, loadWallet, signPermit, walletExists };

package/dist/wallet/index.d.ts

@@ -289,4 +289,203 @@ declare function formatPermitRequest(params: {
     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 };
+/**
+ * signPermit - Agent signs EIP-2612 Permit to authorize another address to spend USDC
+ *
+ * Used for Agent-to-Agent payments where the client agent authorizes
+ * the service provider to pull payment.
+ */
+
+interface SignPermitParams {
+    /** Spender address (service provider's wallet) */
+    spender: string;
+    /** Amount in USDC (e.g., 0.99) */
+    amount: number;
+    /** Deadline timestamp (Unix seconds) or minutes from now if < 1000000 */
+    deadline?: number;
+}
+interface SignPermitResult {
+    /** Permit owner (signer's address) */
+    owner: string;
+    /** Authorized spender */
+    spender: string;
+    /** Authorized amount (raw, 6 decimals) */
+    value: string;
+    /** Expiration timestamp */
+    deadline: number;
+    /** Nonce used */
+    nonce: number;
+    /** Signature v */
+    v: number;
+    /** Signature r */
+    r: string;
+    /** Signature s */
+    s: string;
+}
+interface SignPermitConfig {
+    chain?: ChainName;
+    privateKey?: string;
+    rpcUrl?: string;
+}
+/**
+ * Sign an EIP-2612 Permit
+ *
+ * @example
+ * ```typescript
+ * import { signPermit } from 'moltspay';
+ *
+ * const permit = await signPermit(
+ *   { chain: 'base', privateKey: process.env.WALLET_KEY },
+ *   {
+ *     spender: '0xZen7Wallet...',
+ *     amount: 0.99,
+ *     deadline: 30  // 30 minutes from now
+ *   }
+ * );
+ *
+ * // Send permit to service provider
+ * await fetch('https://service/api/pay', {
+ *   body: JSON.stringify({ permit })
+ * });
+ * ```
+ */
+declare function signPermit(config: SignPermitConfig, params: SignPermitParams): Promise<SignPermitResult>;
+/**
+ * Convenient class method version
+ */
+declare class PermitSigner {
+    private config;
+    constructor(config: SignPermitConfig);
+    sign(params: SignPermitParams): Promise<SignPermitResult>;
+}
+
+/**
+ * AllowanceWallet - Agent spends from Owner's wallet using Permit allowance
+ *
+ * This is the recommended pattern for AI Agents:
+ * 1. Owner signs EIP-2612 Permit in MetaMask (off-chain, no gas)
+ * 2. Owner sends Permit data to Agent
+ * 3. Agent stores Permit and spends within the allowance
+ * 4. Agent only needs minimal ETH for gas, USDC stays in Owner's wallet
+ *
+ * Benefits:
+ * - Agent never holds significant funds
+ * - Owner maintains custody of USDC
+ * - Owner can revoke by spending/transferring USDC
+ * - Clear audit trail of Agent spending
+ */
+
+interface OwnerPermit {
+    /** Owner's wallet address (USDC holder, e.g., MetaMask) */
+    owner: string;
+    /** Authorized amount (raw, 6 decimals for USDC) */
+    value: string;
+    /** Expiration timestamp (Unix seconds) */
+    deadline: number;
+    /** Nonce used when signing */
+    nonce: number;
+    /** Signature components */
+    v: number;
+    r: string;
+    s: string;
+}
+interface AllowanceWalletConfig {
+    chain?: ChainName;
+    /** Agent's private key (only for gas, not for USDC) */
+    privateKey: string;
+    rpcUrl?: string;
+}
+interface SpendParams {
+    /** Recipient address (e.g., service provider) */
+    to: string;
+    /** Amount in USDC */
+    amount: number;
+    /** Owner's Permit (if not yet submitted on-chain) */
+    permit?: OwnerPermit;
+}
+interface SpendResult {
+    success: boolean;
+    txHash?: string;
+    error?: string;
+    from: string;
+    to: string;
+    amount: number;
+    remainingAllowance?: string;
+    explorerUrl?: string;
+}
+interface AllowanceStatus {
+    owner: string;
+    agent: string;
+    allowance: string;
+    ownerBalance: string;
+    agentGasBalance: string;
+    canSpend: boolean;
+    chain: string;
+}
+declare class AllowanceWallet {
+    readonly chain: ChainName;
+    readonly chainConfig: ChainConfig;
+    readonly address: string;
+    private wallet;
+    private provider;
+    private usdcContract;
+    /** Stored permits from owners */
+    private permits;
+    constructor(config: AllowanceWalletConfig);
+    /**
+     * Store a Permit received from Owner
+     * Call this when Owner sends you a signed Permit
+     */
+    storePermit(permit: OwnerPermit): void;
+    /**
+     * Get stored Permit for an owner
+     */
+    getPermit(owner: string): OwnerPermit | undefined;
+    /**
+     * Check allowance status with an owner
+     */
+    checkAllowance(owner: string): Promise<AllowanceStatus>;
+    /**
+     * Spend from Owner's wallet using Permit allowance
+     *
+     * @example
+     * ```typescript
+     * const agent = new AllowanceWallet({
+     *   chain: 'base',
+     *   privateKey: process.env.AGENT_KEY  // Only needs gas
+     * });
+     *
+     * // Owner gave us a Permit
+     * agent.storePermit(ownerPermit);
+     *
+     * // Spend to pay for a service
+     * const result = await agent.spend({
+     *   to: '0xServiceProvider...',
+     *   amount: 2.99,
+     * });
+     * ```
+     */
+    spend(params: SpendParams): Promise<SpendResult>;
+    /**
+     * Get Agent's gas balance (ETH)
+     */
+    getGasBalance(): Promise<string>;
+}
+/**
+ * Generate instructions for Owner to sign a Permit in MetaMask
+ *
+ * Owner can use this with eth_signTypedData_v4 in any web3 wallet
+ */
+declare function generatePermitInstructions(params: {
+    ownerAddress: string;
+    agentAddress: string;
+    amount: number;
+    deadlineHours?: number;
+    chain?: ChainName;
+}): {
+    instructions: string;
+    typedData: object;
+    eip712Domain: object;
+};
+
+export { type AllowanceStatus, AllowanceWallet, type AllowanceWalletConfig, type CreateWalletOptions, type CreateWalletResult, type OwnerPermit, type PermitData, PermitSigner, PermitWallet, type PermitWalletConfig, SecureWallet, type SignPermitConfig, type SignPermitParams, type SignPermitResult, type SpendParams, type SpendResult, type TransferWithPermitParams, type TransferWithPermitResult, Wallet, type WalletConfig, type WalletData, createWallet, formatPermitRequest, generatePermitInstructions, getWalletAddress, loadWallet, signPermit, walletExists };