agentpay-mcp 1.2.0 → 3.1.0

package/dist/tools/x402.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.x402PayTool = exports.X402PaySchema = void 0;
+exports.handleX402Pay = handleX402Pay;
+/**
+ * x402.ts — x402_pay tool.
+ *
+ * Fetches a URL, automatically handling 402 Payment Required responses
+ * by paying with the Agent Wallet and retrying the request.
+ *
+ * v1.1.0: Auto-session detection. If an active x402 V2 session covers the
+ * requested URL, session headers are injected and no new payment is made.
+ * Pass skip_session_check=true to force a fresh payment regardless.
+ */
+const zod_1 = require("zod");
+const agentwallet_sdk_1 = require("agentwallet-sdk");
+const client_js_1 = require("../utils/client.js");
+const format_js_1 = require("../utils/format.js");
+const session_js_1 = require("./session.js");
+const manager_js_1 = require("../session/manager.js");
+// ─── Schema ────────────────────────────────────────────────────────────────
+exports.X402PaySchema = zod_1.z.object({
+    url: zod_1.z
+        .string()
+        .url()
+        .describe('URL to fetch. If it returns HTTP 402, payment is handled automatically.'),
+    method: zod_1.z
+        .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+        .optional()
+        .default('GET')
+        .describe('HTTP method (default: GET)'),
+    headers: zod_1.z
+        .record(zod_1.z.string())
+        .optional()
+        .describe('Additional HTTP request headers as key-value pairs'),
+    body: zod_1.z
+        .string()
+        .optional()
+        .describe('Request body (for POST/PUT/PATCH). Use JSON string for JSON APIs.'),
+    max_payment_eth: zod_1.z
+        .string()
+        .optional()
+        .describe('Maximum ETH equivalent to pay for this request. ' +
+        'Rejects the payment if the required amount exceeds this. ' +
+        'E.g. "0.001" to cap at 0.001 ETH.'),
+    timeout_ms: zod_1.z
+        .number()
+        .int()
+        .min(1000)
+        .max(60000)
+        .optional()
+        .default(30000)
+        .describe('Request timeout in milliseconds (default: 30000, max: 60000)'),
+    skip_session_check: zod_1.z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Skip auto-session detection and always make a fresh x402 payment. ' +
+        'Default: false. When false, if an active session covers this URL, ' +
+        'the session token is used instead of paying again (x402 V2 behaviour).'),
+});
+// ─── Tool definition ───────────────────────────────────────────────────────
+exports.x402PayTool = {
+    name: 'x402_pay',
+    description: 'Fetch a URL and automatically handle HTTP 402 Payment Required responses. ' +
+        'If an active x402 V2 session covers this URL, the session token is used instead ' +
+        'of making a new payment (no on-chain cost). ' +
+        'If no session exists, the Agent Wallet pays the required amount and retries. ' +
+        'Payment is rejected if it exceeds your wallet\'s spend limits or the max_payment_eth cap. ' +
+        'Powered by the x402 protocol on Base network. ' +
+        'Tip: Use x402_session_start to pay once for a session and save on repeated calls.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: {
+                type: 'string',
+                description: 'URL to fetch (HTTP 402 responses are handled automatically)',
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+                description: 'HTTP method (default: GET)',
+                default: 'GET',
+            },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'Additional request headers',
+            },
+            body: {
+                type: 'string',
+                description: 'Request body string (for POST/PUT/PATCH)',
+            },
+            max_payment_eth: {
+                type: 'string',
+                description: 'Maximum payment cap in ETH (e.g. "0.001")',
+            },
+            timeout_ms: {
+                type: 'number',
+                description: 'Timeout in milliseconds (default: 30000)',
+                default: 30000,
+            },
+            skip_session_check: {
+                type: 'boolean',
+                description: 'Skip session auto-detection and force a fresh x402 payment',
+                default: false,
+            },
+        },
+        required: ['url'],
+    },
+};
+// ─── Handler ───────────────────────────────────────────────────────────────
+async function handleX402Pay(input) {
+    try {
+        const wallet = (0, client_js_1.getWallet)();
+        const config = (0, client_js_1.getConfig)();
+        const timeoutMs = input.timeout_ms ?? 30000;
+        // ── Auto-session detection (x402 V2 behaviour) ──────────────────────
+        // If there's an active session for this URL and the caller hasn't
+        // explicitly asked to skip it, use the session token instead of paying.
+        if (!input.skip_session_check) {
+            const activeSession = (0, session_js_1.findSessionForUrl)(input.url);
+            if (activeSession) {
+                const sessionHeaders = (0, session_js_1.buildSessionHeaders)(activeSession);
+                const method = input.method ?? 'GET';
+                const mergedHeaders = {
+                    'Accept': 'application/json, text/plain, */*',
+                    ...sessionHeaders,
+                    ...(input.headers ?? {}),
+                };
+                if (input.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+                    if (!mergedHeaders['Content-Type']) {
+                        mergedHeaders['Content-Type'] = 'application/json';
+                    }
+                }
+                const requestInit = {
+                    method,
+                    headers: mergedHeaders,
+                    ...(input.body ? { body: input.body } : {}),
+                    signal: AbortSignal.timeout(timeoutMs),
+                };
+                const response = await fetch(input.url, requestInit);
+                // If server accepted the session (2xx/3xx), record it and return
+                if (response.status !== 402) {
+                    const responseText = await response.text();
+                    (0, manager_js_1.recordSessionCall)(activeSession.sessionId);
+                    const MAX_LEN = 8000;
+                    const truncated = responseText.length > MAX_LEN;
+                    const displayText = truncated
+                        ? responseText.slice(0, MAX_LEN) + '\n\n... [response truncated]'
+                        : responseText;
+                    const ttlRemaining = activeSession.expiresAt - Math.floor(Date.now() / 1000);
+                    let out = `🌐 **x402 Fetch Result** (session)\n\n`;
+                    out += `  URL:        ${input.url}\n`;
+                    out += `  Method:     ${method}\n`;
+                    out += `  Status:     ${response.status} ${response.statusText}\n`;
+                    out += `  Network:    ${(0, format_js_1.chainName)(config.chainId)}\n`;
+                    out += `\n🔐 **Session Used** (no payment)\n`;
+                    out += `  Session ID: ${activeSession.sessionId}\n`;
+                    if (activeSession.label)
+                        out += `  Label:      ${activeSession.label}\n`;
+                    out += `  TTL:        ${Math.ceil(ttlRemaining / 60)}m remaining\n`;
+                    out += `  Calls:      ${activeSession.callCount}\n`;
+                    out += `\n📄 **Response Body**\n`;
+                    out += '```\n' + displayText + '\n```';
+                    return { content: [(0, format_js_1.textContent)(out)] };
+                }
+                // Server returned 402 despite session headers — fall through to payment
+                // (session may be invalid on the server side)
+            }
+        }
+        // ── Standard x402 payment flow ────────────────────────────────────────
+        // Parse optional max payment cap
+        let maxPaymentWei;
+        if (input.max_payment_eth) {
+            const cap = parseFloat(input.max_payment_eth);
+            if (isNaN(cap) || cap <= 0) {
+                throw new Error(`Invalid max_payment_eth: "${input.max_payment_eth}"`);
+            }
+            maxPaymentWei = BigInt(Math.round(cap * 1e18));
+        }
+        // Track payment result
+        let paymentMade = false;
+        let paymentAmount = 0n;
+        let paymentTxHash = '';
+        let paymentRecipient = '';
+        // Create x402 client with budget controls
+        const x402Client = (0, agentwallet_sdk_1.createX402Client)(wallet, {
+            autoPay: true,
+            maxRetries: 1,
+            // If cap is set, use it as globalPerRequestMax
+            globalPerRequestMax: maxPaymentWei,
+            onBeforePayment: (req, url) => {
+                const amount = BigInt(req.amount);
+                if (maxPaymentWei && amount > maxPaymentWei) {
+                    throw new Error(`Payment required (${amount} wei) exceeds max_payment_eth cap ` +
+                        `(${maxPaymentWei} wei = ${input.max_payment_eth} ETH). ` +
+                        `Increase max_payment_eth or the payment will not proceed.`);
+                }
+                return true;
+            },
+            onPaymentComplete: (log) => {
+                paymentMade = true;
+                paymentAmount = log.amount;
+                paymentTxHash = log.txHash;
+                paymentRecipient = log.recipient;
+            },
+        });
+        // Build request options
+        const method = input.method ?? 'GET';
+        const headers = {
+            'Accept': 'application/json, text/plain, */*',
+            ...(input.headers ?? {}),
+        };
+        if (input.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            if (!headers['Content-Type']) {
+                headers['Content-Type'] = 'application/json';
+            }
+        }
+        const requestInit = {
+            method,
+            headers,
+            ...(input.body ? { body: input.body } : {}),
+            signal: AbortSignal.timeout(timeoutMs),
+        };
+        // Execute request with x402 handling
+        const response = await x402Client.fetch(input.url, requestInit);
+        const responseText = await response.text();
+        // Truncate very large responses for readability
+        const MAX_RESPONSE_LEN = 8000;
+        const truncated = responseText.length > MAX_RESPONSE_LEN;
+        const displayText = truncated
+            ? responseText.slice(0, MAX_RESPONSE_LEN) + '\n\n... [response truncated]'
+            : responseText;
+        let out = `🌐 **x402 Fetch Result**\n\n`;
+        out += `  URL:     ${input.url}\n`;
+        out += `  Method:  ${method}\n`;
+        out += `  Status:  ${response.status} ${response.statusText}\n`;
+        out += `  Network: ${(0, format_js_1.chainName)(config.chainId)}\n`;
+        if (paymentMade) {
+            out += `\n💳 **Payment Made**\n`;
+            out += `  Amount:    ${paymentAmount.toString()} (base units)\n`;
+            out += `  Recipient: ${paymentRecipient}\n`;
+            out += `  TX Hash:   ${paymentTxHash}\n`;
+            out += `\n💡 Tip: Use x402_session_start to pay once for a session and skip per-call payments.\n`;
+        }
+        else {
+            out += `\n✅ No payment required\n`;
+        }
+        out += `\n📄 **Response Body**\n`;
+        out += '```\n' + displayText + '\n```';
+        return { content: [(0, format_js_1.textContent)(out)] };
+    }
+    catch (error) {
+        // Check for AbortError (timeout)
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                content: [(0, format_js_1.textContent)(`❌ x402_pay failed: Request timed out after ${input.timeout_ms ?? 30000}ms`)],
+                isError: true,
+            };
+        }
+        return {
+            content: [(0, format_js_1.textContent)((0, format_js_1.formatError)(error, 'x402_pay'))],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=x402.js.map

package/dist/tools/x402.js.map

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

package/dist/utils/client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AgentWalletClient setup for AgentPay MCP.
+ * Reads config from environment variables and creates a configured wallet instance.
+ */
+import { type Address } from 'viem';
+import { createWallet } from 'agentwallet-sdk';
+export interface AgentPayConfig {
+    /** Agent hot wallet private key (0x-prefixed hex) */
+    agentPrivateKey: `0x${string}`;
+    /** Deployed AgentAccountV2 address */
+    walletAddress: Address;
+    /** Chain ID (default: 8453 Base Mainnet) */
+    chainId: number;
+    /** RPC URL (falls back to public Base RPC) */
+    rpcUrl: string;
+    /** Factory address (for deploy_wallet tool only) */
+    factoryAddress?: Address;
+    /** NFT contract address (for deploy_wallet tool only) */
+    nftContractAddress?: Address;
+}
+/**
+ * Load configuration from environment variables.
+ * Only AGENT_PRIVATE_KEY and AGENT_WALLET_ADDRESS are required to get started.
+ */
+export declare function loadConfig(): AgentPayConfig;
+export type AgentWalletInstance = ReturnType<typeof createWallet>;
+/**
+ * Create an AgentWallet instance from config.
+ * Returns the wallet bound to the configured chain + RPC.
+ */
+export declare function createAgentWallet(config: AgentPayConfig): AgentWalletInstance;
+/**
+ * Get the singleton AgentPay config (loaded once from env).
+ * Throws a descriptive error if env vars are missing.
+ */
+export declare function getConfig(): AgentPayConfig;
+/**
+ * Get the singleton AgentWallet instance.
+ * Lazily initialized on first call.
+ */
+export declare function getWallet(): AgentWalletInstance;
+/**
+ * Reset singletons (for testing only).
+ */
+export declare function _resetSingletons(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/utils/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/utils/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA4B,KAAK,OAAO,EAAc,MAAM,MAAM,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAqB/C,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,eAAe,EAAE,KAAK,MAAM,EAAE,CAAC;IAC/B,sCAAsC;IACtC,aAAa,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAID;;;GAGG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAiD3C;AAID,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAElE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,mBAAmB,CAyB7E;AAOD;;;GAGG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAK1C;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,mBAAmB,CAK/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/utils/client.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.createAgentWallet = createAgentWallet;
+exports.getConfig = getConfig;
+exports.getWallet = getWallet;
+exports._resetSingletons = _resetSingletons;
+/**
+ * AgentWalletClient setup for AgentPay MCP.
+ * Reads config from environment variables and creates a configured wallet instance.
+ */
+const viem_1 = require("viem");
+const accounts_1 = require("viem/accounts");
+const chains_1 = require("viem/chains");
+const agentwallet_sdk_1 = require("agentwallet-sdk");
+// ─── Supported chains ──────────────────────────────────────────────────────
+const CHAIN_MAP = {
+    8453: chains_1.base,
+    84532: chains_1.baseSepolia,
+};
+const CHAIN_NAME_MAP = {
+    8453: 'base',
+    84532: 'base-sepolia',
+};
+const DEFAULT_RPC = {
+    8453: 'https://mainnet.base.org',
+    84532: 'https://sepolia.base.org',
+};
+// ─── Config loader ─────────────────────────────────────────────────────────
+/**
+ * Load configuration from environment variables.
+ * Only AGENT_PRIVATE_KEY and AGENT_WALLET_ADDRESS are required to get started.
+ */
+function loadConfig() {
+    const agentPrivateKey = process.env['AGENT_PRIVATE_KEY'];
+    const walletAddress = process.env['AGENT_WALLET_ADDRESS'];
+    if (!agentPrivateKey) {
+        throw new Error('AGENT_PRIVATE_KEY environment variable is required. ' +
+            'Set it to the agent hot wallet private key (0x-prefixed hex).');
+    }
+    if (!walletAddress) {
+        throw new Error('AGENT_WALLET_ADDRESS environment variable is required. ' +
+            'Set it to the deployed AgentAccountV2 contract address.');
+    }
+    if (!agentPrivateKey.startsWith('0x') || agentPrivateKey.length !== 66) {
+        throw new Error('AGENT_PRIVATE_KEY must be a 0x-prefixed 32-byte hex string (66 chars total).');
+    }
+    if (!walletAddress.startsWith('0x') || walletAddress.length !== 42) {
+        throw new Error('AGENT_WALLET_ADDRESS must be a 0x-prefixed 20-byte hex string (42 chars total).');
+    }
+    const chainId = parseInt(process.env['CHAIN_ID'] ?? '8453', 10);
+    if (!CHAIN_MAP[chainId]) {
+        throw new Error(`Unsupported CHAIN_ID: ${chainId}. Supported values: 8453 (Base Mainnet), 84532 (Base Sepolia).`);
+    }
+    const rpcUrl = process.env['RPC_URL'] ?? DEFAULT_RPC[chainId] ?? 'https://mainnet.base.org';
+    const factoryAddress = process.env['FACTORY_ADDRESS'];
+    const nftContractAddress = process.env['NFT_CONTRACT_ADDRESS'];
+    return {
+        agentPrivateKey: agentPrivateKey,
+        walletAddress: walletAddress,
+        chainId,
+        rpcUrl,
+        factoryAddress,
+        nftContractAddress,
+    };
+}
+/**
+ * Create an AgentWallet instance from config.
+ * Returns the wallet bound to the configured chain + RPC.
+ */
+function createAgentWallet(config) {
+    const chain = CHAIN_MAP[config.chainId];
+    if (!chain) {
+        throw new Error(`Unsupported chain ID: ${config.chainId}`);
+    }
+    const chainName = CHAIN_NAME_MAP[config.chainId];
+    if (!chainName) {
+        throw new Error(`No chain name mapping for chain ID: ${config.chainId}`);
+    }
+    const account = (0, accounts_1.privateKeyToAccount)(config.agentPrivateKey);
+    const walletClient = (0, viem_1.createWalletClient)({
+        account,
+        chain,
+        transport: (0, viem_1.http)(config.rpcUrl),
+    });
+    return (0, agentwallet_sdk_1.createWallet)({
+        accountAddress: config.walletAddress,
+        chain: chainName,
+        rpcUrl: config.rpcUrl,
+        walletClient,
+    });
+}
+// ─── Singleton accessor ────────────────────────────────────────────────────
+let _config = null;
+let _wallet = null;
+/**
+ * Get the singleton AgentPay config (loaded once from env).
+ * Throws a descriptive error if env vars are missing.
+ */
+function getConfig() {
+    if (!_config) {
+        _config = loadConfig();
+    }
+    return _config;
+}
+/**
+ * Get the singleton AgentWallet instance.
+ * Lazily initialized on first call.
+ */
+function getWallet() {
+    if (!_wallet) {
+        _wallet = createAgentWallet(getConfig());
+    }
+    return _wallet;
+}
+/**
+ * Reset singletons (for testing only).
+ */
+function _resetSingletons() {
+    _config = null;
+    _wallet = null;
+}
+//# sourceMappingURL=client.js.map

package/dist/utils/client.js.map

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

package/dist/utils/format.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Response formatters for AgentPay MCP tools.
+ * Converts on-chain bigint/hex values to human-readable MCP content.
+ */
+import type { Address, Hash } from 'viem';
+/**
+ * Format a bigint wei amount as a readable ETH string.
+ * e.g., 1000000000000000000n → "1.000000 ETH"
+ */
+export declare function formatEth(wei: bigint): string;
+/**
+ * Format a bigint token amount with the given decimals.
+ * e.g., 1000000n with decimals=6 → "1.000000 USDC"
+ */
+export declare function formatToken(amount: bigint, decimals: number, symbol: string): string;
+/**
+ * Format a bigint as a readable ETH or "N/A" if zero/unlimited.
+ * Used for spend limits where 0 means "no autonomous spending allowed".
+ */
+export declare function formatSpendLimit(wei: bigint): string;
+/**
+ * Format an address with a label. Truncates middle for readability.
+ */
+export declare function formatAddress(address: Address): string;
+/**
+ * Format a full address (for display in detailed outputs).
+ */
+export declare function formatAddressFull(address: Address): string;
+/**
+ * Format seconds as human-readable duration.
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Format a Unix timestamp as ISO string.
+ */
+export declare function formatTimestamp(ts: number): string;
+/**
+ * Get a utilization badge based on percentage used.
+ */
+export declare function utilizationBadge(pct: number): string;
+export declare function chainName(chainId: number): string;
+export declare function explorerTxUrl(txHash: Hash, chainId: number): string;
+export declare function explorerAddressUrl(address: Address, chainId: number): string;
+/**
+ * Create a standard MCP text content block.
+ */
+export declare function textContent(text: string): {
+    type: 'text';
+    text: string;
+};
+/**
+ * Format an error into a human-readable MCP error response text.
+ */
+export declare function formatError(error: unknown, context: string): string;
+/**
+ * Format a success message with optional details.
+ */
+export declare function formatSuccess(message: string, details?: Record<string, string>): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK1C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD;AAID;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE1D;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CActD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGlD;AAID;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD;AAID,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAU5E;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAExE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CASvF"}