@4mica/sdk 1.0.1 → 1.1.0

package/README.md

@@ -294,7 +294,7 @@ Notes:
 
 #### RecipientClient Methods
 
-- `createTab(userAddress, recipientAddress, erc20Token?, ttl?)`
+- `createTab(userAddress, recipientAddress, erc20Token?, ttl?, guaranteeVersion?)`
 - `getTabPaymentStatus(tabId)`
 - `issuePaymentGuarantee(claims, signature, scheme)` — accepts V1 or V2 claims
 - `verifyPaymentGuarantee(cert)`

package/dist/client/recipient.d.ts

@@ -14,11 +14,12 @@ export declare class RecipientClient {
      * @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.
+     * @param guaranteeVersion - Guarantee version for the version-scoped tab identity.
      * @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<{
+    createTab(userAddress: string, recipientAddress: string, erc20Token: string | undefined | null, ttl?: number | null, guaranteeVersion?: number): Promise<{
         tabId: bigint;
         assetAddress: string;
         nextReqId: bigint;

package/dist/client/recipient.js

@@ -28,16 +28,18 @@ class RecipientClient {
      * @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.
+     * @param guaranteeVersion - Guarantee version for the version-scoped tab identity.
      * @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.
      */
-    async createTab(userAddress, recipientAddress, erc20Token, ttl) {
+    async createTab(userAddress, recipientAddress, erc20Token, ttl, guaranteeVersion = 1) {
         const body = {
             user_address: (0, utils_1.normalizeAddress)(userAddress),
             recipient_address: (0, utils_1.normalizeAddress)(recipientAddress),
             erc20_token: erc20Token ? (0, utils_1.normalizeAddress)(erc20Token) : null,
             ttl: ttl ?? null,
+            guarantee_version: guaranteeVersion,
         };
         const result = await this.client.rpc.createPaymentTab(body);
         const record = result;

package/dist/contract.js

@@ -7,6 +7,7 @@ const chain_1 = require("./chain");
 const errors_1 = require("./errors");
 const utils_1 = require("./utils");
 const DEFAULT_REMUNERATE_GAS_LIMIT = 8000000n;
+const DEFAULT_PAY_TAB_ERC20_GAS_LIMIT = 300000n;
 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 {
@@ -89,10 +90,27 @@ class ContractGateway {
     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 this.enqueueTx(() => erc20.write.approve([spender, (0, utils_1.parseU256)(amount)], this.defaultFeeParams()));
-        return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
+        const targetAllowance = (0, utils_1.parseU256)(amount);
+        const sendApprove = async (value) => {
+            const hash = await this.enqueueTx(() => erc20.write.approve([spender, value], this.defaultFeeParams()));
+            const txReceipt = await this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
+            if (txReceipt.status !== 'success') {
+                throw new errors_1.ContractError(`approve transaction reverted: ${hash}`);
+            }
+            return txReceipt;
+        };
+        try {
+            return await sendApprove(targetAllowance);
+        }
+        catch (error) {
+            // Some ERC20s require resetting allowance to zero before setting a new value.
+            if (targetAllowance === 0n) {
+                throw error;
+            }
+            await sendApprove(0n);
+            return sendApprove(targetAllowance);
+        }
     }
     async deposit(amount, erc20Token, waitOptions) {
         const { receipt } = this.splitWaitOptions(waitOptions);
@@ -141,13 +159,11 @@ class ContractGateway {
         return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async payTabErc20(tabId, amount, erc20Token, recipient, waitOptions) {
-        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,
-        ], this.defaultFeeParams()));
+        const { gas, 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], {
+            gas: gas ?? DEFAULT_PAY_TAB_ERC20_GAS_LIMIT,
+            ...this.defaultFeeParams(),
+        }));
         return this.publicClient.waitForTransactionReceipt({ hash, ...receipt });
     }
     async requestWithdrawal(amount, erc20Token, waitOptions) {

package/dist/guarantee.d.ts

@@ -3,7 +3,7 @@ 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).
+ * by the Core4Mica contract. Supports V1 (10 fields) and V2 (19 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.

package/dist/guarantee.js

@@ -22,7 +22,7 @@ const CLAIM_TYPES = [
 ];
 // 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)
+//          validation_subject_hash, job_hash, required_validation_tag (dynamic string)
 const CLAIM_TYPES_V2 = [
     { type: 'bytes32' }, // domain
     { type: 'uint256' }, // tab_id
@@ -41,6 +41,7 @@ const CLAIM_TYPES_V2 = [
     { type: 'uint256' }, // validator_agent_id
     { type: 'uint8' }, // min_validation_score
     { type: 'bytes32' }, // validation_subject_hash
+    { type: 'bytes32' }, // job_hash
     { type: 'string' }, // required_validation_tag (dynamic)
 ];
 const CLAIM_TYPES_V2_TUPLE = [
@@ -64,6 +65,7 @@ const CLAIM_TYPES_V2_TUPLE = [
             { name: 'validatorAgentId', type: 'uint256' },
             { name: 'minValidationScore', type: 'uint8' },
             { name: 'validationSubjectHash', type: 'bytes32' },
+            { name: 'jobHash', type: 'bytes32' },
             { name: 'requiredValidationTag', type: 'string' },
         ],
     },
@@ -85,7 +87,7 @@ function normalizeHexBytes(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).
+ * by the Core4Mica contract. Supports V1 (10 fields) and V2 (19 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.
@@ -134,6 +136,7 @@ function encodeGuaranteeClaims(claims) {
                 validatorAgentId: p.validatorAgentId,
                 minValidationScore: p.minValidationScore,
                 validationSubjectHash: (0, utils_1.ensureHexPrefix)(p.validationSubjectHash),
+                jobHash: (0, utils_1.ensureHexPrefix)(p.jobHash),
                 requiredValidationTag: p.requiredValidationTag,
             },
         ]);
@@ -228,7 +231,8 @@ function decodeV2Claims(encoded) {
                 validatorAgentId: decoded[14],
                 minValidationScore: decoded[15],
                 validationSubjectHash: decoded[16],
-                requiredValidationTag: decoded[17],
+                jobHash: decoded[17],
+                requiredValidationTag: decoded[18],
             });
         }
         catch (flatErr) {
@@ -237,7 +241,7 @@ function decodeV2Claims(encoded) {
     }
 }
 function buildDecodedV2Claims(decoded) {
-    const { domain, tabId, reqId, user, recipient, amount, totalAmount, asset, timestamp, claimsVersion, validationRegistryAddress, validationRequestHash, validationChainId, validatorAddress, validatorAgentId, minValidationScore, validationSubjectHash, requiredValidationTag, } = decoded;
+    const { domain, tabId, reqId, user, recipient, amount, totalAmount, asset, timestamp, claimsVersion, validationRegistryAddress, validationRequestHash, validationChainId, validatorAddress, validatorAgentId, minValidationScore, validationSubjectHash, jobHash, requiredValidationTag, } = decoded;
     if (claimsVersion !== 2n) {
         throw new errors_1.VerificationError(`expected V2 claims version, got: ${claimsVersion}`);
     }
@@ -249,6 +253,7 @@ function buildDecodedV2Claims(decoded) {
         validatorAgentId: (0, utils_1.parseU256)(validatorAgentId),
         minValidationScore: Number(minValidationScore),
         validationSubjectHash: validationSubjectHash,
+        jobHash: jobHash,
         requiredValidationTag: requiredValidationTag,
     };
     return {

package/dist/models.d.ts

@@ -47,6 +47,7 @@ export interface PaymentGuaranteeValidationPolicyV2 {
     validatorAgentId: bigint;
     minValidationScore: number;
     validationSubjectHash: string;
+    jobHash: string;
     requiredValidationTag: string;
 }
 /**
@@ -54,6 +55,7 @@ export interface PaymentGuaranteeValidationPolicyV2 {
  *
  * Compute `validationSubjectHash` via `computeValidationSubjectHash(baseClaims)` and
  * `validationRequestHash` via `computeValidationRequestHash(partialV2)` before constructing.
+ * The `jobHash` must be provided and included in the validation request hash.
  *
  * @throws {@link ValidationError} if `minValidationScore` is outside [1, 100].
  */
@@ -65,6 +67,7 @@ export declare class PaymentGuaranteeRequestClaimsV2 extends PaymentGuaranteeReq
     validatorAgentId: bigint;
     minValidationScore: number;
     validationSubjectHash: string;
+    jobHash: string;
     requiredValidationTag: string;
     constructor(init: {
         userAddress: string;
@@ -81,6 +84,7 @@ export declare class PaymentGuaranteeRequestClaimsV2 extends PaymentGuaranteeReq
         validatorAgentId: bigint;
         minValidationScore: number;
         validationSubjectHash: string;
+        jobHash: string;
         requiredValidationTag: string;
     });
 }

package/dist/models.js

@@ -60,6 +60,7 @@ exports.PaymentGuaranteeRequestClaims = PaymentGuaranteeRequestClaims;
  *
  * Compute `validationSubjectHash` via `computeValidationSubjectHash(baseClaims)` and
  * `validationRequestHash` via `computeValidationRequestHash(partialV2)` before constructing.
+ * The `jobHash` must be provided and included in the validation request hash.
  *
  * @throws {@link ValidationError} if `minValidationScore` is outside [1, 100].
  */
@@ -71,6 +72,7 @@ class PaymentGuaranteeRequestClaimsV2 extends PaymentGuaranteeRequestClaims {
     validatorAgentId;
     minValidationScore;
     validationSubjectHash;
+    jobHash;
     requiredValidationTag;
     constructor(init) {
         super(init);
@@ -84,6 +86,7 @@ class PaymentGuaranteeRequestClaimsV2 extends PaymentGuaranteeRequestClaims {
         this.validatorAgentId = init.validatorAgentId;
         this.minValidationScore = init.minValidationScore;
         this.validationSubjectHash = (0, utils_1.ensureHexPrefix)(init.validationSubjectHash).toLowerCase();
+        this.jobHash = (0, utils_1.ensureHexPrefix)(init.jobHash).toLowerCase();
         this.requiredValidationTag = init.requiredValidationTag;
     }
 }

package/dist/payment.d.ts

@@ -22,6 +22,7 @@ export interface PaymentPayloadClaimsV2 extends PaymentPayloadClaimsBase {
     validator_agent_id: string;
     min_validation_score: number;
     validation_subject_hash: string;
+    job_hash: string;
     required_validation_tag: string;
 }
 /** Assembled payment payload ready to be submitted to the core RPC `issueGuarantee` endpoint. */
@@ -41,7 +42,7 @@ export declare function serializePaymentClaims(claims: PaymentGuaranteeRequestCl
 /**
  * Serialize V2 payment claims to the wire format expected by the core RPC.
  *
- * Extends the V1 serialisation with the eight additional validation policy fields.
+ * Extends the V1 serialisation with the nine additional validation policy fields.
  *
  * @param claims - V2 payment guarantee request claims with validation policy.
  * @returns JSON-serialisable object with snake_case keys and hex-encoded `uint256` fields.

package/dist/payment.js

@@ -27,7 +27,7 @@ function serializePaymentClaims(claims) {
 /**
  * Serialize V2 payment claims to the wire format expected by the core RPC.
  *
- * Extends the V1 serialisation with the eight additional validation policy fields.
+ * Extends the V1 serialisation with the nine additional validation policy fields.
  *
  * @param claims - V2 payment guarantee request claims with validation policy.
  * @returns JSON-serialisable object with snake_case keys and hex-encoded `uint256` fields.
@@ -43,6 +43,7 @@ function serializePaymentClaimsV2(claims) {
         validator_agent_id: (0, utils_1.serializeU256)(claims.validatorAgentId),
         min_validation_score: claims.minValidationScore,
         validation_subject_hash: claims.validationSubjectHash.toLowerCase(),
+        job_hash: claims.jobHash.toLowerCase(),
         required_validation_tag: claims.requiredValidationTag,
     };
 }

package/dist/signing.d.ts

@@ -88,6 +88,9 @@ export declare const GUARANTEE_EIP712_TYPES_V2: {
     }, {
         readonly name: "validationSubjectHash";
         readonly type: "bytes32";
+    }, {
+        readonly name: "jobHash";
+        readonly type: "bytes32";
     }, {
         readonly name: "requiredValidationTag";
         readonly type: "string";
@@ -134,6 +137,7 @@ export type GuaranteeTypedDataV2 = {
         validatorAgentId: bigint;
         minValidationScore: number;
         validationSubjectHash: Hex;
+        jobHash: Hex;
         requiredValidationTag: string;
     };
 };

package/dist/signing.js

@@ -52,6 +52,7 @@ exports.GUARANTEE_EIP712_TYPES_V2 = {
         { name: 'validatorAgentId', type: 'uint256' },
         { name: 'minValidationScore', type: 'uint8' },
         { name: 'validationSubjectHash', type: 'bytes32' },
+        { name: 'jobHash', type: 'bytes32' },
         { name: 'requiredValidationTag', type: 'string' },
     ],
 };
@@ -190,6 +191,7 @@ function buildGuaranteeTypedDataV2(params, claims) {
             validatorAgentId: claims.validatorAgentId,
             minValidationScore: claims.minValidationScore,
             validationSubjectHash: (0, utils_1.ensureHexPrefix)(claims.validationSubjectHash),
+            jobHash: (0, utils_1.ensureHexPrefix)(claims.jobHash),
             requiredValidationTag: claims.requiredValidationTag,
         },
     };
@@ -210,6 +212,7 @@ function encodeGuaranteeEip191V2(claims) {
         { type: 'uint256' },
         { type: 'uint8' },
         { type: 'bytes32' },
+        { type: 'bytes32' },
         { type: 'string' },
     ], [
         claims.userAddress,
@@ -230,6 +233,7 @@ function encodeGuaranteeEip191V2(claims) {
         (claims.validationSubjectHash.startsWith('0x')
             ? claims.validationSubjectHash
             : `0x${claims.validationSubjectHash}`),
+        (claims.jobHash.startsWith('0x') ? claims.jobHash : `0x${claims.jobHash}`),
         claims.requiredValidationTag,
     ]);
 }

package/dist/validation.d.ts

@@ -3,7 +3,7 @@ import { PaymentGuaranteeRequestClaims, PaymentGuaranteeRequestClaimsV2 } from '
 /** 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";
+export declare const VALIDATION_REQUEST_BINDING_DOMAIN = "4MICA_VALIDATION_REQUEST_V2";
 /**
  * Compute the `validationSubjectHash` for a V2 payment guarantee request.
  *
@@ -19,7 +19,7 @@ export declare function computeValidationSubjectHash(claims: PaymentGuaranteeReq
  * 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
+ * subject hash, required tag, job hash) 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.

package/dist/validation.js

@@ -8,7 +8,7 @@ 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';
+exports.VALIDATION_REQUEST_BINDING_DOMAIN = '4MICA_VALIDATION_REQUEST_V2';
 /**
  * Compute the `validationSubjectHash` for a V2 payment guarantee request.
  *
@@ -46,7 +46,7 @@ function computeValidationSubjectHash(claims) {
  * 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
+ * subject hash, required tag, job hash) 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.
@@ -68,6 +68,7 @@ function computeValidationRequestHash(claims) {
         { type: 'bytes32' },
         { type: 'uint8' },
         { type: 'bytes32' },
+        { type: 'bytes32' },
     ], [
         bindingDomain,
         BigInt(claims.validationChainId),
@@ -77,6 +78,7 @@ function computeValidationRequestHash(claims) {
         (0, utils_1.ensureHexPrefix)(claims.validationSubjectHash),
         claims.minValidationScore,
         tagHash,
+        (0, utils_1.ensureHexPrefix)(claims.jobHash),
     ]);
     return (0, viem_1.keccak256)(encoded);
 }

package/dist/x402/index.d.ts

@@ -57,7 +57,7 @@ export declare class X402Flow {
      *
      * If `accepted.extra` contains all required validation policy fields
      * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
-     * `minValidationScore`, `validationChainId`), the claims are built as V2 with
+     * `minValidationScore`, `validationChainId`, `jobHash`), the claims are built as V2 with
      * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
      * falls back to V1 claims.
      *

package/dist/x402/index.js

@@ -26,7 +26,8 @@ function hasValidationPolicy(extra) {
         extra?.validatorAddress &&
         extra?.validatorAgentId !== undefined &&
         extra?.minValidationScore !== undefined &&
-        extra?.validationChainId !== undefined);
+        extra?.validationChainId !== undefined &&
+        extra?.jobHash);
 }
 /**
  * Handles the x402 HTTP 402 payment protocol for 4Mica.
@@ -93,7 +94,7 @@ class X402Flow {
      *
      * If `accepted.extra` contains all required validation policy fields
      * (`validationRegistryAddress`, `validatorAddress`, `validatorAgentId`,
-     * `minValidationScore`, `validationChainId`), the claims are built as V2 with
+     * `minValidationScore`, `validationChainId`, `jobHash`), the claims are built as V2 with
      * the computed `validationSubjectHash` and `validationRequestHash`. Otherwise
      * falls back to V1 claims.
      *
@@ -211,6 +212,7 @@ class X402Flow {
             validatorAgentId: (0, utils_1.parseU256)(extra.validatorAgentId),
             minValidationScore: extra.minValidationScore,
             validationSubjectHash,
+            jobHash: extra.jobHash,
             requiredValidationTag: extra.requiredValidationTag ?? '',
         });
         const validationRequestHash = (0, validation_1.computeValidationRequestHash)(partialClaims);

package/dist/x402/models.d.ts

@@ -30,6 +30,7 @@ export interface PaymentRequirementsExtra {
     validatorAddress?: string;
     validatorAgentId?: string;
     minValidationScore?: number;
+    jobHash?: string;
     requiredValidationTag?: string;
 }
 export interface TabResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4mica/sdk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "TypeScript SDK for interacting with the 4Mica payment network",
   "license": "MIT",
   "repository": {
@@ -39,10 +39,12 @@
     "ethers"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "example:base-sepolia:x402-v2": "node_modules/.bin/tsx examples/base-sepolia-x402-facilitator-e2e.ts",
+    "example:manual:agents": "node_modules/.bin/tsx examples/manual-agents/demo.ts",
     "lint": "eslint . --ext .ts",
     "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\""
   },