Privacy-first, OpenAI-compatible inference network. A ZeroSignal client age-encrypts each request and ships it to a remote node, which decrypts, forwards to an upstream LLM, and seals the response back. Per-request payment is escrowed in an Algorand smart contract and co-signed for settlement after the node delivers a signed usage receipt.
┌──────────────────────────────────────────────────────────────────┐
│ ZeroSignal client │
│ │
│ Encrypts requests, opens escrow, ack-settles. Two common forms: │
│ │
│ • A ZeroSignal-aware app (web app, agent, daemon) built on a │
│ payer SDK: @txnlab/zerosignal (TS) or go/zs (Go). │
│ • The proxy daemon, built on go/zs, which exposes a vanilla │
│ OpenAI /v1 surface and bridges plaintext clients (tui, │
│ OpenAI SDKs, LM Studio, test harnesses) into the protocol. │
└────────────────────┬───────────────────────────┬─────────────────┘
│ │
Payment+open atomic group, │ age-encrypted
ack-settle / protest │ envelope
│ │ (AAD-binds ticket
▼ ▼ + app-call txid)
┌──────────────────────┐ ┌──────────────────┐
│ algod │ │ node │
│ │ ◀────── │ decrypts, │
│ running the │ verify │ forwards, │
│ ZeroSignalEscrow │ open │ seals, │
│ contract: │ │ signs receipt, │
│ • operator registry│ ──────▶ │ posts op-side │
│ • per-ticket │ op-side │ settle │
│ escrow boxes │ settle └────────┬─────────┘
└──────────────────────┘ │
│ plaintext OpenAI
▼
┌──────────────┐
│ upstream LLM │
│ (OpenAI, │
│ vLLM, LM │
│ Studio, …) │
└──────────────┘
Key invariant: all client→node traffic is encrypted. There is no plaintext path between a client (or its proxy) and a node. Plaintext OpenAI exists only on the two end-segments — between a vanilla client and its local proxy, and between the node and the upstream LLM it forwards to.
Transport privacy: in the default privacy-on mode the sealed envelope is not sent straight to the serving node. A second node acts as a relay that blindly forwards it, so the target never sees the caller's network identity. Relay vs. target selection is covered in docs/operator-node-selection.md and SPEC §3f.
Privacy posture: upstream non-retention is the default; node-side and proxy-side non-retention are unconditional. Two layers carry it: (1) the proxy and node both default store: false on every admitted request before it leaves for the upstream LLM, so a curl one-liner or unsophisticated SDK doesn't silently inherit OpenAI's retention default; clients that need server-side retention features (e.g. Responses API previous_response_id continuation) may opt in by sending store: true explicitly, accepting that the upstream provider will retain the request and response under the operator's account; (2) operators MUST NOT log, persist, mirror, or otherwise retain decrypted request or response content on the node — only metadata needed for settlement and observability (token counts, ticket IDs, addresses, latency, charges). See SPEC.md "Prompt and response non-retention".
User and operator documentation lives at docs.zerosignal.ai.
The protocol specification, its two reference implementations, and the payer SDK built on each. The implementations are kept byte-compatible by shared golden vectors.
The system around it: zs-proxy is a localhost, single-user (payer) daemon that exposes a
plain OpenAI /v1 surface and speaks the protocol on the caller's behalf through the Go payer
SDK, go/zs. zs-node is the operator daemon: it decrypts envelopes, forwards them to an
upstream LLM, signs usage receipts, and settles on chain; it uses the protocol packages but not
zs. The ZeroSignalEscrow contract holds the operator and node registry and per-ticket
escrow. The ZeroSignal web app speaks the protocol directly from the browser and runs each
turn through the TypeScript payer SDK, @txnlab/zerosignal. Source paths such as proxy/internal/... or
client/src/... that appear in SPEC.md and docs/ refer to those implementations.
SPEC.md— authoritative envelope format, AAD binding, two-phase admission, sealed-response shapes, error model. Section references like §5.3 in implementation code point here.ENCRYPTION_OVERVIEW.md— orientation map of the encryption layers (which keys exist, what each protects). Note the mandatory forward secrecy model: the node holds no long-lived encryption key — requests seal to a short-lived, in-memory ephemeral age key the node advertises and signs; trust roots in the on-chain Ed25519 signing key.TEE.md— what a TEE-attested node proves and how a payer verifies it.docs/admission-tag.md— proof-of-possession HMAC that prevents mempool-race ticket hijack.docs/operator-node-selection.md— howmodel Xresolves to a ranked target node and a privacy relay: the shared golden-vectored eligibility/price/diversity policy vs. the app-side RTT/TTFT/tok-s signals layered on top.docs/multi-turn-content.md— what each chat surface replays into the next turn (reasoning is never sent back), and what the proxy/node mutate or strip in transit.docs/*.puml— PlantUML sequence diagrams for the reserve, request/response, ticket-lifecycle, and escrow-payment flows.CHANGELOG.md— protocol version history.
Go — go/, module github.com/TxnLab/zerosignal/go
The canonical implementation; it generates every golden vector.
| Package | Surface |
|---|---|
wire |
Envelope types (RequestEnvelope, ResponseEnvelope), WrapRequest / DecryptRequest / ResponseSealer, AAD helpers (BuildBodyAAD, BuildFrameAAD), admission-tag HMAC, body-hash helpers, the sealed inner frame, ephemeral identity. |
ticket |
Ticket + UsageReceipt + reserve shapes; BytesSigner + Algorand address codec; TicketSigDigest / ReceiptSigDigest / CommitResponseKey. |
selection |
Shared operator- and relay-selection policy: eligibility, price, owner diversity, DeriveMaxOutput. |
pricing |
Token-pricing math; VerifyTicketPrice checks a signed ticket's price before a payer escrows it. |
imageprice |
Deterministic image-generation pricing from (size, quality) and an operator's image rate. |
tokenize |
Model-agnostic input-token bound used to size a reserve and enforce it at inference time. |
transient |
Classifies a failed request as retryable or terminal, with the shared retry schedule; the reserve 429 busy codes and RetryableBusyCode; RetryableAfterPayment. |
steering |
The arithmetic behind a payer's own routing signals: relay-reputation decay, target backoff windows, and the weights-digest consensus. The stores they feed belong to each SDK: go/zs and @txnlab/zerosignal/routing. |
relay |
Relay-indirection metadata and the closed allow-list of inner paths a relay forwards. |
attest |
TEE measurement checks: Intel TDX quote parsing, dstack event-log replay into RTMR3, compose-file policy, PCK chain and collateral, and the trusted dstack OS images and zs-node releases. |
inject |
Body mutators applied before sealing (DefaultStoreFalse, DropEmptyTools, DropRoutingPreferences, InjectSafetyIdentifier, InjectStreamOptionsIncludeUsage) plus FitsContextWindow; discovery shapes (OperatorDetails / OperatorDetailsModel / ModelReasoning, TEEAdvertisement / TEEEvidenceBundle). None touch message/reasoning/tool history. |
tools |
Built-in tool registry + tool-loop helpers (chat/responses rewriters, frame stitchers, marker/effect/status frame marshaling). |
settle |
The settlement rules every payment rail shares: the ticket view, Classify (what call a live ticket allows now), and the protocol fee math (NetFee, ComputeFeeBreakdown). |
escrow |
ZeroSignalEscrow ABI client (embedded ARC-56 JSON). ComposeOpen / ComposeSettle / ComposeProtest, VerifyOpenAppCall / VerifyOpenGroup, box decoders, operator-registry helpers. |
solana |
The Solana rail's wire layer: keys and base58, program derived addresses, the transaction message codec (legacy, and v0 without lookup tables), and the token and compute-budget instructions the rail needs, all checked against the transactions the zs_escrow program's own tests build, whose token and compute-budget instructions come from those programs' interface crates. Hand-rolled rather than solana-go, whose dependencies every consumer would build. TransactionSigner is the custody seam for a transaction signature, and Transaction.SignWith puts one in its signer's slot. solana/idl holds the program's IDL. |
solana/zsescrow |
The zs_escrow program: its addresses, a builder per instruction (each deriving the program addresses from operator and node ids), its account and event decoders, VerifyOpenOffer and VerifyRelayedAck, the payer's checks of a node's open offer and a relayer's ack before it co-signs, and CompleteOpenOffer / CompleteRelayedAck, which run those checks and only then sign. Also the cluster presets (ClusterPreset: RPC endpoint and program id per cluster), which the payer SDK and the node share. |
algod |
Thin Client interface over the algod SDK, plus per-network presets (escrow app id, endpoints). |
algo |
Adapts a keystore entry into a TransactionSigner for AtomicTransactionComposer groups. |
keystore |
Signing-mnemonic loader: <NAME>_MNEMONIC env vars + ZS_MNEMONIC_URLS cloud-secret URLs (AWS/GCP/Azure). See go/keystore/README.md. |
wallet |
A payer's local wallet: generate or import a recovery phrase, held in the OS keychain or a passphrase-encrypted file, shared by every zerosignal program on the machine. Feeds keystore through Wallet.Provider; LoadPayer loads it with the environment's keys and picks a zs.Signer, and LoadSolanaPayer a zs.SolanaSigner. LoadKeys / LoadSolanaKeys load the same keys unchosen, and ChoosePayer / ChooseSolanaPayer pick among them, for a host that signs as several addresses; ReadEnvKeys reads the environment once for a host that decides something from it before loading. |
httpx |
A tuned, shared http.Transport for node↔node and payer↔node calls, with a private-address dial guard. |
gcplog |
slog attribute names for Google Cloud Logging. |
zs |
The Go payer SDK: operator discovery, routing, reserve, escrow open / settle / refund, receipts, and Diagnose, the read-only doctor. Used by zs-proxy, the TUI's -direct mode, and cmd/zschat. |
zs/handler |
The OpenAI-compatible HTTP surface over a zs.Client: chat completions, responses, the emulated /v1/completions, image generation and edits, model discovery, /v1/zs/details. |
zs/tee |
Verifies a node's published attestation evidence: the bundle checks every platform shares, the dstack TDX verifier, and the process-wide Intel collateral cache. |
zs/tokenize |
The safe input-token upper bound a payer reserves against. |
cmd/releasenotes |
Release-notes generator used by the zs-proxy and zs-node release builds. |
cmd/zschat |
One chat-completions prompt through zs, streamed to stdout, with the zs-proxy wallet and a journal on disk. |
examples/ |
Runnable programs: chatstream, discovery, openaishim, each with its own README. examples/README.md indexes them with the TypeScript ones. |
TypeScript — ts/, npm package @txnlab/zs-proto
A port of the vectored Go packages so a browser can speak the protocol directly to a node.
Subpaths: wire, ticket, selection, pricing, imageprice, tokenize, transient,
steering, relay, attest, inject, escrow, settle, solana, tools, plus the fixtures under testdata/*. See
ts/README.md.
Wire-shaped types use snake_case property names matching the JSON wire format, so JSON.stringify(envelope) produces the bytes the Go side emits — no field-rename layer. Function names are camelCase.
Not ported (intentionally): file-IO identity loaders, the Go reflect+unsafe ephemeral-key wipe (JS strings are immutable; see ts/README.md "Secret-key lifetime"), the algo/, algod/, keystore/ subpackages, the node-side half of tools/ (request rewriters, tool loop, markup recovery), and the chain-access half of escrow/ (box reads, and checking and completing the node-built
open and settle groups), which the TypeScript SDK below carries instead (sdk/src/escrow/, and
algod/'s retrying transport in sdk/src/algod-transport.ts).
TypeScript SDK — sdk/, npm package @txnlab/zerosignal
The twin of go/zs, released in lockstep with it; the ZeroSignal web app runs on it. It holds the
payer client (routing, reserve, escrow open / settle, sealing, relay hops, streaming, receipt
checks), the shared API vocabulary (events, error kinds, config and its defaults, network
presets), and the ports a host app implements (signer, storage, cache, logger, clock, fetch).
Its Client builds operator discovery (DiscoveryRegistry) when Config.registry is absent, as
zs.New does, with one difference at boot: zs.New waits for the chain read and a probe of every
node, while Client.create waits only for the chain read, and the first request waits for the
probe. A host can still supply its own registry, or share one across Clients. It depends on
@txnlab/zs-proto at exactly its own version and re-exports it under
@txnlab/zerosignal/proto. The names it shares with Go are pinned by
testdata/sdk_vocabulary_vectors.json. See sdk/README.md.
Examples — examples/
Runnable programs for both SDKs: a streamed chat turn, the OpenAI SDK over zs.fetch, a fleet
listing that pays nothing, one turn built from the SDK's parts, a durable ticket journal, image
generation, and a localnet setup. The TypeScript ones are pnpm workspace members on
@txnlab/zerosignal workspace:*; the Go ones live in go/examples/ inside the
module. make test compiles all of them but runs none. See
examples/README.md. To run every piece of ZeroSignal yourself on a local
chain (chain, operator dashboard, node, payer, chat), see LOCALNET.md.
Golden vectors — testdata/
Each vectored Go package writes its fixture (vectors.json, selection_vectors.json, …) from
a Test*Vectors test, and the matching ts/test/*-vectors.test.ts reads it unchanged, so
byte-format drift between the two implementations fails on either side. make update-vectors
regenerates them all; make check-vector-generators (part of make test) fails if a generator
is missing from that target.
Two fixtures pin the sealing framing instead, and are captured rather than derived (nonces and
age wrapping are random): sealed_vectors.json is sealed by Go and opened by TS, and
ts_sealed_vectors.json is sealed by TS and opened by Go. Regenerate them only when the framing
changes on purpose, with make update-sealed-vectors and make update-ts-sealed-vectors.
Algorand network. Every service that touches chain reads algod.network: localnet | testnet | mainnet (with optional algod.endpoint / algod.token overrides). Resolves to nodely.dev for testnet/mainnet, http://localhost:4001 for localnet.
Node identity. No age-key setup. Under mandatory forward secrecy the node holds no long-lived encryption key — request envelopes seal to an in-memory ephemeral age key the node generates, rotates on a fixed cadence, signs under its Ed25519 key, and advertises at /v1/zs/details; it is never persisted (there is no node.key / identity_path). See ENCRYPTION_OVERVIEW.md. An operator's only persistent secret is its signing mnemonic (below).
Signing mnemonics. Both proxy (payer) and node (operator) load Algorand mnemonics via proto/go/keystore. Either set <NAME>_MNEMONIC env vars or point ZS_MNEMONIC_URLS at cloud-secret URLs. See go/keystore/README.md for the full reference.
Configuration. Each Go service reads ./config.yaml by default; override with --config or the <SERVICE>_CONFIG env var. Per-service config.example.yaml is the canonical reference. The proxy carries no upstream LLM credential — admission to the operator is via the on-chain seal, not a bearer token. The node's LLM provider key comes from env (NODE_LLM_OPENAI_API_KEY); never commit it.
pnpm install # one workspace: ts/, sdk/ and examples/*
make test # guards (check-vector-generators, check-no-hayai, check-lockstep,
# check-escrow-client) + Go suite + ts suite + sdk typecheck/test/build/test:dist
# + examples typecheck and the browser example's bundle
make vet typecheck
make verify-vectors # read-only: every fixture matches current Go output; Go opens the TS-sealed one
make update-vectors # regenerate fixtures after an intentional format change
cd go && go test -race ./... # before crypto/streaming changes
cd ts && pnpm buildThe Solana rail also runs end to end on a local validator: each SDK against a stub node
(go/internal/solanastub) and the real zs_escrow program, through a settle on the payer's ack,
a protest, an over-claim freeze and the admin's resolve of it, a refund of an unserved ticket, a
refund forfeited to the treasury by a payer whose USDC account is closed, a lapse, an open sent
after its blockhash expired, two concurrent turns the payer can afford one of, and free turns with
and without a free credit from the stub's issuer. The Go scenarios
run the stub in-process; the TS ones build and spawn it (go/cmd/solanastub) and check the chain
through its /stub/ routes. Start the validator with make localnet in zerosignal-contracts' solana/, then:
# The localnet's own deploy key, from the zerosignal-contracts checkout beside this one
# (a `KEYS=` directory instead, if the validator started with one).
ZS_SOLANA_E2E_RPC=http://127.0.0.1:8899 \
ZS_SOLANA_E2E_MINT_AUTHORITY=$PWD/../contracts/solana/target/localnet-keys/deployer.json \
make solana-e2e # about 2 min a suite: two scenarios wait out a deadlineWithout the endpoint and a key the scenarios skip, so make test and this repo's CI never need a
validator. The mint's authority is also the localnet Config's admin: the run shortens the default
grace to 60 s, and refuses an endpoint off this machine.
The same suites run on devnet with a funder in its place, a wallet holding SOL and Circle's devnet USDC (from faucet.circle.com, Solana Devnet) that it hands out by transfer and that holds no power over the program. The stub reads devnet's preset program, so an identity registered on another program is refused at start; register it again:
# Once: register the stub's node. The URL is the loopback address later runs serve on.
cd go && go run ./cmd/solanastub -rpc <devnet endpoint> -funder /abs/funder.json \
-register-node http://127.0.0.1:18765 -identity-out /abs/stub-identity.json
# Each run. The paths are absolute: the suites run from go/ and sdk/.
ZS_SOLANA_E2E_RPC=<devnet endpoint> ZS_SOLANA_E2E_CLUSTER=devnet \
ZS_SOLANA_E2E_FUNDER=/abs/funder.json ZS_SOLANA_E2E_STUB_IDENTITY=/abs/stub-identity.json \
make solana-e2eThe grace is then the cluster's, so the deadline scenarios take longer. Each payer hands what it has left back to the funder at the end, except what a frozen ticket holds, which only the admin can release. The identity file holds the node's signing phrase and its owner's, which unregisters it, so keep it as a secret. Off this machine a funder run serves only as a registered identity, so nightly runs reuse one operator rather than stake a new one each time.
zerosignal-contracts' make integration (in solana/) and its integration workflow run both suites on a
throwaway validator, with a real zs-node and zs-proxy; -register-node registers that node too,
since zs-node has no Solana register command.
Go, @txnlab/zs-proto and the @txnlab/zerosignal SDK release in lockstep: one version
number, all three tags on the same commit. Three commands do it:
make release-pr VERSION=X.Y.Z # version commit on release/vX.Y.Z, pushed, PR opened
# squash-merge the PR
make release-tag # tags the version commit, after a y/N confirmation
make release-status # tags, release.yml runs, npm, Go moduleWhat they do, step by step:
release-prrefuses a version not above bothmain's and the latestgo/v*tag. It branchesrelease/vX.Y.Zoffmain, setsversiontoX.Y.Zin bothts/package.jsonandsdk/package.json, relabels each###CHANGELOG heading ending(unreleased)to(X.Y.Z), runsscripts/check-lockstep.sh, commitsts, sdk: X.Y.Z, pushes the branch and opens the PR. It leaves your checkout on that branch.release-tagreads the version frommain's package.json files, so the tags can only name what they say, and tags the commit that set it, notmain's tip: a PR merged after the release PR stays out of the release. It tags that commitgo/vX.Y.Z,ts/vX.Y.Zandsdk/vX.Y.Zand pushes exactly those three, atomically. GitHub starts no workflow for a push of more than three tags, so nevergit push --tags. Re-running it is safe: it pushes only the tags missing from the remote and refuses, pushing nothing, when one already points at another commit.scripts/release.test.sh(inmake test) pins these guards.- The Go module is live as soon as the tag is pushed (
go get github.com/TxnLab/zerosignal/go@vX.Y.Z). Each of thets/v*andsdk/v*tags runsrelease.yml, which runs the full test suite and stages that npm package. It does not publish it. The SDK is staged from itspnpm packtarball, which pins@txnlab/zs-protoatX.Y.Z, and only whents/vX.Y.Zis on the same commit. - A maintainer approves each staged package with 2FA, either in the package's Staged
Packages tab on npmjs.com or with
npm stage approve <id>. Only then is it installable. Approve@txnlab/zs-protofirst: the SDK can't be installed until the version it pins is. If the zs-proto job failed, reject the staged SDK too.
A new package needs a one-time setup before its first tag: npmjs.com lets a trusted publisher be
added only to a package that exists, so publish its first version by hand with
pnpm publish --access public (pnpm, because npm publish would ship a workspace:*
dependency literally), then add a trusted publisher for TxnLab/zerosignal's release.yml that
may only stage.
Both npm packages publish with --access public and provenance, and the Go module resolves through
the public module proxy. publishConfig.access in both package.json files, the --access and
--provenance flags in release.yml, and the access value its two metadata checks expect change
together: npm refuses provenance for a restricted package.
Under 0.x a minor bump is a breaking change and a patch bump is not. Never move or delete a
pushed go/v* tag: sum.golang.org and every consumer's go.sum have recorded its hash, so a
moved tag fails their builds with a checksum mismatch.
Each verifier trusts only the zs-node releases compiled into it, so a node on a release a payer
doesn't list counts as unattested there: it still serves requests that need no TEE, but none that
do. Each node tag runs zs-node's release-allowlist.yml, which opens one pull request here. It
appends the release's image and its two compose skeletons (CPU, and GPU with sealed local models)
to go/attest/releases.go, and regenerates ts/src/attest/trust-lists.ts from it, which
TestTrustListTwinVectors requires. If a pull request arrives with only releases.go changed (a
node tag cut before the workflow gained that step), regenerate by hand with
cd go && go test ./attest -run TestTrustListTwinVectors -update-trust-lists.
Merging it reaches no payer. Once it merges, cut a release here (make release-pr), then bump
the pins in zs-proxy and the web app; each trusts the new node release from its own next release
or deploy. zs-node itself needs no pin bump for it: a node reads only the OS-image list, and its
own image can't be in the release it was built against.
Apache-2.0 — see LICENSE.