@halot/cli 1.0.0

package/.env.example

@@ -0,0 +1,14 @@
+HALOT_SERVER_URL=http://localhost:3001
+HALOT_SPACE_ID_IDENTIFIER=
+HALOT_SPACE_ID_CONTROLLER_ADDRESS=
+HALOT_SPACE_ID_RESOLVER_ADDRESS=
+HALOT_SPACE_ID_SIMULATE_ACCOUNT=
+HALOT_SPACE_ID_SIMULATE_VALUE=
+HALOT_SPACE_ID_GRAPH_URL=
+HALOT_SPACE_ID_VERIFIED_TLD_HUB_ADDRESS=
+HALOT_SPACE_ID_VERIFIED_TLD_HUB_RPC_URL=
+HALOT_ZERO_G_STORAGE_GATEWAY=
+HALOT_AGENT_ID_REGISTRY_ADDRESS=
+HALOT_ZERO_G_VERIFIER_REGISTRY_ADDRESS=
+HALOT_DEFAULT_STELLAR_RPC_URL=
+HALOT_DEFAULT_STELLAR_NETWORK_PASSPHRASE=Public Global Stellar Network ; September 2015

package/README.md

@@ -0,0 +1,374 @@
+# halot
+
+`halot` is the CLI for initializing workspaces and operating against the Halot network.
+
+It covers:
+
+- requester setup and job creation
+- provider registration and updates
+- service drafting and registration
+- verifier registration, runtime, and staking
+
+## Install
+
+```bash
+npm install -g halot
+```
+
+or run it without a global install:
+
+```bash
+npx halot --help
+```
+
+## Provider Flow
+
+### 1. Initialize
+
+```bash
+halot provider init
+```
+
+This creates:
+
+- `wallets.json`
+- `halot.provider.json`
+
+`wallets.json` stores network-scoped private keys:
+
+```json
+{
+  "authorities": {
+    "0g:testnet": {
+      "privateKey": "0x..."
+    },
+    "0g:mainnet": {
+      "privateKey": "0x..."
+    },
+    "stellar:testnet": {
+      "privateKey": "S..."
+    },
+    "stellar:mainnet": {
+      "privateKey": "S..."
+    }
+  }
+}
+```
+
+`halot.provider.json` stores provider identity, the selected Halot actor authority, and settlement wallets:
+
+```json
+{
+  "providerId": "",
+  "displayName": "My Provider",
+  "description": "Provider description",
+  "version": "1.0.0",
+  "identity": {
+    "domain": "myprovider.0g",
+    "domainType": "space-id",
+    "ownerAddress": "0x...",
+    "erc8004TokenId": "",
+    "agentRegistry": "",
+    "agentUri": ""
+  },
+  "authority": {
+    "path": "./wallets.json",
+    "actor": "0g:testnet"
+  },
+  "settlementWallets": {
+    "0g:testnet": "0x...",
+    "0g:mainnet": "0x...",
+    "stellar:testnet": "G...",
+    "stellar:mainnet": "G..."
+  }
+}
+```
+
+### 2. Register
+
+```bash
+halot provider register
+```
+
+This:
+
+- reads `halot.provider.json`
+- signs with `authority.actor` from `wallets.json`
+- uploads the provider config to 0G Storage
+- anchors the root hash on the 0G provider registry
+- writes back the canonical `providerId`
+
+On mainnet, provider registration also performs:
+
+- SPACE ID `.0g` registration
+- Agent ID / ERC-8004 registration
+
+### 3. Update
+
+After editing mutable provider fields such as:
+
+- `displayName`
+- `description`
+- `version`
+- `settlementWallets`
+
+run:
+
+```bash
+halot provider update
+```
+
+### 4. Run
+
+```bash
+halot provider run
+halot provider run --once
+halot provider run --interval 5000
+```
+
+The worker opens an assignment stream, forwards jobs to the assigned service `endpoint.execution`, and submits results back to Halot.
+
+If you are using SDK middleware instead of the worker path, you do not need `halot provider run`.
+
+## Service Flow
+
+Services are drafted separately from provider registration.
+
+### 1. Create a draft
+
+```bash
+halot service init --name "GPT-5.4 Text"
+```
+
+This creates a local draft such as `services/service-001.json`.
+
+Example:
+
+```json
+{
+  "serviceId": "",
+  "name": "GPT-5.4 Text",
+  "description": "Returns paid text output for a prompt",
+  "version": "1.0.0",
+  "category": "text",
+  "trustLevel": "standard",
+  "endpoint": {
+    "health": "https://your-provider.example/health",
+    "execution": "https://your-provider.example/execute"
+  },
+  "pricing": {
+    "baseFee": "3.00",
+    "currency": "USDC",
+    "model": "per-job"
+  },
+  "settlement": {
+    "accepts": [
+      {
+        "network": "0g:testnet",
+        "token": "USDC"
+      },
+      {
+        "network": "stellar:testnet",
+        "token": "USDC"
+      }
+    ]
+  },
+  "input": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "query": { "type": "string", "maxLength": 500 }
+      },
+      "required": ["query"]
+    },
+    "maxSize": "10kb"
+  },
+  "output": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "text": { "type": "string" }
+      },
+      "required": ["text"]
+    },
+    "format": "json"
+  },
+  "acceptanceCriteria": {
+    "schemaValid": true
+  },
+  "sla": {
+    "maxExecutionTime": 120,
+    "retryPolicy": "none"
+  }
+}
+```
+
+### 2. Register
+
+```bash
+halot service register
+halot service register --file service-001.json
+```
+
+This:
+
+- reads `providerId` from `halot.provider.json`
+- signs as that provider from `wallets.json`
+- uploads the service definition to 0G Storage
+- anchors it on the provider registry
+- rewrites the file with the canonical `serviceId`
+
+### 3. Manage services
+
+```bash
+halot service list
+halot service update <serviceId>
+halot service update --file service-svc_abc123.json
+halot service remove <serviceId>
+```
+
+Current categories:
+
+- `text`
+- `code`
+- `image`
+- `audio`
+- `video`
+- `document`
+- `tool`
+- `workflow`
+
+## Verifier Flow
+
+### 1. Initialize
+
+```bash
+halot verifier init
+```
+
+This creates:
+
+- `wallets.json`
+- `halot.verifier.json`
+- `model.config.json`
+- `inference.json`
+- `specializations.json`
+
+`halot.verifier.json`:
+
+```json
+{
+  "verifierId": "",
+  "displayName": "My Verifier",
+  "description": "Multimodal service verification specialist",
+  "identity": {
+    "domain": "myverifier.0g",
+    "domainType": "space-id",
+    "ownerAddress": "0x...",
+    "erc8004TokenId": "",
+    "agentRegistry": "",
+    "agentUri": ""
+  },
+  "authority": {
+    "path": "./wallets.json",
+    "actor": "0g:testnet"
+  },
+  "settlementWallets": {
+    "0g:testnet": "0x...",
+    "0g:mainnet": "0x...",
+    "stellar:testnet": "G...",
+    "stellar:mainnet": "G..."
+  },
+  "stake": {
+    "amount": "1000",
+    "token": "0G",
+    "status": "unlocked"
+  },
+  "fees": {
+    "computeBudgetPerJob": "0.50"
+  }
+}
+```
+
+`model.config.json`:
+
+```json
+{
+  "evaluationModel": {
+    "providerAddress": "0x...",
+    "serviceType": "chatbot",
+    "verifiability": "TeeML"
+  },
+  "sdk": {
+    "network": "testnet",
+    "rpcUrl": "https://evmrpc-testnet.0g.ai"
+  },
+  "timeout": 60
+}
+```
+
+`inference.json`:
+
+```json
+{
+  "systemPrompt": "You are an impartial evaluator.",
+  "promptTemplate": "Evaluate whether the provider result and any referenced artifacts satisfy the acceptance criteria.",
+  "outputSchema": {
+    "decision": "approve | reject | uncertain",
+    "confidence": "number between 0 and 1",
+    "reason": "string",
+    "failedCriteria": "array"
+  },
+  "maxTokens": 1024,
+  "temperature": 0
+}
+```
+
+`specializations.json`:
+
+```json
+{
+  "categories": ["text", "document", "tool"],
+  "serviceIds": [],
+  "maxConcurrentJobs": 5,
+  "minConfidenceThreshold": 0.75
+}
+```
+
+### 2. Register
+
+```bash
+halot verifier register
+```
+
+This:
+
+- registers the verifier with Halot
+- locks native 0G stake in the verifier registry
+- runs mainnet identity steps when applicable
+
+### 3. Run and unstake
+
+```bash
+halot verifier run
+halot verifier run --once
+halot verifier stats
+halot verifier unstake
+halot verifier unstake --claim
+```
+
+## Requester and Jobs
+
+```bash
+halot requester init
+halot quote --service svc_... --input '{"query":"hello"}'
+halot job create --service svc_... --input '{"query":"hello"}'
+halot job watch <jobId>
+halot job result <jobId>
+halot browse
+halot browse --service <serviceId>
+```
+
+## Security
+
+`wallets.json` contains raw private keys. Do not commit it to version control.

