Developer docs · OWP/3
Build with Witness.
Getting started, concepts, verification, owner flows, the public HTTP API and node operation.
SDK · skills for Claude, Codex and Cursor · MCP server
Available to approved partners on request.
Getting started
Witness turns every finalized record in your Oracle into a public proof, without the record ever leaving your infrastructure. Getting there takes four things: being a Species owner, getting the Adapter, meeting the record contract, and connecting.
Your Oracle ──finalized record──► your appliance writes an outbox entry
│
▼
Oracle Adapter (owp3-adapter, on your device)
builds a blinded commitment, signs, publishes
│ commitment only
▼
Witness server ──► receipt, cosigned, anchored to Bitcoin
1. Be a Species owner on the Onli One network
You must be a Species owner, registered on the Onli One network. Connecting to Witness is:
- Per appliance and per device. Each appliance connects on its own, and so does each device that runs its Adapter — one connection never covers another.
- Approved through Onli ID. You, the Species owner, approve every connection with a tap in Onli ID.
- By request in production. Production connections are granted on request; staging lets you try the full flow first.
Once approved, the device publishes on its own, without signing in again.
2. Get the Adapter
The Oracle Adapter (owp3-adapter) is the program that connects your Oracle to Witness. It runs on your own infrastructure, next to your data, and is the only part that ever sees your records.
- By request. The Adapter is proprietary and available to approved partners on request; Onli gives you access to the release with your approval. Use 0.1.5 or later.
- Platforms: Linux x86-64 and ARM64 (glibc), and macOS on Apple silicon (11 or later). Each release ships SHA-256 checksums; verify them before installing.
- Skills for Claude, Codex and Cursor come with it: they teach your coding agent to do this integration with you.
Check the install with owp3-adapter --version.
3. The contract: what your appliance provides
Your side of the integration is small and exact. The Adapter does all of the cryptography; your appliance provides records that meet this contract.
Only final records. Hand over a record only when it is final and immutable in your system — settled, confirmed, committed. Never pending, reversible or intended state: a proof of something that later doesn't happen is worse than no proof.
A Profile for each record type. A Profile is the claim schema of a record type: which claims it has, their types, which are required and which can be proven. Adopt an Onli standard, or extend one under your own delegated prefix:
| Standard | For |
|---|---|
onli.std.asset-transfer v1 |
one side of a settled asset movement |
onli.std.audit-event v1 |
one entry of an append-only audit log |
onli.std.audit-receipt v1 |
a reconciliation verdict for one state change, owner view and asset leg |
onli.std.holdings-snapshot v1 |
one owner's holding of one asset at a cut-off time |
owp3-adapter onboard standards lists them with every claim.
One outbox entry per record, per owner. For each finalized record, and for each member it concerns, your appliance writes one JSON file into the Adapter's outbox pending/ folder:
{
"profile_id": "onli.std.asset-transfer",
"profile_version": 1,
"subject": "usr-8ff1aa0e-2427-52d0-b96e-6fb90dbf277c",
"statement_id": "5d0c7f1a9e2b4c6d8e0f1a2b3c4d5e6f",
"record": {
"record_id": "transfer:txn_7781:sender",
"record_version": 1,
"finalized": true,
"claims": [[[1], "send"], [[2], "USD"], [[3], 12500], [[4], 2], [[5], "settled"], [[6], 1790442000]]
}
}
This is a settled transfer of 125.00 USD under onli.std.asset-transfer v1: slot 1 act, 2 asset, 3 amount_minor, 4 scale, 5 status, 6 finalized_at (epoch seconds).
| Field | What you provide |
|---|---|
profile_id, profile_version |
the Profile this record follows |
subject |
the owner's Onli ID user id, exactly as Onli ID issues it (usr- + lower-case UUID) — never an internal account code |
statement_id |
16 random bytes as 32 lower-case hex, generated once per record version and owner, stored with the record before the first delivery and reused on every retry |
record_id |
your stable id for the record (1–256 bytes), unique across owners |
record_version |
1, then +1 for each correction |
finalized |
exactly true |
claims |
[path, value] pairs on the Profile's slots, each value in its canonical type: integers as integers (amounts in minor units, times in epoch seconds), text as text, bytes as lower-case hex; omit optional claims, never null |
supersedes |
corrections only: the witness_id of the version this one replaces |
Write atomically. Write pending/.<name>.tmp, then rename it into place.
Get back a witness_id. Store the witness_id the Adapter returns against the record in your database. It is the record's public proof.
Never send record contents, claim values, owner e-mails, Onli IDs, keys or tokens to Witness, logs or any public field — the Adapter handles all of that.
Check before you go live. owp3-adapter outbox check <entry>… checks entries against the contract offline (no keys, no network). An entry that breaks the contract is never published or retried: it moves to failed/ with error 1210 and the rule it broke.
4. Connect your Oracle to Witness
Production Witness server: https://onli-witnessd.onrender.com.
Everything the Adapter needs lives in one adapter home — the machine's identity once, and the state of each Witness it connects to beside it:
<home>/keystore/ appliance identity (one per machine)
<home>/service-token made on the appliance, never leaves it
<home>/admission-request.json
<home>/witnesses/<host>/admission.cose
<home>/witnesses/<host>/profiles/ signed Profile manifests
<home>/witnesses/<host>/data/outbox/ pending · delivered · failed
<home>/witnesses/<host>/data/status/ one status file per record
Pass --home <dir> (or set OWP3_HOME) and --server <witness url> to every command, and the Adapter fills in every path. Two Witness servers under one home share one identity and one token.
Create the appliance identity, service token and admission request:
owp3-adapter onboard init --home <home> --profile onli.std.asset-transfer@1The appliance makes its own service token. Only its SHA-256 hash goes into
admission-request.json, so no secret ever passes between you and Onli.Lay out the Witness folders:
owp3-adapter onboard layout --home <home> --server https://onli-witnessd.onrender.com --createConnect this device, with the Species owner's approval:
owp3-adapter onboard connect --home <home> --deployment <your Species symbol>Run this on each device that runs the Adapter. The terminal shows a short code. The Species owner gets an Onli ID prompt with the same code, checks that the two match, and taps Accept — nothing is typed. Finish within about ten minutes. The Adapter then downloads its Admission Attestation and signed Profile manifests from the Witness server and keeps only what verifies.
Production is by request. Self-service connect runs on staging. For production, send
admission-request.jsonto Onli with your request; once it is granted, download everything withowp3-adapter onboard fetch --home <home> --server https://onli-witnessd.onrender.com.Preflight with
doctor. Every line must pass before you publish:owp3-adapter doctor --home <home> --server https://onli-witnessd.onrender.comPublish. Your appliance writes its outbox entries (see the contract above) into
<home>/witnesses/<host>/data/outbox/pending/;onboard envelopewrites a template. Run the publisher as a service; it reads the token from its file, turns each record into a public proof and prints itswitness_id:owp3-adapter witness --home <home> --server https://onli-witnessd.onrender.com --source outbox --watchFollow each record until it is final — published, cosigned by both Witness Nodes and anchored to Bitcoin:
owp3-adapter status --home <home> --server https://onli-witnessd.onrender.com --watchstatusreads only the public Witness and writes one<statement_id>.jsonper record. Add--esplora <url>to check the Bitcoin anchor proofs yourself; without it, a record can be final but is never markedverified.
At any point, owp3-adapter onboard status --home <home> --server <witness url> shows what is done and the next command to run. onboard never prints a secret; only connect, revoke and fetch use the network. Never put the service token on the command line — --token is deprecated because other users of the host can see it.
5. To be confirmed
Placeholder. This step is being finalized and will be added here.
Overview
Witness makes a private Oracle record publicly provable without making it publicly readable. It is an Onli protocol, OWP/3, with reference implementations.
- Oracle record (private). The authoritative record stays inside the appliance that produced it — for example a Species deployment the owner is a member of.
- Public proof. The Oracle Adapter registers a blinded 32-byte commitment in a public, append-only transparency log (RFC 9162). The log returns a signed COSE receipt.
- Witness Nodes. Independent nodes follow the log, verify every checkpoint, cosign it (C2SP
tlog-cosignature/v1) and anchor it through an anchor provider. OpenTimestamps to Bitcoin is the built-in provider and the production default. - Translate. The authenticated owner reconnects an opaque
witness_idto its private meaning. This happens only inside that appliance's Adapter, after the owner signs in with Onli ID. - Prove. The owner discloses selected claims to a chosen recipient, with a purpose and an expiry. The recipient verifies the presentation against the public log with open code.
Nothing about the record is public except the commitment. Running a Headless Witness Server or a Witness Node grants no access to private records.
Components
| Component | Role |
|---|---|
| Witness Protocol (OWP/3) | Contracts, cryptographic construction, verification rules. |
Headless Witness Server (witnessd) |
Public registration, transparency log, receipts, checkpoints, proof retrieval. Content-agnostic. |
Witness Node (witnessnode) |
FOLLOW, VERIFY, MIRROR, COSIGN, ANCHOR, SERVE, AUDIT. |
Oracle Adapter (owp3-adapter) |
Private, appliance-side. Witnesses records; owns Translate and Prove. |
Client SDK (@onli/witness-sdk) |
TypeScript, browser and Node.js. Verification runs the reference owp3-core compiled to WebAssembly. |
Which piece do I need?
- Check a proof or a
witness_id: the SDK'sverifyWitnessorverifyPresentation. No account needed. See Verify. - Build an owner app (sign-in, Translate, Prove): the SDK's
AdapterClientagainst the Adapter of each appliance the owner is a member of. See Owner flows. - Run a node (auditor, institution):
witnessnode. See Nodes. - Read the public log directly: the HTTP API. See HTTP API.
Install
Three developer packages build on Witness. They are available to approved partners on request; they are not publicly released.
| Package | What it is |
|---|---|
TypeScript SDK (@onli/witness-sdk) |
Verification (the reference owp3-core compiled to WebAssembly), the Oracle Adapter client and the Headless Witness read client. Node.js 20.16 or later, or a browser with Web Crypto. |
| Skills for Claude, Codex and Cursor | These docs, packaged so your coding agent can build with Witness. |
MCP server (onli-witness-mcp) |
Tools for Claude or any MCP client: verify a witness_id, read the latest checkpoint, read these docs. It reads public data only. |
Approved partners receive the packages and their install instructions with their agreement.
Using the SDK
Load the WebAssembly once before calling a synchronous verifier:
import { init } from "@onli/witness-sdk";
await init();
verifyWitness calls init() for you.
Without the SDK
Anyone can read the public log over HTTP (see HTTP API) and check its structures against the OWP/3 specification and the published conformance vectors.
Verify
Anyone can verify. No account, no private access.
Verify a witness_id
import { WitnessdClient, verifyWitness } from "@onli/witness-sdk";
const log = new WitnessdClient("https://onli-witnessd.onrender.com");
const r = await verifyWitness(log, witnessIdHex, {
tsPks: ["4a247208f625d449ae050090a63c102515ad1d09ba847d74a6af669ce4554933"], // receipt key
checkpointPks: ["ef4235259b28a633d5e36ce27caf9bfddfa8753ff8d130fb3677819b2da83101"], // adds note-signed
});
r.ok; // true only when every check passes
r.checks; // [{ id, ok, detail }]
Checks, in order:
| Check | Passes when |
|---|---|
published |
The bundle is served with state 3 PUBLISHED. |
receipt |
The first receipt verifies under the Transparency Service key. |
stable-id |
The statement hashes to the requested witness_id. |
on-log |
The statement's index is inside a checkpoint of the log. |
note-signed |
Only with checkpointPks: that checkpoint is signed by the log under a pinned key. |
cosigned |
Only with nodeKeys: at least one pinned Witness Node cosigned it, and every pinned node's line verifies. |
Pin keys. witnessd serves keys for discovery only. Without tsPks, checkpointPks and nodeKeys, every check trusts what witnessd serves. Get keys out of band — the production keys are on the Production page.
A 404 or 202 is a failed published check; the other checks report skipped. Transport errors throw. An id that is not 64 hex characters throws invalid_input.
Anchors
r.anchors lists the anchors of the checkpoint that decided on-log. Anchors are reporting only: they never change ok or checks.
- Without an anchor option every anchor is
NOT_CHECKED, whatever it claims. A verifier that does not implement a system reportsNOT_CHECKED, never verified. - Statuses:
NOT_CHECKED,VERIFIED,FAILED,PENDING.heightis present only whenVERIFIED. - The anchor state name for code 2 is
ANCHORED(formerlyBITCOIN_ANCHORED). Test withisAnchored(state).
OpenTimestamps to Bitcoin (production)
import { esploraHeaders, verifyWitness } from "@onli/witness-sdk";
const headers = esploraHeaders("https://your-esplora.example/api"); // you choose the source; there is no default
const r = await verifyWitness(log, witnessIdHex, { tsPks, anchors: { ots: { headers } } });
// r.anchors[0] → { system: "opentimestamps-bitcoin", status: "VERIFIED", height: <block>, … }
The SDK fetches raw 80-byte block headers and checks the hash, proof of work, a minimum-work floor (maxTargetBits, default 0x17100000) and the merkle root itself. A header source's own claims are never trusted.
Other anchoring systems plug into Witness Nodes through the owp3-anchor-plugin/1 protocol, and every system must define a proof that third parties verify independently. The SDK also contains a verifier for an Ethereum L1 calldata provider, which is a reference add-on example of the plugin architecture; production anchors to Bitcoin through OpenTimestamps.
Verify a Proof Presentation
A recipient of an owner's proof verifies it offline:
import { init, verifyPresentation } from "@onli/witness-sdk";
await init();
const result = verifyPresentation(coseHex, {
now: Math.floor(Date.now() / 1000),
tsPks: ["4a247208…4933"],
policyPks: ["260396295a5c2185c2f1e85407b06efee68b06ba8ce123804cdf53c74d391767"],
profileAuthorityPks: ["8bd61df0bf110ce2b6889e83c5f2b312005dffb788271eecbbdbfe3feb4d012a"],
requireAdmission: true,
expectedChallenge: challengeHex, // if you issued one
});
With requireAdmission, a trusted policyPks key and no oracleRootPks, the Oracle root key is derived from the Admission Attestation (zero-config). Each dimension reports its own status; show "verified" only for dimensions that verified. A presentation with neither expires_at nor a challenge is unbound — never show it as current.
Owner flows: Translate and Prove
The owner of a record is the member it concerns, identified by their Onli ID. Owner flows run against the Oracle Adapter of the appliance that holds the record — the Species deployment the owner is a member of — never the public Witness. Sign-in is Onli ID: the owner gives their Onli ID email and approves with one tap in OnliYou. Sign-in is per appliance; an owner who is a member of several appliances signs in to each one.
import { AdapterClient, TranslateSession, endTranslate, AUDIENCE_NAMED } from "@onli/witness-sdk";
const adapter = new AdapterClient(ADAPTER_URL);
const { token } = await adapter.session("owner@example.com"); // Onli ID sign-in; keep the bearer in memory only
const st = await adapter.status(token); // READY · DEGRADED · LOCKED, profiles, bindingCount
const page = await adapter.listBindings(token, { limit: 100 }); // the owner's witnessed records
Translate
const view = new TranslateSession(adapter, token);
const [item] = await view.translate([witnessIdHex], { includeProofableClaims: true });
item.headline; // e.g. "Bought 10 OB"
item.proofableClaims; // claim paths the owner may disclose
item.supersededBy; // set when the record was corrected — show it as superseded, not current
endTranslate(view); // clears the in-memory cache (local only; no server call)
Translated values belong in client memory only. Never send them to analytics, logs or the public Witness.
Prove
Disclose chosen claims to one named recipient, for a purpose, until an expiry:
const grant = await adapter.prove(token, {
witnessId: witnessIdHex,
claims: [item.proofableClaims![0]],
audience: { kind: AUDIENCE_NAMED },
recipient: "auditor@firm.example",
purpose: "quarterly review",
expiresAt: Math.floor(Date.now() / 1000) + 7 * 86400, // required for a named recipient
});
// grant → { envelope, grantId }
listGrants/revokeGrantmanage grants. Revoking stops future access; it cannot make a recipient forget what they saw.- Recipients register an X25519 key with
setRecipientKey(create one withgenerateRecipientKeyPair()), list grants withlistReceived, and open envelopes withopenEnvelope(envelope, skHex). - For interactive checks, the recipient supplies a challenge and verifies with
expectedChallenge.
Errors are WitnessSdkError with code, errorName and, for HTTP errors, httpStatus.
HTTP API (public, read-only)
The Headless Witness serves CBOR (Accept: application/cbor). Ids in paths are base64url of the 32-byte value, not hex. The SDK's WitnessdClient wraps these.
| Method and path | Returns |
|---|---|
GET /owp |
Discovery. |
GET /owp/3/checkpoints/latest |
Latest checkpoint: signed note, cosignatures, anchor states. |
GET /owp/3/checkpoints/{checkpoint_id} |
One checkpoint. |
GET /owp/3/witnesses/{witness_id} |
Bundle: statement, receipts, log index, checkpoint. 202 while pending. |
GET /owp/3/keys/{kid} |
A served key record (discovery, not trust). |
GET /owp/3/profiles |
The Profile Registry. |
GET /owp/3/profiles/{id}/{version} |
A Signed Profile Manifest. |
curl -H "Accept: application/cbor" https://onli-witnessd.onrender.com/owp/3/checkpoints/latest
Registration (POST /owp/3/statements) needs an Onli-issued appliance token and is done by the Oracle Adapter, not by apps.
The server does not send CORS headers for arbitrary origins. Call it from a server, a CLI or the MCP server, or from an origin it allows.
Witness Nodes
A Witness Node verifies public history without seeing any private record. You can run one yourself, or an independent audit firm can run it for you.
Roles (NODE_ROLES, comma list; default follow,verify):
| Role | Does |
|---|---|
follow |
Tracks checkpoints and log growth. |
verify |
Checks signatures, log identity, protocol version and RFC 9162 consistency. |
mirror |
Keeps public history to serve or rebuild evidence. |
cosign |
Countersigns verified checkpoints (tlog-cosignature/v1). Never cosigns two histories that disagree. |
anchor |
Anchors each checkpoint_id through the configured anchor provider. |
serve |
Serves /node/checkpoint, /node/audit, /node/health and more. |
audit |
Applies NODE_AUDIT_POLICY: attestation quorum and maximum checkpoint age. |
Attestation quorum (audit)
{
"required_attestations": 2,
"eligible_node_ids": ["node-a", "node-b", "node-c"],
"eligible_node_keys": { "node-a": "<base64 Ed25519>", "node-b": "<base64 Ed25519>", "node-c": "<base64 Ed25519>" },
"max_checkpoint_age_seconds": 900
}
Production runs a two-node quorum: both Witness Nodes must cosign every checkpoint. A cosignature counts only when it verifies under that node's pinned key, once per node. States: pending, satisfied, failed, not_required. A failed quorum is never silent: an ERROR log, GET /node/audit shows it, /node/health answers 503 (a readiness and alerting signal, not a liveness probe), and NODE_AUDIT_HALT_ON_FAIL=1 halts the node.
Anchor providers
NODE_ANCHOR_PROVIDER |
System | Notes |
|---|---|---|
ots (default) |
opentimestamps-bitcoin |
NODE_OTS_CALENDARS (required), NODE_OTS_HEADERS_URL, NODE_OTS_MAX_TARGET_BITS, NODE_OTS_FAIL_AFTER. Production. |
testchain |
testchain-v1 |
Tests only. Refused by production verifiers. |
exec |
the plugin's own id | A pinned external plugin speaking owp3-anchor-plugin/1 (JSON lines on stdin/stdout). NODE_ANCHOR_EXEC, NODE_ANCHOR_EXEC_SHA256 (required), NODE_ANCHOR_EXEC_ARGS, NODE_ANCHOR_EXEC_TIMEOUT. |
NODE_ANCHOR_INTERVAL (default 1h) limits anchoring to one checkpoint per interval. Only the 32-byte checkpoint_id leaves the node; one transaction covers every proof in that checkpoint. A plugin runs as the node's user and is fully trusted — contain it with a separate uid or a container.
The full operator reference is node/README.md in the Witness repository.
Production
| Service | URL |
|---|---|
| Headless Witness | https://onli-witnessd.onrender.com |
Witness Node onli-node-1 (cosign, Bitcoin anchoring) |
https://onli-witness-node-1.onrender.com |
Witness Node onli-node-2 (cosign) |
https://onli-witness-node-2.onrender.com |
Attestation quorum: 2 — both nodes cosign every checkpoint.
Public keys to pin (hex, Ed25519). Served keys are discovery only; pin these.
| Key | Value | SDK option |
|---|---|---|
| Transparency Service (receipts) | 4a247208f625d449ae050090a63c102515ad1d09ba847d74a6af669ce4554933 |
tsPks |
| Checkpoint (signed note) | ef4235259b28a633d5e36ce27caf9bfddfa8753ff8d130fb3677819b2da83101 |
checkpointPks |
| Registration Policy | 260396295a5c2185c2f1e85407b06efee68b06ba8ce123804cdf53c74d391767 |
policyPks |
| Profile Authority root | 8bd61df0bf110ce2b6889e83c5f2b312005dffb788271eecbbdbfe3feb4d012a |
profileAuthorityPks |
Log id: fc46c284b39253cbe0e798b58357c2da9dbe9f7bb2564b1dce18f85a898db4be.
Staging
Staging is a separate log with its own keys. Use it to try the tools; never pin staging keys for production.
| Staging | |
|---|---|
| Headless Witness | https://onli-witness.fly.dev |
| Transparency Service pk | c6da07f9baf7f33734b6096ac8dfbbd0b206ed25ac09279ca43093ea90fdc120 |
| Checkpoint pk | 964fce686134e2de36cb0df84ca7f874caff03895b2c62b05ab922d096ccc212 |
| Log id | f00717e35aa2be000eaa87749b75c42a6d6fd7f9e4fb315ab85ca390082d951b |
| Example witness (staging only) | 2ab8537479c458025519e801885dcd65ef853e7f7b65950a83515a0b20cf777f — anchored to Bitcoin block 968863 |