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

npm install -g @halot/cli

or run it without a global install:

npx @halot/cli --help

Provider Flow

1. Initialize

halot provider init
halot provider init --testnet
halot provider init --mainnet

This creates:

• wallets.json
• halot.provider.json

wallets.json stores network-scoped private keys:

{
  "authorities": {
    "0g:testnet": {
      "privateKey": "0x..."
    },
    "stellar:testnet": {
      "privateKey": "S..."
    }
  }
}

The default is --testnet. --mainnet generates the equivalent 0g:mainnet and stellar:mainnet scoped workspace without adding testnet entries.

halot.provider.json stores provider identity, the selected Halot actor authority, and settlement wallets:

{
  "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...",
    "stellar:testnet": "G..."
  }
}

2. Register

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:

halot provider update

4. Run

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

halot service init --name "GPT-5.4 Text"

This creates a local draft such as services/service-001.json.

Example:

{
  "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

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

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

halot verifier init

This creates:

• wallets.json
• halot.verifier.json
• model.config.json
• inference.json
• specializations.json

halot.verifier.json:

{
  "verifierId": "",
  "displayName": "My Verifier",
  "description": "Text 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...",
    "stellar:testnet": "G..."
  },
  "stake": {
    "amount": "1000",
    "token": "0G",
    "status": "unlocked"
  },
  "fees": {
    "computeBudgetPerJob": "0.50"
  }
}

model.config.json:

{
  "evaluationMode": "testnet",
  "evaluationModel": {
    "model": "openai/gpt-oss-20b"
  },
  "sdk": {
    "network": "testnet"
  },
  "timeout": 60
}

evaluationMode is local, testnet, or mainnet. Local mode runs signed verifier evaluation in the CLI process. Network modes resolve the live TeeML chatbot provider for evaluationModel.model from the 0G registry before sending the evaluation request.

Current 0G testnet TeeML chatbot models include:

• openai/gpt-oss-20b
• google/gemma-3-27b-it
• qwen/qwen-2.5-7b-instruct

inference.json:

{
  "systemPrompt": "You are a Halot verifier for paid text-generation services. Be strict, evidence-based, and deterministic. Return only valid JSON.",
  "promptTemplate": "Evaluate this Halot text-generation job.\\n\\nService:\\n- ID: {{serviceId}}\\n- Name: {{serviceName}}\\n- Description: {{serviceDescription}}\\n- Category: {{serviceCategory}}\\n- Trust level: {{trustLevel}}\\n\\nRequester input:\\n{{input}}\\n\\nProvider result:\\n{{result}}\\n\\nService acceptance criteria:\\n{{acceptanceCriteria}}\\n\\nExpected output schema:\\n{{outputSchema}}\\n\\nInput artifacts:\\n{{inputArtifacts}}\\n\\nResult artifacts:\\n{{resultArtifacts}}\\n\\nArtifact validation issues:\\n{{artifactValidationIssues}}\\n\\nDecision rules:\\n- Approve only if the result directly fulfills the requester input, matches the expected output schema, and satisfies the acceptance criteria.\\n- Reject if the result is empty, irrelevant, materially incomplete, malformed, unsafe, inaccessible, or artifact-mismatched.\\n- Reject if required fields are missing, placeholder content is returned, or the answer contradicts the request.\\n- Use uncertain only when the evidence is genuinely insufficient or the result is partially interpretable but not confidently approvable or rejectable.\\n\\nConfidence rules:\\n- 0.90 to 1.00: clear outcome with strong evidence.\\n- 0.70 to 0.89: likely outcome with minor ambiguity.\\n- Below 0.70: use uncertain.\\n\\nReturn only JSON with fields:\\n- decision\\n- confidence\\n- reason\\n- failedCriteria",
  "outputSchema": {
    "decision": "approve | reject | uncertain",
    "confidence": "number between 0 and 1",
    "reason": "string",
    "failedCriteria": "array"
  },
  "maxTokens": 1024,
  "temperature": 0
}

specializations.json:

{
  "categories": ["text"],
  "serviceIds": [],
  "maxConcurrentJobs": 3,
  "minConfidenceThreshold": 0.75
}

2. Register

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

halot verifier run
halot verifier run --once
halot verifier stats
halot verifier unstake
halot verifier unstake --claim

Requester and Jobs

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.