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:

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.

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.

  1. Create the appliance identity, service token and admission request:

    owp3-adapter onboard init --home <home> --profile onli.std.asset-transfer@1
    

    The 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.

  2. Lay out the Witness folders:

    owp3-adapter onboard layout --home <home> --server https://onli-witnessd.onrender.com --create
    
  3. Connect 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.json to Onli with your request; once it is granted, download everything with owp3-adapter onboard fetch --home <home> --server https://onli-witnessd.onrender.com.

  4. Preflight with doctor. Every line must pass before you publish:

    owp3-adapter doctor --home <home> --server https://onli-witnessd.onrender.com
    
  5. Publish. Your appliance writes its outbox entries (see the contract above) into <home>/witnesses/<host>/data/outbox/pending/; onboard envelope writes a template. Run the publisher as a service; it reads the token from its file, turns each record into a public proof and prints its witness_id:

    owp3-adapter witness --home <home> --server https://onli-witnessd.onrender.com --source outbox --watch
    
  6. Follow 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 --watch
    

    status reads only the public Witness and writes one <statement_id>.json per record. Add --esplora <url> to check the Bitcoin anchor proofs yourself; without it, a record can be final but is never marked verified.

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.

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?

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.

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 }

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