@4mica/sdk 0.5.6 → 1.0.1

package/dist/contract.d.ts

@@ -9,16 +9,26 @@ type CoreContract = GetContractReturnType<typeof core4micaAbi, {
 export type TxReceiptWaitOptions = {
     timeout?: number;
     pollingInterval?: number;
+    gas?: bigint;
 };
 export declare class ContractGateway {
     readonly publicClient: TPublicClient;
     readonly walletClient: TWalletClient;
     readonly contract: CoreContract;
     private erc20Cache;
+    private txQueue;
     private constructor();
     static create(rpcUrl: string, signer: Account, contractAddress: Hex, chainId: number): Promise<ContractGateway>;
     private erc20;
+    private enqueueTx;
+    private defaultFeeParams;
+    private splitWaitOptions;
     getGuaranteeDomain(): Promise<string>;
+    getGuaranteeVersionConfig(version: number): Promise<{
+        domainSeparator: string;
+        decoder: string;
+        enabled: boolean;
+    }>;
     approveErc20(token: string, amount: number | bigint | string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
     deposit(amount: number | bigint | string, erc20Token?: string, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
     getUserAssets(): Promise<{

package/dist/contract.js

@@ -4,12 +4,17 @@ exports.ContractGateway = void 0;
 const viem_1 = require("viem");
 const core4mica_1 = require("./abi/core4mica");
 const chain_1 = require("./chain");
+const errors_1 = require("./errors");
 const utils_1 = require("./utils");
+const DEFAULT_REMUNERATE_GAS_LIMIT = 8000000n;
+const DEFAULT_MAX_FEE_PER_GAS = (0, viem_1.parseGwei)('0.1');
+const DEFAULT_MAX_PRIORITY_FEE_PER_GAS = (0, viem_1.parseGwei)('0.1');
 class ContractGateway {
     publicClient;
     walletClient;
     contract;
     erc20Cache = new Map();
+    txQueue = Promise.resolve();
     constructor(publicClient, walletClient, contract) {
         this.publicClient = publicClient;
         this.walletClient = walletClient;
@@ -22,7 +27,7 @@ class ContractGateway {
         });
         const rpcChainId = await publicClient.getChainId();
         if (rpcChainId !== Number(chainId)) {
-            throw new Error(`Connected to chain ${rpcChainId}, expected ${chainId}`);
+            throw new errors_1.ContractError(`Connected to chain ${rpcChainId}, expected ${chainId}`);
         }
         const walletClient = (0, viem_1.createWalletClient)({
             transport: (0, viem_1.http)(rpcUrl),
@@ -49,28 +54,63 @@ class ContractGateway {
         }
         return this.erc20Cache.get(token);
     }
+    enqueueTx(fn) {
+        // Serialize transaction submissions to avoid nonce collisions.
+        const run = this.txQueue.then(fn, fn);
+        this.txQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    defaultFeeParams() {
+        return {
+            maxFeePerGas: DEFAULT_MAX_FEE_PER_GAS,
+            maxPriorityFeePerGas: DEFAULT_MAX_PRIORITY_FEE_PER_GAS,
+        };
+    }
+    splitWaitOptions(waitOptions) {
+        if (!waitOptions) {
+            return { receipt: {} };
+        }
+        const { gas, timeout, pollingInterval } = waitOptions;
+        return {
+            gas,
+            receipt: {
+                ...(timeout !== undefined ? { timeout } : {}),
+                ...(pollingInterval !== undefined ? { pollingInterval } : {}),
+            },
+        };
+    }
     async getGuaranteeDomain() {
         return this.contract.read.guaranteeDomainSeparator();
     }
+    async getGuaranteeVersionConfig(version) {
+        const [, domainSeparator, decoder, enabled] = await this.contract.read.getGuaranteeVersionConfig([BigInt(version)]);
+        return { domainSeparator: domainSeparator, decoder: decoder, enabled };
+    }
     async approveErc20(token, amount, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         const erc20 = this.erc20(token);
         // spender address logic
         const spender = this.contract.address;
-        const hash = await erc20.write.approve([spender, (0, utils_1.parseU256)(amount)]);
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        const hash = await this.enqueueTx(() => erc20.write.approve([spender, (0, utils_1.parseU256)(amount)], this.defaultFeeParams()));
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async deposit(amount, erc20Token, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         let hash;
         if (erc20Token) {
-            hash = await this.contract.write.depositStablecoin([erc20Token, (0, utils_1.parseU256)(amount)]);
+            hash = await this.enqueueTx(() => this.contract.write.depositStablecoin([erc20Token, (0, utils_1.parseU256)(amount)], this.defaultFeeParams()));
         }
         else {
-            hash = await this.contract.write.deposit({ value: (0, utils_1.parseU256)(amount) });
+            hash = await this.enqueueTx(() => this.contract.write.deposit({ value: (0, utils_1.parseU256)(amount), ...this.defaultFeeParams() }));
         }
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async getUserAssets() {
-        const addr = this.walletClient.account.address;
+        const account = this.walletClient.account;
+        if (!account) {
+            throw new errors_1.ContractError('wallet client has no account configured');
+        }
+        const addr = account.address;
         const result = await this.contract.read.getUserAllAssets([addr]);
         return result.map((a) => ({
             asset: a.asset,
@@ -90,55 +130,62 @@ class ContractGateway {
         };
     }
     async payTabEth(tabId, reqId, amount, recipient, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         const data = new TextEncoder().encode(`tab_id:${tabId.toString(16)};req_id:${reqId.toString(16)}`);
-        const hash = await this.walletClient.sendTransaction({
+        const hash = await this.enqueueTx(() => this.walletClient.sendTransaction({
             to: recipient,
             value: (0, utils_1.parseU256)(amount),
             data: (0, utils_1.hexFromBytes)(data),
-        });
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+            ...this.defaultFeeParams(),
+        }));
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async payTabErc20(tabId, amount, erc20Token, recipient, waitOptions) {
-        const hash = await this.contract.write.payTabInERC20Token([
+        const { receipt } = this.splitWaitOptions(waitOptions);
+        const hash = await this.enqueueTx(() => this.contract.write.payTabInERC20Token([
             (0, utils_1.parseU256)(tabId),
             erc20Token,
             (0, utils_1.parseU256)(amount),
             recipient,
-        ]);
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        ], this.defaultFeeParams()));
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async requestWithdrawal(amount, erc20Token, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         const value = (0, utils_1.parseU256)(amount);
         let hash;
         if (erc20Token) {
-            hash = await this.contract.write.requestWithdrawal([erc20Token, value]);
+            hash = await this.enqueueTx(() => this.contract.write.requestWithdrawal([erc20Token, value], this.defaultFeeParams()));
         }
         else {
-            hash = await this.contract.write.requestWithdrawal([value]);
+            hash = await this.enqueueTx(() => this.contract.write.requestWithdrawal([value], this.defaultFeeParams()));
         }
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async cancelWithdrawal(erc20Token, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         let hash;
         if (erc20Token) {
-            hash = await this.contract.write.cancelWithdrawal([erc20Token]);
+            hash = await this.enqueueTx(() => this.contract.write.cancelWithdrawal([erc20Token], this.defaultFeeParams()));
         }
         else {
-            hash = await this.contract.write.cancelWithdrawal();
+            hash = await this.enqueueTx(() => this.contract.write.cancelWithdrawal(this.defaultFeeParams()));
         }
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async finalizeWithdrawal(erc20Token, waitOptions) {
+        const { receipt } = this.splitWaitOptions(waitOptions);
         let hash;
         if (erc20Token) {
-            hash = await this.contract.write.finalizeWithdrawal([erc20Token]);
+            hash = await this.enqueueTx(() => this.contract.write.finalizeWithdrawal([erc20Token], this.defaultFeeParams()));
         }
         else {
-            hash = await this.contract.write.finalizeWithdrawal();
+            hash = await this.enqueueTx(() => this.contract.write.finalizeWithdrawal(this.defaultFeeParams()));
         }
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async remunerate(claimsBlob, signatureWords, waitOptions) {
+        const { gas, receipt } = this.splitWaitOptions(waitOptions);
         const sigStruct = {
             x_c0_a: (0, utils_1.hexFromBytes)(signatureWords[0]),
             x_c0_b: (0, utils_1.hexFromBytes)(signatureWords[1]),
@@ -149,8 +196,11 @@ class ContractGateway {
             y_c1_a: (0, utils_1.hexFromBytes)(signatureWords[6]),
             y_c1_b: (0, utils_1.hexFromBytes)(signatureWords[7]),
         };
-        const hash = await this.contract.write.remunerate([(0, utils_1.hexFromBytes)(claimsBlob), sigStruct]);
-        return this.publicClient.waitForTransactionReceipt({ hash, ...(waitOptions ?? {}) });
+        const hash = await this.enqueueTx(() => this.contract.write.remunerate([(0, utils_1.hexFromBytes)(claimsBlob), sigStruct], {
+            gas: gas ?? DEFAULT_REMUNERATE_GAS_LIMIT,
+            ...this.defaultFeeParams(),
+        }));
+        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
 }
 exports.ContractGateway = ContractGateway;

package/dist/errors.d.ts

@@ -1,8 +1,11 @@
+/** Base class for all 4Mica SDK errors. Sets `error.name` to the subclass name. */
 export declare class FourMicaError extends Error {
     constructor(message: string);
 }
+/** Thrown when the SDK configuration is invalid (e.g. missing required fields or bad URL). */
 export declare class ConfigError extends FourMicaError {
 }
+/** Thrown when a 4Mica core RPC call fails. Includes the HTTP status and raw response body. */
 export declare class RpcError extends FourMicaError {
     readonly status?: number;
     readonly body?: unknown;
@@ -11,24 +14,34 @@ export declare class RpcError extends FourMicaError {
         body?: unknown;
     });
 }
+/** Thrown when the SDK client fails to initialise (e.g. chain ID mismatch). */
 export declare class ClientInitializationError extends FourMicaError {
 }
+/** Thrown when signing a payment claim fails (e.g. unsupported scheme, address mismatch). */
 export declare class SigningError extends FourMicaError {
 }
+/** Thrown when an on-chain contract call fails or returns an unexpected result. */
 export declare class ContractError extends FourMicaError {
 }
+/** Thrown when BLS certificate verification fails (e.g. domain mismatch, invalid encoding). */
 export declare class VerificationError extends FourMicaError {
 }
+/** Thrown when an x402 HTTP payment flow encounters an error. */
 export declare class X402Error extends FourMicaError {
 }
+/** Base class for authentication-related errors. */
 export declare class AuthError extends FourMicaError {
 }
+/** Thrown when the auth URL is invalid or unreachable. */
 export declare class AuthUrlError extends AuthError {
 }
+/** Thrown when a network-level error occurs during authentication. */
 export declare class AuthTransportError extends AuthError {
 }
+/** Thrown when the auth server response cannot be decoded. */
 export declare class AuthDecodeError extends AuthError {
 }
+/** Thrown when the auth server returns an error response. Includes HTTP status and body. */
 export declare class AuthApiError extends AuthError {
     readonly status?: number;
     readonly body?: unknown;
@@ -37,7 +50,9 @@ export declare class AuthApiError extends AuthError {
         body?: unknown;
     });
 }
+/** Thrown when auth configuration is invalid. */
 export declare class AuthConfigError extends AuthError {
 }
+/** Thrown when an authenticated operation is attempted without auth being configured. */
 export declare class AuthMissingConfigError extends AuthConfigError {
 }

package/dist/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthMissingConfigError = exports.AuthConfigError = exports.AuthApiError = exports.AuthDecodeError = exports.AuthTransportError = exports.AuthUrlError = exports.AuthError = exports.X402Error = exports.VerificationError = exports.ContractError = exports.SigningError = exports.ClientInitializationError = exports.RpcError = exports.ConfigError = exports.FourMicaError = void 0;
+/** Base class for all 4Mica SDK errors. Sets `error.name` to the subclass name. */
 class FourMicaError extends Error {
     constructor(message) {
         super(message);
@@ -8,9 +9,11 @@ class FourMicaError extends Error {
     }
 }
 exports.FourMicaError = FourMicaError;
+/** Thrown when the SDK configuration is invalid (e.g. missing required fields or bad URL). */
 class ConfigError extends FourMicaError {
 }
 exports.ConfigError = ConfigError;
+/** Thrown when a 4Mica core RPC call fails. Includes the HTTP status and raw response body. */
 class RpcError extends FourMicaError {
     status;
     body;
@@ -21,33 +24,43 @@ class RpcError extends FourMicaError {
     }
 }
 exports.RpcError = RpcError;
+/** Thrown when the SDK client fails to initialise (e.g. chain ID mismatch). */
 class ClientInitializationError extends FourMicaError {
 }
 exports.ClientInitializationError = ClientInitializationError;
+/** Thrown when signing a payment claim fails (e.g. unsupported scheme, address mismatch). */
 class SigningError extends FourMicaError {
 }
 exports.SigningError = SigningError;
+/** Thrown when an on-chain contract call fails or returns an unexpected result. */
 class ContractError extends FourMicaError {
 }
 exports.ContractError = ContractError;
+/** Thrown when BLS certificate verification fails (e.g. domain mismatch, invalid encoding). */
 class VerificationError extends FourMicaError {
 }
 exports.VerificationError = VerificationError;
+/** Thrown when an x402 HTTP payment flow encounters an error. */
 class X402Error extends FourMicaError {
 }
 exports.X402Error = X402Error;
+/** Base class for authentication-related errors. */
 class AuthError extends FourMicaError {
 }
 exports.AuthError = AuthError;
+/** Thrown when the auth URL is invalid or unreachable. */
 class AuthUrlError extends AuthError {
 }
 exports.AuthUrlError = AuthUrlError;
+/** Thrown when a network-level error occurs during authentication. */
 class AuthTransportError extends AuthError {
 }
 exports.AuthTransportError = AuthTransportError;
+/** Thrown when the auth server response cannot be decoded. */
 class AuthDecodeError extends AuthError {
 }
 exports.AuthDecodeError = AuthDecodeError;
+/** Thrown when the auth server returns an error response. Includes HTTP status and body. */
 class AuthApiError extends AuthError {
     status;
     body;
@@ -58,9 +71,11 @@ class AuthApiError extends AuthError {
     }
 }
 exports.AuthApiError = AuthApiError;
+/** Thrown when auth configuration is invalid. */
 class AuthConfigError extends AuthError {
 }
 exports.AuthConfigError = AuthConfigError;
+/** Thrown when an authenticated operation is attempted without auth being configured. */
 class AuthMissingConfigError extends AuthConfigError {
 }
 exports.AuthMissingConfigError = AuthMissingConfigError;

package/dist/guarantee.d.ts

@@ -1,3 +1,25 @@
 import { PaymentGuaranteeClaims } from './models';
+/**
+ * ABI-encode a {@link PaymentGuaranteeClaims} object into a hex string.
+ *
+ * Produces the outer `(uint64 version, bytes innerClaims)` envelope format expected
+ * by the Core4Mica contract. Supports V1 (10 fields) and V2 (18 fields with validation policy).
+ *
+ * @param claims - Decoded claims to encode. Must have `version` set to `1` or `2`.
+ * @returns `0x`-prefixed hex string of the ABI-encoded envelope.
+ * @throws {@link VerificationError} if `version` is not `1` or `2`, the domain is not 32 bytes,
+ *   or V2 claims are missing `validationPolicy`.
+ */
 export declare function encodeGuaranteeClaims(claims: PaymentGuaranteeClaims): string;
+/**
+ * Decode ABI-encoded guarantee claims into a {@link PaymentGuaranteeClaims} object.
+ *
+ * Accepts either the modern `(uint64 version, bytes innerClaims)` envelope or the legacy
+ * unwrapped V1 format (raw 320-byte ABI encoding without an outer envelope).
+ *
+ * @param data - Hex string or raw bytes of the ABI-encoded claims.
+ * @returns Decoded {@link PaymentGuaranteeClaims} with `version` set to `1` or `2`.
+ * @throws {@link VerificationError} if the data is too short, the inner length is wrong,
+ *   or the encoded version number is unsupported.
+ */
 export declare function decodeGuaranteeClaims(data: string | Uint8Array): PaymentGuaranteeClaims;

package/dist/guarantee.js

@@ -6,7 +6,8 @@ const viem_1 = require("viem");
 const errors_1 = require("./errors");
 const utils_1 = require("./utils");
 const CLAIMS_ENCODED_BYTES = 32 * 10;
-const WRAPPED_CLAIMS_BYTES = 32 * 2 + 32 + CLAIMS_ENCODED_BYTES;
+// Minimum bytes for a valid outer envelope: uint64 + bytes offset + bytes length
+const MIN_ENVELOPE_BYTES = 32 * 2 + 32;
 const CLAIM_TYPES = [
     { type: 'bytes32' },
     { type: 'uint256' },
@@ -19,6 +20,54 @@ const CLAIM_TYPES = [
     { type: 'uint64' },
     { type: 'uint64' },
 ];
+// V2 adds: validation_registry_address, validation_request_hash, validation_chain_id,
+//          validator_address, validator_agent_id, min_validation_score,
+//          validation_subject_hash, required_validation_tag (dynamic string)
+const CLAIM_TYPES_V2 = [
+    { type: 'bytes32' }, // domain
+    { type: 'uint256' }, // tab_id
+    { type: 'uint256' }, // req_id
+    { type: 'address' }, // client (user)
+    { type: 'address' }, // recipient
+    { type: 'uint256' }, // amount
+    { type: 'uint256' }, // total_amount
+    { type: 'address' }, // asset
+    { type: 'uint64' }, // timestamp
+    { type: 'uint64' }, // version
+    { type: 'address' }, // validation_registry_address
+    { type: 'bytes32' }, // validation_request_hash
+    { type: 'uint64' }, // validation_chain_id
+    { type: 'address' }, // validator_address
+    { type: 'uint256' }, // validator_agent_id
+    { type: 'uint8' }, // min_validation_score
+    { type: 'bytes32' }, // validation_subject_hash
+    { type: 'string' }, // required_validation_tag (dynamic)
+];
+const CLAIM_TYPES_V2_TUPLE = [
+    {
+        type: 'tuple',
+        components: [
+            { name: 'domain', type: 'bytes32' },
+            { name: 'tabId', type: 'uint256' },
+            { name: 'reqId', type: 'uint256' },
+            { name: 'user', type: 'address' },
+            { name: 'recipient', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+            { name: 'totalAmount', type: 'uint256' },
+            { name: 'asset', type: 'address' },
+            { name: 'timestamp', type: 'uint64' },
+            { name: 'claimsVersion', type: 'uint64' },
+            { name: 'validationRegistryAddress', type: 'address' },
+            { name: 'validationRequestHash', type: 'bytes32' },
+            { name: 'validationChainId', type: 'uint64' },
+            { name: 'validatorAddress', type: 'address' },
+            { name: 'validatorAgentId', type: 'uint256' },
+            { name: 'minValidationScore', type: 'uint8' },
+            { name: 'validationSubjectHash', type: 'bytes32' },
+            { name: 'requiredValidationTag', type: 'string' },
+        ],
+    },
+];
 function ensureDomainBytes(domain) {
     const bytes = typeof domain === 'string' ? (0, viem_1.toBytes)(domain) : domain;
     if (bytes.length !== 32) {
@@ -28,47 +77,115 @@ function ensureDomainBytes(domain) {
 }
 function normalizeHexBytes(data) {
     if (typeof data === 'string') {
-        return (data.startsWith('0x') ? data : `0x${data}`);
+        return (0, utils_1.ensureHexPrefix)(data);
     }
     return (0, utils_1.hexFromBytes)(data);
 }
+/**
+ * ABI-encode a {@link PaymentGuaranteeClaims} object into a hex string.
+ *
+ * Produces the outer `(uint64 version, bytes innerClaims)` envelope format expected
+ * by the Core4Mica contract. Supports V1 (10 fields) and V2 (18 fields with validation policy).
+ *
+ * @param claims - Decoded claims to encode. Must have `version` set to `1` or `2`.
+ * @returns `0x`-prefixed hex string of the ABI-encoded envelope.
+ * @throws {@link VerificationError} if `version` is not `1` or `2`, the domain is not 32 bytes,
+ *   or V2 claims are missing `validationPolicy`.
+ */
 function encodeGuaranteeClaims(claims) {
-    if (claims.version !== 1) {
-        throw new errors_1.VerificationError(`unsupported guarantee claims version: ${claims.version}`);
+    if (claims.version === 1) {
+        const domain = ensureDomainBytes(claims.domain);
+        const encoded = (0, viem_1.encodeAbiParameters)(CLAIM_TYPES, [
+            (0, utils_1.hexFromBytes)(domain),
+            (0, utils_1.parseU256)(claims.tabId),
+            (0, utils_1.parseU256)(claims.reqId),
+            claims.userAddress,
+            claims.recipientAddress,
+            (0, utils_1.parseU256)(claims.amount),
+            (0, utils_1.parseU256)(claims.totalAmount),
+            claims.assetAddress,
+            BigInt(claims.timestamp),
+            BigInt(claims.version),
+        ]);
+        return (0, viem_1.encodeAbiParameters)([{ type: 'uint64' }, { type: 'bytes' }], [BigInt(claims.version), encoded]);
+    }
+    if (claims.version === 2) {
+        if (!claims.validationPolicy) {
+            throw new errors_1.VerificationError('V2 guarantee claims missing validationPolicy');
+        }
+        const p = claims.validationPolicy;
+        const domain = ensureDomainBytes(claims.domain);
+        const encoded = (0, viem_1.encodeAbiParameters)(CLAIM_TYPES_V2_TUPLE, [
+            {
+                domain: (0, utils_1.hexFromBytes)(domain),
+                tabId: (0, utils_1.parseU256)(claims.tabId),
+                reqId: (0, utils_1.parseU256)(claims.reqId),
+                user: claims.userAddress,
+                recipient: claims.recipientAddress,
+                amount: (0, utils_1.parseU256)(claims.amount),
+                totalAmount: (0, utils_1.parseU256)(claims.totalAmount),
+                asset: claims.assetAddress,
+                timestamp: BigInt(claims.timestamp),
+                claimsVersion: BigInt(claims.version),
+                validationRegistryAddress: p.validationRegistryAddress,
+                validationRequestHash: (0, utils_1.ensureHexPrefix)(p.validationRequestHash),
+                validationChainId: BigInt(p.validationChainId),
+                validatorAddress: p.validatorAddress,
+                validatorAgentId: p.validatorAgentId,
+                minValidationScore: p.minValidationScore,
+                validationSubjectHash: (0, utils_1.ensureHexPrefix)(p.validationSubjectHash),
+                requiredValidationTag: p.requiredValidationTag,
+            },
+        ]);
+        return (0, viem_1.encodeAbiParameters)([{ type: 'uint64' }, { type: 'bytes' }], [BigInt(claims.version), encoded]);
     }
-    const domain = ensureDomainBytes(claims.domain);
-    const encoded = (0, viem_1.encodeAbiParameters)(CLAIM_TYPES, [
-        (0, utils_1.hexFromBytes)(domain),
-        (0, utils_1.parseU256)(claims.tabId),
-        (0, utils_1.parseU256)(claims.reqId),
-        claims.userAddress,
-        claims.recipientAddress,
-        (0, utils_1.parseU256)(claims.amount),
-        (0, utils_1.parseU256)(claims.totalAmount),
-        claims.assetAddress,
-        BigInt(claims.timestamp),
-        BigInt(claims.version),
-    ]);
-    return (0, viem_1.encodeAbiParameters)([{ type: 'uint64' }, { type: 'bytes' }], [BigInt(claims.version), encoded]);
+    throw new errors_1.VerificationError(`unsupported guarantee claims version: ${claims.version}`);
 }
+/**
+ * Decode ABI-encoded guarantee claims into a {@link PaymentGuaranteeClaims} object.
+ *
+ * Accepts either the modern `(uint64 version, bytes innerClaims)` envelope or the legacy
+ * unwrapped V1 format (raw 320-byte ABI encoding without an outer envelope).
+ *
+ * @param data - Hex string or raw bytes of the ABI-encoded claims.
+ * @returns Decoded {@link PaymentGuaranteeClaims} with `version` set to `1` or `2`.
+ * @throws {@link VerificationError} if the data is too short, the inner length is wrong,
+ *   or the encoded version number is unsupported.
+ */
 function decodeGuaranteeClaims(data) {
     const hex = normalizeHexBytes(data);
     const byteLen = (hex.length - 2) / 2;
-    let encoded;
+    // Try to decode as unwrapped V1 (legacy)
     if (byteLen === CLAIMS_ENCODED_BYTES) {
-        encoded = hex;
+        return decodeV1Claims(hex);
     }
-    else {
-        if (byteLen !== WRAPPED_CLAIMS_BYTES) {
-            throw new errors_1.VerificationError(`unexpected guarantee claims length: ${byteLen} bytes`);
-        }
-        const [version, wrapped] = (0, viem_1.decodeAbiParameters)([{ type: 'uint64' }, { type: 'bytes' }], hex);
-        if (version !== 1n) {
-            throw new errors_1.VerificationError(`unsupported guarantee claims version: ${version}`);
+    // Decode outer envelope to get version
+    if (byteLen < MIN_ENVELOPE_BYTES) {
+        throw new errors_1.VerificationError(`unexpected guarantee claims length: ${byteLen} bytes`);
+    }
+    const [version, wrapped] = (0, viem_1.decodeAbiParameters)([{ type: 'uint64' }, { type: 'bytes' }], hex);
+    if (version === 1n) {
+        const innerHex = wrapped;
+        const innerByteLen = (innerHex.length - 2) / 2;
+        if (innerByteLen !== CLAIMS_ENCODED_BYTES) {
+            throw new errors_1.VerificationError(`unexpected V1 claims inner length: ${innerByteLen} bytes`);
         }
-        encoded = wrapped;
+        return decodeV1Claims(innerHex);
     }
-    const [domain, tabId, reqId, user, recipient, amount, totalAmount, asset, timestamp, claimsVersion,] = (0, viem_1.decodeAbiParameters)(CLAIM_TYPES, encoded);
+    if (version === 2n) {
+        return decodeV2Claims(wrapped);
+    }
+    throw new errors_1.VerificationError(`unsupported guarantee claims version: ${version}`);
+}
+function decodeV1Claims(encoded) {
+    let decoded;
+    try {
+        decoded = (0, viem_1.decodeAbiParameters)(CLAIM_TYPES, encoded);
+    }
+    catch (err) {
+        throw new errors_1.VerificationError(`failed to decode V1 guarantee claims: ${String(err)}`);
+    }
+    const [domain, tabId, reqId, user, recipient, amount, totalAmount, asset, timestamp, claimsVersion,] = decoded;
     if (claimsVersion !== 1n) {
         throw new errors_1.VerificationError(`unsupported guarantee claims version: ${claimsVersion}`);
     }
@@ -85,3 +202,66 @@ function decodeGuaranteeClaims(data) {
         version: Number(claimsVersion),
     };
 }
+function decodeV2Claims(encoded) {
+    try {
+        const [decoded] = (0, viem_1.decodeAbiParameters)(CLAIM_TYPES_V2_TUPLE, encoded);
+        return buildDecodedV2Claims(decoded);
+    }
+    catch (tupleErr) {
+        try {
+            const decoded = (0, viem_1.decodeAbiParameters)(CLAIM_TYPES_V2, encoded);
+            return buildDecodedV2Claims({
+                domain: decoded[0],
+                tabId: decoded[1],
+                reqId: decoded[2],
+                user: decoded[3],
+                recipient: decoded[4],
+                amount: decoded[5],
+                totalAmount: decoded[6],
+                asset: decoded[7],
+                timestamp: decoded[8],
+                claimsVersion: decoded[9],
+                validationRegistryAddress: decoded[10],
+                validationRequestHash: decoded[11],
+                validationChainId: decoded[12],
+                validatorAddress: decoded[13],
+                validatorAgentId: decoded[14],
+                minValidationScore: decoded[15],
+                validationSubjectHash: decoded[16],
+                requiredValidationTag: decoded[17],
+            });
+        }
+        catch (flatErr) {
+            throw new errors_1.VerificationError(`failed to decode V2 guarantee claims: ${String(tupleErr)}; fallback decode failed: ${String(flatErr)}`);
+        }
+    }
+}
+function buildDecodedV2Claims(decoded) {
+    const { domain, tabId, reqId, user, recipient, amount, totalAmount, asset, timestamp, claimsVersion, validationRegistryAddress, validationRequestHash, validationChainId, validatorAddress, validatorAgentId, minValidationScore, validationSubjectHash, requiredValidationTag, } = decoded;
+    if (claimsVersion !== 2n) {
+        throw new errors_1.VerificationError(`expected V2 claims version, got: ${claimsVersion}`);
+    }
+    const validationPolicy = {
+        validationRegistryAddress: validationRegistryAddress,
+        validationRequestHash: validationRequestHash,
+        validationChainId: Number(validationChainId),
+        validatorAddress: validatorAddress,
+        validatorAgentId: (0, utils_1.parseU256)(validatorAgentId),
+        minValidationScore: Number(minValidationScore),
+        validationSubjectHash: validationSubjectHash,
+        requiredValidationTag: requiredValidationTag,
+    };
+    return {
+        domain: (0, viem_1.toBytes)(domain),
+        userAddress: user,
+        recipientAddress: recipient,
+        tabId: (0, utils_1.parseU256)(tabId),
+        reqId: (0, utils_1.parseU256)(reqId),
+        amount: (0, utils_1.parseU256)(amount),
+        totalAmount: (0, utils_1.parseU256)(totalAmount),
+        assetAddress: asset,
+        timestamp: Number(timestamp),
+        version: Number(claimsVersion),
+        validationPolicy,
+    };
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './config';
 export * from './utils';
 export * from './models';
 export * from './payment';
+export * from './validation';
 export * from './signing';
 export * from './rpc';
 export * from './auth';

package/dist/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./config"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./models"), exports);
 __exportStar(require("./payment"), exports);
+__exportStar(require("./validation"), exports);
 __exportStar(require("./signing"), exports);
 __exportStar(require("./rpc"), exports);
 __exportStar(require("./auth"), exports);