@4mica/sdk 0.5.5 → 1.0.0

package/README.md

@@ -279,9 +279,9 @@ Notes:
 
 - `createTab(userAddress, recipientAddress, erc20Token?, ttl?)`
 - `getTabPaymentStatus(tabId)`
-- `issuePaymentGuarantee(claims, signature, scheme)`
+- `issuePaymentGuarantee(claims, signature, scheme)` — accepts V1 or V2 claims
 - `verifyPaymentGuarantee(cert)`
-- `remunerate(cert)`
+- `remunerate(cert)` — requires `@noble/curves` peer dependency
 - `listSettledTabs()`
 - `listPendingRemunerations()`
 - `getTab(tabId)`
@@ -302,10 +302,71 @@ Available under `client.rpc` (requires an admin API key):
 - `listAdminApiKeys()`
 - `revokeAdminApiKey(keyId)`
 
+### V2 Payment Guarantees (on-chain validation policy)
+
+V2 guarantees attach an on-chain validation policy that lets a validator agent attest to the
+quality/validity of a payment before it is remunerated. Use `PaymentGuaranteeRequestClaimsV2`
+and the canonical hash helpers:
+
+```ts
+import {
+  PaymentGuaranteeRequestClaimsV2,
+  computeValidationSubjectHash,
+  computeValidationRequestHash,
+  SigningScheme,
+} from "@4mica/sdk";
+
+// 1) Build base V1 claims first
+const baseClaims = PaymentGuaranteeRequestClaims.new(
+  userAddress, recipientAddress, tabId, amount, timestamp, erc20Token, reqId
+);
+
+// 2) Compute canonical hashes
+const validationSubjectHash = computeValidationSubjectHash(baseClaims);
+
+const partialV2 = new PaymentGuaranteeRequestClaimsV2({
+  ...baseClaims,
+  validationRegistryAddress: "0x...",
+  validationRequestHash: "0x" + "00".repeat(32), // placeholder
+  validationChainId: 1,
+  validatorAddress: "0x...",
+  validatorAgentId: 1n,
+  minValidationScore: 80,  // 1–100
+  validationSubjectHash,
+  requiredValidationTag: "my-tag",
+});
+
+const validationRequestHash = computeValidationRequestHash(partialV2);
+const claimsV2 = new PaymentGuaranteeRequestClaimsV2({ ...partialV2, validationRequestHash });
+
+// 3) Sign and issue
+const { signature, scheme } = await client.user.signPayment(claimsV2, SigningScheme.EIP712);
+const cert = await client.recipient.issuePaymentGuarantee(claimsV2, signature, scheme);
+```
+
 ## Error Handling
 
-All SDK errors extend `FourMicaError`. Common error types include `ConfigError`, `RpcError`,
-`SigningError`, `VerificationError`, `X402Error`, and `AuthError`.
+All SDK errors extend `FourMicaError`. Import individual error classes to distinguish them:
+
+```ts
+import {
+  ConfigError,       // invalid ConfigBuilder input
+  RpcError,          // 4Mica core service error (has .status and .body)
+  SigningError,       // signing scheme unsupported or address mismatch
+  ContractError,      // on-chain call failed or unexpected result
+  VerificationError,  // BLS certificate decode/domain mismatch
+  X402Error,          // x402 flow error (bad scheme, tab resolution, settlement)
+  AuthError,          // base class for all auth errors
+  AuthMissingConfigError, // auth not configured when login() is called
+} from "@4mica/sdk";
+
+try {
+  await client.recipient.remunerate(cert);
+} catch (err) {
+  if (err instanceof VerificationError) { /* bad cert */ }
+  if (err instanceof ContractError) { /* on-chain failure */ }
+}
+```
 
 ## License
 

package/dist/abi/core4mica.d.ts

@@ -25,14 +25,6 @@ export declare const core4micaAbi: readonly [{
             readonly type: "bytes32";
             readonly internalType: "bytes32";
         }];
