@halot/sdk 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# @halot/sdk
+
+`@halot/sdk` is the public SDK for integrating provider endpoints and requester flows with Halot.
+
+Use it in 2 cases:
+
+- provider apps that want to expose a paid route with `halot()`
+- requester apps that want to automate the x402 flow with `HalotClient`
+
+The root import is the public surface:
+
+```ts
+import { halot, HalotClient } from '@halot/sdk';
+```
+
+## Install
+
+```bash
+npm install @halot/sdk
+```
+
+## What It Exports
+
+The main public exports are:
+
+- `halot`
+- `HalotClient`
+- `createActorAuthHeaders`
+- `decodePaymentRequirement`
+- `encodePaymentRequirement`
+- `signPaymentRequirement`
+- shared types and Zod schemas such as `QuoteSchema`, `PreparedJobSchema`, `JobSchema`, `PaymentRequirementSchema`, and `PaymentAuthorizationSchema`
+
+## Provider Middleware
+
+`halot()` is the provider integration path for Express routes.
+
+It handles:
+
+- quote challenges
+- receipt verification
+- result reporting
+
+against the Halot facilitator endpoints.
+
+### Before you use it
+
+The route must use a real registered `serviceId`.
+
+The actual order is:
+
+1. register the provider
+2. register the service under that provider
+3. use the returned `serviceId` in middleware
+
+If you are using middleware for a service, you do not need `halot provider run` for that same service.
+
+### Basic usage
+
+```ts
+import express from 'express';
+import { halot } from '@halot/sdk';
+
+const app = express();
+app.use(express.json());
+
+app.post('/text', halot({
+  serviceId: 'svc_text_gpt54',
+}), async (req, res) => {
+  const { jobId, providerId, requesterAddress } = req.halot;
+  const text = await runProviderLogic(req.body.message, {
+    jobId,
+    providerId,
+    requesterAddress,
+  });
+
+  res.json({ text });
+});
+```
+
+### One route, multiple services
+
+If one route fronts multiple registered services, resolve `serviceId` from the request:
+
+```ts
+app.post('/text', halot({
+  serviceId: (req) => {
+    switch (req.body.model) {
+      case 'gpt-5.4':
+        return 'svc_text_gpt54';
+      case 'gpt-5.4-mini':
+        return 'svc_text_gpt54mini';
+      default:
+        throw new Error('Unsupported model');
+    }
+  },
+}), async (req, res) => {
+  const text = await runProviderLogic(req.body.message);
+  res.json({ text, model: req.body.model });
+});
+```
+
+### Signing facilitator report requests
+
+Use `providerHeaders` when your provider app needs to sign `/facilitator/report` as the registered provider:
+
+```ts
+import express from 'express';
+import { createActorAuthHeaders, halot } from '@halot/sdk';
+
+const app = express();
+app.use(express.json());
+
+const providerWallet = {
+  address: process.env.PROVIDER_ADDRESS!,
+  signMessage: async (message: string) => signWithWallet(message),
+};
+
+app.post('/text', halot({
+  serviceId: 'svc_text_gpt54',
+  providerHeaders: async (_req, context) => createActorAuthHeaders(providerWallet, {
+    actorId: context.providerId,
+    role: 'provider',
+    method: 'POST',
+    path: '/facilitator/report',
+    timestamp: new Date().toISOString(),
+  }),
+}), async (req, res) => {
+  const text = await runProviderLogic(req.body.message);
+  res.json({ text });
+});
+```
+
+### Middleware flow
+
+When a requester calls your middleware route:
+
+1. if there is no `x-halot-receipt`, the middleware requests a quote and returns `402`
+2. the requester signs the payment requirement
+3. the requester prepares and funds the job through Halot
+4. the requester retries with `x-halot-receipt`
+5. the middleware verifies that receipt through `/facilitator/verify`
+6. your handler runs
+7. on a 2xx handler response, the middleware reports the output through `/facilitator/report`
+
+### Request context
+
+Inside a middleware-backed route:
+
+```ts
+app.post('/text', halot({ serviceId: 'svc_text_gpt54' }), (req, res) => {
+  const { jobId, quoteId, serviceId, providerId, requesterAddress } = req.halot;
+  const output = runProviderLogic(req.body.message);
+  res.json({ output });
+});
+```
+
+### Options
+
+`halot()` supports:
+
+- `serviceId`
+- `providerHeaders`
+- `reportMaxAttempts`
+- `reportRetryDelayMs`
+- `onError`
+
+## Requester Client
+
+`HalotClient` is the requester-side helper.
+
+It automates:
+
+1. triggering a `402` challenge
+2. decoding and signing the payment requirement
+3. preparing the job
+4. funding the prepared job through your adapter
+5. confirming the funding transaction
+6. retrying the target endpoint with `x-halot-receipt`
+
+```ts
+import { HalotClient } from '@halot/sdk';
+import { Wallet } from 'ethers';
+
+const wallet = new Wallet(process.env.HALOT_PRIVATE_KEY!);
+
+const client = new HalotClient({
+  wallet: {
+    address: wallet.address,
+    signMessage: (message) => wallet.signMessage(message),
+  },
+  funding: {
+    async fund(preparedJob) {
+      const transactionHash = await fundPreparedJobOnChain(preparedJob);
+      return { transactionHash };
+    },
+  },
+  defaultNetwork: '0g:testnet',
+});
+
+const response = await client.request<{ text: string }>('https://provider.example/text', {
+  method: 'POST',
+  body: {
+    model: 'gpt-5.4',
+    message: 'Summarize the latest verifier assignment state.',
+  },
+});
+```
+
+`response` includes:
+
+- `data`
+- `jobId`
+- `status`
+
+## Auth and Payment Helpers
+
+The SDK also exports helpers for:
+
+- actor-signed provider or verifier requests via `createActorAuthHeaders`
+- payment requirement encoding and decoding
+- payment requirement signing
+
+```ts
+import {
+  createActorAuthHeaders,
+  decodePaymentRequirement,
+  encodePaymentRequirement,
+  signPaymentRequirement,
+} from '@halot/sdk';
+```
+
+## Shared Types and Schemas
+
+You can also import shared runtime types and validators such as:
+
+- `QuoteSchema`
+- `PreparedJobSchema`
+- `JobSchema`
+- `PaymentRequirementSchema`
+- `PaymentAuthorizationSchema`
+
+These are useful when you are building custom clients or validating Halot payloads outside the default middleware and client helpers.

