node hzb-demo-server.mjs

node hzb-client.mjs
# Or, with Python 3.9+:
python hzb-client.py

curl http://127.0.0.1:8787/v1/tasks \
  -H "Authorization: Bearer local-demo-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-read-only-task" \
  --data-binary @task-request.json

{
  "demo": true,
  "task_id": "demo_<generated-id>",
  "status": "fixture_complete",
  "policy": {
    "decision": "permit_read_only",
    "external_writes": false
  },
  "execution_performed": false,
  "output": {
    "kind": "static_fixture"
  },
  "receipt": {
    "steps": [
      "validate_input",
      "check_read_only_policy",
      "return_fixture"
    ],
    "source_verified": false
  }
}

examples/
  hzb-demo-server.mjs   HTTP routes → validation → read-only policy → fixture receipt
  hzb-client.mjs        Node.js fetch client + timeout + error handling
  hzb-client.py         Python standard-library client
  task-request.json    Local HTTP request sample
  hivm-plan.json       Conceptual instruction plan (not executable)
  README.md            Scope and run instructions

{
  "application": "web3-llm",
  "question": "Explain the upgrade permissions of the supplied contract.",
  "context": {
    "chain_id": 1,
    "block_ref": "<observed-block>",
    "source_ids": [
      "<authorized-document>"
    ]
  },
  "output": [
    "answer",
    "citations",
    "unresolved_items"
  ]
}

{
  "application": "contract-auditor",
  "artifact": {
    "source_hash": "<sha256>",
    "compiler": "<pinned-version>"
  },
  "checks": [
    "access-control",
    "reentrancy",
    "upgradeability"
  ],
  "policy": {
    "external_writes": false
  },
  "output": [
    "findings",
    "evidence",
    "review_status"
  ]
}

{
  "application": "contract-generator",
  "spec": {
    "kind": "role-based-registry",
    "roles": [
      "admin",
      "editor"
    ],
    "upgradeable": false
  },
  "deliverables": [
    "spec",
    "source",
    "tests"
  ],
  "policy": {
    "deploy": false,
    "human_review_required": true
  }
}

{
  "application": "nft-generator",
  "brief": {
    "theme": "HZB community builders",
    "reference": "<licensed-ip-asset>",
    "traits": [
      "role",
      "background"
    ]
  },
  "output": [
    "image_candidates",
    "metadata_draft"
  ],
  "policy": {
    "mint": false,
    "rights_review_required": true
  }
}

{
  "application": "onchain-analysis",
  "query": {
    "chain_id": 1,
    "address": "<public-address>",
    "from_block": "<start>",
    "to_block": "<end>"
  },
  "mode": "read_only",
  "output": [
    "flows",
    "source_blocks",
    "uncertainties"
  ]
}

{
  "application": "developer-api",
  "capability": "<selected-capability>",
  "request_id": "<client-request-id>",
  "context": {
    "project": "<project-id>"
  },
  "policy": {
    "external_writes": false
  },
  "output": [
    "task_status",
    "result",
    "receipt"
  ]
}

{
  "application": "hivm-agents",
  "plan": [
    {
      "op": "READ",
      "source": "<authorized-source>"
    },
    {
      "op": "ANALYZE",
      "output": "research_summary"
    },
    {
      "op": "VALIDATE",
      "claim": "source_attribution"
    },
    {
      "op": "ATTEST",
      "scope": "recorded_process"
    }
  ],
  "policy": {
    "allowed_ops": [
      "READ",
      "ANALYZE",
      "VALIDATE",
      "ATTEST"
    ],
    "external_writes": false
  }
}

{
  "application": "enterprise-knowledge",
  "tenant_id": "<tenant>",
  "principal": "<authenticated-user>",
  "query": "Summarize the current release process.",
  "sources": [
    "<authorized-collection>"
  ],
  "policy": {
    "enforce_document_acl": true,
    "training_use": false
  },
  "output": [
    "answer",
    "citations",
    "document_versions"
  ]
}

{
  "capability": "hzb-solidity",
  "goal": "From requirements to contract review",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": [
      "read",
      "analyze"
    ],
    "external_writes": false
  }
}

{
  "capability": "hzb-chain-intelligence",
  "goal": "Make on-chain activity understandable",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": [
      "read",
      "analyze"
    ],
    "external_writes": false
  }
}

{
  "capability": "hzb-risk",
  "goal": "Risk signals with evidence and context",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": [
      "read",
      "analyze"
    ],
    "external_writes": false
  }
}

{
  "capability": "hzb-agent",
  "goal": "Turn complex goals into structured workflows",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": [
      "read",
      "analyze"
    ],
    "external_writes": false
  }
}

{
  "capability": "hzb-embed",
  "goal": "Connect documents, code and knowledge",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": [
      "read",
      "analyze"
    ],
    "external_writes": false
  }
}

