agentwallet-sdk 5.0.0 → 5.0.1

package/dist/mev/protection.js

@@ -0,0 +1,185 @@
+import { ethers } from 'ethers';
+import { MEVRiskAssessor } from './risk.js';
+const DEFAULTS = {
+    autoProtectAboveRisk: 'medium',
+    flashbotsRpcUrl: 'https://rpc.flashbots.net',
+    mevBlockerRpcUrl: 'https://rpc.mevblocker.io',
+    maxProtectionLatencyMs: 5000,
+    minSwapUsdForProtection: 100,
+};
+export class MEVProtection {
+    constructor(config) {
+        this.config = {
+            enabled: config.enabled,
+            autoProtectAboveRisk: config.autoProtectAboveRisk ?? DEFAULTS.autoProtectAboveRisk,
+            flashbotsRpcUrl: config.flashbotsRpcUrl ?? DEFAULTS.flashbotsRpcUrl,
+            mevBlockerRpcUrl: config.mevBlockerRpcUrl ?? DEFAULTS.mevBlockerRpcUrl,
+            maxProtectionLatencyMs: config.maxProtectionLatencyMs ?? DEFAULTS.maxProtectionLatencyMs,
+            minSwapUsdForProtection: config.minSwapUsdForProtection ?? DEFAULTS.minSwapUsdForProtection,
+        };
+        this.assessor = new MEVRiskAssessor();
+        this._createProvider = (url) => new ethers.JsonRpcProvider(url);
+    }
+    /**
+     * Assess MEV risk for a proposed swap.
+     * Fetches live gas price from provider if available.
+     */
+    async assessRisk(params) {
+        let gasPriceGwei = 20; // sensible default
+        if (params.provider) {
+            try {
+                const feeData = await params.provider.getFeeData();
+                if (feeData.gasPrice) {
+                    gasPriceGwei = Number(ethers.formatUnits(feeData.gasPrice, 'gwei'));
+                }
+            }
+            catch {
+                // fallback to default
+            }
+        }
+        return this.assessor.assess({
+            fromToken: params.fromToken,
+            toToken: params.toToken,
+            amountUsd: params.amountUsd,
+            slippageBps: params.slippageBps,
+            gasPriceGwei,
+            chain: params.chain,
+        });
+    }
+    /**
+     * Get the protected RPC URL for a given protection method.
+     */
+    getProtectedRpc(method) {
+        switch (method) {
+            case 'flashbots-protect':
+                return this.config.flashbotsRpcUrl;
+            case 'private-rpc':
+                return this.config.mevBlockerRpcUrl;
+            case 'flashbots-bundle':
+            case 'cowswap-order':
+            case 'none':
+            default:
+                return '';
+        }
+    }
+    /**
+     * Submit a signed transaction through the appropriate protected route.
+     * Main API called by SmartSwapRouter.
+     */
+    async submitProtected(params) {
+        const startTime = Date.now();
+        switch (params.assessment.recommendedMethod) {
+            case 'flashbots-protect':
+                return this.submitViaFlashbotsProtect(params.signedTx, params.provider, startTime, params.assessment);
+            case 'flashbots-bundle':
+                return this.submitViaFlashbotsBundle(params.signedTx, params.targetBlock, startTime, params.assessment);
+            case 'private-rpc':
+                return this.submitViaMEVBlocker(params.signedTx, params.provider, startTime, params.assessment);
+            default:
+                return this.submitPublic(params.signedTx, params.provider, startTime, params.assessment);
+        }
+    }
+    /**
+     * Flashbots Protect: broadcast via rpc.flashbots.net.
+     * No bundle auth required. Best for most users.
+     */
+    async submitViaFlashbotsProtect(signedTx, _provider, startTime, assessment) {
+        const protectedProvider = this._createProvider(this.config.flashbotsRpcUrl);
+        const txResponse = await protectedProvider.broadcastTransaction(signedTx);
+        const receipt = await txResponse.wait(1);
+        return {
+            success: receipt?.status === 1,
+            txHash: receipt?.hash,
+            protectionMethod: 'flashbots-protect',
+            riskAssessment: assessment,
+            mevSavedUsd: assessment.estimatedSavingsUsd,
+            blockNumber: receipt?.blockNumber,
+            latencyMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Flashbots Bundle: maximum protection for critical-risk swaps.
+     * Falls back to Flashbots Protect RPC if no bundle signing key configured.
+     */
+    async submitViaFlashbotsBundle(signedTx, targetBlock, startTime, assessment) {
+        // Full bundle submission requires a Flashbots signing key (ECDSA).
+        // Without one, we fall back to Flashbots Protect RPC which still gives
+        // strong protection for most users.
+        const protectedProvider = this._createProvider(this.config.flashbotsRpcUrl);
+        try {
+            // Attempt bundle submission via relay
+            const currentBlock = await protectedProvider.getBlockNumber();
+            const blockTarget = targetBlock ?? currentBlock + 2;
+            const blockHex = `0x${blockTarget.toString(16)}`;
+            const response = await fetch('https://relay.flashbots.net', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'eth_sendBundle',
+                    params: [{ txs: [signedTx], blockNumber: blockHex }],
+                }),
+            });
+            if (response.ok) {
+                const json = await response.json();
+                const bundleHash = json.result?.bundleHash;
+                return {
+                    success: true,
+                    protectionMethod: 'flashbots-bundle',
+                    bundleHash,
+                    riskAssessment: assessment,
+                    mevSavedUsd: assessment.estimatedSavingsUsd,
+                    latencyMs: Date.now() - startTime,
+                };
+            }
+        }
+        catch {
+            // Bundle submission failed — fall through to Protect RPC fallback
+        }
+        // Fallback: broadcast via Flashbots Protect RPC
+        const txResponse = await protectedProvider.broadcastTransaction(signedTx);
+        const receipt = await txResponse.wait(1);
+        return {
+            success: receipt?.status === 1,
+            txHash: receipt?.hash,
+            protectionMethod: 'flashbots-bundle',
+            riskAssessment: assessment,
+            mevSavedUsd: assessment.estimatedSavingsUsd,
+            blockNumber: receipt?.blockNumber,
+            latencyMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * MEV Blocker: alternative private RPC by CoW Protocol.
+     */
+    async submitViaMEVBlocker(signedTx, _provider, startTime, assessment) {
+        const mevBlockerProvider = this._createProvider(this.config.mevBlockerRpcUrl);
+        const txResponse = await mevBlockerProvider.broadcastTransaction(signedTx);
+        const receipt = await txResponse.wait(1);
+        return {
+            success: receipt?.status === 1,
+            txHash: receipt?.hash,
+            protectionMethod: 'private-rpc',
+            riskAssessment: assessment,
+            mevSavedUsd: assessment.estimatedSavingsUsd,
+            blockNumber: receipt?.blockNumber,
+            latencyMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Public mempool fallback for low-risk swaps.
+     */
+    async submitPublic(signedTx, provider, startTime, assessment) {
+        const txResponse = await provider.broadcastTransaction(signedTx);
+        const receipt = await txResponse.wait(1);
+        return {
+            success: receipt?.status === 1,
+            txHash: receipt?.hash,
+            protectionMethod: 'none',
+            riskAssessment: assessment,
+            latencyMs: Date.now() - startTime,
+        };
+    }
+}
+//# sourceMappingURL=protection.js.map

package/dist/mev/protection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protection.js","sourceRoot":"","sources":["../../src/mev/protection.ts"],"names":[],"mappings":"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"}

package/dist/mev/risk.d.ts

@@ -0,0 +1,19 @@
+import type { MEVRiskAssessment } from './types.js';
+/** Deterministic MEV risk scorer — no external calls required */
+export declare class MEVRiskAssessor {
+    /**
+     * Assess MEV risk for a proposed swap.
+     * Scoring model produces a 0-100 risk score mapped to a risk level.
+     */
+    assess(params: {
+        fromToken: string;
+        toToken: string;
+        amountUsd: number;
+        slippageBps: number;
+        gasPriceGwei: number;
+        chain: string;
+    }): MEVRiskAssessment;
+    /** Check if a token pair is "popular" (highly watched by MEV bots) */
+    isPopularPair(fromToken: string, toToken: string): boolean;
+}
+//# sourceMappingURL=risk.d.ts.map

package/dist/mev/risk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../../src/mev/risk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAkC,MAAM,YAAY,CAAC;AAOpF,iEAAiE;AACjE,qBAAa,eAAe;IAC1B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB;IA6ErB,sEAAsE;IACtE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;CAG3D"}

package/dist/mev/risk.js

@@ -0,0 +1,95 @@
+/** Popular tokens that are heavily watched by MEV bots */
+const POPULAR_TOKENS = new Set([
+    'ETH', 'WETH', 'USDC', 'USDT', 'DAI', 'WBTC', 'SOL', 'WSOL',
+]);
+/** Deterministic MEV risk scorer — no external calls required */
+export class MEVRiskAssessor {
+    /**
+     * Assess MEV risk for a proposed swap.
+     * Scoring model produces a 0-100 risk score mapped to a risk level.
+     */
+    assess(params) {
+        const { fromToken, toToken, amountUsd, slippageBps, gasPriceGwei, chain } = params;
+        let score = 0;
+        // 1. Size risk
+        if (amountUsd >= 10000)
+            score += 40;
+        else if (amountUsd >= 1000)
+            score += 20;
+        else if (amountUsd >= 100)
+            score += 10;
+        // < $100 = 0 pts
+        // 2. Slippage risk (high slippage = easy sandwich)
+        if (slippageBps > 200)
+            score += 20;
+        else if (slippageBps >= 50)
+            score += 10;
+        // 3. Popular pair risk (heavily watched by bots)
+        if (this.isPopularPair(fromToken, toToken))
+            score += 15;
+        // 4. Gas spike risk (high gas = bots are active)
+        if (gasPriceGwei > 100)
+            score += 25;
+        else if (gasPriceGwei > 50)
+            score += 15;
+        // 5. Chain risk
+        const chainLower = chain.toLowerCase();
+        if (chainLower === 'ethereum' || chainLower === 'mainnet')
+            score += 10;
+        else if (chainLower === 'arbitrum')
+            score += 5;
+        else if (chainLower === 'base')
+            score += 3;
+        // Cap at 100
+        score = Math.min(100, score);
+        // Map score to risk level
+        let riskLevel;
+        if (score >= 76)
+            riskLevel = 'critical';
+        else if (score >= 51)
+            riskLevel = 'high';
+        else if (score >= 26)
+            riskLevel = 'medium';
+        else
+            riskLevel = 'low';
+        // Recommended method by risk level
+        let recommendedMethod;
+        if (riskLevel === 'critical')
+            recommendedMethod = 'flashbots-bundle';
+        else if (riskLevel === 'high')
+            recommendedMethod = 'flashbots-protect';
+        else if (riskLevel === 'medium')
+            recommendedMethod = 'private-rpc';
+        else
+            recommendedMethod = 'none';
+        // Estimated savings: risk-weighted sandwich loss model
+        // ~0.5-2% of swap size; simplified: amountUsd * riskScore/100 * 0.01
+        const estimatedSavingsUsd = amountUsd * (score / 100) * 0.01;
+        // Derive factor labels
+        const gasPrice = gasPriceGwei > 100 ? 'spike' :
+            gasPriceGwei > 50 ? 'high' :
+                gasPriceGwei > 20 ? 'normal' : 'low';
+        const tokenPairLiquidity = this.isPopularPair(fromToken, toToken) ? 'high' : 'low';
+        const marketVolatility = gasPriceGwei > 100 ? 'extreme' :
+            gasPriceGwei > 50 ? 'volatile' : 'stable';
+        return {
+            riskLevel,
+            riskScore: score,
+            factors: {
+                swapSizeUsd: amountUsd,
+                slippageBps,
+                tokenPairLiquidity,
+                marketVolatility,
+                gasPrice,
+                isPopularPair: this.isPopularPair(fromToken, toToken),
+            },
+            recommendedMethod,
+            estimatedSavingsUsd,
+        };
+    }
+    /** Check if a token pair is "popular" (highly watched by MEV bots) */
+    isPopularPair(fromToken, toToken) {
+        return POPULAR_TOKENS.has(fromToken.toUpperCase()) && POPULAR_TOKENS.has(toToken.toUpperCase());
+    }
+}
+//# sourceMappingURL=risk.js.map

package/dist/mev/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../../src/mev/risk.ts"],"names":[],"mappings":"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"}

package/dist/mev/types.d.ts

@@ -0,0 +1,49 @@
+export type MEVRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export type ProtectionMethod = 'flashbots-protect' | 'flashbots-bundle' | 'cowswap-order' | 'private-rpc' | 'none';
+export interface MEVRiskAssessment {
+    riskLevel: MEVRiskLevel;
+    riskScore: number;
+    factors: {
+        swapSizeUsd: number;
+        slippageBps: number;
+        tokenPairLiquidity: 'high' | 'medium' | 'low';
+        marketVolatility: 'stable' | 'volatile' | 'extreme';
+        gasPrice: 'low' | 'normal' | 'high' | 'spike';
+        isPopularPair: boolean;
+    };
+    recommendedMethod: ProtectionMethod;
+    estimatedSavingsUsd: number;
+}
+export interface MEVProtectionConfig {
+    enabled: boolean;
+    /** Risk threshold above which protection is auto-applied */
+    autoProtectAboveRisk?: MEVRiskLevel;
+    /** Flashbots RPC endpoint */
+    flashbotsRpcUrl?: string;
+    /** MEV Blocker RPC (alternative) */
+    mevBlockerRpcUrl?: string;
+    /** Max extra latency accepted for protection (ms) */
+    maxProtectionLatencyMs?: number;
+    /** Minimum swap USD value to trigger protection */
+    minSwapUsdForProtection?: number;
+}
+export interface ProtectedSwapResult {
+    success: boolean;
+    txHash?: string;
+    protectionMethod: ProtectionMethod;
+    bundleHash?: string;
+    riskAssessment: MEVRiskAssessment;
+    /** Gas saved vs public mempool (estimated) */
+    gasSavedGwei?: number;
+    /** MEV loss avoided (estimated USD) */
+    mevSavedUsd?: number;
+    blockNumber?: number;
+    latencyMs: number;
+}
+export interface FlashbotsBundle {
+    transactions: string[];
+    blockNumber: string;
+    minTimestamp?: number;
+    maxTimestamp?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mev/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mev/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAElE,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;QAC9C,gBAAgB,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;QACpD,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;QAC9C,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,YAAY,CAAC;IACpC,6BAA6B;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,iBAAiB,CAAC;IAClC,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/mev/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mev/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mev/types.ts"],"names":[],"mappings":""}

package/dist/plugins/elizaos.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @elizaos/plugin-agentwallet
+ *
+ * ElizaOS plugin for agentwallet-sdk — non-custodial AI agent wallet with
+ * x402 payment support, CCTP V2 cross-chain transfers, and on-chain spend limits.
+ *
+ * Your agent holds its own private key. No custodian. No KYC.
+ */
+import type { Plugin } from '@elizaos/core';
+import { createWallet } from '../index.js';
+type AgentWallet = ReturnType<typeof createWallet>;
+export interface AgentWalletPluginConfig {
+    /** Agent private key — stays in your environment, never transmitted */
+    privateKey: `0x${string}`;
+    /** Deployed AgentAccountV2 contract address */
+    accountAddress: `0x${string}`;
+    /** Chain to connect to (default: 'base') */
+    chain?: 'base' | 'base-sepolia' | 'ethereum' | 'arbitrum' | 'polygon' | 'etherlink';
+    /** Optional custom RPC URL */
+    rpcUrl?: string;
+    /** Optional daily x402 spend limit in USDC base units (default: 50 USDC = 50_000_000n) */
+    x402DailyLimit?: bigint;
+}
+/**
+ * Get or create the agent wallet singleton.
+ */
+export declare function getAgentWallet(config: AgentWalletPluginConfig): AgentWallet;
+/**
+ * Create an x402-enabled fetch function for the agent to pay APIs automatically.
+ */
+export declare function createAgentFetch(config: AgentWalletPluginConfig): typeof fetch;
+/**
+ * ElizaOS Plugin definition for agentwallet-sdk.
+ *
+ * Usage in your Eliza character config:
+ *
+ * ```json
+ * {
+ *   "plugins": ["@elizaos/plugin-agentwallet"],
+ *   "settings": {
+ *     "AGENT_PRIVATE_KEY": "0x...",
+ *     "AGENT_ACCOUNT_ADDRESS": "0x...",
+ *     "AGENT_CHAIN": "base",
+ *     "X402_DAILY_LIMIT": "50000000"
+ *   }
+ * }
+ * ```
+ */
+declare const AgentWalletPlugin: Plugin;
+export default AgentWalletPlugin;
+export { AgentWalletPlugin };
+//# sourceMappingURL=elizaos.d.ts.map

package/dist/plugins/elizaos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elizaos.d.ts","sourceRoot":"","sources":["../../src/plugins/elizaos.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,YAAY,EAGb,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAInD,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,UAAU,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACpF,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,WAAW,CAuB3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,gBAK/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,iBAAiB,EAAE,MAiCxB,CAAC;AAEF,eAAe,iBAAiB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/plugins/elizaos.js

@@ -0,0 +1,89 @@
+import { createWallet, createX402Fetch, } from '../index.js';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+let walletInstance = null;
+/**
+ * Get or create the agent wallet singleton.
+ */
+export function getAgentWallet(config) {
+    if (!walletInstance) {
+        const account = privateKeyToAccount(config.privateKey);
+        const rpcUrls = {
+            base: 'https://mainnet.base.org',
+            'base-sepolia': 'https://sepolia.base.org',
+            ethereum: 'https://eth.llamarpc.com',
+            arbitrum: 'https://arb1.arbitrum.io/rpc',
+            polygon: 'https://polygon-rpc.com',
+            etherlink: 'https://node.mainnet.etherlink.com',
+        };
+        const chain = config.chain ?? 'base';
+        const walletClient = createWalletClient({
+            account,
+            transport: http(config.rpcUrl ?? rpcUrls[chain] ?? rpcUrls.base),
+        });
+        walletInstance = createWallet({
+            accountAddress: config.accountAddress,
+            chain,
+            walletClient,
+        });
+    }
+    return walletInstance;
+}
+/**
+ * Create an x402-enabled fetch function for the agent to pay APIs automatically.
+ */
+export function createAgentFetch(config) {
+    const wallet = getAgentWallet(config);
+    return createX402Fetch(wallet, {
+        globalDailyLimit: config.x402DailyLimit ?? 50000000n, // 50 USDC default
+    });
+}
+/**
+ * ElizaOS Plugin definition for agentwallet-sdk.
+ *
+ * Usage in your Eliza character config:
+ *
+ * ```json
+ * {
+ *   "plugins": ["@elizaos/plugin-agentwallet"],
+ *   "settings": {
+ *     "AGENT_PRIVATE_KEY": "0x...",
+ *     "AGENT_ACCOUNT_ADDRESS": "0x...",
+ *     "AGENT_CHAIN": "base",
+ *     "X402_DAILY_LIMIT": "50000000"
+ *   }
+ * }
+ * ```
+ */
+const AgentWalletPlugin = {
+    name: '@elizaos/plugin-agentwallet',
+    description: 'Non-custodial agent wallet for ElizaOS — x402 payments, CCTP cross-chain, on-chain spend limits. Agent holds its own keys.',
+    actions: [],
+    providers: [
+        {
+            name: 'agentWallet',
+            description: 'Provides agent wallet and x402 fetch capability to the runtime',
+            async get(runtime) {
+                const privateKey = runtime.getSetting('AGENT_PRIVATE_KEY');
+                const accountAddress = runtime.getSetting('AGENT_ACCOUNT_ADDRESS');
+                const chain = (runtime.getSetting('AGENT_CHAIN') ?? 'base');
+                const dailyLimitStr = runtime.getSetting('X402_DAILY_LIMIT');
+                const x402DailyLimit = dailyLimitStr ? BigInt(dailyLimitStr) : 50000000n;
+                if (!privateKey || !accountAddress) {
+                    return 'AgentWallet not configured: AGENT_PRIVATE_KEY and AGENT_ACCOUNT_ADDRESS required.';
+                }
+                const config = { privateKey, accountAddress, chain, x402DailyLimit };
+                const wallet = getAgentWallet(config);
+                const x402Fetch = createAgentFetch(config);
+                // Expose on runtime for actions to use
+                runtime.agentWallet = wallet;
+                runtime.x402Fetch = x402Fetch;
+                return `AgentWallet ready — non-custodial, keys stay local. Chain: ${chain}. x402 daily limit: ${x402DailyLimit / 1000000n} USDC.`;
+            },
+        },
+    ],
+    evaluators: [],
+};
+export default AgentWalletPlugin;
+export { AgentWalletPlugin };
+//# sourceMappingURL=elizaos.js.map

package/dist/plugins/elizaos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elizaos.js","sourceRoot":"","sources":["../../src/plugins/elizaos.ts"],"names":[],"mappings":"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"}

package/dist/policy/SpendingPolicy.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SpendingPolicy — Programmable spending guardrails for AI agents.
+ *
+ * Beats PolicyLayer.com to market with:
+ *   - MerchantAllowlist  — allowlist-only merchant enforcement
+ *   - RollingSpendCap    — time-windowed spend limits
+ *   - DraftThenApprove   — human-in-the-loop for large transactions
+ *   - AuditTrail         — immutable local log of every payment attempt
+ *   - FailClosed         — policy errors always reject, never approve
+ *
+ * @module policy/SpendingPolicy
+ */
+/** A payment the agent wants to make. */
+export interface PaymentIntent {
+    /** Merchant contract address or domain (e.g. "0xABC..." or "api.example.com") */
+    merchant: string;
+    /** Amount in the smallest token unit (e.g. USDC micro-cents = 6 decimals). Use number for JS safety in tests; real on-chain code passes BigInt via adapter. */
+    amount: number;
+    /** ISO-8601 timestamp string. Defaults to now if omitted. */
+    timestamp?: string;
+    /** Optional human-readable label */
+    description?: string;
+}
+export type PolicyStatus = 'approved' | 'rejected' | 'draft';
+/** Result returned by SpendingPolicy.check(). */
+export interface PolicyResult {
+    status: PolicyStatus;
+    reason?: string;
+    draftId?: string;
+}
+/** A queued draft transaction awaiting approval. */
+export interface DraftEntry {
+    draftId: string;
+    payment: PaymentIntent;
+    queuedAt: string;
+    approved: boolean;
+    rejected: boolean;
+}
+/** Immutable record written to the audit log. */
+export interface AuditEntry {
+    id: string;
+    timestamp: string;
+    merchant: string;
+    amount: number;
+    status: PolicyStatus;
+    reason?: string;
+    draftId?: string;
+}
+/** Configuration passed to SpendingPolicy constructor. */
+export interface SpendingPolicyConfig {
+    /**
+     * MerchantAllowlist: list of allowed contract addresses or domains.
+     * If provided and non-empty, only these merchants are allowed.
+     * Pass an empty array [] to disable allowlist enforcement (allow all).
+     */
+    merchantAllowlist?: string[];
+    /**
+     * RollingSpendCap: maximum cumulative spend in a rolling time window.
+     * Set to undefined to disable.
+     */
+    rollingCap?: {
+        /** Max amount (same units as PaymentIntent.amount) */
+        maxAmount: number;
+        /** Window size in milliseconds (e.g. 86_400_000 for 24 h) */
+        windowMs: number;
+    };
+    /**
+     * DraftThenApprove: payments above this threshold are placed in draft status
+     * for human (or another agent) approval rather than executed immediately.
+     * Set to undefined to disable.
+     */
+    draftThreshold?: number;
+}
+export declare class SpendingPolicy {
+    private config;
+    private allowlist;
+    private spendWindow;
+    private auditLog;
+    private drafts;
+    constructor(config: SpendingPolicyConfig);
+    /**
+     * FailClosed: wraps the actual check logic so that ANY unhandled error
+     * produces a rejection rather than inadvertently approving a payment.
+     */
+    check(payment: PaymentIntent): Promise<PolicyResult>;
+    /**
+     * Write a payment attempt to the immutable audit log.
+     */
+    log(payment: PaymentIntent, result: PolicyResult): Promise<void>;
+    /** Return a copy of the current merchant allowlist. */
+    getMerchantAllowlist(): string[];
+    /** Add a merchant address/domain to the allowlist at runtime. */
+    addMerchant(address: string): void;
+    /** Return the full, immutable audit log (copy). */
+    getAuditLog(): AuditEntry[];
+    /** Approve a queued draft by its draftId. Returns false if not found. */
+    approveDraft(draftId: string): boolean;
+    /** Reject a queued draft by its draftId. Returns false if not found. */
+    rejectDraft(draftId: string): boolean;
+    /** Return all pending (not yet approved or rejected) drafts. */
+    getPendingDrafts(): DraftEntry[];
+    /** Return all drafts. */
+    getAllDrafts(): DraftEntry[];
+    private _check;
+}
+//# sourceMappingURL=SpendingPolicy.d.ts.map

package/dist/policy/SpendingPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendingPolicy.d.ts","sourceRoot":"","sources":["../../src/policy/SpendingPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,+JAA+J;IAC/J,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAE7D,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,UAAU,CAAC,EAAE;QACX,sDAAsD;QACtD,SAAS,EAAE,MAAM,CAAC;QAClB,6DAA6D;QAC7D,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,WAAW,CAAwC;IAC3D,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,MAAM,CAA0B;gBAE5B,MAAM,EAAE,oBAAoB;IAYxC;;;OAGG;IACG,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAW1D;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAatE,uDAAuD;IACvD,oBAAoB,IAAI,MAAM,EAAE;IAIhC,iEAAiE;IACjE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlC,mDAAmD;IACnD,WAAW,IAAI,UAAU,EAAE;IAM3B,yEAAyE;IACzE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOtC,wEAAwE;IACxE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOrC,gEAAgE;IAChE,gBAAgB,IAAI,UAAU,EAAE;IAMhC,yBAAyB;IACzB,YAAY,IAAI,UAAU,EAAE;YAMd,MAAM;CAmErB"}