package/dist/features/browse/browse.command.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBrowseCommand = runBrowseCommand;
+const api_client_1 = require("@halot/cli/shared/http/api-client");
+const print_util_1 = require("@halot/cli/shared/output/print.util");
+async function runBrowseCommand(options) {
+    const api = new api_client_1.ApiClient(options.server);
+    if (options.service) {
+        const service = await api.get(`/services/${options.service}`);
+        (0, print_util_1.printJson)(service);
+        return;
+    }
+    const providers = await api.get('/providers');
+    (0, print_util_1.printJson)(providers);
+}

package/dist/features/jobs/job-create.command.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runJobCreateCommand = runJobCreateCommand;
+const sdk_1 = require("@halot/sdk");
+const api_client_1 = require("@halot/cli/shared/http/api-client");
+const print_util_1 = require("@halot/cli/shared/output/print.util");
+const authority_util_1 = require("@halot/cli/shared/wallet/authority.util");
+const workspace_service_1 = require("@halot/cli/shared/workspace/workspace.service");
+const job_funding_service_1 = require("@halot/cli/features/jobs/job-funding.service");
+function encodePaymentSignature(authorization) {
+    return Buffer.from(JSON.stringify(authorization)).toString('base64');
+}
+async function runJobCreateCommand(options) {
+    const workspace = new workspace_service_1.WorkspaceService();
+    const api = new api_client_1.ApiClient(options.server);
+    const fundingService = new job_funding_service_1.JobFundingService();
+    const requesterConfig = workspace.readRequesterConfig();
+    const wallets = workspace.readWallets(requesterConfig.authority.path);
+    const requesterWallet = (0, authority_util_1.resolveActorWallet)(wallets, requesterConfig.authority.actor);
+    const input = JSON.parse(options.input);
+    const quote = await api.post('/quote', {
+        serviceId: options.service,
+        input,
+        requesterAddress: requesterWallet.address,
+    });
+    const requirement = {
+        x402Version: 2,
+        scheme: 'exact',
+        quoteId: quote.quoteId,
+        accepts: quote.accepts,
+        expiresAt: quote.expiresAt,
+        resource: '/jobs',
+        description: `Halot escrow payment for ${quote.serviceId}`,
+    };
+    const authorization = await (0, sdk_1.signPaymentRequirement)(requesterWallet, requirement, options.network);
+    const response = await api.postRaw('/jobs/prepare', {
+        quoteId: quote.quoteId,
+        settlementAddress: (0, authority_util_1.resolveAuthorityAddress)(wallets, sdk_1.SettlementNetworkSchema.parse(authorization.network)),
+    }, {
+        'PAYMENT-SIGNATURE': encodePaymentSignature(authorization),
+    });
+    const preparedJob = await response.json();
+    if (!response.ok) {
+        throw new Error(preparedJob?.error ?? 'Failed to prepare job');
+    }
+    const transactionHash = await fundingService.fundPreparedJob(preparedJob, {
+        wallets,
+    });
+    const body = await api.post('/jobs', {
+        prepareId: preparedJob.prepareId,
+        transactionHash,
+    });
+    (0, print_util_1.printJson)({
+        requesterId: requesterConfig.requesterId,
+        ...body,
+    });
+}

