@halot/sdk 1.0.0

package/dist/zero-g/compute.d.ts

@@ -0,0 +1,53 @@
+import { Decision } from '../types/common';
+import { TeeProof } from '../types/job';
+import { Service } from '../types/service';
+export type ComputeEvaluationInput = {
+    jobHash: string;
+    resultHash: string;
+    input: unknown;
+    result: unknown;
+    service: Service;
+    providerAddress?: string;
+    systemPrompt?: string;
+    promptTemplate?: string;
+    outputSchema?: Record<string, string>;
+    maxTokens?: number;
+    temperature?: number;
+    model?: string;
+};
+export type ComputeEvaluationOutput = {
+    decision: Decision;
+    confidence: number;
+    reason: string;
+    failedCriteria: string[];
+    teeVerified: boolean;
+    teeProof: TeeProof;
+};
+export type ZeroGComputeOptions = {
+    rpcUrl?: string;
+    privateKey?: string;
+    providerAddress?: string;
+    ledgerContractAddress?: string;
+    inferenceContractAddress?: string;
+    fineTuningContractAddress?: string;
+    fetchImplementation?: typeof fetch;
+};
+export declare class ZeroGComputeService {
+    private readonly rpcUrl?;
+    private readonly privateKey?;
+    private readonly providerAddress?;
+    private readonly ledgerContractAddress?;
+    private readonly inferenceContractAddress?;
+    private readonly fineTuningContractAddress?;
+    private readonly fetchImplementation;
+    constructor(options?: ZeroGComputeOptions);
+    evaluate(input: ComputeEvaluationInput): Promise<ComputeEvaluationOutput>;
+    private evaluateWithZeroG;
+    private renderPrompt;
+    private buildUserContent;
+    private extractMessageContent;
+    private parseEvaluationResponse;
+    private extractJson;
+    private parseDecision;
+    private createWallet;
+}

