@agirails/sdk 4.4.9 → 4.6.0

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

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

package/dist/delivery/types.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * AIP-16 Delivery Surface — Type Definitions (Phase 2a Foundation)
+ * =================================================================
+ *
+ * Type-level contract for the AGIRAILS delivery layer (AIP-16 Rev 5).
+ *
+ * The delivery surface is the post-COMMITTED / pre-DELIVERED protocol
+ * step in which the provider hands the requester the *actual* deliverable
+ * (the bytes the requester paid for), with cryptographic guarantees of
+ * authenticity, integrity, and (optionally) confidentiality.
+ *
+ * Two privacy modes are supported in v1:
+ *
+ *  - `public-v1`        — body is plaintext UTF-8 JSON. Anyone observing
+ *                         the channel can read it. Useful for public
+ *                         deliverables (open data, public model outputs).
+ *  - `x25519-aes256gcm-v1` — body is AES-256-GCM ciphertext, key derived
+ *                         via X25519 ECDH + HKDF-SHA256 between provider
+ *                         and requester ephemeral keys. End-to-end
+ *                         confidential.
+ *
+ * The delivery surface is composed of two signed objects:
+ *
+ *  1. **DeliverySetup** — signed by the *requester* (buyer). Posted to the
+ *     channel after COMMITTED. Declares the buyer's ephemeral pubkey,
+ *     accepted channels, and expected privacy mode.
+ *
+ *  2. **DeliveryEnvelope** — signed by the *provider* (seller). Carries
+ *     the body bytes (plaintext or ciphertext), AEAD nonce + tag, and
+ *     `payloadHash = keccak256(bodyBytes)` for on-chain anchoring.
+ *
+ * Both objects use a *signed projection* + *wire envelope* split:
+ *   - The *signed* object is the canonical EIP-712 payload — exact byte
+ *     ordering and field layout matter for cross-SDK interoperability.
+ *   - The *wire* object wraps it with the signature and optional relay
+ *     server metadata for transport.
+ *
+ * ## Critical conventions
+ *
+ * - **EIP-712 domain**: ALWAYS `{name: "AGIRAILS Delivery", version: "1",
+ *   chainId, verifyingContract: kernelAddress}`. Domain reuse across
+ *   AIP features (negotiation, receipts) would enable cross-feature
+ *   signature replay.
+ *
+ * - **Canonical empty values**: For `scheme: "public-v1"`, the encryption
+ *   fields (`providerEphemeralPubkey`, `nonce`, `tag`) MUST be canonical
+ *   empty (zero-filled bytes of the correct length), NOT omitted. EIP-712
+ *   has no concept of an "absent" field — the type schema is fixed and
+ *   every field has a value.
+ *
+ * - **Smart wallet two-step auth**: `signerAddress` is the EOA that
+ *   produced the signature; `requesterAddress` / `providerAddress` is the
+ *   on-chain participant (which may be a Smart Wallet — a contract that
+ *   does not itself sign). Verification recovers the EOA from the
+ *   signature, then checks either equality with the participant OR that
+ *   the participant is the Smart Wallet derived from the EOA.
+ *
+ * - **Address comparisons** are always case-insensitive (.toLowerCase()).
+ *
+ * - **Field order in EIP-712 types is IMMUTABLE.** Any reordering of
+ *   fields in `DeliverySetupSignedV1` or `DeliveryEnvelopeSignedV1`
+ *   constitutes a breaking SDK change because both client and server
+ *   must encode byte-for-byte identical typed-data structures.
+ *
+ * @module delivery/types
+ * @see {@link https://eips.ethereum.org/EIPS/eip-712 EIP-712 Typed Structured Data}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc5869 RFC 5869 — HKDF}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7748 RFC 7748 — X25519}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_EMPTY_BYTES16 = exports.CANONICAL_EMPTY_BYTES12 = exports.CANONICAL_EMPTY_BYTES32 = void 0;
+// ============================================================================
+// Canonical Empty Value Constants
+// ============================================================================
+/**
+ * Canonical empty `bytes32` value: 32 zero bytes, hex-encoded.
+ *
+ * Used as the value of `buyerEphemeralPubkey` (in setups) and
+ * `providerEphemeralPubkey` / `payloadHash` slots whenever the field is
+ * scheme-irrelevant. EIP-712 has no concept of an absent field; every
+ * field in the typed schema has a value, so we use a canonical
+ * "no-data" sentinel that hashes to a known, predictable value.
+ *
+ * Specifically for `public-v1` envelopes:
+ *  - `providerEphemeralPubkey` MUST equal this constant.
+ *
+ * For setups with `expectedPrivacy: "public"`:
+ *  - `buyerEphemeralPubkey` MUST equal this constant.
+ *
+ * NOTE: `payloadHash` is NEVER canonical-empty in practice — even an
+ * empty body produces `keccak256("") = 0xc5d2…`. The constant is
+ * exported for type-level uniformity, not because `payloadHash` is
+ * ever zero.
+ *
+ * @example
+ * ```typescript
+ * // 0x0000000000000000000000000000000000000000000000000000000000000000
+ * console.log(CANONICAL_EMPTY_BYTES32);
+ * ```
+ */
+exports.CANONICAL_EMPTY_BYTES32 = ('0x' + '00'.repeat(32));
+/**
+ * Canonical empty `bytes12` value: 12 zero bytes, hex-encoded.
+ *
+ * Used for the AES-GCM `nonce` field when `scheme: "public-v1"` (the
+ * envelope is not encrypted, so there is no real nonce). Receivers
+ * MUST reject envelopes whose scheme is `public-v1` but whose `nonce`
+ * is NOT this constant.
+ *
+ * For `x25519-aes256gcm-v1`, `nonce` MUST be 12 random bytes — never
+ * this constant; a zero nonce under a real key catastrophically breaks
+ * AES-GCM (key recovery via tag forgery).
+ *
+ * @example
+ * ```typescript
+ * // 0x000000000000000000000000
+ * console.log(CANONICAL_EMPTY_BYTES12);
+ * ```
+ */
+exports.CANONICAL_EMPTY_BYTES12 = ('0x' + '00'.repeat(12));
+/**
+ * Canonical empty `bytes16` value: 16 zero bytes, hex-encoded.
+ *
+ * Used for the AES-GCM authentication `tag` field when
+ * `scheme: "public-v1"` (no encryption, no tag). Receivers MUST
+ * reject envelopes whose scheme is `public-v1` but whose `tag` is
+ * NOT this constant.
+ *
+ * @example
+ * ```typescript
+ * // 0x00000000000000000000000000000000
+ * console.log(CANONICAL_EMPTY_BYTES16);
+ * ```
+ */
+exports.CANONICAL_EMPTY_BYTES16 = ('0x' + '00'.repeat(16));
+// ============================================================================
+// Domain Constants
+// ============================================================================
+//
+// The EIP-712 domain ("AGIRAILS Delivery") and the typed-data schemas
+// (DeliverySetupV1, DeliveryEnvelopeV1) are intentionally defined in
+// `src/delivery/eip712.ts` — they are the contract surface between
+// signer, verifier, and Platform server, and live with the helpers that
+// build and verify the signatures. Importing them from a single
+// location keeps domain-string discipline tight.
+//
+// (No domain constants are re-exported here; consumers should import
+// directly from `src/delivery/eip712`.)
+//# sourceMappingURL=types.js.map

package/dist/delivery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/delivery/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;;;AAgrBH,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACU,QAAA,uBAAuB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAkB,CAAC;AAEjF;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,uBAAuB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAkB,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACU,QAAA,uBAAuB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAkB,CAAC;AAEjF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAC/E,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,mEAAmE;AACnE,wEAAwE;AACxE,gEAAgE;AAChE,iDAAiD;AACjD,EAAE;AACF,qEAAqE;AACrE,wCAAwC"}

package/dist/delivery/validate.d.ts

@@ -0,0 +1,288 @@
+/**
+ * AIP-16 Delivery Surface — Runtime Validation (Phase 2a)
+ * ========================================================
+ *
+ * Pure, dependency-light runtime validators for the delivery surface
+ * wire and signed shapes. Used by:
+ *
+ *  - Buyer SDK when receiving a {@link DeliveryEnvelopeWireV1} from the
+ *    relay, before signature recovery and decryption.
+ *  - Provider SDK when receiving a {@link DeliverySetupWireV1} from the
+ *    relay, before signature recovery and ECDH key derivation.
+ *  - Server-side Platform routes that accept these objects over HTTP
+ *    (mirrored in Phase 2c so client and server share the same
+ *    validation contract — defense-in-depth against a malicious peer
+ *    or a buggy/older client).
+ *
+ * Design notes:
+ *
+ *  - Validators are PURE — they do not throw, do not perform I/O, do
+ *    not consult network state. They return a discriminated
+ *    {@link ValidationResult} so callers can branch cleanly.
+ *
+ *  - On the first failure the validator returns; we do NOT accumulate
+ *    error lists. The first structural defect makes downstream checks
+ *    meaningless and the order in which we check is deliberately
+ *    coarse → fine (top-level shape, then individual fields, then
+ *    cross-field invariants).
+ *
+ *  - The error string is a stable, machine-actionable identifier
+ *    (snake_case, no message punctuation). Higher layers map it to a
+ *    {@link DeliveryErrorCode} when they want a structured error.
+ *
+ *  - Field order in {@link DeliverySetupSignedV1} and
+ *    {@link DeliveryEnvelopeSignedV1} is part of the EIP-712 type hash
+ *    and therefore part of the cross-SDK contract. The validators here
+ *    do NOT enforce order (it cannot be enforced on a parsed
+ *    JavaScript object), but they DO enforce the *presence and type*
+ *    of every field — which is sufficient to guarantee that signature
+ *    recovery has a well-formed input.
+ *
+ *  - Canonical-empty rule: for `scheme: "public-v1"`, the
+ *    encryption-related slots (`providerEphemeralPubkey`, `nonce`,
+ *    `tag`) MUST be the canonical zero-filled values of the correct
+ *    length — NOT omitted, NOT non-zero. This is enforced by
+ *    {@link validateSchemeConsistency} after the per-field validators
+ *    pass.
+ *
+ * @module delivery/validate
+ * @see ./types — the underlying signed/wire interfaces
+ * @see ./eip712 — domain + signed-type schemas (kept in lock-step)
+ */
+import { type DeliveryEnvelopeSignedV1, type DeliveryEnvelopeWireV1, type DeliveryPrivacy, type DeliveryScheme, type DeliverySetupSignedV1, type DeliverySetupWireV1, type ParticipantRole } from './types';
+/**
+ * Discriminated-union result of every validator in this module.
+ *
+ * - `{ ok: true }` — the object satisfies all structural and field-level
+ *   invariants enforced here. The caller MAY proceed to signature
+ *   recovery, smart-wallet auth, decryption, etc.
+ *
+ * - `{ ok: false, error }` — the object failed at least one invariant.
+ *   `error` is a stable snake_case identifier suitable for logging,
+ *   metric labels, and mapping to a {@link DeliveryErrorCode}.
+ *
+ * Errors are surfaced as VALUES (not exceptions) because every call
+ * site here is hot-path validation of untrusted input from the relay
+ * or a peer SDK — throwing would force every caller into a try/catch
+ * just to branch on a boolean.
+ */
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * True iff `s` is a string of exactly `0x` + 64 hex characters
+ * (case-insensitive), i.e. a well-formed `bytes32` hex value.
+ *
+ * Does NOT enforce lowercase — both lower and upper hex digits are
+ * accepted. Higher layers (signature recovery, canonical-empty
+ * checks) are responsible for case normalization where it matters.
+ */
+export declare function isValidBytes32(s: unknown): s is `0x${string}`;
+/**
+ * True iff `s` is a string of exactly `0x` + 24 hex characters
+ * (case-insensitive), i.e. a well-formed `bytes12` value — the
+ * AES-GCM nonce length.
+ */
+export declare function isValidBytes12(s: unknown): s is `0x${string}`;
+/**
+ * True iff `s` is a string of exactly `0x` + 32 hex characters
+ * (case-insensitive), i.e. a well-formed `bytes16` value — the
+ * AES-GCM authentication tag length.
+ */
+export declare function isValidBytes16(s: unknown): s is `0x${string}`;
+/**
+ * True iff `s` is a string that `ethers.isAddress` accepts as an EVM
+ * address. Accepts both lowercase and EIP-55 mixed-case checksummed
+ * addresses. `ethers.isAddress` returns false on invalid checksums,
+ * so a mixed-case address whose case is wrong is rejected here too —
+ * which is the intended behaviour.
+ *
+ * NOTE: We do NOT enforce a particular case at this layer; callers
+ * that need canonical (lowercase) comparison MUST `.toLowerCase()`
+ * both sides themselves, per the repo-wide convention.
+ */
+export declare function isValidAddress(s: unknown): s is `0x${string}`;
+/**
+ * True iff `s` is a decimal-string representation of a non-negative
+ * integer with no leading zeros (other than the literal `"0"`).
+ *
+ * Exists for forward-compat with future receipts-style integer
+ * fields that must round-trip across JSON without losing precision
+ * (JavaScript numbers cannot represent uint256 values).
+ */
+export declare function isValidUintString(s: unknown): boolean;
+/**
+ * True iff `s` is one of the {@link DeliveryScheme} discriminants.
+ * Type guard so downstream code can branch on `scheme` with
+ * exhaustiveness.
+ */
+export declare function isValidScheme(s: unknown): s is DeliveryScheme;
+/**
+ * True iff `s` is one of the {@link DeliveryPrivacy} discriminants.
+ */
+export declare function isValidPrivacy(s: unknown): s is DeliveryPrivacy;
+/**
+ * True iff `s` is one of the {@link ParticipantRole} discriminants.
+ */
+export declare function isValidRole(s: unknown): s is ParticipantRole;
+/**
+ * True iff `s` is the canonical empty bytes32 value (32 zero bytes,
+ * hex-encoded). Comparison is case-insensitive — the canonical form
+ * itself is all-zero so case is moot, but accepting `0x0000…` and
+ * `0x0000…` (uppercase X is not valid per regex) consistently is
+ * cheapest with a single `.toLowerCase()`.
+ *
+ * Used by {@link validateSchemeConsistency} to enforce the
+ * `public-v1` canonical-empty rule on `providerEphemeralPubkey`
+ * and (in setups) `buyerEphemeralPubkey`.
+ */
+export declare function isCanonicalEmptyBytes32(s: string): boolean;
+/**
+ * True iff `s` is the canonical empty bytes12 value (12 zero bytes,
+ * hex-encoded). Used to enforce the `public-v1` canonical-empty rule
+ * on the AES-GCM `nonce` slot.
+ */
+export declare function isCanonicalEmptyBytes12(s: string): boolean;
+/**
+ * True iff `s` is the canonical empty bytes16 value (16 zero bytes,
+ * hex-encoded). Used to enforce the `public-v1` canonical-empty rule
+ * on the AES-GCM authentication `tag` slot.
+ */
+export declare function isCanonicalEmptyBytes16(s: string): boolean;
+/**
+ * Validate a {@link DeliverySetupSignedV1} object's structure and
+ * field-level invariants.
+ *
+ * Checks performed (in order):
+ *
+ *  1. Top-level shape is a non-null object.
+ *  2. `version === 1` exactly (integer-equal, not string-equal).
+ *  3. `txId` is a well-formed bytes32 hex string.
+ *  4. `chainId` is a positive integer.
+ *  5. `kernelAddress`, `requesterAddress`, `signerAddress` are valid
+ *     EVM addresses (case-insensitive per `ethers.isAddress`).
+ *  6. `buyerEphemeralPubkey` is a well-formed bytes32 hex string.
+ *  7. `acceptedChannels` is a non-empty bounded array of non-empty
+ *     bounded strings.
+ *  8. `expectedPrivacy` is one of the {@link DeliveryPrivacy} values.
+ *  9. `createdAt`, `expiresAt` are positive integers (Unix seconds).
+ * 10. `expiresAt > createdAt` (cross-field).
+ *
+ * Does NOT verify the signature, the chainId↔network mapping, the
+ * smart-wallet derivation, the kernel allowlist, or the canonical-
+ * empty rule for `buyerEphemeralPubkey` against `expectedPrivacy` —
+ * those are the responsibility of higher layers (signature recovery,
+ * verifier modules, scheme-consistency in {@link validateSchemeConsistency}
+ * for envelopes; setup-side privacy/pubkey consistency is enforced
+ * by the setup verifier in Phase 2b).
+ *
+ * @param obj — value of `unknown` static type (validated at runtime).
+ * @returns {@link ValidationResult}.
+ */
+export declare function validateSetupSigned(obj: unknown): ValidationResult;
+/**
+ * Validate a {@link DeliverySetupWireV1} object's structure.
+ *
+ * Checks performed (in order):
+ *
+ *  1. Top-level shape is a non-null object.
+ *  2. `signed` validates as a {@link DeliverySetupSignedV1}.
+ *  3. `requesterSig` is a string starting with `0x` and of even hex
+ *     length consistent with a typical 65-byte EIP-712 signature
+ *     (132 hex chars + `0x` = 134 chars). We accept any `0x`-hex
+ *     string of plausible signature length; the actual cryptographic
+ *     validity is checked by `ethers.verifyTypedData` in the
+ *     recovery helpers — there is no point duplicating that here.
+ *  4. `serverMeta`, if present, is an object with `receivedAt`
+ *     (non-empty string) and `relayId` (non-empty string). Absence
+ *     is fine — `serverMeta` is set by the relay on read and is not
+ *     present on freshly built setups.
+ *
+ * @param obj — value of `unknown` static type.
+ * @returns {@link ValidationResult}.
+ */
+export declare function validateSetupWire(obj: unknown): ValidationResult;
+/**
+ * Validate a {@link DeliveryEnvelopeSignedV1} object's structure and
+ * field-level invariants.
+ *
+ * Checks performed (in order):
+ *
+ *  1. Top-level shape is a non-null object.
+ *  2. `version === 1` exactly.
+ *  3. `txId` is a well-formed bytes32 hex string.
+ *  4. `chainId` is a positive integer.
+ *  5. `kernelAddress`, `providerAddress`, `signerAddress` are valid
+ *     EVM addresses.
+ *  6. `scheme` is one of the {@link DeliveryScheme} discriminants.
+ *  7. `providerEphemeralPubkey` is a well-formed bytes32 hex string.
+ *  8. `nonce` is a well-formed bytes12 hex string.
+ *  9. `payloadHash` is a well-formed bytes32 hex string.
+ * 10. `tag` is a well-formed bytes16 hex string.
+ * 11. `createdAt` is a positive integer.
+ * 12. Scheme/canonical-empty consistency via
+ *     {@link validateSchemeConsistency}.
+ *
+ * Does NOT verify the signature, recompute `payloadHash`, or
+ * decrypt — those happen in higher layers.
+ *
+ * @param obj — value of `unknown` static type.
+ * @returns {@link ValidationResult}.
+ */
+export declare function validateEnvelopeSigned(obj: unknown): ValidationResult;
+/**
+ * Validate a {@link DeliveryEnvelopeWireV1} object's structure.
+ *
+ * Checks performed (in order):
+ *
+ *  1. Top-level shape is a non-null object.
+ *  2. `signed` validates as a {@link DeliveryEnvelopeSignedV1}
+ *     (which includes the scheme/canonical-empty consistency check).
+ *  3. `body` is a string. For `public-v1` this is plaintext UTF-8
+ *     JSON; for `x25519-aes256gcm-v1` this is base64-encoded
+ *     ciphertext. We do NOT verify base64-ness here because the
+ *     receiver will discover any malformed encoding when it
+ *     recomputes `payloadHash`. We DO insist on non-empty — an
+ *     empty body would imply the provider sent nothing.
+ *  4. `providerSig` is a `0x`-hex string of plausible signature length.
+ *  5. `serverMeta`, if present, is well-formed.
+ *
+ * @param obj — value of `unknown` static type.
+ * @returns {@link ValidationResult}.
+ */
+export declare function validateEnvelopeWire(obj: unknown): ValidationResult;
+/**
+ * Cross-field check enforcing the AIP-16 canonical-empty rule on a
+ * {@link DeliveryEnvelopeSignedV1}.
+ *
+ * Rule:
+ *
+ *  - `scheme === "public-v1"` →
+ *      `providerEphemeralPubkey === CANONICAL_EMPTY_BYTES32` AND
+ *      `nonce === CANONICAL_EMPTY_BYTES12` AND
+ *      `tag === CANONICAL_EMPTY_BYTES16`.
+ *
+ *  - `scheme === "x25519-aes256gcm-v1"` →
+ *      `providerEphemeralPubkey` MUST NOT be canonical empty (a zero
+ *      X25519 public key cannot produce a usable shared secret —
+ *      RFC 7748 §6.1 actually requires implementations to reject it)
+ *      AND `nonce` MUST NOT be canonical empty (a zero AES-GCM nonce
+ *      under a real key catastrophically breaks GCM) AND `tag` MUST
+ *      NOT be canonical empty (a zero 128-bit tag has ~2^-128 chance
+ *      of matching, so this is effectively a signal that the
+ *      provider built the envelope incorrectly).
+ *
+ * This validator assumes the underlying field types are already
+ * correct (length, hex shape) — callers must run
+ * {@link validateEnvelopeSigned} first, which is also where this is
+ * invoked from automatically.
+ *
+ * @param env — already-shape-validated envelope.
+ * @returns {@link ValidationResult}.
+ */
+export declare function validateSchemeConsistency(env: DeliveryEnvelopeSignedV1): ValidationResult;
+export type { DeliveryEnvelopeSignedV1, DeliveryEnvelopeWireV1, DeliverySetupSignedV1, DeliverySetupWireV1, };
+//# sourceMappingURL=validate.d.ts.map

package/dist/delivery/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/delivery/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,OAAO,EAIL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAgFjC;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAE7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAE7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAE/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAE5D;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CA0DlE;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CA4BhE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CA6DrE;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAgCnE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,wBAAwB,GAC5B,gBAAgB,CA8BlB;AA+CD,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,CAAC"}