@4mica/sdk 1.0.2 → 1.1.1

package/README.md

@@ -25,12 +25,30 @@ yarn add @4mica/sdk
 
 Node.js 18+ is required.
 
+## Networks
+
+| Shorthand | CAIP-2 | Core API URL |
+|---|---|---|
+| `ethereum-sepolia` | `eip155:11155111` | `https://ethereum.sepolia.4mica.xyz/` |
+| `base-sepolia` | `eip155:84532` | `https://base.sepolia.4mica.xyz/` |
+
+The default network is Ethereum Sepolia. Use `.network()` or the `4MICA_NETWORK` environment
+variable to switch networks.
+
+```ts
+import { NETWORKS } from "@4mica/sdk";
+
+console.log(NETWORKS["base-sepolia"].caip2);   // "eip155:84532"
+console.log(NETWORKS["base-sepolia"].rpcUrl);  // "https://base.sepolia.4mica.xyz/"
+```
+
 ## Initialization and Configuration
 
 The SDK requires a signing key and can use sensible defaults for the rest:
 
 - `walletPrivateKey` (**required** unless `signer` is provided): private key used for signing
-- `rpcUrl` (optional): URL of the 4Mica core RPC server. Defaults to `https://api.4mica.xyz/`.
+- `network` (optional): select a network by shorthand or CAIP-2 id. Defaults to `ethereum-sepolia`.
+- `rpcUrl` (optional): override the core API URL directly (for self-hosted deployments).
 - `ethereumHttpRpcUrl` (optional): Ethereum JSON-RPC endpoint; fetched from core if omitted
 - `contractAddress` (optional): Core4Mica contract address; fetched from core if omitted
 - `adminApiKey` (optional): API key for admin RPCs
@@ -49,7 +67,7 @@ import { Client, ConfigBuilder } from "@4mica/sdk";
 
 async function main() {
   const cfg = new ConfigBuilder()
-    .rpcUrl("https://api.4mica.xyz/")
+    .network("base-sepolia")   // or "ethereum-sepolia" (default)
     .walletPrivateKey("0x...")
     .build();
 
@@ -68,12 +86,14 @@ Set environment variables (example `.env`):
 
 ```bash
 4MICA_WALLET_PRIVATE_KEY="0x..."
-4MICA_RPC_URL="https://api.4mica.xyz/"
+4MICA_NETWORK="base-sepolia"           # shorthand or CAIP-2 id
+# or override URL directly:
+# 4MICA_RPC_URL="https://base.sepolia.4mica.xyz/"
 4MICA_ETHEREUM_HTTP_RPC_URL="http://localhost:8545"
 4MICA_CONTRACT_ADDRESS="0x..."
 4MICA_ADMIN_API_KEY="ak_..."
 4MICA_BEARER_TOKEN="Bearer <access_token>"
-4MICA_AUTH_URL="https://api.4mica.xyz/"
+4MICA_AUTH_URL="https://ethereum.sepolia.4mica.xyz/"
 4MICA_AUTH_REFRESH_MARGIN_SECS="60"
 ```
 
@@ -81,7 +101,7 @@ If you want to set them inline for a single command, use `env` since most shells
 variable names that start with a digit:
 
 ```bash
-env 4MICA_WALLET_PRIVATE_KEY="0x..." 4MICA_RPC_URL="https://api.4mica.xyz/" node app.js
+env 4MICA_WALLET_PRIVATE_KEY="0x..." 4MICA_NETWORK="base-sepolia" node app.js
 ```
 
 Then in code:
@@ -294,7 +314,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/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.2",
+  "version": "1.1.1",
   "description": "TypeScript SDK for interacting with the 4Mica payment network",
   "license": "MIT",
   "repository": {