package/dist/zero-g/compute.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZeroGComputeService = void 0;
+const _0g_serving_broker_1 = require("@0glabs/0g-serving-broker");
+const ethers_1 = require("ethers");
+const artifacts_1 = require("../utils/artifacts");
+const hash_1 = require("../utils/hash");
+const id_1 = require("../utils/id");
+class ZeroGComputeService {
+    rpcUrl;
+    privateKey;
+    providerAddress;
+    ledgerContractAddress;
+    inferenceContractAddress;
+    fineTuningContractAddress;
+    fetchImplementation;
+    constructor(options = {}) {
+        this.rpcUrl = options.rpcUrl;
+        this.privateKey = options.privateKey;
+        this.providerAddress = options.providerAddress;
+        this.ledgerContractAddress = options.ledgerContractAddress;
+        this.inferenceContractAddress = options.inferenceContractAddress;
+        this.fineTuningContractAddress = options.fineTuningContractAddress;
+        this.fetchImplementation = options.fetchImplementation ?? fetch;
+    }
+    async evaluate(input) {
+        return this.evaluateWithZeroG(input);
+    }
+    async evaluateWithZeroG(input) {
+        const providerAddress = (0, ethers_1.getAddress)(input.providerAddress ?? this.providerAddress ?? '');
+        const wallet = this.createWallet();
+        const broker = await (0, _0g_serving_broker_1.createZGComputeNetworkBroker)(wallet, this.ledgerContractAddress, this.inferenceContractAddress, this.fineTuningContractAddress);
+        if (!(await broker.inference.acknowledged(providerAddress))) {
+            await broker.inference.acknowledgeProviderSigner(providerAddress);
+        }
+        const { endpoint, model } = await broker.inference.getServiceMetadata(providerAddress);
+        const artifacts = await (0, artifacts_1.resolveImageArtifacts)(input.input, input.result, {
+            fetchImplementation: this.fetchImplementation,
+            outputFormat: input.service.output.format,
+        });
+        const prompt = this.renderPrompt(input, artifacts);
+        const requestBody = {
+            model: input.model ?? model,
+            messages: [
+                {
+                    role: 'system',
+                    content: input.systemPrompt ?? 'You are an impartial evaluator. Return only valid JSON.',
+                },
+                {
+                    role: 'user',
+                    content: this.buildUserContent(prompt, artifacts),
+                },
+            ],
+            temperature: input.temperature ?? 0,
+            max_tokens: input.maxTokens ?? 1024,
+        };
+        const headers = await broker.inference.getRequestHeaders(providerAddress, JSON.stringify(requestBody));
+        const response = await this.fetchImplementation(`${endpoint}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(requestBody),
+        });
+        if (!response.ok) {
+            throw new Error(`0G compute request failed with status ${response.status}`);
+        }
+        const body = await response.json();
+        const chatId = String(response.headers.get('ZG-Res-Key') ?? body.id ?? (0, id_1.createPrefixedId)('chat'));
+        const content = this.extractMessageContent(body);
+        const teeVerified = Boolean(await broker.inference.processResponse(providerAddress, chatId, JSON.stringify(body.usage ?? { content })));
+        const parsed = this.parseEvaluationResponse(content);
+        const signerStatus = await broker.inference.checkProviderSignerStatus(providerAddress).catch(() => null);
+        const signatureUrl = await broker.inference.getChatSignatureDownloadLink(providerAddress, chatId).catch(() => undefined);
+        return {
+            decision: parsed.decision,
+            confidence: parsed.confidence,
+            reason: parsed.reason,
+            failedCriteria: parsed.failedCriteria,
+            teeVerified,
+            teeProof: {
+                chatId,
+                digest: (0, hash_1.hashText)(content),
+                signature: signatureUrl ?? '',
+                signerAddress: signerStatus?.teeSignerAddress ?? providerAddress,
+                signatureUrl,
+                providerAddress,
+            },
+        };
+    }
+    renderPrompt(input, artifacts) {
+        const inputArtifactsSummary = (0, artifacts_1.buildArtifactSummary)(artifacts.inputImages);
+        const resultArtifactsSummary = (0, artifacts_1.buildArtifactSummary)(artifacts.resultImages);
+        const artifactValidationIssues = artifacts.issues.length > 0
+            ? artifacts.issues.map((issue) => `- ${issue}`).join('\n')
+            : 'None';
+        if (input.promptTemplate) {
+            const rendered = input.promptTemplate
+                .replaceAll('{{input}}', JSON.stringify(input.input, null, 2))
+                .replaceAll('{{acceptanceCriteria}}', JSON.stringify(input.service.acceptanceCriteria, null, 2))
+                .replaceAll('{{result}}', JSON.stringify(input.result, null, 2))
+                .replaceAll('{{outputSchema}}', JSON.stringify(input.outputSchema ?? input.service.output.schema, null, 2))
+                .replaceAll('{{inputArtifacts}}', inputArtifactsSummary)
+                .replaceAll('{{resultArtifacts}}', resultArtifactsSummary)
+                .replaceAll('{{artifactValidationIssues}}', artifactValidationIssues);
+            if (artifacts.inputImages.length === 0 && artifacts.resultImages.length === 0 && artifacts.issues.length === 0) {
+                return rendered;
+            }
+            return [
+                rendered,
+                '',
+                'Input image artifacts:',
+                inputArtifactsSummary,
+                '',
+                'Result image artifacts:',
+                resultArtifactsSummary,
+                '',
+                'Artifact validation issues:',
+                artifactValidationIssues,
+            ].join('\n');
+        }
+        return [
+            'Job input:',
+            JSON.stringify(input.input, null, 2),
+            '',
+            'Acceptance criteria:',
+            JSON.stringify(input.service.acceptanceCriteria, null, 2),
+            '',
+            'Expected output schema:',
+            JSON.stringify(input.outputSchema ?? input.service.output.schema, null, 2),
+            '',
+            'Input image artifacts:',
+            inputArtifactsSummary,
+            '',
+            'Provider result:',
+            JSON.stringify(input.result, null, 2),
+            '',
+            'Result image artifacts:',
+            resultArtifactsSummary,
+            '',
+            'Artifact validation issues:',
+            artifactValidationIssues,
+            '',
+            'If the returned artifacts are inaccessible, mismatched, or do not satisfy the request, reject the result.',
+            '',
+            'Return JSON with fields: decision, confidence, reason, failedCriteria.',
+        ].join('\n');
+    }
+    buildUserContent(prompt, artifacts) {
+        if (artifacts.inputImages.length === 0 && artifacts.resultImages.length === 0) {
+            return prompt;
+        }
+        const parts = [
+            {
+                type: 'text',
+                text: prompt,
+            },
+        ];
+        for (const artifact of artifacts.inputImages) {
+            parts.push({
+                type: 'text',
+                text: `Reference input image: ${artifact.path} (${artifact.mimeType}${artifact.width && artifact.height ? `, ${artifact.width}x${artifact.height}` : ''})`,
+            });
+            parts.push({
+                type: 'image_url',
+                image_url: {
+                    url: artifact.dataUrl,
+                },
+            });
+        }
+        for (const artifact of artifacts.resultImages) {
+            parts.push({
+                type: 'text',
+                text: `Provider result image: ${artifact.path} (${artifact.mimeType}${artifact.width && artifact.height ? `, ${artifact.width}x${artifact.height}` : ''})`,
+            });
+            parts.push({
+                type: 'image_url',
+                image_url: {
+                    url: artifact.dataUrl,
+                },
+            });
+        }
+        return parts;
+    }
+    extractMessageContent(body) {
+        const content = body?.choices?.[0]?.message?.content;
+        if (typeof content === 'string') {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            return content
+                .map((part) => {
+                if (typeof part === 'string') {
+                    return part;
+                }
+                return typeof part?.text === 'string' ? part.text : JSON.stringify(part);
+            })
+                .join('\n');
+        }
+        throw new Error('0G compute response did not include an assistant message');
+    }
+    parseEvaluationResponse(content) {
+        const parsed = JSON.parse(this.extractJson(content));
+        const decision = this.parseDecision(parsed.decision);
+        const confidenceValue = Number(parsed.confidence);
+        const confidence = Number.isFinite(confidenceValue) ? Math.max(0, Math.min(1, confidenceValue)) : 0.5;
+        const reason = typeof parsed.reason === 'string' && parsed.reason.length > 0
+            ? parsed.reason
+            : 'No evaluation reason was returned by the 0G compute provider.';
+        const failedCriteria = Array.isArray(parsed.failedCriteria)
+            ? parsed.failedCriteria.map((item) => String(item))
+            : [];
+        return {
+            decision,
+            confidence,
+            reason,
+            failedCriteria,
+        };
+    }
+    extractJson(content) {
+        const fenced = content.match(/```json\s*([\s\S]+?)\s*```/i);
+        if (fenced?.[1]) {
+            return fenced[1];
+        }
+        const firstBrace = content.indexOf('{');
+        const lastBrace = content.lastIndexOf('}');
+        if (firstBrace >= 0 && lastBrace > firstBrace) {
+            return content.slice(firstBrace, lastBrace + 1);
+        }
+        return content;
+    }
+    parseDecision(value) {
+        if (value === 'approve' || value === 'reject' || value === 'uncertain') {
+            return value;
+        }
+        throw new Error(`Unsupported decision returned by 0G compute provider: ${String(value)}`);
+    }
+    createWallet() {
+        if (!this.privateKey) {
+            throw new Error('0G compute mode requires privateKey');
+        }
+        if (!this.rpcUrl) {
+            throw new Error('0G compute mode requires rpcUrl');
+        }
+        return new ethers_1.Wallet(this.privateKey, new ethers_1.JsonRpcProvider(this.rpcUrl));
+    }
+}
+exports.ZeroGComputeService = ZeroGComputeService;

package/dist/zero-g/storage.d.ts

@@ -0,0 +1,28 @@
+export type ObjectStorage = {
+    upload<T>(data: T): Promise<string>;
+    download<T>(hash: string): Promise<T>;
+    exists(hash: string): Promise<boolean>;
+};
+export type ZeroGStorageOptions = {
+    storageRoot?: string;
+    indexerRpcUrl: string;
+    blockchainRpcUrl: string;
+    privateKey: string;
+};
+export declare class ZeroGStorageService implements ObjectStorage {
+    private readonly objectsRoot;
+    private readonly indexerRpcUrl;
+    private readonly blockchainRpcUrl;
+    private readonly privateKey;
+    constructor(options: ZeroGStorageOptions);
+    upload<T>(data: T): Promise<string>;
+    download<T>(hash: string): Promise<T>;
+    exists(hash: string): Promise<boolean>;
+    private uploadToZeroG;
+    private downloadFromZeroG;
+    private existsOnZeroG;
+    private getObjectPath;
+    private createIndexer;
+    private createSigner;
+    private getBlockchainRpcUrl;
+}

package/dist/zero-g/storage.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZeroGStorageService = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = require("node:os");
+const _0g_ts_sdk_1 = require("@0gfoundation/0g-ts-sdk");
+const ethers_1 = require("ethers");
+const json_file_1 = require("../utils/json-file");
+class ZeroGStorageService {
+    objectsRoot;
+    indexerRpcUrl;
+    blockchainRpcUrl;
+    privateKey;
+    constructor(options) {
+        this.objectsRoot = node_path_1.default.resolve(options.storageRoot ?? node_path_1.default.join(process.cwd(), '.halot', 'storage'));
+        this.indexerRpcUrl = options.indexerRpcUrl;
+        this.blockchainRpcUrl = options.blockchainRpcUrl;
+        this.privateKey = options.privateKey;
+        (0, json_file_1.ensureDirectory)(this.objectsRoot);
+    }
+    async upload(data) {
+        return this.uploadToZeroG(data);
+    }
+    async download(hash) {
+        return this.downloadFromZeroG(hash);
+    }
+    async exists(hash) {
+        return this.existsOnZeroG(hash);
+    }
+    async uploadToZeroG(data) {
+        const indexer = this.createIndexer();
+        const signer = this.createSigner();
+        const file = new _0g_ts_sdk_1.MemData(Buffer.from(JSON.stringify(data)));
+        const [result, error] = await indexer.upload(file, this.getBlockchainRpcUrl(), signer);
+        if (error || !result) {
+            throw new Error(`0G upload failed: ${error?.message ?? 'unknown error'}`);
+        }
+        const rootHash = 'rootHash' in result ? result.rootHash : result.rootHashes[0];
+        if (!rootHash) {
+            throw new Error('0G upload returned no root hash');
+        }
+        const cachePath = this.getObjectPath(rootHash);
+        if (!node_fs_1.default.existsSync(cachePath)) {
+            node_fs_1.default.writeFileSync(cachePath, JSON.stringify(data, null, 2));
+        }
+        return rootHash;
+    }
+    async downloadFromZeroG(hash) {
+        const cachedPath = this.getObjectPath(hash);
+        if (node_fs_1.default.existsSync(cachedPath)) {
+            return JSON.parse(node_fs_1.default.readFileSync(cachedPath, 'utf8'));
+        }
+        const tempPath = node_path_1.default.join((0, node_os_1.tmpdir)(), `halot-0g-${hash}.json`);
+        const indexer = this.createIndexer();
+        const error = await indexer.download(hash, tempPath, false);
+        if (error) {
+            throw new Error(`0G download failed for hash ${hash}: ${error.message}`);
+        }
+        const content = node_fs_1.default.readFileSync(tempPath, 'utf8');
+        node_fs_1.default.rmSync(tempPath, { force: true });
+        node_fs_1.default.writeFileSync(cachedPath, content);
+        return JSON.parse(content);
+    }
+    async existsOnZeroG(hash) {
+        if (node_fs_1.default.existsSync(this.getObjectPath(hash))) {
+            return true;
+        }
+        try {
+            const locations = await this.createIndexer().getFileLocations(hash);
+            return locations.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    getObjectPath(hash) {
+        return node_path_1.default.join(this.objectsRoot, `${hash}.json`);
+    }
+    createIndexer() {
+        return new _0g_ts_sdk_1.Indexer(this.indexerRpcUrl);
+    }
+    createSigner() {
+        return new ethers_1.Wallet(this.privateKey, new ethers_1.JsonRpcProvider(this.getBlockchainRpcUrl()));
+    }
+    getBlockchainRpcUrl() {
+        return this.blockchainRpcUrl;
+    }
+}
+exports.ZeroGStorageService = ZeroGStorageService;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@halot/sdk",
+  "version": "1.0.0",
+  "description": "Shared Halot protocol SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "halot",
+    "sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "files": [
+    "dist/auth",
+    "dist/client",
+    "dist/middleware",
+    "dist/types",
+    "dist/utils",
+    "dist/x402",
+    "dist/zero-g",
+    "dist/config.js",
+    "dist/config.d.ts",
+    "dist/index.js",
+    "dist/index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "default": "./dist/middleware/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@0gfoundation/0g-ts-sdk": "^1.2.1",
+    "@0glabs/0g-serving-broker": "^0.7.4",
+    "ethers": "6.13.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.2",
+    "typescript": "^6.0.2"
+  }
+}