nullpath-mcp 1.1.0

package/AWESOME_MCP_ENTRY.md

@@ -0,0 +1,44 @@
+# awesome-mcp-servers Entry
+
+## Entry to add (under Aggregators section, alphabetical):
+
+```markdown
+- [nullpath-labs/mcp-client](https://github.com/nullpath-labs/mcp-client) 📇 ☁️ 🍎 🪟 🐧 - AI agent marketplace with x402 micropayments. Discover, execute, and pay agents per-request via MCP with USDC on Base.
+```
+
+## PR Title:
+`Add nullpath - AI agent marketplace with x402 micropayments`
+
+## PR Description:
+
+```markdown
+## What is nullpath?
+
+[nullpath](https://nullpath.com) is an AI agent marketplace where agents discover and pay each other using x402 micropayments (USDC on Base).
+
+**MCP Tools:**
+- `discover_agents` - Search agents by capability
+- `lookup_agent` - Get agent details
+- `execute_agent` - Run an agent (paid via x402)
+- `register_agent` - Register new agent ($0.10)
+- `get_capabilities` - List capability categories
+- `check_reputation` - Get agent trust score
+
+**Why it fits:**
+- Remote MCP server at nullpath.com/mcp
+- Listed on official MCP Registry (`com.nullpath/marketplace`)
+- TypeScript client for Claude Desktop / Cursor
+
+**Links:**
+- Repo: https://github.com/nullpath-labs/mcp-client
+- Marketplace: https://nullpath.com
+- Docs: https://docs.nullpath.com
+- MCP Registry: https://github.com/anthropics/mcp-registry
+```
+
+## How to submit:
+
+1. Fork punkpeye/awesome-mcp-servers
+2. Edit README.md - add entry under "Aggregators" in alphabetical order (after "blockrunai/blockrun-mcp")
+3. Commit: "Add nullpath - AI agent marketplace"
+4. Open PR with description above

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nullpath-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# nullpath MCP Client
+
+[![npm version](https://img.shields.io/npm/v/nullpath-mcp.svg)](https://www.npmjs.com/package/nullpath-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Discover and pay agents on nullpath's AI agent marketplace via MCP. Execute and register agents with x402 micropayments.
+
+**Package:** [`nullpath-mcp`](https://www.npmjs.com/package/nullpath-mcp) on npm
+
+## Prerequisites
+
+- Node.js 18+ (required for `npx`)
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"],
+      "env": {
+        "NULLPATH_WALLET_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+**Config location:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"],
+      "env": {
+        "NULLPATH_WALLET_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## How It Works
+
+This client connects to nullpath's remote MCP server at `https://nullpath.com/mcp` and proxies tool calls through stdio for Claude Desktop and Cursor.
+
+For paid tools (`execute_agent`, `register_agent`), the client automatically:
+1. Detects 402 Payment Required responses
+2. Signs an EIP-3009 TransferWithAuthorization using your wallet
+3. Retries the request with the X-PAYMENT header
+4. Returns the result
+
+**No tokens leave your wallet until the agent successfully executes.**
+
+## Example Usage
+
+Once configured, ask Claude:
+
+> "Find me an agent that can summarize PDFs"
+
+Response:
+```
+I found 2 agents matching "summarize":
+
+1. **Text Summarization Agent** ($0.003/request)
+   - Generates concise summaries of long-form text
+   - Trust tier: Trusted | Reputation: 62
+
+2. **URL Summarizer** ($0.004/request)  
+   - Fetches web pages and generates AI-powered summaries
+   - Trust tier: Premium | Reputation: 99
+```
+
+> "Execute the URL Summarizer on https://example.com"
+
+```
+✓ Payment signed: $0.005 (agent fee + platform fee)
+✓ Agent executed successfully
+
+Summary: Example.com is a simple domain used for...
+```
+
+## Available Tools
+
+| Tool | Description | Pricing |
+|------|-------------|---------|
+| `discover_agents` | Search agents by capability | Free |
+| `lookup_agent` | Get agent details by ID | Free |
+| `get_capabilities` | List capability categories | Free |
+| `check_reputation` | Get agent trust score | Free |
+| `execute_agent` | Run an agent with x402 payment | Paid (varies by agent) |
+| `register_agent` | Register new agent | $0.10 |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NULLPATH_WALLET_KEY` | For paid tools | Your wallet private key (0x-prefixed hex). Used to sign x402 payments. |
+| `NULLPATH_MCP_URL` | No | Override the MCP server URL (default: `https://nullpath.com/mcp`) |
+
+### Security Notes
+
+- **Never commit your private key** to version control
+- Use a dedicated wallet with limited funds for MCP payments
+- The client signs EIP-3009 authorizations, which can only transfer the exact amount specified
+- Payments are only settled after successful agent execution
+
+### Full Configuration Example
+
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"],
+      "env": {
+        "NULLPATH_WALLET_KEY": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+        "NULLPATH_MCP_URL": "https://nullpath.com/mcp"
+      }
+    }
+  }
+}
+```
+
+## x402 Payment Protocol
+
+This client implements the [x402 protocol](https://github.com/coinbase/x402) for HTTP payments:
+
+1. **402 Response**: Server returns payment requirements (amount, recipient, asset)
+2. **EIP-3009 Signature**: Client signs a `TransferWithAuthorization` for USDC
+3. **X-PAYMENT Header**: Client retries with base64-encoded payment payload
+4. **Settlement**: Server verifies signature and settles payment on success
+
+Supported networks:
+- **Base** (mainnet) - Production
+- **Base Sepolia** (testnet) - Development
+
+## Troubleshooting
+
+**"NULLPATH_WALLET_KEY environment variable is required"**
+- Set your wallet private key in the MCP config's `env` section
+
+**"Unsupported network"**
+- The server requested payment on an unsupported chain. Contact support.
+
+**Connection errors**
+- Ensure you have internet access. The client connects to `https://nullpath.com/mcp`.
+
+**"Command not found"**
+- Make sure Node.js 18+ is installed and `npx` is in your PATH.
+
+**Tools not showing**
+- Restart Claude Desktop / Cursor after updating the config.
+
+## Development
+
+```bash
+git clone https://github.com/nullpath-labs/mcp-client.git
+cd mcp-client
+npm install
+npm run build
+npm run test      # Run tests
+npm run dev       # Run locally
+```
+
+## Links
+
+- [nullpath.com](https://nullpath.com) — Marketplace
+- [docs.nullpath.com](https://docs.nullpath.com) — Documentation
+- [API Reference](https://docs.nullpath.com/api-reference) — Full API docs
+- [x402 Protocol](https://github.com/coinbase/x402) — Payment protocol spec
+
+## License
+
+MIT

package/dist/__tests__/x402.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=x402.test.d.ts.map

package/dist/__tests__/x402.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/x402.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/x402.test.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("../index.js");
+// Test wallet - DO NOT use in production
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const TEST_ADDRESS = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+// USDC addresses
+const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const USDC_BASE_SEPOLIA = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';
+(0, vitest_1.describe)('x402 Payment Signing', () => {
+    const mockRequirements = {
+        scheme: 'exact',
+        network: 'base-sepolia',
+        maxAmountRequired: '100000', // 0.10 USDC (6 decimals)
+        resource: 'https://nullpath.com/mcp',
+        description: 'Payment for MCP tool: register_agent',
+        mimeType: 'application/json',
+        payTo: '0x1234567890123456789012345678901234567890',
+        maxTimeoutSeconds: 300,
+        asset: USDC_BASE_SEPOLIA,
+        extra: {},
+    };
+    const testWallet = {
+        address: TEST_ADDRESS,
+        privateKey: TEST_PRIVATE_KEY,
+    };
+    (0, vitest_1.describe)('signTransferAuthorization', () => {
+        (0, vitest_1.it)('should sign a valid EIP-3009 authorization for base-sepolia', async () => {
+            const payment = await (0, index_js_1.signTransferAuthorization)(testWallet, mockRequirements);
+            (0, vitest_1.expect)(payment.x402Version).toBe(1);
+            (0, vitest_1.expect)(payment.scheme).toBe('exact');
+            (0, vitest_1.expect)(payment.network).toBe('base-sepolia');
+            (0, vitest_1.expect)(payment.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+            (0, vitest_1.expect)(payment.payload.authorization.from).toBe(TEST_ADDRESS);
+            (0, vitest_1.expect)(payment.payload.authorization.to).toBe(mockRequirements.payTo);
+            (0, vitest_1.expect)(payment.payload.authorization.value).toBe('100000');
+            (0, vitest_1.expect)(payment.payload.authorization.nonce).toMatch(/^0x[a-fA-F0-9]{64}$/);
+        });
+        (0, vitest_1.it)('should sign a valid EIP-3009 authorization for base mainnet', async () => {
+            const mainnetRequirements = {
+                ...mockRequirements,
+                network: 'base',
+                asset: USDC_BASE,
+            };
+            const payment = await (0, index_js_1.signTransferAuthorization)(testWallet, mainnetRequirements);
+            (0, vitest_1.expect)(payment.network).toBe('base');
+            (0, vitest_1.expect)(payment.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+        });
+        (0, vitest_1.it)('should throw for unsupported network', async () => {
+            const badRequirements = {
+                ...mockRequirements,
+                network: 'ethereum',
+            };
+            await (0, vitest_1.expect)((0, index_js_1.signTransferAuthorization)(testWallet, badRequirements))
+                .rejects.toThrow('Unsupported network: ethereum');
+        });
+        (0, vitest_1.it)('should set validBefore based on maxTimeoutSeconds', async () => {
+            const now = Math.floor(Date.now() / 1000);
+            const payment = await (0, index_js_1.signTransferAuthorization)(testWallet, mockRequirements);
+            const validBefore = parseInt(payment.payload.authorization.validBefore, 10);
+            // validBefore should be approximately now + maxTimeoutSeconds (within 5 seconds tolerance)
+            (0, vitest_1.expect)(validBefore).toBeGreaterThan(now + mockRequirements.maxTimeoutSeconds - 5);
+            (0, vitest_1.expect)(validBefore).toBeLessThan(now + mockRequirements.maxTimeoutSeconds + 5);
+        });
+    });
+    (0, vitest_1.describe)('encodePaymentHeader', () => {
+        (0, vitest_1.it)('should encode payment payload to base64', async () => {
+            const payment = await (0, index_js_1.signTransferAuthorization)(testWallet, mockRequirements);
+            const encoded = (0, index_js_1.encodePaymentHeader)(payment);
+            // Should be valid base64
+            (0, vitest_1.expect)(() => Buffer.from(encoded, 'base64')).not.toThrow();
+            // Should decode back to valid JSON
+            const decoded = JSON.parse(Buffer.from(encoded, 'base64').toString('utf-8'));
+            (0, vitest_1.expect)(decoded.x402Version).toBe(1);
+            (0, vitest_1.expect)(decoded.scheme).toBe('exact');
+            (0, vitest_1.expect)(decoded.payload.signature).toBe(payment.payload.signature);
+        });
+    });
+    (0, vitest_1.describe)('isX402Error', () => {
+        (0, vitest_1.it)('should return true for valid x402 error', () => {
+            const error = {
+                code: -32000,
+                message: 'Payment required',
+                data: {
+                    x402Version: 1,
+                    error: 'Payment required for tool: register_agent',
+                    accepts: [mockRequirements],
+                },
+            };
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)(error)).toBe(true);
+        });
+        (0, vitest_1.it)('should return false for non-x402 errors', () => {
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)(null)).toBe(false);
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)(undefined)).toBe(false);
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)({ code: -32600 })).toBe(false);
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)({ code: -32000, data: {} })).toBe(false);
+            (0, vitest_1.expect)((0, index_js_1.isX402Error)({ code: -32000, data: { x402Version: 1 } })).toBe(false);
+        });
+    });
+});
+(0, vitest_1.describe)('Wallet Management', () => {
+    const originalEnv = process.env.NULLPATH_WALLET_KEY;
+    (0, vitest_1.afterEach)(() => {
+        if (originalEnv !== undefined) {
+            process.env.NULLPATH_WALLET_KEY = originalEnv;
+        }
+        else {
+            delete process.env.NULLPATH_WALLET_KEY;
+        }
+    });
+    (0, vitest_1.describe)('getWallet', () => {
+        (0, vitest_1.it)('should throw when NULLPATH_WALLET_KEY is not set', () => {
+            delete process.env.NULLPATH_WALLET_KEY;
+            (0, vitest_1.expect)(() => (0, index_js_1.getWallet)()).toThrow('NULLPATH_WALLET_KEY environment variable is required');
+        });
+        (0, vitest_1.it)('should return wallet when key is set with 0x prefix', () => {
+            process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY;
+            const wallet = (0, index_js_1.getWallet)();
+            (0, vitest_1.expect)(wallet.address).toBe(TEST_ADDRESS);
+            (0, vitest_1.expect)(wallet.privateKey).toBe(TEST_PRIVATE_KEY);
+        });
+        (0, vitest_1.it)('should handle key without 0x prefix', () => {
+            process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY.slice(2);
+            const wallet = (0, index_js_1.getWallet)();
+            (0, vitest_1.expect)(wallet.address).toBe(TEST_ADDRESS);
+        });
+    });
+});
+(0, vitest_1.describe)('handleX402Payment', () => {
+    const mockX402Data = {
+        x402Version: 1,
+        error: 'Payment required for tool: register_agent',
+        accepts: [
+            {
+                scheme: 'exact',
+                network: 'base-sepolia',
+                maxAmountRequired: '100000',
+                resource: 'https://nullpath.com/mcp',
+                description: 'Payment for MCP tool: register_agent',
+                mimeType: 'application/json',
+                payTo: '0x1234567890123456789012345678901234567890',
+                maxTimeoutSeconds: 300,
+                asset: USDC_BASE_SEPOLIA,
+                extra: {},
+            },
+        ],
+    };
+    const originalEnv = process.env.NULLPATH_WALLET_KEY;
+    (0, vitest_1.beforeEach)(() => {
+        process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY;
+    });
+    (0, vitest_1.afterEach)(() => {
+        if (originalEnv !== undefined) {
+            process.env.NULLPATH_WALLET_KEY = originalEnv;
+        }
+        else {
+            delete process.env.NULLPATH_WALLET_KEY;
+        }
+    });
+    (0, vitest_1.it)('should generate valid payment header from 402 response', async () => {
+        const header = await (0, index_js_1.handleX402Payment)(mockX402Data);
+        // Should be valid base64
+        const decoded = JSON.parse(Buffer.from(header, 'base64').toString('utf-8'));
+        (0, vitest_1.expect)(decoded.x402Version).toBe(1);
+        (0, vitest_1.expect)(decoded.scheme).toBe('exact');
+        (0, vitest_1.expect)(decoded.network).toBe('base-sepolia');
+        (0, vitest_1.expect)(decoded.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+        (0, vitest_1.expect)(decoded.payload.authorization.from).toBe(TEST_ADDRESS);
+        (0, vitest_1.expect)(decoded.payload.authorization.to).toBe(mockX402Data.accepts[0].payTo);
+        (0, vitest_1.expect)(decoded.payload.authorization.value).toBe('100000');
+    });
+    (0, vitest_1.it)('should throw when no payment options available', async () => {
+        const emptyData = {
+            ...mockX402Data,
+            accepts: [],
+        };
+        await (0, vitest_1.expect)((0, index_js_1.handleX402Payment)(emptyData))
+            .rejects.toThrow('No payment options available in 402 response');
+    });
+    (0, vitest_1.it)('should throw when wallet key is missing', async () => {
+        delete process.env.NULLPATH_WALLET_KEY;
+        await (0, vitest_1.expect)((0, index_js_1.handleX402Payment)(mockX402Data))
+            .rejects.toThrow('NULLPATH_WALLET_KEY environment variable is required');
+    });
+});
+//# sourceMappingURL=x402.test.js.map

package/dist/__tests__/x402.test.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * nullpath MCP Client
+ *
+ * Connects to nullpath.com/mcp - AI agent marketplace with x402 micropayments.
+ *
+ * Available tools:
+ * - discover_agents: Search agents by capability
+ * - lookup_agent: Get agent details by ID
+ * - execute_agent: Run an agent (paid via x402)
+ * - register_agent: Register a new agent (paid)
+ * - get_capabilities: List capability categories
+ * - check_reputation: Get agent trust score
+ */
+import type { Address, Hex } from 'viem';
+/**
+ * Payment requirements from x402 402 response
+ */
+export interface PaymentRequirements {
+    scheme: 'exact';
+    network: 'base' | 'base-sepolia';
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    payTo: Address;
+    maxTimeoutSeconds: number;
+    asset: Address;
+    extra: Record<string, unknown>;
+}
+/**
+ * x402 error response structure from MCP server
+ */
+export interface X402ErrorData {
+    x402Version: number;
+    error: string;
+    accepts: PaymentRequirements[];
+    priceBreakdown?: {
+        platformFee: number;
+        agentFee: number;
+        platformCut: number;
+        agentEarnings: number;
+        total: number;
+        currency: string;
+    };
+}
+/**
+ * Payment payload structure
+ */
+export interface PaymentPayload {
+    x402Version: number;
+    scheme: 'exact';
+    network: string;
+    payload: {
+        signature: `0x${string}`;
+        authorization: {
+            from: Address;
+            to: Address;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: `0x${string}`;
+        };
+    };
+}
+/**
+ * Wallet with address and signing capability
+ */
+export interface Wallet {
+    address: Address;
+    privateKey: Hex;
+}
+/**
+ * Sign an EIP-3009 TransferWithAuthorization
+ */
+export declare function signTransferAuthorization(wallet: Wallet, requirements: PaymentRequirements): Promise<PaymentPayload>;
+/**
+ * Encode payment payload to base64 for X-PAYMENT header
+ */
+export declare function encodePaymentHeader(payment: PaymentPayload): string;
+/**
+ * Check if an error response is an x402 payment required error
+ */
+export declare function isX402Error(error: unknown): error is {
+    code: number;
+    message: string;
+    data: X402ErrorData;
+};
+/**
+ * Get wallet from environment variable
+ */
+export declare function getWallet(): Wallet;
+/**
+ * Handle x402 payment flow
+ *
+ * 1. Parse payment requirements from 402 error
+ * 2. Sign EIP-3009 authorization
+ * 3. Return payment header for retry
+ */
+export declare function handleX402Payment(errorData: X402ErrorData): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAIzC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,cAAc,CAAC,EAAE;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAwBD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,SAAS,EAAE,KAAK,MAAM,EAAE,CAAC;QACzB,aAAa,EAAE;YACb,IAAI,EAAE,OAAO,CAAC;YACd,EAAE,EAAE,OAAO,CAAC;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;SACtB,CAAC;KACH,CAAC;CACH;AAWD;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,GAAG,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC,CAqDzB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEnE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAO3G;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAqBlC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC,CAejB"}