@azeth/sdk 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +139 -0
  3. package/dist/account/balance.d.ts +41 -0
  4. package/dist/account/balance.d.ts.map +1 -0
  5. package/dist/account/balance.js +264 -0
  6. package/dist/account/balance.js.map +1 -0
  7. package/dist/account/create.d.ts +27 -0
  8. package/dist/account/create.d.ts.map +1 -0
  9. package/dist/account/create.js +116 -0
  10. package/dist/account/create.js.map +1 -0
  11. package/dist/account/deposit.d.ts +34 -0
  12. package/dist/account/deposit.d.ts.map +1 -0
  13. package/dist/account/deposit.js +88 -0
  14. package/dist/account/deposit.js.map +1 -0
  15. package/dist/account/guardian-approval.d.ts +111 -0
  16. package/dist/account/guardian-approval.d.ts.map +1 -0
  17. package/dist/account/guardian-approval.js +223 -0
  18. package/dist/account/guardian-approval.js.map +1 -0
  19. package/dist/account/guardian.d.ts +27 -0
  20. package/dist/account/guardian.d.ts.map +1 -0
  21. package/dist/account/guardian.js +67 -0
  22. package/dist/account/guardian.js.map +1 -0
  23. package/dist/account/history.d.ts +22 -0
  24. package/dist/account/history.d.ts.map +1 -0
  25. package/dist/account/history.js +144 -0
  26. package/dist/account/history.js.map +1 -0
  27. package/dist/account/transfer.d.ts +28 -0
  28. package/dist/account/transfer.d.ts.map +1 -0
  29. package/dist/account/transfer.js +137 -0
  30. package/dist/account/transfer.js.map +1 -0
  31. package/dist/auth/erc8128.d.ts +14 -0
  32. package/dist/auth/erc8128.d.ts.map +1 -0
  33. package/dist/auth/erc8128.js +92 -0
  34. package/dist/auth/erc8128.js.map +1 -0
  35. package/dist/client.d.ts +394 -0
  36. package/dist/client.d.ts.map +1 -0
  37. package/dist/client.js +970 -0
  38. package/dist/client.js.map +1 -0
  39. package/dist/events/emitter.d.ts +96 -0
  40. package/dist/events/emitter.d.ts.map +1 -0
  41. package/dist/events/emitter.js +90 -0
  42. package/dist/events/emitter.js.map +1 -0
  43. package/dist/index.d.ts +29 -0
  44. package/dist/index.d.ts.map +1 -0
  45. package/dist/index.js +33 -0
  46. package/dist/index.js.map +1 -0
  47. package/dist/messaging/message-router.d.ts +69 -0
  48. package/dist/messaging/message-router.d.ts.map +1 -0
  49. package/dist/messaging/message-router.js +307 -0
  50. package/dist/messaging/message-router.js.map +1 -0
  51. package/dist/messaging/rate-limiter.d.ts +31 -0
  52. package/dist/messaging/rate-limiter.d.ts.map +1 -0
  53. package/dist/messaging/rate-limiter.js +74 -0
  54. package/dist/messaging/rate-limiter.js.map +1 -0
  55. package/dist/messaging/xmtp.d.ts +144 -0
  56. package/dist/messaging/xmtp.d.ts.map +1 -0
  57. package/dist/messaging/xmtp.js +473 -0
  58. package/dist/messaging/xmtp.js.map +1 -0
  59. package/dist/payments/agreements.d.ts +87 -0
  60. package/dist/payments/agreements.d.ts.map +1 -0
  61. package/dist/payments/agreements.js +337 -0
  62. package/dist/payments/agreements.js.map +1 -0
  63. package/dist/payments/budget.d.ts +118 -0
  64. package/dist/payments/budget.d.ts.map +1 -0
  65. package/dist/payments/budget.js +176 -0
  66. package/dist/payments/budget.js.map +1 -0
  67. package/dist/payments/smart-fetch.d.ts +65 -0
  68. package/dist/payments/smart-fetch.d.ts.map +1 -0
  69. package/dist/payments/smart-fetch.js +115 -0
  70. package/dist/payments/smart-fetch.js.map +1 -0
  71. package/dist/payments/x402.d.ts +89 -0
  72. package/dist/payments/x402.d.ts.map +1 -0
  73. package/dist/payments/x402.js +620 -0
  74. package/dist/payments/x402.js.map +1 -0
  75. package/dist/registry/discover.d.ts +43 -0
  76. package/dist/registry/discover.d.ts.map +1 -0
  77. package/dist/registry/discover.js +272 -0
  78. package/dist/registry/discover.js.map +1 -0
  79. package/dist/registry/register.d.ts +44 -0
  80. package/dist/registry/register.d.ts.map +1 -0
  81. package/dist/registry/register.js +126 -0
  82. package/dist/registry/register.js.map +1 -0
  83. package/dist/reputation/opinion.d.ts +52 -0
  84. package/dist/reputation/opinion.d.ts.map +1 -0
  85. package/dist/reputation/opinion.js +198 -0
  86. package/dist/reputation/opinion.js.map +1 -0
  87. package/dist/utils/addresses.d.ts +6 -0
  88. package/dist/utils/addresses.d.ts.map +1 -0
  89. package/dist/utils/addresses.js +53 -0
  90. package/dist/utils/addresses.js.map +1 -0
  91. package/dist/utils/errors.d.ts +23 -0
  92. package/dist/utils/errors.d.ts.map +1 -0
  93. package/dist/utils/errors.js +188 -0
  94. package/dist/utils/errors.js.map +1 -0
  95. package/dist/utils/execution.d.ts +20 -0
  96. package/dist/utils/execution.d.ts.map +1 -0
  97. package/dist/utils/execution.js +28 -0
  98. package/dist/utils/execution.js.map +1 -0
  99. package/dist/utils/paymaster.d.ts +35 -0
  100. package/dist/utils/paymaster.d.ts.map +1 -0
  101. package/dist/utils/paymaster.js +115 -0
  102. package/dist/utils/paymaster.js.map +1 -0
  103. package/dist/utils/retry.d.ts +19 -0
  104. package/dist/utils/retry.d.ts.map +1 -0
  105. package/dist/utils/retry.js +68 -0
  106. package/dist/utils/retry.js.map +1 -0
  107. package/dist/utils/userop.d.ts +55 -0
  108. package/dist/utils/userop.d.ts.map +1 -0
  109. package/dist/utils/userop.js +201 -0
  110. package/dist/utils/userop.js.map +1 -0
  111. package/dist/utils/validation.d.ts +8 -0
  112. package/dist/utils/validation.d.ts.map +1 -0
  113. package/dist/utils/validation.js +35 -0
  114. package/dist/utils/validation.js.map +1 -0
  115. package/package.json +63 -0