-    }, {
-        readonly name: "usdc_";
-        readonly type: "address";
-        readonly internalType: "address";
-    }, {
-        readonly name: "usdt_";
-        readonly type: "address";
-        readonly internalType: "address";
     }];
     readonly stateMutability: "nonpayable";
 }, {
@@ -73,26 +65,6 @@ export declare const core4micaAbi: readonly [{
         readonly internalType: "uint64";
     }];
     readonly stateMutability: "view";
-}, {
-    readonly type: "function";
-    readonly name: "USDC";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "address";
-        readonly internalType: "address";
-    }];
-    readonly stateMutability: "view";
-}, {
-    readonly type: "function";
-    readonly name: "USDT";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "address";
-        readonly internalType: "address";
-    }];
-    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "authority";

package/dist/abi/core4mica.js

@@ -37,16 +37,6 @@ exports.core4micaAbi = [
                     },
                 ],
             },
-            {
-                name: 'usdc_',
-                type: 'address',
-                internalType: 'address',
-            },
-            {
-                name: 'usdt_',
-                type: 'address',
-                internalType: 'address',
-            },
         ],
         stateMutability: 'nonpayable',
     },
@@ -99,32 +89,6 @@ exports.core4micaAbi = [
         ],
         stateMutability: 'view',
     },
-    {
-        type: 'function',
-        name: 'USDC',
-        inputs: [],
-        outputs: [
-            {
-                name: '',
-                type: 'address',
-                internalType: 'address',
-            },
-        ],
-        stateMutability: 'view',
-    },
-    {
-        type: 'function',
-        name: 'USDT',
-        inputs: [],
-        outputs: [
-            {
-                name: '',
-                type: 'address',
-                internalType: 'address',
-            },
-        ],
-        stateMutability: 'view',
-    },
     {
         type: 'function',
         name: 'authority',

package/dist/abi/erc20.d.ts

@@ -48,6 +48,16 @@ export declare const erc20Abi: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+        readonly internalType: "uint8";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "totalSupply";

package/dist/abi/erc20.js

@@ -69,6 +69,19 @@ exports.erc20Abi = [
         ],
         stateMutability: 'view',
     },
+    {
+        type: 'function',
+        name: 'decimals',
+        inputs: [],
+        outputs: [
+            {
+                name: '',
+                type: 'uint8',
+                internalType: 'uint8',
+            },
+        ],
+        stateMutability: 'view',
+    },
     {
         type: 'function',
         name: 'totalSupply',

package/dist/bls.js

@@ -78,6 +78,10 @@ const loadCurvesSync = () => {
         }
     }
 };
+const isBlsModule = (mod) => mod !== null &&
+    typeof mod === 'object' &&
+    'bls12_381' in mod &&
+    typeof mod.bls12_381 === 'object';
 const loadCurvesAsync = async () => {
     if (curvesCache)
         return curvesCache;
@@ -90,7 +94,10 @@ const loadCurvesAsync = async () => {
             return require('@noble/curves/bls12-381');
         }
         catch {
-            const mod = (await Promise.resolve().then(() => __importStar(require('@noble/curves/bls12-381.js'))));
+            const mod = await Promise.resolve().then(() => __importStar(require('@noble/curves/bls12-381.js')));
+            if (!isBlsModule(mod)) {
+                throw new errors_1.VerificationError('BLS decoding: unexpected module shape from @noble/curves');
+            }
             return mod;
         }
     })();