{
  "query": "Which roles may upgrade this contract?",
  "scope": {
    "project": "demo",
    "network": "local-demo"
  },
  "context": [
    {
      "source_id": "authorized-document-1",
      "version": "example-v1",
      "retrieved_at": "<ISO-8601 timestamp>",
      "excerpt": "<authorized passage>",
      "access_scope": [
        "project:demo"
      ]
    }
  ],
  "policy": {
    "require_citations": true,
    "exclude_unauthorized_sources": true
  }
}

{
  "schema": "hzb-hivm-concept-v1",
  "status": "architecture-example-not-executable-bytecode",
  "task": "Review authorized contract permissions",
  "plan": [
    {"op": "READ", "resource": "authorized-source"},
    {"op": "ANALYZE", "purpose": "identify privileged roles"},
    {"op": "GENERATE", "artifact": "candidate-review-plan"},
    {"op": "SIMULATE", "mode": "read-only"},
    {"op": "VALIDATE", "checks": ["scope", "budget", "expiry"]},
    {"op": "AUTHORIZE", "decision": "permit-read-only"},
    {"op": "EXECUTE", "allowed_tools": ["read_authorized_source"], "external_writes": false},
    {"op": "ATTEST", "artifact": "reviewable-receipt"}
  ],
  "on_uncertain_state": "pause-and-reconcile",
  "note": "Architecture illustration only. No published HIVM bytecode or runtime is implied."
}

{
  "schema": "hzb-task-spec-concept-v1",
  "status": "illustrative-template",
  "goal": "Review roles and permissions in an authorized contract",
  "capability": "hzb-solidity",
  "context": { "network": "bnb-chain", "compiler": "0.8.24", "source": "YOUR_AUTHORIZED_CONTRACT" },
  "permissions": { "actions": ["read", "analyze"], "external_writes": false, "human_approval_required": true },
  "constraints": { "max_tool_calls": 10, "timeout_seconds": 120 },
  "deliverables": ["permission-summary", "source-citations", "human-review-checklist"],
  "note": "Conceptual example only. This is not a published API schema and does not execute actions."
}

if tool not in granted_tools: DENY
if resource not in granted_scope: DENY
if authorization_expired or budget_exceeded: DENY
if external_write or high_risk_action: REQUIRE_HUMAN_APPROVAL
else: PERMIT_SCOPED_ACTION

# Before execution, recheck authorization and external state.
# After an uncertain result, PAUSE and RECONCILE; do not blindly retry.

Authorization: Bearer local-demo-key
Content-Type: application/json
Idempotency-Key: first-read-only-task

{
  "capability": "hzb-solidity",
  "goal": "Prepare a human-review checklist for an authorized contract",
  "context": {
    "network": "local-demo",
    "source": "contract Example { address public owner; }"
  },
  "permissions": {
    "actions": ["read", "analyze"],
    "external_writes": false
  }
}

