@4mica/sdk 0.5.5 → 1.0.0

package/dist/signing.js

@@ -1,43 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PaymentSigner = exports.GUARANTEE_EIP712_TYPES = exports.CorePublicParameters = void 0;
+exports.PaymentSigner = exports.GUARANTEE_EIP712_TYPES_V2 = exports.GUARANTEE_EIP712_TYPES = exports.computeValidationRequestHash = exports.computeValidationSubjectHash = void 0;
 exports.validateGuaranteeTypedData = validateGuaranteeTypedData;
 exports.validateGuaranteeSigningContext = validateGuaranteeSigningContext;
 exports.buildGuaranteeTypedData = buildGuaranteeTypedData;
+exports.buildGuaranteeTypedDataV2 = buildGuaranteeTypedDataV2;
+exports.encodeGuaranteeEip191V2 = encodeGuaranteeEip191V2;
 exports.encodeGuaranteeEip191 = encodeGuaranteeEip191;
 const viem_1 = require("viem");
+var validation_1 = require("./validation");
+Object.defineProperty(exports, "computeValidationSubjectHash", { enumerable: true, get: function () { return validation_1.computeValidationSubjectHash; } });
+Object.defineProperty(exports, "computeValidationRequestHash", { enumerable: true, get: function () { return validation_1.computeValidationRequestHash; } });
 const errors_1 = require("./errors");
 const models_1 = require("./models");
 const utils_1 = require("./utils");
 const serde_1 = require("./serde");
-class CorePublicParameters {
-    publicKey;
-    contractAddress;
-    ethereumHttpRpcUrl;
-    eip712Name;
-    eip712Version;
-    chainId;
-    constructor(publicKey, contractAddress, ethereumHttpRpcUrl, eip712Name, eip712Version, chainId) {
-        this.publicKey = publicKey;
-        this.contractAddress = contractAddress;
-        this.ethereumHttpRpcUrl = ethereumHttpRpcUrl;
-        this.eip712Name = eip712Name;
-        this.eip712Version = eip712Version;
-        this.chainId = chainId;
-    }
-    static fromRpc(payload) {
-        const pkRaw = payload.public_key ?? payload.publicKey;
-        const pk = typeof pkRaw === 'string'
-            ? (0, viem_1.toBytes)(pkRaw)
-            : pkRaw instanceof Uint8Array
-                ? pkRaw
-                : Array.isArray(pkRaw)
-                    ? Uint8Array.from(pkRaw)
-                    : new Uint8Array();
-        return new CorePublicParameters(pk, String(payload.contract_address ?? payload.contractAddress ?? ''), String(payload.ethereum_http_rpc_url ?? payload.ethereumHttpRpcUrl ?? ''), (payload.eip712_name ?? payload.eip712Name ?? '4Mica'), (payload.eip712_version ?? payload.eip712Version ?? '1'), Number(payload.chain_id ?? payload.chainId));
-    }
-}
-exports.CorePublicParameters = CorePublicParameters;
 exports.GUARANTEE_EIP712_TYPES = {
     EIP712Domain: [
         { name: 'name', type: 'string' },
@@ -54,6 +31,30 @@ exports.GUARANTEE_EIP712_TYPES = {
         { name: 'timestamp', type: 'uint64' },
     ],
 };
+exports.GUARANTEE_EIP712_TYPES_V2 = {
+    EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+    ],
+    SolGuaranteeRequestClaimsV2: [
+        { name: 'user', type: 'address' },
+        { name: 'recipient', type: 'address' },
+        { name: 'tabId', type: 'uint256' },
+        { name: 'reqId', type: 'uint256' },
+        { name: 'amount', type: 'uint256' },
+        { name: 'asset', type: 'address' },
+        { name: 'timestamp', type: 'uint64' },
+        { name: 'validationRegistryAddress', type: 'address' },
+        { name: 'validationRequestHash', type: 'bytes32' },
+        { name: 'validationChainId', type: 'uint256' },
+        { name: 'validatorAddress', type: 'address' },
+        { name: 'validatorAgentId', type: 'uint256' },
+        { name: 'minValidationScore', type: 'uint8' },
+        { name: 'validationSubjectHash', type: 'bytes32' },
+        { name: 'requiredValidationTag', type: 'string' },
+    ],
+};
 const fieldsMatch = (actual, expected) => {
     if (!Array.isArray(actual) || actual.length !== expected.length)
         return false;
@@ -165,6 +166,73 @@ function buildGuaranteeTypedData(params, claims) {
         },
     };
 }