@@ -0,0 +1,65 @@
1
+ /** Smart service discovery + payment routing with fallback.
2
+ *
3
+ * Combines discoverServices → fetch402 into one operation with automatic
4
+ * fallback to alternative services on failure. This is a pure routing layer —
5
+ * reputation feedback is handled by AzethKit, which has access to the
6
+ * SmartAccountClient required for on-chain opinion submission.
7
+ */
8
+ import type { PublicClient, WalletClient, Chain, Transport, Account } from 'viem';
9
+ import { type RegistryEntry, type EntityType, type SupportedChainName } from '@azeth/common';
10
+ import { type Fetch402Options, type Fetch402Result } from './x402.js';
11
+ /** Options for smartFetch402 */
12
+ export interface SmartFetch402Options extends Fetch402Options {
13
+ /** Minimum reputation score to consider (0-100). Default: 0 */
14
+ minReputation?: number;
15
+ /** Maximum services to try before giving up. Default: 3 */
16
+ maxRetries?: number;
17
+ /** Whether to submit reputation feedback after the call. Default: true.
18
+ * Only effective when called via AzethKit (which owns the SmartAccountClient). */
19
+ autoFeedback?: boolean;
20
+ /** Entity type filter (e.g., 'service'). Default: undefined (any) */
21
+ entityType?: EntityType;
22
+ /** Preferred service tokenId — tried first if available in results */
23
+ preferredService?: bigint;
24
+ }
25
+ /** Result from smartFetch402 including routing metadata */
26
+ export interface SmartFetch402Result extends Fetch402Result {
27
+ /** The service that was successfully called */
28
+ service: RegistryEntry;
29
+ /** Number of services attempted before success */
30
+ attemptsCount: number;
31
+ /** Services that failed (for debugging) */
32
+ failedServices?: Array<{
33
+ service: RegistryEntry;
34
+ error: string;
35
+ }>;
36
+ }
37
+ /** Compute reputation feedback value from response time.
38
+ *
39
+ * Maps response latency to a 0-100 quality score:
40
+ * - < 200ms → 90 (excellent)
41
+ * - < 500ms → 70 (good)
42
+ * - < 2000ms → 50 (acceptable)
43
+ * - >= 2000ms → 30 (slow)
44
+ */
45
+ export declare function computeFeedbackValue(responseTimeMs: number): number;
46
+ /** Penalty value for services that failed outright */
47
+ export declare const FAILURE_PENALTY_VALUE = -20;
48
+ /** Smart discovery and payment routing with fallback.
49
+ *
50
+ * This is a pure routing function — it discovers services, tries them in
51
+ * reputation order, and falls back on failure. It does NOT submit reputation
52
+ * feedback (that requires a SmartAccountClient, which only AzethKit owns).
53
+ *
54
+ * @param publicClient - viem public client for chain reads
55
+ * @param walletClient - viem wallet client for signing
56
+ * @param account - EOA address
57
+ * @param serverUrl - Azeth server URL for discovery
58
+ * @param capability - Service capability to discover (e.g., 'price-feed')
59
+ * @param options - Smart fetch options
60
+ * @returns SmartFetch402Result with the successful service and attempt metadata
61
+ */
62
+ export declare function smartFetch402(publicClient: PublicClient<Transport, Chain>, walletClient: WalletClient<Transport, Chain, Account>, account: `0x${string}`, serverUrl: string, capability: string, options?: SmartFetch402Options,
63
+ /** Chain name for on-chain fallback discovery */
64
+ chainName?: SupportedChainName): Promise<SmartFetch402Result>;
65
+ //# sourceMappingURL=smart-fetch.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"smart-fetch.d.ts","sourceRoot":"","sources":["../../src/payments/smart-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAClF,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAY,MAAM,WAAW,CAAC;AAGhF,gCAAgC;AAChC,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;uFACmF;IACnF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,+CAA+C;IAC/C,OAAO,EAAE,aAAa,CAAC;IACvB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,EAC5C,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,OAAO,EAAE,KAAK,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,oBAAoB;AAC9B,iDAAiD;AACjD,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAsF9B"}
@@ -0,0 +1,115 @@
1
+ /** Smart service discovery + payment routing with fallback.
2
+ *
3
+ * Combines discoverServices → fetch402 into one operation with automatic
4
+ * fallback to alternative services on failure. This is a pure routing layer —
5
+ * reputation feedback is handled by AzethKit, which has access to the
6
+ * SmartAccountClient required for on-chain opinion submission.
7
+ */
8
+ import { AzethError, chainIdToName, } from '@azeth/common';
9
+ import { fetch402 } from './x402.js';
10
+ import { discoverServicesWithFallback } from '../registry/discover.js';
11
+ /** Compute reputation feedback value from response time.
12
+ *
13
+ * Maps response latency to a 0-100 quality score:
14
+ * - < 200ms → 90 (excellent)
15
+ * - < 500ms → 70 (good)
16
+ * - < 2000ms → 50 (acceptable)
17
+ * - >= 2000ms → 30 (slow)
18
+ */
19
+ export function computeFeedbackValue(responseTimeMs) {
20
+ if (responseTimeMs < 200)
21
+ return 90;
22
+ if (responseTimeMs < 500)
23
+ return 70;
24
+ if (responseTimeMs < 2000)
25
+ return 50;
26
+ return 30;
27
+ }
28
+ /** Penalty value for services that failed outright */
29
+ export const FAILURE_PENALTY_VALUE = -20;
30
+ /** Smart discovery and payment routing with fallback.
31
+ *
32
+ * This is a pure routing function — it discovers services, tries them in
33
+ * reputation order, and falls back on failure. It does NOT submit reputation
34
+ * feedback (that requires a SmartAccountClient, which only AzethKit owns).
35
+ *
36
+ * @param publicClient - viem public client for chain reads
37
+ * @param walletClient - viem wallet client for signing
38
+ * @param account - EOA address
39
+ * @param serverUrl - Azeth server URL for discovery
40
+ * @param capability - Service capability to discover (e.g., 'price-feed')
41
+ * @param options - Smart fetch options
42
+ * @returns SmartFetch402Result with the successful service and attempt metadata
43
+ */
44
+ export async function smartFetch402(publicClient, walletClient, account, serverUrl, capability, options,
45
+ /** Chain name for on-chain fallback discovery */
46
+ chainName) {
47
+ const maxRetries = options?.maxRetries ?? 3;
48
+ // Discover services sorted by reputation (best first).
49
+ // Uses discoverServicesWithFallback: tries the server API first, then
50
+ // falls back to on-chain ERC-8004 reads if the server is unavailable.
51
+ const discoveryParams = {
52
+ capability,
53
+ sortByReputation: true,
54
+ minReputation: options?.minReputation,
55
+ entityType: options?.entityType,
56
+ limit: maxRetries * 3,
57
+ };
58
+ const resolvedChain = chainName ?? chainIdToName(publicClient.chain?.id ?? 0) ?? 'baseSepolia';
59
+ const discoveryResult = await discoverServicesWithFallback(serverUrl, discoveryParams, publicClient, resolvedChain);
60
+ const services = discoveryResult.entries
61
+ .filter(s => !!s.endpoint)
62
+ .slice(0, maxRetries);
63
+ if (services.length === 0) {
64
+ throw new AzethError(`No services found for capability "${capability}"`, 'SERVICE_NOT_FOUND', { capability, minReputation: options?.minReputation });
65
+ }
66
+ // If preferredService is specified, move it to the front of the list
67
+ if (options?.preferredService !== undefined) {
68
+ const prefIdx = services.findIndex(s => s.tokenId === options.preferredService);
69
+ if (prefIdx > 0) {
70
+ const [preferred] = services.splice(prefIdx, 1);
71
+ services.unshift(preferred);
72
+ }
73
+ }
74
+ const failedServices = [];
75
+ for (let i = 0; i < services.length; i++) {
76
+ const service = services[i];
77
+ // Skip services without an endpoint
78
+ if (!service.endpoint) {
79
+ failedServices.push({ service, error: 'No endpoint URL' });
80
+ continue;
81
+ }
82
+ try {
83
+ const result = await fetch402(publicClient, walletClient, account, service.endpoint, {
84
+ ...options,
85
+ smartAccount: options?.smartAccount,
86
+ });
87
+ // Treat non-success HTTP responses (429 rate-limited, 5xx server error) as
88
+ // soft failures when no payment was made — try the next service instead of
89
+ // returning a broken response to the caller.
90
+ const status = result.response.status;
91
+ if (!result.paymentMade && status >= 400) {
92
+ failedServices.push({ service, error: `HTTP ${status}` });
93
+ continue;
94
+ }
95
+ return {
96
+ ...result,
97
+ service,
98
+ attemptsCount: i + 1,
99
+ failedServices: failedServices.length > 0 ? failedServices : undefined,
100
+ };
101
+ }
102
+ catch (err) {
103
+ const errorMsg = err instanceof Error ? err.message : String(err);
104
+ failedServices.push({ service, error: errorMsg });
105
+ // Continue to next service
106
+ }
107
+ }
108
+ // All services failed
109
+ throw new AzethError(`All ${services.length} services for capability "${capability}" failed`, 'SERVICE_NOT_FOUND', {
110
+ capability,
111
+ attemptsCount: services.length,
112
+ failures: failedServices.map(f => ({ name: f.service.name, error: f.error })),
113
+ });
114
+ }
115
+ //# sourceMappingURL=smart-fetch.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"smart-fetch.js","sourceRoot":"","sources":["../../src/payments/smart-fetch.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,89 @@
1
+ import { type PublicClient, type WalletClient, type Chain, type Transport, type Account } from 'viem';
2
+ /** Verify that a settlement receipt contains a USDC Transfer event matching expectations.
3
+ *
4
+ * Decodes Transfer event logs from the receipt and checks:
5
+ * - Transfer emitted from the expected USDC contract address
6
+ * - Recipient (`to`) matches the expected payTo address
7
+ * - Amount (`value`) >= the expected payment amount
8
+ *
9
+ * @returns true if a matching Transfer event was found, false otherwise
10
+ */
11
+ export declare function verifySettlementReceipt(receipt: {
12
+ logs: ReadonlyArray<{
13
+ address: string;
14
+ topics: ReadonlyArray<string>;
15
+ data: string;
16
+ }>;
17
+ }, expectedPayTo: string, expectedAsset: string, expectedAmount: bigint): boolean;
18
+ /** Parameters for executing a payment via a smart account (UserOp path).
19
+ * The callback receives the pre-encoded USDC calldata and returns the tx hash. */
20
+ export interface SmartAccountTransferParams {
21
+ usdcAddress: `0x${string}`;
22
+ payTo: `0x${string}`;
23
+ amount: bigint;
24
+ /** Full ABI-encoded transferWithAuthorization calldata (bytes variant, 0xcf092995) */
25
+ calldata: `0x${string}`;
26
+ }
27
+ /** Callback that submits a UserOp to execute transferWithAuthorization from the smart account.
28
+ * Returns the transaction hash of the settled UserOp. */
29
+ export type SmartAccountTransferCallback = (params: SmartAccountTransferParams) => Promise<`0x${string}`>;
30
+ export interface Fetch402Options {
31
+ method?: string;
32
+ headers?: Record<string, string>;
33
+ body?: string;
34
+ maxAmount?: bigint;
35
+ autoReputation?: boolean;
36
+ /** Smart account address for SIWx identity (address field in SIWE message).
37
+ * When set, the client will attempt SIWx authentication before paying.
38
+ * The EOA signs the SIWE message, but the smart account address is used
39
+ * so the server can look up agreements by smart account. */
40
+ smartAccount?: `0x${string}`;
41
+ /** M-7: Override the USDC EIP-712 domain name/version if needed.
42
+ * Defaults to known production values ('USD Coin', '2').
43
+ * Override if the USDC contract on your chain uses different domain parameters. */
44
+ usdcDomain?: {
45
+ name: string;
46
+ version: string;
47
+ };
48
+ /** When true, throws PAYMENT_FAILED if the server doesn't return a valid X-Payment-Tx
49
+ * header or if the on-chain settlement receipt shows a revert. Default: false (advisory). */
50
+ strictSettlement?: boolean;
51
+ /** Callback to execute payment via a smart account UserOp.
52
+ * When provided, the payment goes through the smart account (with guardian guardrails)
53
+ * instead of the x402 facilitator settling from the EOA. */
54
+ smartAccountTransfer?: SmartAccountTransferCallback;
55
+ }
56
+ export interface Fetch402Result {
57
+ response: Response;
58
+ paymentMade: boolean;
59
+ amount?: bigint;
60
+ txHash?: `0x${string}`;
61
+ /** Response time in milliseconds (measured from paid request to response) */
62
+ responseTimeMs?: number;
63
+ /** Whether on-chain settlement was verified after payment.
64
+ * True if the server returned an X-Payment-Tx header and the tx receipt shows success. */
65
+ settlementVerified: boolean;
66
+ /** How access was obtained.
67
+ * - 'x402': Standard x402 payment flow (ERC-3009 authorization signed and submitted)
68
+ * - 'smart-account': Payment via smart account UserOp (guardian guardrails enforced)
69
+ * - 'session': Access granted via SIWx identity (prior payment session or agreement)
70
+ * - 'none': No payment was required (non-402 response) */
71
+ paymentMethod: 'x402' | 'smart-account' | 'session' | 'none';
72
+ }
73
+ /** Fetch a URL, automatically paying x402 requirements
74
+ *
75
+ * Flow:
76
+ * 1. Make initial request
77
+ * 2. If 402 returned, parse payment requirements from X-Payment-Required header
78
+ * 3. If SIWx extension present and smartAccount provided, attempt identity proof
79
+ * 4. If SIWx grants access, return (no payment needed)
80
+ * 5. If smartAccountTransfer callback provided, pay via smart account UserOp
81
+ * (guardian guardrails enforced on-chain). Throws on failure — NO EOA fallback.
82
+ * 6. Otherwise (no smart account), sign ERC-3009 transferWithAuthorization from EOA
83
+ * 7. Retry with payment proof header
84
+ *
85
+ * SECURITY: When a smart account is configured (smartAccountTransfer + smartAccount),
86
+ * the EOA payment path is unreachable. This prevents guardian guardrail bypass.
87
+ */
88
+ export declare function fetch402(publicClient: PublicClient<Transport, Chain>, walletClient: WalletClient<Transport, Chain, Account>, account: `0x${string}`, url: string, options?: Fetch402Options): Promise<Fetch402Result>;
89
+ //# sourceMappingURL=x402.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../../src/payments/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,OAAO,EAIb,MAAM,MAAM,CAAC;AAcd;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,EAClG,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,CAsBT;AAyBD;mFACmF;AACnF,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,QAAQ,EAAE,KAAK,MAAM,EAAE,CAAC;CACzB;AAED;0DAC0D;AAC1D,MAAM,MAAM,4BAA4B,GAAG,CAAC,MAAM,EAAE,0BAA0B,KAAK,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;AAE1G,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;iEAG6D;IAC7D,YAAY,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC7B;;wFAEoF;IACpF,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;kGAC8F;IAC9F,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;iEAE6D;IAC7D,oBAAoB,CAAC,EAAE,4BAA4B,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+FAC2F;IAC3F,kBAAkB,EAAE,OAAO,CAAC;IAC5B;;;;+DAI2D;IAC3D,aAAa,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC;CAC9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAC5B,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,EAC5C,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,OAAO,EAAE,KAAK,MAAM,EAAE,EACtB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAwZzB"}