package/dist/features/jobs/job-funding.service.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobFundingService = void 0;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const ethers_1 = require("ethers");
+const env_1 = require("@halot/cli/shared/config/env");
+const authority_util_1 = require("@halot/cli/shared/wallet/authority.util");
+const erc20Abi = [
+    'function allowance(address owner, address spender) view returns (uint256)',
+    'function approve(address spender, uint256 amount) returns (bool)',
+];
+const zeroGEscrowAbi = [
+    'function createJob(address token, bytes32 jobHash, address provider, address[] verifierAddresses, uint256 threshold, uint256 providerAmount, uint256 verifierPool, uint256 platformFee)',
+];
+class JobFundingService {
+    env = (0, env_1.loadCliEnv)();
+    async fundPreparedJob(preparedJob, options) {
+        if (preparedJob.paymentNetwork.startsWith('0g:')) {
+            const authority = (0, authority_util_1.resolveAuthorityWallet)(options.wallets, preparedJob.paymentNetwork);
+            const chain = (0, authority_util_1.resolveZeroGAuthorityProfile)(preparedJob.paymentNetwork);
+            return this.fundZeroGPreparedJob(preparedJob, authority.privateKey, chain.rpcUrl);
+        }
+        if (preparedJob.paymentNetwork.startsWith('stellar:')) {
+            const authority = (0, authority_util_1.resolveAuthorityWallet)(options.wallets, preparedJob.paymentNetwork);
+            return this.fundStellarPreparedJob(preparedJob, authority.privateKey);
+        }
+        throw new Error(`Unsupported settlement network ${preparedJob.paymentNetwork}`);
+    }
+    async fundZeroGPreparedJob(preparedJob, privateKey, rpcUrl) {
+        const provider = new ethers_1.JsonRpcProvider(rpcUrl);
+        const wallet = new ethers_1.Wallet(privateKey, provider);
+        const token = new ethers_1.Contract(preparedJob.settlementTokenAddress, erc20Abi, wallet);
+        const escrow = new ethers_1.Contract(preparedJob.settlementContractAddress, zeroGEscrowAbi, wallet);
+        const allowance = await token.allowance(wallet.address, preparedJob.settlementContractAddress);
+        const totalAmountUnits = BigInt(preparedJob.totalAmountUnits);
+        if (allowance < totalAmountUnits) {
+            const approval = await token.approve(preparedJob.settlementContractAddress, ethers_1.MaxUint256);
+            await approval.wait();
+        }
+        const transaction = await escrow.createJob(preparedJob.settlementTokenAddress, preparedJob.jobHash, preparedJob.providerPayoutAddress, preparedJob.assignedVerifiers.map((verifier) => verifier.ownerAddress), preparedJob.threshold, preparedJob.providerAmountUnits, preparedJob.verifierPoolUnits, preparedJob.platformFeeUnits);
+        const receipt = await transaction.wait();
+        if (!receipt || receipt.status !== 1) {
+            throw new Error('0G createJob transaction failed');
+        }
+        return transaction.hash;
+    }
+    async fundStellarPreparedJob(preparedJob, secretKey) {
+        if (!this.env.defaultStellarRpcUrl || !this.env.defaultStellarNetworkPassphrase) {
+            throw new Error('Missing HALOT_DEFAULT_STELLAR_RPC_URL or HALOT_DEFAULT_STELLAR_NETWORK_PASSPHRASE for Stellar funding');
+        }
+        const server = new stellar_sdk_1.rpc.Server(this.env.defaultStellarRpcUrl);
+        const keypair = stellar_sdk_1.Keypair.fromSecret(secretKey);
+        const sourceAccount = await server.getAccount(keypair.publicKey());
+        const contract = new stellar_sdk_1.Contract(preparedJob.settlementContractAddress);
+        const verifierPublicKeys = preparedJob.assignedVerifiers.map((verifier) => stellar_sdk_1.xdr.ScVal.scvBytes(hexToBuffer(verifier.signingPublicKey, 65)));
+        const verifierPayouts = preparedJob.assignedVerifiers.map((verifier) => new stellar_sdk_1.Address(verifier.payoutAddress).toScVal());
+        const transaction = new stellar_sdk_1.TransactionBuilder(sourceAccount, {
+            fee: stellar_sdk_1.BASE_FEE,
+            networkPassphrase: this.env.defaultStellarNetworkPassphrase,
+        })
+            .addOperation(contract.call('create_job', new stellar_sdk_1.Address(preparedJob.settlementTokenAddress).toScVal(), stellar_sdk_1.xdr.ScVal.scvBytes(hexToBuffer(preparedJob.jobHash, 32)), new stellar_sdk_1.Address(preparedJob.requesterAddress).toScVal(), new stellar_sdk_1.Address(preparedJob.providerPayoutAddress).toScVal(), stellar_sdk_1.xdr.ScVal.scvVec(verifierPublicKeys), stellar_sdk_1.xdr.ScVal.scvVec(verifierPayouts), stellar_sdk_1.xdr.ScVal.scvU32(preparedJob.threshold), (0, stellar_sdk_1.nativeToScVal)(BigInt(preparedJob.providerAmountUnits), { type: 'i128' }), (0, stellar_sdk_1.nativeToScVal)(BigInt(preparedJob.verifierPoolUnits), { type: 'i128' }), (0, stellar_sdk_1.nativeToScVal)(BigInt(preparedJob.platformFeeUnits), { type: 'i128' })))
+            .setTimeout(30)
+            .build();
+        const preparedTransaction = await server.prepareTransaction(transaction);
+        preparedTransaction.sign(keypair);
+        const response = await server.sendTransaction(preparedTransaction);
+        if (response.status !== 'PENDING' && response.status !== 'DUPLICATE') {
+            throw new Error(`Stellar create_job submission failed with status ${response.status}`);
+        }
+        await waitForStellarSuccess(server, response.hash);
+        return response.hash;
+    }
+}
+exports.JobFundingService = JobFundingService;
+function hexToBuffer(value, size) {
+    const normalized = value.startsWith('0x') ? value.slice(2) : value;
+    if (normalized.length !== size * 2) {
+        throw new Error(`Expected ${size} byte hex value, received ${value}`);
+    }
+    return Buffer.from(normalized, 'hex');
+}
+async function waitForStellarSuccess(server, transactionHash) {
+    const deadline = Date.now() + 120_000;
+    while (Date.now() <= deadline) {
+        const receipt = await server.getTransaction(transactionHash);
+        if (receipt.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.SUCCESS) {
+            return;
+        }
+        if (receipt.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.FAILED) {
+            throw new Error(`Stellar create_job transaction ${transactionHash} failed`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+    }
+    throw new Error(`Timed out waiting for Stellar create_job transaction ${transactionHash}`);
+}

package/dist/features/jobs/job-result.command.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runJobResultCommand = runJobResultCommand;
+const api_client_1 = require("@halot/cli/shared/http/api-client");
+const print_util_1 = require("@halot/cli/shared/output/print.util");
+async function runJobResultCommand(jobId, options) {
+    const api = new api_client_1.ApiClient(options.server);
+    const result = await api.get(`/jobs/${jobId}/result`);
+    (0, print_util_1.printJson)(result);
+}

package/dist/features/jobs/job-watch.command.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runJobWatchCommand = runJobWatchCommand;
+const api_client_1 = require("@halot/cli/shared/http/api-client");
+const print_util_1 = require("@halot/cli/shared/output/print.util");
+const terminalStatuses = new Set(['approved', 'rejected', 'escalated', 'settlement-failed']);
+async function runJobWatchCommand(jobId, options) {
+    const api = new api_client_1.ApiClient(options.server);
+    const intervalMs = Number(options.interval);
+    do {
+        const job = await api.get(`/jobs/${jobId}`);
+        (0, print_util_1.printJson)(job);
+        if (terminalStatuses.has(job.status)) {
+            return;
+        }
+        await (0, print_util_1.sleep)(intervalMs);
+    } while (true);
+}

package/dist/features/provider/provider-init.command.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProviderInitCommand = runProviderInitCommand;
+const wallet_manager_1 = require("@halot/cli/shared/wallet/wallet.manager");
+const authority_util_1 = require("@halot/cli/shared/wallet/authority.util");
+const workspace_service_1 = require("@halot/cli/shared/workspace/workspace.service");
+async function runProviderInitCommand() {
+    const workspace = new workspace_service_1.WorkspaceService();
+    const walletManager = new wallet_manager_1.WalletManager(workspace);
+    const wallets = walletManager.createWallets();
+    workspace.writeProviderConfig({
+        providerId: '',
+        displayName: 'My Provider',
+        description: 'Provider description',
+        version: '1.0.0',
+        identity: {
+            erc8004TokenId: '',
+            agentRegistry: '',
+            agentUri: '',
+            ownerAddress: (0, authority_util_1.resolveAuthorityAddress)(wallets, '0g:testnet'),
+            domain: 'myprovider.0g',
+            domainType: 'space-id',
+        },
+        authority: {
+            path: './wallets.json',
+            actor: '0g:testnet',
+        },
+        settlementWallets: (0, authority_util_1.createDefaultSettlementWallets)(wallets),
+    });
+    console.log('Provider workspace initialized.');
+    console.log(`0G testnet authority: ${(0, authority_util_1.resolveAuthorityAddress)(wallets, '0g:testnet')}`);
+    console.log(`Stellar testnet authority: ${(0, authority_util_1.resolveAuthorityAddress)(wallets, 'stellar:testnet')}`);
+}