package/dist/auth/actor.d.ts

@@ -0,0 +1,17 @@
+export type ActorRole = 'provider' | 'verifier';
+type MessageSigner = {
+    address: string;
+    signMessage(message: string): Promise<string>;
+};
+export type ActorAuthPayload = {
+    actorId: string;
+    actorAddress: string;
+    role: ActorRole;
+    method: string;
+    path: string;
+    timestamp: string;
+};
+export declare function createActorAuthMessage(payload: ActorAuthPayload): string;
+export declare function createActorAuthHeaders(wallet: MessageSigner, payload: Omit<ActorAuthPayload, 'actorAddress'>): Promise<Record<string, string>>;
+export declare function verifyActorAuth(payload: ActorAuthPayload, signature: string): boolean;
+export {};

package/dist/auth/actor.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createActorAuthMessage = createActorAuthMessage;
+exports.createActorAuthHeaders = createActorAuthHeaders;
+exports.verifyActorAuth = verifyActorAuth;
+const ethers_1 = require("ethers");
+const hash_1 = require("../utils/hash");
+function createActorAuthMessage(payload) {
+    return (0, hash_1.hashValue)({
+        actorId: payload.actorId,
+        actorAddress: (0, ethers_1.getAddress)(payload.actorAddress),
+        role: payload.role,
+        method: payload.method.toUpperCase(),
+        path: payload.path,
+        timestamp: payload.timestamp,
+    });
+}
+async function createActorAuthHeaders(wallet, payload) {
+    const actorAddress = (0, ethers_1.getAddress)(wallet.address);
+    const message = createActorAuthMessage({ ...payload, actorAddress });
+    const signature = await wallet.signMessage(message);
+    return {
+        'x-halot-actor-id': payload.actorId,
+        'x-halot-actor-address': actorAddress,
+        'x-halot-actor-role': payload.role,
+        'x-halot-actor-timestamp': payload.timestamp,
+        'x-halot-actor-signature': signature,
+    };
+}
+function verifyActorAuth(payload, signature) {
+    const message = createActorAuthMessage(payload);
+    return (0, ethers_1.getAddress)((0, ethers_1.verifyMessage)(message, signature)) === (0, ethers_1.getAddress)(payload.actorAddress);
+}