+function buildGuaranteeTypedDataV2(params, claims) {
+    return {
+        types: exports.GUARANTEE_EIP712_TYPES_V2,
+        primaryType: 'SolGuaranteeRequestClaimsV2',
+        domain: {
+            name: params.eip712Name,
+            version: params.eip712Version,
+            chainId: params.chainId,
+        },
+        message: {
+            user: claims.userAddress,
+            recipient: claims.recipientAddress,
+            tabId: claims.tabId,
+            reqId: claims.reqId,
+            amount: claims.amount,
+            asset: claims.assetAddress,
+            timestamp: BigInt(claims.timestamp),
+            validationRegistryAddress: claims.validationRegistryAddress,
+            validationRequestHash: (0, utils_1.ensureHexPrefix)(claims.validationRequestHash),
+            validationChainId: BigInt(claims.validationChainId),
+            validatorAddress: claims.validatorAddress,
+            validatorAgentId: claims.validatorAgentId,
+            minValidationScore: claims.minValidationScore,
+            validationSubjectHash: (0, utils_1.ensureHexPrefix)(claims.validationSubjectHash),
+            requiredValidationTag: claims.requiredValidationTag,
+        },
+    };
+}
+function encodeGuaranteeEip191V2(claims) {
+    return (0, viem_1.encodeAbiParameters)([
+        { type: 'address' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'uint64' },
+        { type: 'address' },
+        { type: 'bytes32' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'uint8' },
+        { type: 'bytes32' },
+        { type: 'string' },
+    ], [
+        claims.userAddress,
+        claims.recipientAddress,
+        claims.tabId,
+        claims.reqId,
+        claims.amount,
+        claims.assetAddress,
+        BigInt(claims.timestamp),
+        claims.validationRegistryAddress,
+        (claims.validationRequestHash.startsWith('0x')
+            ? claims.validationRequestHash
+            : `0x${claims.validationRequestHash}`),
+        BigInt(claims.validationChainId),
+        claims.validatorAddress,
+        claims.validatorAgentId,
+        claims.minValidationScore,
+        (claims.validationSubjectHash.startsWith('0x')
+            ? claims.validationSubjectHash
+            : `0x${claims.validationSubjectHash}`),
+        claims.requiredValidationTag,
+    ]);
+}
 function encodeGuaranteeEip191(claims) {
     const payload = (0, viem_1.encodeAbiParameters)([
         { type: 'address' },
@@ -193,10 +261,21 @@ class PaymentSigner {
     async signRequest(params, claims, scheme = models_1.SigningScheme.EIP712) {
         try {
             validateGuaranteeSigningContext(params, claims, { signerAddress: this.signer.address });
+            const isV2 = claims instanceof models_1.PaymentGuaranteeRequestClaimsV2;
             if (scheme === models_1.SigningScheme.EIP712) {
                 if (!this.signer.signTypedData) {
                     throw new errors_1.SigningError('signTypedData is not supported for this account');
                 }
+                if (isV2) {
+                    const typed = buildGuaranteeTypedDataV2(params, claims);
+                    const signature = await this.signer.signTypedData({
+                        domain: typed.domain,
+                        types: { SolGuaranteeRequestClaimsV2: typed.types.SolGuaranteeRequestClaimsV2 },
+                        primaryType: typed.primaryType,
+                        message: typed.message,
+                    });
+                    return { signature, scheme };
+                }
                 const typed = buildGuaranteeTypedData(params, claims);
                 const signature = await this.signer.signTypedData({
                     domain: typed.domain,
@@ -210,7 +289,7 @@ class PaymentSigner {
                 if (!this.signer.signMessage) {
                     throw new errors_1.SigningError('signMessage is not supported for this account');
                 }
-                const message = encodeGuaranteeEip191(claims);
+                const message = isV2 ? encodeGuaranteeEip191V2(claims) : encodeGuaranteeEip191(claims);
                 const signature = await this.signer.signMessage({ message });
                 return { signature, scheme };
             }

package/dist/utils.d.ts

@@ -5,6 +5,7 @@ export declare class ValidationError extends Error {
 export declare function validateUrl(raw: string): string;
 export declare function normalizePrivateKey(raw: string): string;
 export declare function normalizeAddress(raw: string): string;
+export declare function ensureHexPrefix(value: string): Hex;
 export declare function parseU256(value: number | bigint | string): bigint;
 export declare function serializeU256(value: number | bigint | string): string;
 export declare function hexFromBytes(bytes: Uint8Array): Hex;

package/dist/utils.js

@@ -4,6 +4,7 @@ exports.ValidationError = void 0;
 exports.validateUrl = validateUrl;
 exports.normalizePrivateKey = normalizePrivateKey;
 exports.normalizeAddress = normalizeAddress;
+exports.ensureHexPrefix = ensureHexPrefix;
 exports.parseU256 = parseU256;
 exports.serializeU256 = serializeU256;
 exports.hexFromBytes = hexFromBytes;
@@ -16,16 +17,17 @@ class ValidationError extends Error {
 }
 exports.ValidationError = ValidationError;
 function validateUrl(raw) {
+    let url;
     try {
-        const url = new URL(raw);
-        if (!url.protocol || !url.host) {
-            throw new Error('missing parts');
-        }
-        return raw;
+        url = new URL(raw);
     }
     catch {
         throw new ValidationError(`invalid URL: ${raw}`);
     }
+    if (!url.protocol || !url.host) {
+        throw new ValidationError(`invalid URL: ${raw}`);
+    }
+    return raw;
 }
 function normalizePrivateKey(raw) {
     const key = raw.startsWith('0x') ? raw.slice(2) : raw;
@@ -45,6 +47,9 @@ function normalizeAddress(raw) {
     }
     throw new ValidationError(`invalid address: ${raw}`);
 }
+function ensureHexPrefix(value) {
+    return (value.startsWith('0x') ? value : `0x${value}`);
+}
 function parseNumericString(raw) {
     const text = raw.trim();
     const n = BigInt(text);
@@ -58,6 +63,9 @@ function parseU256(value) {
         if (!Number.isFinite(value)) {
             throw new ValidationError('invalid integer');
         }
+        if (!Number.isSafeInteger(value)) {
+            throw new ValidationError('integer value exceeds safe precision; use bigint or hex string for large values');
+        }
         if (value < 0) {
             throw new ValidationError('u256 cannot be negative');
         }

package/dist/validation.d.ts

@@ -0,0 +1,32 @@
+import { type Hex } from 'viem';
+import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2 } from './models';
+/** Binding domain string used as a prefix when hashing validation subjects. */
+export declare const VALIDATION_SUBJECT_BINDING_DOMAIN = "4MICA_VALIDATION_SUBJECT_V1";
+/** Binding domain string used as a prefix when hashing validation requests. */
+export declare const VALIDATION_REQUEST_BINDING_DOMAIN = "4MICA_VALIDATION_REQUEST_V1";
+/**
+ * Compute the `validationSubjectHash` for a V2 payment guarantee request.
+ *
+ * Binds the payment subject (tab, user, recipient, amount, asset, timestamp) to
+ * a keccak256 hash prefixed by {@link VALIDATION_SUBJECT_BINDING_DOMAIN} so that
+ * on-chain validators can verify which payment the validation refers to.
+ *
+ * @param claims - V1 base claims (the subject fields are the same for V1 and V2).
+ * @returns 32-byte keccak256 hash as a `0x`-prefixed hex string.
+ */
+export declare function computeValidationSubjectHash(claims: PaymentGuaranteeRequestClaims): Hex;
+/**
+ * Compute the `validationRequestHash` for a V2 payment guarantee request.
+ *
+ * Binds the full validation policy (chain, registry, validator, score threshold,
+ * subject hash, required tag) to a keccak256 hash prefixed by
+ * {@link VALIDATION_REQUEST_BINDING_DOMAIN}. This hash is included in the V2 claims
+ * that are BLS-signed by the core service, allowing on-chain verification that the
+ * validation policy was not tampered with.
+ *
+ * @param claims - V2 claims with all validation policy fields populated.
+ *   The `validationSubjectHash` field must already be computed via
+ *   {@link computeValidationSubjectHash} before calling this function.
+ * @returns 32-byte keccak256 hash as a `0x`-prefixed hex string.
+ */
+export declare function computeValidationRequestHash(claims: PaymentGuaranteeRequestClaimsV2): Hex;

package/dist/validation.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALIDATION_REQUEST_BINDING_DOMAIN = exports.VALIDATION_SUBJECT_BINDING_DOMAIN = void 0;
+exports.computeValidationSubjectHash = computeValidationSubjectHash;
+exports.computeValidationRequestHash = computeValidationRequestHash;
+const viem_1 = require("viem");
+const utils_1 = require("./utils");
+/** Binding domain string used as a prefix when hashing validation subjects. */
+exports.VALIDATION_SUBJECT_BINDING_DOMAIN = '4MICA_VALIDATION_SUBJECT_V1';
+/** Binding domain string used as a prefix when hashing validation requests. */
+exports.VALIDATION_REQUEST_BINDING_DOMAIN = '4MICA_VALIDATION_REQUEST_V1';
+/**
+ * Compute the `validationSubjectHash` for a V2 payment guarantee request.
+ *
+ * Binds the payment subject (tab, user, recipient, amount, asset, timestamp) to
+ * a keccak256 hash prefixed by {@link VALIDATION_SUBJECT_BINDING_DOMAIN} so that
+ * on-chain validators can verify which payment the validation refers to.
+ *
+ * @param claims - V1 base claims (the subject fields are the same for V1 and V2).
+ * @returns 32-byte keccak256 hash as a `0x`-prefixed hex string.
+ */
+function computeValidationSubjectHash(claims) {
+    const bindingDomain = (0, viem_1.keccak256)(new TextEncoder().encode(exports.VALIDATION_SUBJECT_BINDING_DOMAIN));
+    const encoded = (0, viem_1.encodeAbiParameters)([
+        { type: 'bytes32' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'uint64' },
+    ], [
+        bindingDomain,
+        claims.tabId,
+        claims.reqId,
+        claims.userAddress,
+        claims.recipientAddress,
+        claims.amount,
+        claims.assetAddress,
+        BigInt(claims.timestamp),
+    ]);
+    return (0, viem_1.keccak256)(encoded);
+}
+/**
+ * Compute the `validationRequestHash` for a V2 payment guarantee request.
+ *
+ * Binds the full validation policy (chain, registry, validator, score threshold,
+ * subject hash, required tag) to a keccak256 hash prefixed by
+ * {@link VALIDATION_REQUEST_BINDING_DOMAIN}. This hash is included in the V2 claims
+ * that are BLS-signed by the core service, allowing on-chain verification that the
+ * validation policy was not tampered with.
+ *
+ * @param claims - V2 claims with all validation policy fields populated.
+ *   The `validationSubjectHash` field must already be computed via
+ *   {@link computeValidationSubjectHash} before calling this function.
+ * @returns 32-byte keccak256 hash as a `0x`-prefixed hex string.
+ */
+function computeValidationRequestHash(claims) {
+    const bindingDomain = (0, viem_1.keccak256)(new TextEncoder().encode(exports.VALIDATION_REQUEST_BINDING_DOMAIN));
+    const tagHash = (0, viem_1.keccak256)(new TextEncoder().encode(claims.requiredValidationTag));
+    const encoded = (0, viem_1.encodeAbiParameters)([
+        { type: 'bytes32' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'bytes32' },
+        { type: 'uint8' },
+        { type: 'bytes32' },
+    ], [
+        bindingDomain,
+        BigInt(claims.validationChainId),
+        claims.validationRegistryAddress,
+        claims.validatorAddress,
+        claims.validatorAgentId,
+        (0, utils_1.ensureHexPrefix)(claims.validationSubjectHash),
+        claims.minValidationScore,
+        tagHash,
+    ]);
+    return (0, viem_1.keccak256)(encoded);
+}

package/dist/x402/index.d.ts

@@ -1,22 +1,90 @@
-import { PaymentGuaranteeRequestClaims, PaymentSignature, SigningScheme } from '../models';
+import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PaymentSignature, SigningScheme } from '../models';
 import { PaymentRequirementsV1, TabResponse, X402SignedPayment, X402SettledPayment, PaymentRequirementsV2, X402PaymentRequired, X402ResourceInfo } from './models';
 import type { FetchFn } from '../rpc';
 export * from './models';
+/**
+ * Minimal signing interface required by {@link X402Flow}.
+ * Implemented by {@link UserClient} from the main SDK client.
+ */
 export interface FlowSigner {
-    signPayment(claims: PaymentGuaranteeRequestClaims, scheme: SigningScheme): Promise<PaymentSignature>;
+    signPayment(claims: PaymentGuaranteeRequestClaims | PaymentGuaranteeRequestClaimsV2, scheme: SigningScheme): Promise<PaymentSignature>;
 }
+/**
+ * Handles the x402 HTTP 402 payment protocol for 4Mica.
+ *
+ * Orchestrates the full client-side x402 flow: resolving a tab from the recipient's
+ * tab endpoint, building and signing payment claims (V1 or V2), and optionally settling
+ * the payment against a facilitator service.
+ *
+ * @example
+ * ```ts
+ * const flow = X402Flow.fromClient(client);
+ * const signed = await flow.signPayment(paymentRequirements, userAddress);
+ * // attach signed.header as the X-PAYMENT header on the protected request
+ * ```
+ */
 export declare class X402Flow {
     private signer;
     private fetchFn;
+    /**
+     * @param signer - Payment signer, typically `client.user`.
+     * @param fetchFn - HTTP fetch implementation. Defaults to global `fetch`.
+     */
     constructor(signer: FlowSigner, fetchFn?: FetchFn);
+    /**
+     * Convenience factory — creates an `X402Flow` from the user sub-client of a `Client`.
+     *
+     * @param client - Any object with a `.user` property implementing {@link FlowSigner}.
+     */
     static fromClient(client: {
         user: FlowSigner;
     }): X402Flow;
+    /**
+     * Sign an x402 V1 payment.
+     *
+     * Resolves a tab from `paymentRequirements.extra.tabEndpoint`, builds V1 claims,
+     * signs them with EIP-712, and returns the base64-encoded payment header together
+     * with the raw payload and signature.
+     *
+     * @param paymentRequirements - V1 payment requirements from the `402 Payment Required` response.
+     * @param userAddress - Address of the paying user.
+     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
+     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
+     */
     signPayment(paymentRequirements: PaymentRequirementsV1, userAddress: string): Promise<X402SignedPayment>;
+    /**
+     * Sign an x402 V2 payment, optionally including a V2 validation policy.
+     *
+     * If `accepted.extra` contains all required validation policy fields
+     * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
+     * `minValidationScore`, `validationChainId`), the claims are built as V2 with
+     * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
+     * falls back to V1 claims.
+     *
+     * @param paymentRequired - The original `402 Payment Required` response object.
+     * @param accepted - The accepted V2 payment requirements.
+     * @param userAddress - Address of the paying user.
+     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
+     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
+     */
     signPaymentV2(paymentRequired: X402PaymentRequired, accepted: PaymentRequirementsV2, userAddress: string): Promise<X402SignedPayment>;
+    /**
+     * Submit a signed payment to a facilitator for on-chain settlement.
+     *
+     * Sends a POST request to `{facilitatorUrl}/settle` with the payment header,
+     * decoded payload, and payment requirements. Use this when the protected resource
+     * requires facilitator-confirmed settlement before granting access.
+     *
+     * @param payment - Signed payment returned by {@link signPayment} or {@link signPaymentV2}.
+     * @param paymentRequirements - V1 payment requirements included in the settlement request.
+     * @param facilitatorUrl - Base URL of the facilitator service.
+     * @returns The original payment plus the raw settlement response from the facilitator.
+     * @throws {@link X402Error} if the facilitator returns a non-2xx response.
+     */
     settlePayment(payment: X402SignedPayment, paymentRequirements: PaymentRequirementsV1, facilitatorUrl: string): Promise<X402SettledPayment>;
     protected requestTab(x402Version: number, paymentRequirements: PaymentRequirementsV1 | PaymentRequirementsV2, userAddress: string, resource?: X402ResourceInfo): Promise<TabResponse>;
     protected buildClaims(requirements: PaymentRequirementsV1 | PaymentRequirementsV2, tab: TabResponse, userAddress: string): PaymentGuaranteeRequestClaims;
+    protected buildClaimsV2(requirements: PaymentRequirementsV2, tab: TabResponse, userAddress: string): PaymentGuaranteeRequestClaimsV2;
     private static validateScheme;
     private static decodePaymentHeader;
 }

package/dist/x402/index.js

@@ -19,17 +19,60 @@ const models_1 = require("../models");
 const utils_1 = require("../utils");
 const errors_1 = require("../errors");
 const payment_1 = require("../payment");
+const validation_1 = require("../validation");
 __exportStar(require("./models"), exports);
+function hasValidationPolicy(extra) {
+    return !!(extra?.validationRegistryAddress &&
+        extra?.validatorAddress &&
+        extra?.validatorAgentId !== undefined &&
+        extra?.minValidationScore !== undefined &&
+        extra?.validationChainId !== undefined);
+}
+/**
+ * Handles the x402 HTTP 402 payment protocol for 4Mica.
+ *
+ * Orchestrates the full client-side x402 flow: resolving a tab from the recipient's
+ * tab endpoint, building and signing payment claims (V1 or V2), and optionally settling
+ * the payment against a facilitator service.
+ *
+ * @example
+ * ```ts
+ * const flow = X402Flow.fromClient(client);
+ * const signed = await flow.signPayment(paymentRequirements, userAddress);
+ * // attach signed.header as the X-PAYMENT header on the protected request
+ * ```
+ */
 class X402Flow {
     signer;
     fetchFn;
+    /**
+     * @param signer - Payment signer, typically `client.user`.
+     * @param fetchFn - HTTP fetch implementation. Defaults to global `fetch`.
+     */
     constructor(signer, fetchFn = fetch) {
         this.signer = signer;
         this.fetchFn = fetchFn;
     }
+    /**
+     * Convenience factory — creates an `X402Flow` from the user sub-client of a `Client`.
+     *
+     * @param client - Any object with a `.user` property implementing {@link FlowSigner}.
+     */
     static fromClient(client) {
         return new X402Flow(client.user);
     }
+    /**
+     * Sign an x402 V1 payment.
+     *
+     * Resolves a tab from `paymentRequirements.extra.tabEndpoint`, builds V1 claims,
+     * signs them with EIP-712, and returns the base64-encoded payment header together
+     * with the raw payload and signature.
+     *
+     * @param paymentRequirements - V1 payment requirements from the `402 Payment Required` response.
+     * @param userAddress - Address of the paying user.
+     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
+     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
+     */
     async signPayment(paymentRequirements, userAddress) {
         X402Flow.validateScheme(paymentRequirements.scheme);
         const tab = await this.requestTab(1, paymentRequirements, userAddress);
@@ -45,10 +88,27 @@ class X402Flow {
         const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
         return { header, payload: paymentPayload, signature };
     }
+    /**
+     * Sign an x402 V2 payment, optionally including a V2 validation policy.
+     *
+     * If `accepted.extra` contains all required validation policy fields
+     * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
+     * `minValidationScore`, `validationChainId`), the claims are built as V2 with
+     * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
+     * falls back to V1 claims.
+     *
+     * @param paymentRequired - The original `402 Payment Required` response object.
+     * @param accepted - The accepted V2 payment requirements.
+     * @param userAddress - Address of the paying user.
+     * @returns Signed payment ready to attach as the `X-PAYMENT` request header.
+     * @throws {@link X402Error} if the scheme is not a 4Mica scheme or the tab endpoint fails.
+     */
     async signPaymentV2(paymentRequired, accepted, userAddress) {
         X402Flow.validateScheme(accepted.scheme);
         const tab = await this.requestTab(2, accepted, userAddress, paymentRequired.resource);
-        const claims = this.buildClaims(accepted, tab, userAddress);
+        const claims = hasValidationPolicy(accepted.extra)
+            ? this.buildClaimsV2(accepted, tab, userAddress)
+            : this.buildClaims(accepted, tab, userAddress);
         const signature = await this.signer.signPayment(claims, models_1.SigningScheme.EIP712);
         const paymentPayload = (0, payment_1.buildPaymentPayload)(claims, signature);
         const envelope = {
@@ -60,6 +120,19 @@ class X402Flow {
         const header = Buffer.from(JSON.stringify(envelope)).toString('base64');
         return { header, payload: paymentPayload, signature };
     }
+    /**
+     * Submit a signed payment to a facilitator for on-chain settlement.
+     *
+     * Sends a POST request to `{facilitatorUrl}/settle` with the payment header,
+     * decoded payload, and payment requirements. Use this when the protected resource
+     * requires facilitator-confirmed settlement before granting access.
+     *
+     * @param payment - Signed payment returned by {@link signPayment} or {@link signPaymentV2}.
+     * @param paymentRequirements - V1 payment requirements included in the settlement request.
+     * @param facilitatorUrl - Base URL of the facilitator service.
+     * @returns The original payment plus the raw settlement response from the facilitator.
+     * @throws {@link X402Error} if the facilitator returns a non-2xx response.
+     */
     async settlePayment(payment, paymentRequirements, facilitatorUrl) {
         const url = `${facilitatorUrl.replace(/\/$/, '')}/settle`;
         const paymentPayload = X402Flow.decodePaymentHeader(payment.header);
@@ -119,6 +192,33 @@ class X402Flow {
         const timestamp = Math.floor(Date.now() / 1000);
         return models_1.PaymentGuaranteeRequestClaims.new(userAddress, (0, utils_1.normalizeAddress)(requirements.payTo), tabId, amount, timestamp, requirements.asset, reqId);
     }
+    buildClaimsV2(requirements, tab, userAddress) {
+        const base = this.buildClaims(requirements, tab, userAddress);
+        const extra = requirements.extra;
+        const validationSubjectHash = (0, validation_1.computeValidationSubjectHash)(base);
+        const partialClaims = new models_1.PaymentGuaranteeRequestClaimsV2({
+            userAddress: base.userAddress,
+            recipientAddress: base.recipientAddress,
+            tabId: base.tabId,
+            reqId: base.reqId,
+            amount: base.amount,
+            timestamp: base.timestamp,
+            assetAddress: base.assetAddress,
+            validationRegistryAddress: extra.validationRegistryAddress,
+            validationRequestHash: '0x' + '00'.repeat(32),
+            validationChainId: extra.validationChainId,
+            validatorAddress: extra.validatorAddress,
+            validatorAgentId: (0, utils_1.parseU256)(extra.validatorAgentId),
+            minValidationScore: extra.minValidationScore,
+            validationSubjectHash,
+            requiredValidationTag: extra.requiredValidationTag ?? '',
+        });
+        const validationRequestHash = (0, validation_1.computeValidationRequestHash)(partialClaims);
+        return new models_1.PaymentGuaranteeRequestClaimsV2({
+            ...partialClaims,
+            validationRequestHash,
+        });
+    }
     static validateScheme(scheme) {
         if (!scheme.toLowerCase().includes('4mica')) {
             throw new errors_1.X402Error(`invalid scheme: ${scheme}`);

package/dist/x402/models.d.ts

@@ -1,5 +1,5 @@
 import { PaymentSignature } from '../models';
-import type { PaymentPayload, PaymentPayloadClaims } from '../payment';
+import type { PaymentPayload } from '../payment';
 export interface PaymentRequirementsV1 {
     scheme: string;
     network: string;
@@ -25,13 +25,19 @@ export interface PaymentRequirementsV2 {
 export type PaymentRequirements = PaymentRequirementsV2;
 export interface PaymentRequirementsExtra {
     tabEndpoint?: string;
+    validationRegistryAddress?: string;
+    validationChainId?: number;
+    validatorAddress?: string;
+    validatorAgentId?: string;
+    minValidationScore?: number;
+    requiredValidationTag?: string;
 }
 export interface TabResponse {
     tabId: string;
     userAddress: string;
     nextReqId?: string;
 }
-export type X402PaymentPayloadClaims = PaymentPayloadClaims;
+export type X402PaymentPayloadClaims = PaymentPayload['claims'];
 export type X402PaymentPayload = PaymentPayload;
 export interface X402PaymentEnvelopeV1 {
     x402Version: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/sdk",
-  "version": "0.5.5",
+  "version": "1.0.0",
   "description": "TypeScript SDK for interacting with the 4Mica payment network",
   "license": "MIT",
   "repository": {
@@ -41,6 +41,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "lint": "eslint . --ext .ts",
     "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\""
   },
@@ -53,6 +54,7 @@
     "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
+    "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",