@halot/sdk 1.0.0

package/dist/middleware/halot.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.halot = halot;
+const config_js_1 = require("../config.js");
+const aggregator_client_js_1 = require("./aggregator-client.js");
+const RECEIPT_HEADER = 'x-halot-receipt';
+function halot(options) {
+    const aggregatorUrl = (0, config_js_1.resolveHalotAggregatorUrl)(options.aggregatorUrl);
+    const aggregator = new aggregator_client_js_1.AggregatorClient(aggregatorUrl);
+    const reportMaxAttempts = Math.max(1, options.reportMaxAttempts ?? 2);
+    const reportRetryDelayMs = Math.max(0, options.reportRetryDelayMs ?? 250);
+    return async (request, response, next) => {
+        const receipt = request.headers[RECEIPT_HEADER];
+        const serviceId = await resolveServiceId(options.serviceId, request).catch((error) => {
+            options.onError?.(error);
+            response.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to resolve service',
+            });
+            return null;
+        });
+        if (!serviceId) {
+            return;
+        }
+        if (!receipt) {
+            try {
+                const result = await aggregator.quote(serviceId, request.body);
+                response
+                    .status(402)
+                    .setHeader('PAYMENT-REQUIRED', result.paymentRequired)
+                    .json({
+                    x402Version: 2,
+                    serviceId,
+                    aggregatorUrl,
+                    quote: result.quote,
+                });
+            }
+            catch (error) {
+                options.onError?.(error);
+                response.status(500).json({ error: 'Failed to fetch payment requirement' });
+            }
+            return;
+        }
+        let context;
+        try {
+            const verification = await aggregator.verify(receipt);
+            if (!verification.valid) {
+                response.status(402).json({ error: 'Invalid or unfunded receipt' });
+                return;
+            }
+            if (verification.serviceId !== serviceId) {
+                response.status(403).json({ error: 'Receipt is valid for a different service' });
+                return;
+            }
+            context = {
+                jobId: verification.jobId,
+                quoteId: verification.quoteId,
+                serviceId: verification.serviceId,
+                providerId: verification.providerId,
+                requesterAddress: verification.requesterAddress,
+            };
+        }
+        catch (error) {
+            options.onError?.(error);
+            response.status(402).json({ error: 'Receipt verification failed' });
+            return;
+        }
+        request.halot = context;
+        const originalJson = response.json.bind(response);
+        const originalSend = response.send.bind(response);
+        let completed = false;
+        const sendWithReport = (body, send) => {
+            if (completed) {
+                return response;
+            }
+            completed = true;
+            void (async () => {
+                if (response.statusCode >= 200 && response.statusCode < 300) {
+                    try {
+                        await reportWithRetry(aggregator, request, context, body, options.providerHeaders, reportMaxAttempts, reportRetryDelayMs);
+                    }
+                    catch (error) {
+                        options.onError?.(error);
+                        response.status(502);
+                        originalJson({ error: 'Failed to report result to Halot' });
+                        return;
+                    }
+                }
+                send(body);
+            })().catch((error) => {
+                options.onError?.(error);
+                response.status(500);
+                originalJson({ error: 'Failed to finalize Halot response' });
+            });
+            return response;
+        };
+        response.json = function (body) {
+            return sendWithReport(body, originalJson);
+        };
+        response.send = function (body) {
+            return sendWithReport(body, originalSend);
+        };
+        next();
+    };
+}
+async function reportWithRetry(aggregator, request, context, output, providerHeaders, maxAttempts, retryDelayMs) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const resolvedHeaders = await resolveProviderHeaders(providerHeaders, request, context);
+            await aggregator.report(context.jobId, context.providerId, output, resolvedHeaders);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < maxAttempts && retryDelayMs > 0) {
+                await sleep(retryDelayMs);
+            }
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+async function resolveProviderHeaders(providerHeaders, request, context) {
+    if (!providerHeaders) {
+        return {};
+    }
+    return typeof providerHeaders === 'function'
+        ? await providerHeaders(request, context)
+        : providerHeaders;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function resolveServiceId(serviceId, request) {
+    const resolved = typeof serviceId === 'function'
+        ? await serviceId(request)
+        : serviceId;
+    const normalized = resolved.trim();
+    if (!normalized) {
+        throw new Error('Resolved serviceId must be a non-empty string');
+    }
+    return normalized;
+}

package/dist/middleware/index.d.ts

@@ -0,0 +1,2 @@
+export { halot } from './halot';
+export type { HalotOptions, HalotRequestContext, ProviderHeadersResolver, ServiceIdResolver } from './halot';

package/dist/middleware/index.js

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

package/dist/middleware/types.d.ts

@@ -0,0 +1,45 @@
+import type { Request } from 'express';
+export type ServiceIdResolver = string | ((request: Request) => string | Promise<string>);
+export type HalotRequestContext = {
+    jobId: string;
+    quoteId: string;
+    serviceId: string;
+    providerId: string;
+    requesterAddress: string;
+};
+export type ProviderHeadersResolver = Record<string, string> | ((request: Request, context: HalotRequestContext) => Record<string, string> | Promise<Record<string, string>>);
+export type HalotOptions = {
+    serviceId: ServiceIdResolver;
+    aggregatorUrl?: string;
+    providerHeaders?: ProviderHeadersResolver;
+    reportMaxAttempts?: number;
+    reportRetryDelayMs?: number;
+    onError?: (error: unknown) => void;
+};
+export type FacilitateQuoteResponse = {
+    quote: {
+        quoteId: string;
+        total: string;
+        currency: string;
+        breakdown: Record<string, string>;
+        accepts: Array<{
+            network: string;
+            token: string;
+            amount: string;
+            payTo: string;
+            memo: string;
+        }>;
+        expiresAt: string;
+    };
+    paymentRequired: string;
+    serviceId: string;
+    aggregatorUrl: string;
+};
+export type FacilitateVerifyResponse = {
+    valid: boolean;
+    jobId: string;
+    quoteId: string;
+    serviceId: string;
+    providerId: string;
+    requesterAddress: string;
+};

package/dist/middleware/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/common.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+export declare const serviceCategoryValues: readonly ["text", "code", "image", "audio", "video", "document", "tool", "workflow"];
+export declare const settlementNetworkValues: readonly ["0g:testnet", "0g:mainnet", "stellar:testnet", "stellar:mainnet"];
+export declare const jobStatusValues: readonly ["relayed", "executing", "verifying", "settlement-pending", "settlement-submitted", "settlement-failed", "approved", "rejected", "escalated"];
+export declare const trustLevelValues: readonly ["standard", "thorough", "critical", "auto"];
+export declare const decisionValues: readonly ["approve", "reject", "uncertain"];
+export declare const ServiceCategorySchema: z.ZodEnum<{
+    text: "text";
+    code: "code";
+    image: "image";
+    audio: "audio";
+    video: "video";
+    document: "document";
+    tool: "tool";
+    workflow: "workflow";
+}>;
+export declare const SettlementNetworkSchema: z.ZodEnum<{
+    "0g:testnet": "0g:testnet";
+    "0g:mainnet": "0g:mainnet";
+    "stellar:testnet": "stellar:testnet";
+    "stellar:mainnet": "stellar:mainnet";
+}>;
+export declare const TrustLevelSchema: z.ZodEnum<{
+    standard: "standard";
+    thorough: "thorough";
+    critical: "critical";
+    auto: "auto";
+}>;
+export declare const JobStatusSchema: z.ZodEnum<{
+    relayed: "relayed";
+    executing: "executing";
+    verifying: "verifying";
+    "settlement-pending": "settlement-pending";
+    "settlement-submitted": "settlement-submitted";
+    "settlement-failed": "settlement-failed";
+    approved: "approved";
+    rejected: "rejected";
+    escalated: "escalated";
+}>;
+export declare const DecisionSchema: z.ZodEnum<{
+    approve: "approve";
+    reject: "reject";
+    uncertain: "uncertain";
+}>;
+export declare const trustLevelVerifierCount: Record<TrustLevel, number>;
+export declare function resolveVerifierCount(trustLevel: TrustLevel, baseFee?: number): number;
+export declare const WalletSchema: z.ZodObject<{
+    privateKey: z.ZodString;
+}, z.core.$strip>;
+export declare const SettlementWalletsSchema: z.ZodObject<{
+    '0g:testnet': z.ZodDefault<z.ZodString>;
+    '0g:mainnet': z.ZodDefault<z.ZodString>;
+    'stellar:testnet': z.ZodDefault<z.ZodString>;
+    'stellar:mainnet': z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export declare const WalletBundleSchema: z.ZodObject<{
+    authorities: z.ZodObject<{
+        '0g:testnet': z.ZodObject<{
+            privateKey: z.ZodString;
+        }, z.core.$strip>;
+        '0g:mainnet': z.ZodObject<{
+            privateKey: z.ZodString;
+        }, z.core.$strip>;
+        'stellar:testnet': z.ZodObject<{
+            privateKey: z.ZodString;
+        }, z.core.$strip>;
+        'stellar:mainnet': z.ZodObject<{
+            privateKey: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const OnchainAnchorSchema: z.ZodObject<{
+    network: z.ZodEnum<{
+        "0g:testnet": "0g:testnet";
+        "0g:mainnet": "0g:mainnet";
+        "stellar:testnet": "stellar:testnet";
+        "stellar:mainnet": "stellar:mainnet";
+    }>;
+    registryAddress: z.ZodString;
+    transactionHash: z.ZodString;
+    anchoredAt: z.ZodString;
+}, z.core.$strip>;
+export type ServiceCategory = z.infer<typeof ServiceCategorySchema>;
+export type SettlementNetwork = z.infer<typeof SettlementNetworkSchema>;
+export type TrustLevel = z.infer<typeof TrustLevelSchema>;
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+export type Decision = z.infer<typeof DecisionSchema>;
+export type SettlementWallets = z.infer<typeof SettlementWalletsSchema>;
+export type WalletBundle = z.infer<typeof WalletBundleSchema>;
+export type OnchainAnchor = z.infer<typeof OnchainAnchorSchema>;

package/dist/types/common.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnchainAnchorSchema = exports.WalletBundleSchema = exports.SettlementWalletsSchema = exports.WalletSchema = exports.trustLevelVerifierCount = exports.DecisionSchema = exports.JobStatusSchema = exports.TrustLevelSchema = exports.SettlementNetworkSchema = exports.ServiceCategorySchema = exports.decisionValues = exports.trustLevelValues = exports.jobStatusValues = exports.settlementNetworkValues = exports.serviceCategoryValues = void 0;
+exports.resolveVerifierCount = resolveVerifierCount;
+const zod_1 = require("zod");
+exports.serviceCategoryValues = ['text', 'code', 'image', 'audio', 'video', 'document', 'tool', 'workflow'];
+exports.settlementNetworkValues = ['0g:testnet', '0g:mainnet', 'stellar:testnet', 'stellar:mainnet'];
+exports.jobStatusValues = [
+    'relayed',
+    'executing',
+    'verifying',
+    'settlement-pending',
+    'settlement-submitted',
+    'settlement-failed',
+    'approved',
+    'rejected',
+    'escalated',
+];
+exports.trustLevelValues = ['standard', 'thorough', 'critical', 'auto'];
+exports.decisionValues = ['approve', 'reject', 'uncertain'];
+exports.ServiceCategorySchema = zod_1.z.enum(exports.serviceCategoryValues);
+exports.SettlementNetworkSchema = zod_1.z.enum(exports.settlementNetworkValues);
+exports.TrustLevelSchema = zod_1.z.enum(exports.trustLevelValues);
+exports.JobStatusSchema = zod_1.z.enum(exports.jobStatusValues);
+exports.DecisionSchema = zod_1.z.enum(exports.decisionValues);
+exports.trustLevelVerifierCount = {
+    standard: 3,
+    thorough: 5,
+    critical: 7,
+    auto: 3,
+};
+function resolveVerifierCount(trustLevel, baseFee) {
+    if (trustLevel !== 'auto') {
+        return exports.trustLevelVerifierCount[trustLevel];
+    }
+    if (baseFee !== undefined && baseFee >= 50)
+        return 7;
+    if (baseFee !== undefined && baseFee >= 10)
+        return 5;
+    return 3;
+}
+exports.WalletSchema = zod_1.z.object({
+    privateKey: zod_1.z.string(),
+});
+exports.SettlementWalletsSchema = zod_1.z.object({
+    '0g:testnet': zod_1.z.string().default(''),
+    '0g:mainnet': zod_1.z.string().default(''),
+    'stellar:testnet': zod_1.z.string().default(''),
+    'stellar:mainnet': zod_1.z.string().default(''),
+});
+exports.WalletBundleSchema = zod_1.z.object({
+    authorities: zod_1.z.object({
+        '0g:testnet': exports.WalletSchema,
+        '0g:mainnet': exports.WalletSchema,
+        'stellar:testnet': exports.WalletSchema,
+        'stellar:mainnet': exports.WalletSchema,
+    }),
+});
+exports.OnchainAnchorSchema = zod_1.z.object({
+    network: exports.SettlementNetworkSchema.refine((value) => value.startsWith('0g:'), {
+        message: 'Onchain anchors must use a 0G network',
+    }),
+    registryAddress: zod_1.z.string(),
+    transactionHash: zod_1.z.string(),
+    anchoredAt: zod_1.z.string(),
+});

package/dist/types/job.d.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+export declare const TeeProofSchema: z.ZodObject<{
+    chatId: z.ZodString;
+    digest: z.ZodString;
+    signature: z.ZodString;
+    signerAddress: z.ZodString;
+    signatureUrl: z.ZodOptional<z.ZodString>;
+    providerAddress: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PreparedVerifierSchema: z.ZodObject<{
+    verifierId: z.ZodString;
+    ownerAddress: z.ZodString;
+    signingPublicKey: z.ZodString;
+    payoutAddress: z.ZodString;
+}, z.core.$strip>;
+export declare const PreparedJobSchema: z.ZodObject<{
+    prepareId: z.ZodString;
+    quoteId: z.ZodString;
+    assignmentSeed: z.ZodString;
+    trustLevel: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    jobHash: z.ZodString;
+    serviceId: z.ZodString;
+    providerId: z.ZodString;
+    requesterAddress: z.ZodString;
+    paymentNetwork: z.ZodString;
+    paymentToken: z.ZodString;
+    settlementContractAddress: z.ZodString;
+    settlementTokenAddress: z.ZodString;
+    settlementTokenDecimals: z.ZodNumber;
+    providerPayoutAddress: z.ZodString;
+    providerAmount: z.ZodString;
+    providerAmountUnits: z.ZodString;
+    verifierFee: z.ZodString;
+    verifierFeeUnits: z.ZodString;
+    computeFee: z.ZodString;
+    computeFeeUnits: z.ZodString;
+    verifierPool: z.ZodString;
+    verifierPoolUnits: z.ZodString;
+    platformFee: z.ZodString;
+    platformFeeUnits: z.ZodString;
+    totalAmount: z.ZodString;
+    totalAmountUnits: z.ZodString;
+    threshold: z.ZodNumber;
+    selectedVerifierIds: z.ZodArray<z.ZodString>;
+    assignedVerifiers: z.ZodArray<z.ZodObject<{
+        verifierId: z.ZodString;
+        ownerAddress: z.ZodString;
+        signingPublicKey: z.ZodString;
+        payoutAddress: z.ZodString;
+    }, z.core.$strip>>;
+    input: z.ZodAny;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const JobResultSchema: z.ZodObject<{
+    resultHash: z.ZodString;
+    output: z.ZodAny;
+    submittedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const AttestationSchema: z.ZodObject<{
+    attestationId: z.ZodString;
+    attestationHash: z.ZodString;
+    jobHash: z.ZodString;
+    resultHash: z.ZodString;
+    verifierId: z.ZodString;
+    verifierAddress: z.ZodString;
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        uncertain: "uncertain";
+    }>;
+    confidence: z.ZodNumber;
+    reason: z.ZodString;
+    failedCriteria: z.ZodArray<z.ZodString>;
+    teeVerified: z.ZodBoolean;
+    teeProof: z.ZodObject<{
+        chatId: z.ZodString;
+        digest: z.ZodString;
+        signature: z.ZodString;
+        signerAddress: z.ZodString;
+        signatureUrl: z.ZodOptional<z.ZodString>;
+        providerAddress: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    verifierSignature: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const SettlementStateSchema: z.ZodEnum<{
+    pending: "pending";
+    submitted: "submitted";
+    confirmed: "confirmed";
+    failed: "failed";
+}>;
+export declare const SettlementSchema: z.ZodObject<{
+    network: z.ZodString;
+    contractAddress: z.ZodString;
+    decision: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        uncertain: "uncertain";
+    }>;
+    threshold: z.ZodNumber;
+    approvals: z.ZodNumber;
+    rejections: z.ZodNumber;
+    providerPayout: z.ZodString;
+    verifierPayout: z.ZodString;
+    requesterRefund: z.ZodString;
+    platformFee: z.ZodString;
+    state: z.ZodEnum<{
+        pending: "pending";
+        submitted: "submitted";
+        confirmed: "confirmed";
+        failed: "failed";
+    }>;
+    transactionHash: z.ZodOptional<z.ZodString>;
+    submittedAt: z.ZodOptional<z.ZodString>;
+    settledAt: z.ZodOptional<z.ZodString>;
+    confirmedAt: z.ZodOptional<z.ZodString>;
+    blockNumber: z.ZodOptional<z.ZodNumber>;
+    ledger: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const JobSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    quoteId: z.ZodString;
+    assignmentSeed: z.ZodString;
+    trustLevel: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    jobHash: z.ZodString;
+    serviceId: z.ZodString;
+    providerId: z.ZodString;
+    requesterAddress: z.ZodString;
+    paymentNetwork: z.ZodString;
+    paymentToken: z.ZodString;
+    settlementContractAddress: z.ZodString;
+    settlementTokenAddress: z.ZodString;
+    settlementTokenDecimals: z.ZodNumber;
+    totalAmount: z.ZodString;
+    breakdown: z.ZodObject<{
+        providerFee: z.ZodString;
+        verifierFee: z.ZodString;
+        computeFee: z.ZodString;
+        platformFee: z.ZodString;
+        verifierCount: z.ZodNumber;
+    }, z.core.$strip>;
+    currency: z.ZodString;
+    input: z.ZodAny;
+    status: z.ZodEnum<{
+        relayed: "relayed";
+        executing: "executing";
+        verifying: "verifying";
+        "settlement-pending": "settlement-pending";
+        "settlement-submitted": "settlement-submitted";
+        "settlement-failed": "settlement-failed";
+        approved: "approved";
+        rejected: "rejected";
+        escalated: "escalated";
+    }>;
+    selectedVerifierIds: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    fundedAt: z.ZodString;
+    fundingTransactionHash: z.ZodString;
+    fundingBlockNumber: z.ZodOptional<z.ZodNumber>;
+    fundingLedger: z.ZodOptional<z.ZodString>;
+    result: z.ZodOptional<z.ZodObject<{
+        resultHash: z.ZodString;
+        output: z.ZodAny;
+        submittedAt: z.ZodString;
+    }, z.core.$strip>>;
+    attestations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        attestationId: z.ZodString;
+        attestationHash: z.ZodString;
+        jobHash: z.ZodString;
+        resultHash: z.ZodString;
+        verifierId: z.ZodString;
+        verifierAddress: z.ZodString;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+            uncertain: "uncertain";
+        }>;
+        confidence: z.ZodNumber;
+        reason: z.ZodString;
+        failedCriteria: z.ZodArray<z.ZodString>;
+        teeVerified: z.ZodBoolean;
+        teeProof: z.ZodObject<{
+            chatId: z.ZodString;
+            digest: z.ZodString;
+            signature: z.ZodString;
+            signerAddress: z.ZodString;
+            signatureUrl: z.ZodOptional<z.ZodString>;
+            providerAddress: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        verifierSignature: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>>;
+    settlement: z.ZodOptional<z.ZodObject<{
+        network: z.ZodString;
+        contractAddress: z.ZodString;
+        decision: z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+            uncertain: "uncertain";
+        }>;
+        threshold: z.ZodNumber;
+        approvals: z.ZodNumber;
+        rejections: z.ZodNumber;
+        providerPayout: z.ZodString;
+        verifierPayout: z.ZodString;
+        requesterRefund: z.ZodString;
+        platformFee: z.ZodString;
+        state: z.ZodEnum<{
+            pending: "pending";
+            submitted: "submitted";
+            confirmed: "confirmed";
+            failed: "failed";
+        }>;
+        transactionHash: z.ZodOptional<z.ZodString>;
+        submittedAt: z.ZodOptional<z.ZodString>;
+        settledAt: z.ZodOptional<z.ZodString>;
+        confirmedAt: z.ZodOptional<z.ZodString>;
+        blockNumber: z.ZodOptional<z.ZodNumber>;
+        ledger: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PreparedVerifier = z.infer<typeof PreparedVerifierSchema>;
+export type PreparedJob = z.infer<typeof PreparedJobSchema>;
+export type TeeProof = z.infer<typeof TeeProofSchema>;
+export type JobResult = z.infer<typeof JobResultSchema>;
+export type Attestation = z.infer<typeof AttestationSchema>;
+export type SettlementState = z.infer<typeof SettlementStateSchema>;
+export type Settlement = z.infer<typeof SettlementSchema>;
+export type Job = z.infer<typeof JobSchema>;