package/dist/auth/attestation.d.ts

@@ -0,0 +1,24 @@
+import { Decision } from '../types/common';
+type MessageSigner = {
+    address: string;
+    signMessage(message: Uint8Array | string): Promise<string>;
+};
+export type AttestationSignaturePayload = {
+    jobHash: string;
+    resultHash: string;
+    decision: Decision;
+    teeDigest: string;
+};
+export type AttestationRecoveryData = {
+    compactSignature: string;
+    recoveryId: number;
+    publicKey: string;
+};
+export declare function createAttestationVote(payload: Pick<AttestationSignaturePayload, 'decision'>): number;
+export declare function createAttestationSettlementDigest(payload: AttestationSignaturePayload): string;
+export declare function createAttestationMessageHash(payload: AttestationSignaturePayload): string;
+export declare function signAttestationPayload(wallet: MessageSigner, payload: AttestationSignaturePayload): Promise<string>;
+export declare function recoverAttestationPublicKey(payload: AttestationSignaturePayload, signature: string): string;
+export declare function extractAttestationRecoveryData(payload: AttestationSignaturePayload, signature: string): AttestationRecoveryData;
+export declare function verifyAttestationPayload(payload: AttestationSignaturePayload, signature: string, expectedAddress: string): boolean;
+export {};

package/dist/auth/attestation.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAttestationVote = createAttestationVote;
+exports.createAttestationSettlementDigest = createAttestationSettlementDigest;
+exports.createAttestationMessageHash = createAttestationMessageHash;
+exports.signAttestationPayload = signAttestationPayload;
+exports.recoverAttestationPublicKey = recoverAttestationPublicKey;
+exports.extractAttestationRecoveryData = extractAttestationRecoveryData;
+exports.verifyAttestationPayload = verifyAttestationPayload;
+const ethers_1 = require("ethers");
+function createAttestationVote(payload) {
+    if (payload.decision === 'approve') {
+        return 1;
+    }
+    if (payload.decision === 'reject') {
+        return 2;
+    }
+    return 3;
+}
+function createAttestationSettlementDigest(payload) {
+    return (0, ethers_1.solidityPackedKeccak256)(['bytes32', 'bytes32', 'uint8', 'bytes32'], [
+        payload.jobHash,
+        payload.resultHash,
+        createAttestationVote(payload),
+        payload.teeDigest,
+    ]);
+}
+function createAttestationMessageHash(payload) {
+    return (0, ethers_1.hashMessage)((0, ethers_1.getBytes)(createAttestationSettlementDigest(payload)));
+}
+async function signAttestationPayload(wallet, payload) {
+    return wallet.signMessage((0, ethers_1.getBytes)(createAttestationSettlementDigest(payload)));
+}
+function recoverAttestationPublicKey(payload, signature) {
+    return ethers_1.SigningKey.recoverPublicKey(createAttestationMessageHash(payload), signature);
+}
+function extractAttestationRecoveryData(payload, signature) {
+    const parsed = ethers_1.Signature.from(signature);
+    return {
+        compactSignature: parsed.compactSerialized,
+        recoveryId: Number(parsed.yParity),
+        publicKey: recoverAttestationPublicKey(payload, signature),
+    };
+}
+function verifyAttestationPayload(payload, signature, expectedAddress) {
+    return (0, ethers_1.verifyMessage)((0, ethers_1.getBytes)(createAttestationSettlementDigest(payload)), signature).toLowerCase() === expectedAddress.toLowerCase();
+}

package/dist/client/halot-client.d.ts

@@ -0,0 +1,37 @@
+import type { PreparedJob } from '../types/job.js';
+type MessageSigner = {
+    address: string;
+    signMessage(message: string): Promise<string>;
+};
+export type FundingAdapter = {
+    fund(preparedJob: PreparedJob): Promise<{
+        transactionHash: string;
+    }>;
+};
+export type HalotClientOptions = {
+    aggregatorUrl?: string;
+    wallet: MessageSigner;
+    funding: FundingAdapter;
+    defaultNetwork?: string;
+};
+export type HalotResponse<T = unknown> = {
+    data: T;
+    jobId: string;
+    status: number;
+};
+export declare class HalotClient {
+    private readonly aggregatorUrl;
+    private readonly wallet;
+    private readonly funding;
+    private readonly defaultNetwork?;
+    constructor(options: HalotClientOptions);
+    request<T = unknown>(url: string, options?: {
+        method?: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        network?: string;
+    }): Promise<HalotResponse<T>>;
+    private prepareJob;
+    private confirmJob;
+}
+export {};

