clutch-hub-sdk-js 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [3.0.0](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v2.0.1...v3.0.0) (2026-07-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* verifying an unsigned transaction now requires a chainId
+pinned via the ClutchHubSdk constructor or expected.chainId.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+* signTransaction's hash preimage and signed payload
+both gained chain_id (inserted after nonce; everything after it shifts
+by one index). fare/amount/balance public types moved from number to
+bigint; the corresponding GraphQL mutation variables changed from
+Int to String. buildAuthChallengeMessage/authChallengeHashHex/
+signAuthChallenge gained a required leading chainId parameter and the
+auth challenge string format changed — no fallback to the old
+two-field format. Requires clutch-node treasury-break and a hub-api
+build with chainInfo/createUnsignedBurn. The orchestrator REST client
+described in the task brief was deliberately not built: it targets a
+payment-orchestrator service that does not exist yet.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+### Features
+
+* v3 wire format — chain_id in signing, bigint amounts, tx verification, Burn ([b677894](https://github.com/clutchprotocol/clutch-hub-sdk-js/commit/b677894d92cd39a9444bec93b09226d775145dfd))
+
+
+### Bug Fixes
+
+* fail closed when verifying an unsigned tx with no pinned chainId ([353a5f2](https://github.com/clutchprotocol/clutch-hub-sdk-js/commit/353a5f278bb2192cdfa4dbed9c4d850cd1a06042))
+
 ## [2.0.1](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v2.0.0...v2.0.1) (2026-07-24)
 
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from './types';
-export * from './sdk';
-export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions';
-export type { SubscriptionHandlers } from './subscriptions';
+export * from './types.js';
+export * from './sdk.js';
+export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions.js';
+export type { SubscriptionHandlers } from './subscriptions.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export * from './types';
-export * from './sdk';
-export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions';
+export * from './types.js';
+export * from './sdk.js';
+export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions.js';

package/dist/sdk.d.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'buffer';
-import { type SubscriptionHandlers } from './subscriptions';
-import { AvailableRideRequest, AvailableRideOffer, AvailableActiveTrip, AvailableCompletedTrip, AvailableRecentTrip, FaucetResponse, MapBounds, RideRequestArgs, RideOfferArgs, RideAcceptanceArgs, RidePayArgs, RideCancelArgs, RideRequestCancelArgs, Signature } from './types';
+import { type SubscriptionHandlers } from './subscriptions.js';
+import { AvailableRideRequest, AvailableRideOffer, AvailableActiveTrip, AvailableCompletedTrip, AvailableRecentTrip, BurnArgs, FaucetResponse, MapBounds, RideRequestArgs, RideOfferArgs, RideAcceptanceArgs, RidePayArgs, RideCancelArgs, RideRequestCancelArgs, Signature } from './types.js';
 /** Strip 0x/0X prefix - hex parsers (e.g. @noble/secp256k1) do not accept it. Exported for consumers. */
 export declare function stripHexPrefix(hex: string): string;
 /**
@@ -17,21 +17,23 @@ declare global {
 export declare const AUTH_CHALLENGE_PREFIX = "clutch-auth";
 /**
  * Canonical auth challenge message for `generateToken`. Must match clutch-hub-api
- * (`hub::auth::build_auth_challenge_message`) byte-for-byte: the exact `publicKey` string
- * sent as the mutation argument and the timestamp in decimal unix seconds.
+ * (`hub::auth::build_auth_challenge_message`) byte-for-byte: `clutch-auth:{chainId}:{publicKey}:{timestamp}`.
+ * `chainId` binds the signed challenge to this hub's chain — without it, a challenge captured
+ * on one chain would authenticate the same key on any other Clutch hub within the clock-skew
+ * window. Breaking change from the pre-treasury (chainId-less) format; no fallback.
  */
-export declare function buildAuthChallengeMessage(publicKey: string, timestamp: number): string;
+export declare function buildAuthChallengeMessage(chainId: number, publicKey: string, timestamp: number): string;
 /**
  * Keccak-256 of the canonical auth message as 64-char lowercase hex (no 0x).
  * The signature is then computed over the UTF-8 bytes of this hex string (see `signHashHex`),
  * the same convention used for transaction hashes.
  */
-export declare function authChallengeHashHex(publicKey: string, timestamp: number): string;
+export declare function authChallengeHashHex(chainId: number, publicKey: string, timestamp: number): string;
 /**
  * Sign the `generateToken` proof-of-key-ownership challenge.
  * @param timestamp Unix seconds; the Hub API rejects timestamps more than ±120s from server time.
  */
-export declare function signAuthChallenge(publicKey: string, timestamp: number, privateKey: string): Promise<Signature>;
+export declare function signAuthChallenge(chainId: number, publicKey: string, timestamp: number, privateKey: string): Promise<Signature>;
 /**
  * Represents an unsigned transaction returned by the GraphQL API.
  */
@@ -39,7 +41,58 @@ export interface UnsignedTransaction {
     data: any;
     from: string;
     nonce: number;
+    /** u64 on the wire; kept as `number` here since real chain ids fit well under 2^53. */
+    chain_id: number;
 }
+/**
+ * Expectations `signTransaction` verifies an unsigned blob against before signing it — see
+ * `verifyUnsignedTransaction`. The hub is untrusted in this design (that's the entire point of
+ * client-side signing), so a caller who knows what it asked for should say so and have the SDK
+ * check the hub's answer instead of signing it blind.
+ */
+export interface ExpectedTx {
+    type: 'RideRequest' | 'RideOffer' | 'RidePay' | 'RideAcceptance' | 'RideCancel' | 'RideRequestCancel' | 'Burn';
+    /** The wallet's own address/pk form; `signTransaction` fills this in automatically. */
+    from?: string;
+    /** Pinned CLIENT-side (app config, e.g. 2077) — never sourced from the hub's own `chainInfo`. */
+    chainId?: number;
+    /** RideRequest/RideOffer/RidePay. */
+    fare?: bigint;
+    /** Burn. */
+    amount?: bigint;
+    /** The acceptance/offer/request hash the caller itself passed in. */
+    refTxHash?: string;
+    /** Burn. */
+    redemptionRef?: string;
+}
+/**
+ * Result of a passing `verifyUnsignedTransaction` check.
+ */
+export interface VerifiedTx {
+    /**
+     * The referrer the hub injected into this transaction, if any. The hub picks the referrer
+     * server-side and there is currently no signed-quote flow to pin it client-side, so this
+     * value CANNOT be verified — it is surfaced only so a caller can display it to the user
+     * before they sign. Displaying it is the interim mitigation, not a fix; full referrer
+     * pinning needs the signed-quote flow (a later plan).
+     */
+    referrer: string | null;
+}
+/**
+ * Verify an unsigned-transaction blob from the hub against what the caller actually asked for,
+ * before it gets signed. Pure and side-effect-free.
+ *
+ * WHY THIS EXISTS: the hub is the untrusted party in this design — the private key never
+ * leaves the client precisely because the hub is not trusted — yet without this check a
+ * compromised hub can alter the fare, swap the referrer, or hand back a different chain's id,
+ * and the SDK would sign whatever it was given. This closes the blind-signing hole for every
+ * field it's possible to pin client-side. It does NOT close the referrer hole (see
+ * `VerifiedTx.referrer`).
+ *
+ * Any mismatch throws `Error('unsigned tx does not match request: <field>')` naming the
+ * offending field.
+ */
+export declare function verifyUnsignedTransaction(unsignedTx: UnsignedTransaction, expected: ExpectedTx): VerifiedTx;
 /**
  * SDK for interacting with the Clutch Hub API and signing transactions.
  * Provides client-side transaction signing and blockchain interaction capabilities.
@@ -49,14 +102,24 @@ export declare class ClutchHubSdk {
     private publicKey;
     private token;
     private tokenExpireTime;
+    private chainId;
+    /** Whether the caller actually passed a `chainId` (vs. the 0 default) — see `signTransaction`. */
+    private chainIdConfigured;
     /**
      * @param apiUrl Hub API base URL.
      * @param publicKey Wallet address (0x + 40 hex) or uncompressed public key (130 hex).
      * @param privateKey Optional wallet private key, required to obtain JWTs: `generateToken`
      *   demands a signed proof-of-key-ownership challenge. May also be provided later via
      *   {@link setPrivateKey}. Never sent to the API — only used for local signing.
+     * @param chainId This chain's id (e.g. 2077 for the app's own config), used for the
+     *   chain-bound auth challenge and as the default `expected.chainId` pin in
+     *   {@link signTransaction}'s `verifyUnsignedTransaction` check. Get this from app config,
+     *   never from the hub's own `chainInfo` response — asking the untrusted party what chain
+     *   it is defeats the check chain_id exists to provide. If omitted, `signTransaction` still
+     *   verifies every other `expected` field but skips the chain_id pin (nothing was pinned to
+     *   check against) rather than failing every real transaction against a phantom "chain 0".
      */
-    constructor(apiUrl: string, publicKey: string, privateKey?: string);
+    constructor(apiUrl: string, publicKey: string, privateKey?: string, chainId?: number);
     /**
      * Get the current public key associated with this SDK instance.
      * @returns The public key string
@@ -90,6 +153,12 @@ export declare class ClutchHubSdk {
     private subscribeGraphqlListField;
     private executeGraphQL;
     private ensureAuth;
+    /**
+     * Public wrapper around `ensureAuth`: resolves (fetching if needed) a valid JWT for this
+     * wallet and returns it as an `Authorization: Bearer <token>` header ready to attach to a
+     * hand-rolled request (e.g. an orchestrator REST client that reuses this SDK's auth).
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
     /**
      * Fetches an unsigned ride request transaction from the GraphQL API.
      */
@@ -118,10 +187,15 @@ export declare class ClutchHubSdk {
      * Only the passenger who created the request can cancel.
      */
     createUnsignedRideRequestCancel(args: RideRequestCancelArgs): Promise<UnsignedTransaction>;
+    /**
+     * Fetches an unsigned Burn transaction. Burns `amount` CLT from the caller's balance,
+     * optionally tagged with a treasury `redemptionRef` (hex(keccak256(intent_id))).
+     */
+    createUnsignedBurn(args: BurnArgs): Promise<UnsignedTransaction>;
     /**
      * Signs a transaction and returns the signature and raw RLP-encoded payload.
      */
-    signTransaction(unsignedTx: UnsignedTransaction, privateKey: string): Promise<Signature & {
+    signTransaction(unsignedTx: UnsignedTransaction, privateKey: string, expected?: ExpectedTx): Promise<Signature & {
         rawTransaction: string;
         txHash: string;
     }>;
@@ -193,14 +267,14 @@ export declare class ClutchHubSdk {
     /**
      * Fetches the current account balance for a public key.
      */
-    getAccountBalance(publicKey?: string): Promise<number>;
+    getAccountBalance(publicKey?: string): Promise<bigint>;
     /**
      * Subscribes to periodic `accountBalance` updates over WebSocket.
      * Returns a dispose function to stop the subscription.
      */
     subscribeAccountBalance(options: {
         publicKey?: string;
-    } | undefined, handlers: SubscriptionHandlers<number>): () => void;
+    } | undefined, handlers: SubscriptionHandlers<bigint>): () => void;
     /**
      * Request test CLT from the Hub API faucet (POST /faucet). Requires `faucet_enabled` and a funded
      * `faucet_private_key` on the server. No GraphQL auth token required for this HTTP endpoint.
@@ -218,3 +292,10 @@ export declare class ClutchHubSdk {
     private static readonly floatView;
     private float64ToUint64;
 }
+/**
+ * Formats CLT base units (micro-USD, at the 1 USD = 1,000,000 CLT peg) as a `$`-prefixed
+ * decimal string for display — integer math only, never floats, since a float division would
+ * reintroduce the precision loss bigint amounts exist to avoid. Cents are floored (truncated),
+ * matching how the treasury peg treats CLT as an integer.
+ */
+export declare function formatUsd(microUsd: bigint): string;