@@ -137,7 +144,11 @@ const normalizeSignature = (input) => {
     if (input && typeof input === 'object') {
         const record = input;
         if (Array.isArray(record.data)) {
-            const bytes = Uint8Array.from(record.data);
+            const arr = record.data;
+            if (arr.some((b) => typeof b !== 'number' || b < 0 || b > 255 || !Number.isInteger(b))) {
+                throw new errors_1.VerificationError('signature data array contains invalid byte values');
+            }
+            const bytes = Uint8Array.from(arr);
             const hex = Buffer.from(bytes).toString('hex');
             return { hex, bytes };
         }

package/dist/client/index.d.ts

@@ -2,22 +2,69 @@ import type { AuthTokens } from '../auth';
 import { Config } from '../config';
 import { ContractGateway } from '../contract';
 import { RpcProxy } from '../rpc';
-import { CorePublicParameters, PaymentSigner } from '../signing';
+import { CorePublicParameters } from '../models';
+import { PaymentSigner } from '../signing';
 import { RecipientClient } from './recipient';
 import { UserClient } from './user';
+/**
+ * Top-level SDK client. Holds a live connection to the 4Mica core RPC and the
+ * on-chain Core4Mica contract. Obtain an instance via {@link Client.new}.
+ *
+ * @example
+ * ```ts
+ * const cfg = new ConfigBuilder().walletPrivateKey("0x...").build();
+ * const client = await Client.new(cfg);
+ * try {
+ *   // client.user  – payer-side operations
+ *   // client.recipient – recipient-side operations
+ * } finally {
+ *   await client.aclose();
+ * }
+ * ```
+ */
 export declare class Client {
+    /** Low-level RPC proxy to the 4Mica core service. */
     readonly rpc: RpcProxy;
+    /** Chain and contract parameters fetched from the core service at startup. */
     readonly params: CorePublicParameters;
+    /** viem-backed gateway for on-chain calls (deposit, remunerate, …). */
     readonly gateway: ContractGateway;
+    /** 32-byte domain separator used to verify V1 BLS guarantee certificates. */
     readonly guaranteeDomain: string;
+    /** Payer-side operations: deposit, sign, withdraw. */
     readonly user: UserClient;
+    /** Recipient-side operations: tabs, guarantees, remuneration. */
     readonly recipient: RecipientClient;
+    /** Payment signing wrapper around the configured viem Account. */
     readonly signer: PaymentSigner;
     private authSession?;
     private constructor();
+    /**
+     * Create and fully initialise a Client.
+     *
+     * Fetches public parameters from the core service, validates that the
+     * Ethereum RPC is on the expected chain, and sets up SIWE auth if configured.
+     *
+     * @param cfg - Validated configuration produced by {@link ConfigBuilder.build}.
+     * @throws {@link ConfigError} if the configuration is invalid.
+     * @throws {@link RpcError} if the core service is unreachable.
+     * @throws {@link ContractError} if the Ethereum RPC returns the wrong chain ID.
+     */
     static new(cfg: Config): Promise<Client>;
     private static buildGateway;
+    /**
+     * Release client resources. Safe to call multiple times.
+     * Use in a `finally` block to ensure cleanup after use.
+     */
     aclose(): Promise<void>;
+    /**
+     * Perform an explicit SIWE login and return the resulting tokens.
+     *
+     * Not required for normal operation — the first authenticated RPC call
+     * triggers auth automatically. Call this to pre-warm the session.
+     *
+     * @throws {@link AuthMissingConfigError} if auth was not enabled in the config.
+     */
     login(): Promise<AuthTokens>;
 }
 export { UserClient } from './user';

package/dist/client/index.js

@@ -8,13 +8,36 @@ const rpc_1 = require("../rpc");
 const signing_1 = require("../signing");
 const recipient_1 = require("./recipient");
 const user_1 = require("./user");
+/**
+ * Top-level SDK client. Holds a live connection to the 4Mica core RPC and the
+ * on-chain Core4Mica contract. Obtain an instance via {@link Client.new}.
+ *
+ * @example
+ * ```ts
+ * const cfg = new ConfigBuilder().walletPrivateKey("0x...").build();
+ * const client = await Client.new(cfg);
+ * try {
+ *   // client.user  – payer-side operations
+ *   // client.recipient – recipient-side operations
+ * } finally {
+ *   await client.aclose();
+ * }
+ * ```
+ */
 class Client {
+    /** Low-level RPC proxy to the 4Mica core service. */
     rpc;
+    /** Chain and contract parameters fetched from the core service at startup. */
     params;
+    /** viem-backed gateway for on-chain calls (deposit, remunerate, …). */
     gateway;
+    /** 32-byte domain separator used to verify V1 BLS guarantee certificates. */
     guaranteeDomain;
+    /** Payer-side operations: deposit, sign, withdraw. */
     user;
+    /** Recipient-side operations: tabs, guarantees, remuneration. */
     recipient;
+    /** Payment signing wrapper around the configured viem Account. */
     signer;
     authSession;
     constructor(rpc, params, gateway, guaranteeDomain, signer, authSession) {
@@ -27,6 +50,17 @@ class Client {
         this.user = new user_1.UserClient(this);
         this.recipient = new recipient_1.RecipientClient(this);
     }
+    /**
+     * Create and fully initialise a Client.
+     *
+     * Fetches public parameters from the core service, validates that the
+     * Ethereum RPC is on the expected chain, and sets up SIWE auth if configured.
+     *
+     * @param cfg - Validated configuration produced by {@link ConfigBuilder.build}.
+     * @throws {@link ConfigError} if the configuration is invalid.
+     * @throws {@link RpcError} if the core service is unreachable.
+     * @throws {@link ContractError} if the Ethereum RPC returns the wrong chain ID.
+     */
     static async new(cfg) {
         const rpc = new rpc_1.RpcProxy(cfg.rpcUrl, cfg.adminApiKey);
         const params = await rpc.getPublicParams();
@@ -54,9 +88,21 @@ class Client {
         const contractAddress = cfg.contractAddress ?? params.contractAddress;
         return contract_1.ContractGateway.create(ethRpcUrl, cfg.signer, contractAddress, params.chainId);
     }
+    /**
+     * Release client resources. Safe to call multiple times.
+     * Use in a `finally` block to ensure cleanup after use.
+     */
     async aclose() {
         await this.rpc.aclose();
     }
+    /**
+     * Perform an explicit SIWE login and return the resulting tokens.
+     *
+     * Not required for normal operation — the first authenticated RPC call
+     * triggers auth automatically. Call this to pre-warm the session.
+     *
+     * @throws {@link AuthMissingConfigError} if auth was not enabled in the config.
+     */
     async login() {
         if (!this.authSession) {
             throw new errors_1.AuthMissingConfigError('auth is not enabled');

package/dist/client/recipient.d.ts

@@ -1,24 +1,128 @@
-import { AssetBalanceInfo, BLSCert, CollateralEventInfo, GuaranteeInfo, PaymentGuaranteeClaims, PaymentGuaranteeRequestClaims, PendingRemunerationInfo, RecipientPaymentInfo, SigningScheme, TabInfo, TabPaymentStatus } from '../models';
+import { AssetBalanceInfo, BLSCert, CollateralEventInfo, GuaranteeInfo, PaymentGuaranteeClaims, PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2, PendingRemunerationInfo, RecipientPaymentInfo, SigningScheme, TabInfo, TabPaymentStatus } from '../models';
 import type { TxReceiptWaitOptions } from '../contract';
 import type { Client } from './index';
+/** Recipient-side operations: tab management, guarantee issuance, remuneration. */
 export declare class RecipientClient {
     private client;
     constructor(client: Client);
     private get recipientAddress();
     get guaranteeDomain(): string;
-    createTab(userAddress: string, recipientAddress: string, erc20Token: string | undefined | null, ttl?: number | null): Promise<bigint>;
+    /**
+     * Create a payment tab via the core RPC.
+     *
+     * @param userAddress - Address of the payer.
+     * @param recipientAddress - Address of the recipient.
+     * @param erc20Token - ERC20 token address for the tab, or `null`/`undefined` for ETH.
+     * @param ttl - Optional time-to-live in seconds.
+     * @returns `{ tabId, assetAddress, nextReqId }` — the tab ID, the asset address as stored
+     *   by the core (use this for all subsequent claims), and the first request ID to use.
+     * @throws {@link RpcError} if the request fails.
+     */
+    createTab(userAddress: string, recipientAddress: string, erc20Token: string | undefined | null, ttl?: number | null): Promise<{
+        tabId: bigint;
+        assetAddress: string;
+        nextReqId: bigint;
+    }>;
+    /**
+     * Query the on-chain payment status of a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns `{ paid, remunerated, asset }`.
+     */
     getTabPaymentStatus(tabId: number | bigint): Promise<TabPaymentStatus>;
-    issuePaymentGuarantee(claims: PaymentGuaranteeRequestClaims, signature: string, scheme: SigningScheme): Promise<BLSCert>;
-    verifyPaymentGuarantee(cert: BLSCert): PaymentGuaranteeClaims;
+    /**
+     * Issue a BLS-signed payment guarantee certificate via the core RPC.
+     *
+     * The returned {@link BLSCert} can be stored and later passed to
+     * {@link remunerate} to claim the payment on-chain.
+     *
+     * @param claims - Signed payment claims (V1 or V2).
+     * @param signature - ECDSA signature hex string from the payer.
+     * @param scheme - Signing scheme used to produce the signature.
+     * @returns BLS certificate with ABI-encoded claims and BLS signature.
+     * @throws {@link RpcError} if the core service rejects the request.
+     */
+    issuePaymentGuarantee(claims: PaymentGuaranteeRequestClaims | PaymentGuaranteeRequestClaimsV2, signature: string, scheme: SigningScheme): Promise<BLSCert>;
+    /**
+     * Verify and decode a BLS guarantee certificate.
+     *
+     * Decodes the ABI-encoded claims and validates the domain separator against
+     * the on-chain configuration. For V2 certificates, the active V2 domain is
+     * fetched from the contract and verified to be enabled.
+     *
+     * @param cert - BLS certificate (hex-encoded claims + hex-encoded signature).
+     * @returns Decoded {@link PaymentGuaranteeClaims}, including validation policy for V2.
+     * @throws {@link VerificationError} on domain mismatch, invalid length, or disabled version.
+     */
+    verifyPaymentGuarantee(cert: BLSCert): Promise<PaymentGuaranteeClaims>;
+    /**
+     * Claim payment on-chain by submitting a verified BLS certificate.
+     *
+     * Verifies the certificate first (see {@link verifyPaymentGuarantee}), then
+     * converts the BLS signature into the G2 coordinate words expected by the
+     * contract and submits the `remunerate` transaction.
+     *
+     * Requires the optional `@noble/curves` package for BLS point decompression.
+     *
+     * @param cert - BLS certificate to settle.
+     * @param waitOptions - Optional timeout/polling overrides for receipt polling.
+     * @throws {@link VerificationError} if the certificate is invalid or `claims`/`signature`
+     *   are not hex strings.
+     * @throws {@link ContractError} if the contract call fails.
+     */
     remunerate(cert: BLSCert, waitOptions?: TxReceiptWaitOptions): Promise<import("viem").TransactionReceipt>;
+    /** List all tabs for this recipient that have been settled on-chain. */
     listSettledTabs(): Promise<TabInfo[]>;
+    /** List all tabs with outstanding (un-remunerated) guarantees for this recipient. */
     listPendingRemunerations(): Promise<PendingRemunerationInfo[]>;
+    /**
+     * Fetch a single tab by ID.
+     *
+     * @param tabId - Tab identifier.
+     * @returns The tab, or `null` if not found.
+     */
     getTab(tabId: number | bigint): Promise<TabInfo | null>;
+    /**
+     * List all tabs belonging to this recipient.
+     *
+     * @param settlementStatuses - Optional filter on settlement status (e.g. `['PENDING']`).
+     */
     listRecipientTabs(settlementStatuses?: string[]): Promise<TabInfo[]>;
+    /**
+     * List all guarantee requests associated with a tab.
+     *
+     * @param tabId - Tab identifier.
+     */
     getTabGuarantees(tabId: number | bigint): Promise<GuaranteeInfo[]>;
+    /**
+     * Fetch the most recent guarantee for a tab.
+     *
+     * @param tabId - Tab identifier.
+     * @returns The latest {@link GuaranteeInfo}, or `null` if none exists.
+     */
     getLatestGuarantee(tabId: number | bigint): Promise<GuaranteeInfo | null>;
+    /**
+     * Fetch a specific guarantee by tab ID and request ID.
+     *
+     * @param tabId - Tab identifier.
+     * @param reqId - Guarantee request identifier.
+     * @returns The {@link GuaranteeInfo}, or `null` if not found.
+     */
     getGuarantee(tabId: number | bigint, reqId: number | bigint): Promise<GuaranteeInfo | null>;
+    /** List all on-chain payments received by this recipient. */
     listRecipientPayments(): Promise<RecipientPaymentInfo[]>;
+    /**
+     * List collateral deposit/withdrawal events associated with a tab.
+     *
+     * @param tabId - Tab identifier.
+     */
     getCollateralEventsForTab(tabId: number | bigint): Promise<CollateralEventInfo[]>;
+    /**
+     * Fetch the collateral balance a user has locked for a specific asset.
+     *
+     * @param userAddress - Address of the payer.
+     * @param assetAddress - ERC20 token address, or zero address for ETH.
+     * @returns Balance info, or `null` if no record exists.
+     */
     getUserAssetBalance(userAddress: string, assetAddress: string): Promise<AssetBalanceInfo | null>;
 }