package/dist/client/halot-client.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HalotClient = void 0;
+const config_js_1 = require("../config.js");
+const payment_js_1 = require("../x402/payment.js");
+const payment_js_2 = require("../x402/payment.js");
+class HalotClient {
+    aggregatorUrl;
+    wallet;
+    funding;
+    defaultNetwork;
+    constructor(options) {
+        this.aggregatorUrl = (0, config_js_1.resolveHalotAggregatorUrl)(options.aggregatorUrl);
+        this.wallet = options.wallet;
+        this.funding = options.funding;
+        this.defaultNetwork = options.defaultNetwork;
+    }
+    async request(url, options = {}) {
+        const method = options.method ?? 'POST';
+        const network = options.network ?? this.defaultNetwork;
+        const initialResponse = await fetch(url, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...options.headers },
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        if (initialResponse.status !== 402) {
+            const data = await initialResponse.json();
+            return { data, jobId: '', status: initialResponse.status };
+        }
+        const paymentRequiredHeader = initialResponse.headers.get('payment-required');
+        const body = await initialResponse.json();
+        const aggregatorUrl = (0, config_js_1.resolveHalotAggregatorUrl)(body.aggregatorUrl ?? this.aggregatorUrl);
+        let requirement;
+        if (paymentRequiredHeader) {
+            requirement = (0, payment_js_2.decodePaymentRequirement)(paymentRequiredHeader);
+        }
+        else {
+            throw new Error('402 response missing PAYMENT-REQUIRED header');
+        }
+        const authorization = await (0, payment_js_1.signPaymentRequirement)(this.wallet, requirement, network);
+        const preparedJob = await this.prepareJob(aggregatorUrl, requirement.quoteId, authorization);
+        const { transactionHash } = await this.funding.fund(preparedJob);
+        const jobId = await this.confirmJob(aggregatorUrl, preparedJob.prepareId, transactionHash);
+        const retryResponse = await fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-halot-receipt': jobId,
+                ...options.headers,
+            },
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        const data = await retryResponse.json();
+        return { data, jobId, status: retryResponse.status };
+    }
+    async prepareJob(aggregatorUrl, quoteId, authorization) {
+        const encoded = Buffer.from(JSON.stringify(authorization)).toString('base64');
+        const response = await fetch(`${aggregatorUrl}/jobs/prepare`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'PAYMENT-SIGNATURE': encoded,
+            },
+            body: JSON.stringify({
+                quoteId,
+                settlementAddress: authorization.requesterAddress,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Job preparation failed (${response.status}): ${error}`);
+        }
+        return response.json();
+    }
+    async confirmJob(aggregatorUrl, prepareId, transactionHash) {
+        const response = await fetch(`${aggregatorUrl}/jobs`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ prepareId, transactionHash }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Job confirmation failed (${response.status}): ${error}`);
+        }
+        const job = await response.json();
+        return job.jobId;
+    }
+}
+exports.HalotClient = HalotClient;

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { HalotClient } from './halot-client.js';
+export type { HalotClientOptions, HalotResponse, FundingAdapter } from './halot-client.js';

package/dist/client/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HalotClient = void 0;
+var halot_client_js_1 = require("./halot-client.js");
+Object.defineProperty(exports, "HalotClient", { enumerable: true, get: function () { return halot_client_js_1.HalotClient; } });

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_HALOT_AGGREGATOR_URL = "https://api.halot.xyz";
+export declare function resolveHalotAggregatorUrl(override?: string): string;