// Node.js 20+. Start hzb-demo-server.mjs first. Never use production secrets here.
import {randomUUID} from 'node:crypto';
const baseURL = 'http://127.0.0.1:8787';
const response = await fetch(`${baseURL}/v1/tasks`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer local-demo-key',
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID()
  },
  signal: AbortSignal.timeout(10000),
  body: JSON.stringify({
    capability: 'hzb-solidity',
    goal: 'Prepare a human-review checklist for an authorized contract',
    context: {network: 'local-demo', source: 'contract Example { address public owner; }'},
    permissions: {actions: ['read', 'analyze'], external_writes: false}
  })
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status} ${result.error?.code}: ${result.error?.message}`);
if (result.demo !== true || result.execution_performed !== false) throw new Error('Unexpected example response');
console.log(JSON.stringify(result, null, 2));

"""Python 3.9+. Start hzb-demo-server.mjs first. Local static fixture only."""
import json
import uuid
import urllib.request
import urllib.error

payload = {
    "capability": "hzb-solidity",
    "goal": "Prepare a human-review checklist for an authorized contract",
    "context": {"network": "local-demo", "source": "contract Example { address public owner; }"},
    "permissions": {"actions": ["read", "analyze"], "external_writes": False},
}
request = urllib.request.Request(
    "http://127.0.0.1:8787/v1/tasks",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Authorization": "Bearer local-demo-key", "Content-Type": "application/json", "Idempotency-Key": str(uuid.uuid4())},
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=10) as response:
        result = json.load(response)
        if result.get("demo") is not True or result.get("execution_performed") is not False:
            raise ValueError("Unexpected example response")
        print(json.dumps(result, indent=2, ensure_ascii=False))
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
    raise SystemExit(1)

curl http://127.0.0.1:8787/v1/tasks \
  -H "Authorization: Bearer local-demo-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-read-only-task" \
  --data-binary @task-request.json

// HZB documentation example. Local, deterministic fixture; NOT a model or HIVM implementation.
// Node.js 20+. No external services, wallets, transactions or production credentials.
import http from 'node:http';
import {createHash, randomUUID} from 'node:crypto';
import {pathToFileURL} from 'node:url';

const capabilities = ['hzb-solidity', 'hzb-chain-intelligence', 'hzb-risk', 'hzb-agent', 'hzb-embed'];
const MAX_BODY = 64 * 1024;
export function createDemoServer() {
  const receipts = new Map(); // Memory only; erased on restart. Not production idempotency storage.
  return http.createServer(async (req, res) => {
    const requestId = randomUUID();
    const reply = (status, data) => {
      res.writeHead(status, {'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store'});
      res.end(JSON.stringify({demo: true, request_id: requestId, ...data}, null, 2));
    };
    const fail = (status, code, message) => reply(status, {error: {code, message}});
    if (req.method === 'GET' && req.url === '/health') return reply(200, {status: 'local-fixture-only'});
    if (req.headers.authorization !== 'Bearer local-demo-key') return fail(401, 'DEMO_UNAUTHORIZED', 'Use the public local-demo-key only with this local example.');
    if (req.method === 'GET' && req.url === '/v1/models') return reply(200, {data: capabilities.map(id => ({id, status: 'fixture-only'}))});
    if (req.method !== 'POST' || req.url !== '/v1/tasks') return fail(404, 'DEMO_NOT_FOUND', 'This example supports GET /v1/models and POST /v1/tasks.');
    if (!req.headers['content-type']?.startsWith('application/json')) return fail(415, 'DEMO_CONTENT_TYPE', 'Send application/json.');
    const key = req.headers['idempotency-key'];
    if (typeof key !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(key)) return fail(400, 'DEMO_IDEMPOTENCY_KEY', 'Provide a 1–80 character Idempotency-Key.');
    let payload, raw = '', size = 0;
    const chunks=[];
    try {
      for await (const chunk of req) {
        size += chunk.length;
        if (size <= MAX_BODY) chunks.push(chunk);
      }
      if (size > MAX_BODY) return fail(413, 'DEMO_PAYLOAD_TOO_LARGE', 'The local example accepts at most 64 KiB.');
      raw=Buffer.concat(chunks).toString('utf8');
      payload = JSON.parse(raw);
    } catch { return fail(400, 'DEMO_INVALID_JSON', 'Send a valid JSON object.'); }
    if (!payload || typeof payload !== 'object' || Array.isArray(payload) || typeof payload.goal !== 'string' || !payload.goal.trim() || !capabilities.includes(payload.capability)) return fail(422, 'DEMO_INVALID_TASK', 'Provide a goal and one of the fixture capability IDs.');
    const permissions = payload.permissions;
    if (!permissions || permissions.external_writes !== false || !Array.isArray(permissions.actions) || !permissions.actions.length || permissions.actions.some(action => !['read', 'analyze'].includes(action))) return fail(403, 'DEMO_POLICY_DENIED', 'Only explicit read/analyze permissions and external_writes=false are accepted.');
    const digest = createHash('sha256').update(raw).digest('hex');
    if (receipts.has(key)) {
      const previous = receipts.get(key);
      if (previous.digest !== digest) return fail(409, 'DEMO_IDEMPOTENCY_CONFLICT', 'This key already belongs to a different request body.');
      return reply(200, {...previous.result, replayed: true});
    }
    if (receipts.size >= 100) return fail(503, 'DEMO_STORE_FULL', 'Restart the local example to clear its 100-entry memory store.');
    const result = {
      task_id: `demo_${randomUUID()}`, schema: 'hzb-docs-demo-v1',
      capability: payload.capability, status: 'fixture_complete',
      policy: {decision: 'permit_read_only', external_writes: false},
      execution_performed: false,
      output: {kind: 'static_fixture', checklist: ['Confirm source ownership and authorization.', 'Review privileged roles and acceptance criteria with an engineer.'], note: 'Fixed example output. No AI inference, contract analysis, security audit or external execution occurred.'},
      receipt: {request_sha256: digest, steps: ['validate_input', 'check_read_only_policy', 'return_fixture'], source_verified: false},
      replayed: false
    };
    receipts.set(key, {digest, result});
    return reply(200, result);
  });
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  createDemoServer().listen(8787, '127.0.0.1', () => console.log('HZB local fixture: http://127.0.0.1:8787 — no real AI or external execution'));
}

{"permissions":{"actions":["read"],"external_writes":true}}

{
  "demo": true,
  "request_id": "<generated-id>",
  "error": {
    "code": "DEMO_POLICY_DENIED",
    "message": "Only explicit read/analyze permissions and external_writes=false are accepted."
  }
}