package/dist/config.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HALOT_AGGREGATOR_URL = void 0;
+exports.resolveHalotAggregatorUrl = resolveHalotAggregatorUrl;
+exports.DEFAULT_HALOT_AGGREGATOR_URL = 'https://api.halot.xyz';
+function resolveHalotAggregatorUrl(override) {
+    return normalizeBaseUrl(override ?? exports.DEFAULT_HALOT_AGGREGATOR_URL);
+}
+function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, '');
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export * from './types/common';
+export * from './types/provider';
+export * from './types/requester';
+export * from './types/service';
+export * from './types/verifier';
+export * from './types/quote';
+export * from './types/job';
+export * from './types/x402';
+export * from './config';
+export * from './utils/date';
+export * from './utils/amount';
+export * from './utils/category';
+export * from './utils/hash';
+export * from './utils/id';
+export * from './utils/json-file';
+export * from './utils/schema';
+export * from './utils/artifacts';
+export * from './auth/actor';
+export * from './auth/attestation';
+export * from './x402/payment';
+export * from './zero-g/compute';
+export * from './zero-g/storage';
+export { halot } from './middleware/halot';
+export type { HalotOptions, HalotRequestContext, ProviderHeadersResolver, ServiceIdResolver } from './middleware/halot';
+export { HalotClient } from './client/halot-client';
+export type { HalotClientOptions, HalotResponse, FundingAdapter } from './client/halot-client';

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HalotClient = exports.halot = void 0;
+__exportStar(require("./types/common"), exports);
+__exportStar(require("./types/provider"), exports);
+__exportStar(require("./types/requester"), exports);
+__exportStar(require("./types/service"), exports);
+__exportStar(require("./types/verifier"), exports);
+__exportStar(require("./types/quote"), exports);
+__exportStar(require("./types/job"), exports);
+__exportStar(require("./types/x402"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./utils/date"), exports);
+__exportStar(require("./utils/amount"), exports);
+__exportStar(require("./utils/category"), exports);
+__exportStar(require("./utils/hash"), exports);
+__exportStar(require("./utils/id"), exports);
+__exportStar(require("./utils/json-file"), exports);
+__exportStar(require("./utils/schema"), exports);
+__exportStar(require("./utils/artifacts"), exports);
+__exportStar(require("./auth/actor"), exports);
+__exportStar(require("./auth/attestation"), exports);
+__exportStar(require("./x402/payment"), exports);
+__exportStar(require("./zero-g/compute"), exports);
+__exportStar(require("./zero-g/storage"), exports);
+var halot_1 = require("./middleware/halot");
+Object.defineProperty(exports, "halot", { enumerable: true, get: function () { return halot_1.halot; } });
+var halot_client_1 = require("./client/halot-client");
+Object.defineProperty(exports, "HalotClient", { enumerable: true, get: function () { return halot_client_1.HalotClient; } });

package/dist/middleware/aggregator-client.d.ts

@@ -0,0 +1,8 @@
+import type { FacilitateQuoteResponse, FacilitateVerifyResponse } from './types.js';
+export declare class AggregatorClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    quote(serviceId: string, input?: unknown): Promise<FacilitateQuoteResponse>;
+    verify(jobId: string): Promise<FacilitateVerifyResponse>;
+    report(jobId: string, providerId: string, output: unknown, providerHeaders?: Record<string, string>): Promise<void>;
+}

package/dist/middleware/aggregator-client.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregatorClient = void 0;
+class AggregatorClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    async quote(serviceId, input) {
+        const response = await fetch(`${this.baseUrl}/facilitator/quote`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ serviceId, input }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Aggregator quote failed (${response.status}): ${body}`);
+        }
+        return response.json();
+    }
+    async verify(jobId) {
+        const response = await fetch(`${this.baseUrl}/facilitator/verify`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jobId }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Aggregator verify failed (${response.status}): ${body}`);
+        }
+        return response.json();
+    }
+    async report(jobId, providerId, output, providerHeaders) {
+        const extraHeaders = providerHeaders ?? {};
+        const response = await fetch(`${this.baseUrl}/facilitator/report`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...extraHeaders,
+            },
+            body: JSON.stringify({ jobId, providerId, output }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Aggregator report failed (${response.status}): ${body}`);
+        }
+    }
+}
+exports.AggregatorClient = AggregatorClient;

package/dist/middleware/halot.d.ts

@@ -0,0 +1,4 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { HalotOptions, HalotRequestContext, ProviderHeadersResolver, ServiceIdResolver } from './types.js';
+export declare function halot(options: HalotOptions): (request: Request, response: Response, next: NextFunction) => Promise<void>;
+export type { HalotOptions, HalotRequestContext, ProviderHeadersResolver, ServiceIdResolver };