Ledger & CLI

Demo API offline

The public OSDF Live Ledger explorer is offline until production telemetry is connected. The proof API routes below may still serve synthetic demo data for development; entries are machine-generated and signing keys and witnesses are synthetic. The same contract maps directly onto a production deployment.

The OSDF Live Ledger is the public trust substrate of the platform: an append-only, hash-chained, witness-backed transparency log. Every verification, access decision, and policy evaluation is recorded, cryptographically linked to prior state, and publicly inspectable. The ledger stores compact commitments - digests, never document contents.

osdf-cli treats the ledger as its authoritative source of proof: it anchors artifact digests to the log and proves them against a signed checkpoint, online or offline.

How the tree works

Entries are committed to an RFC 6962 -style Merkle tree with domain-separated hashing:

text

entry_hash = SHA-256( domain || seq || canonical_entry || prior_entry_hash )leaf       = SHA-256( 0x00 || entry_hash )parent     = SHA-256( 0x01 || left || right )root       = Merkle Tree Hash over all committed leaves

The checkpoint (a Signed Tree Head) publishes the current tree_size and root_hash. An inclusion proof is the audit path from a leaf to that root; a consistency proof shows an older root is an append-only prefix of a newer one - so the log cannot rewrite history without detection.

Proof API

All routes run on the Node runtime and return JSON. Responses are isomorphic with the TypeScript models in @/lib/ledger/types.

Method	Endpoint	Purpose
`GET`	`/api/ledger/checkpoint`	Current signed checkpoint (tree size + root).
`GET`	`/api/ledger/entry?id=…`	Entry + inclusion proof (also `?artifact=` / `?hash=`).
`GET`	`/api/ledger/consistency?first=&second=`	Consistency proof between two sizes.
`POST`	`/api/ledger/anchor`	Append a submitted digest; returns id + proof.
`GET`	`/api/ledger/summary`	Lightweight headline counters.

Get the current checkpoint

bash

curl https://osdfsystems.com/api/ledger/checkpoint

json

{  "logId": "osdf-public-demo-log",  "treeSize": 184203,  "rootHash": "9f3a1c4e…b27d",  "timestamp": "2026-06-25T22:14:07.512Z",  "keyId": "osdf-log-key-2026-synthetic",  "signature": "ed25519:Ym9ndXNzaWduYXR1cmVk…",  "witnesses": [    { "name": "witness-eu-1", "signature": "ed25519:…" },    { "name": "witness-us-2", "signature": "ed25519:…" },    { "name": "witness-apac-3", "signature": "ed25519:…" }  ],  "lifetimeEntries": 8472913}

Fetch an entry + inclusion proof

bash

curl "https://osdfsystems.com/api/ledger/entry?id=led_000123_9f3a1c"

json

{  "leafIndex": 122,  "treeSize": 184203,  "leafHash": "c0de…aa11",  "auditPath": ["7b1e…", "33af…", "90c2…"],  "rootHash": "9f3a1c4e…b27d",  "checkpoint": { "treeSize": 184203, "rootHash": "9f3a1c4e…b27d", "…": "…" },  "entry": { "id": "led_000123_9f3a1c", "type": "document_verified", "…": "…" }}

Look an entry up by anchored content digest with ?hash=<sha256> or by artifact id with ?artifact=art_….

Fetch a consistency proof

bash

curl "https://osdfsystems.com/api/ledger/consistency?first=184000&second=184203"

json

{  "first": 184000,  "second": 184203,  "firstRoot": "1aa2…",  "secondRoot": "9f3a1c4e…b27d",  "proof": ["b41c…", "0f9e…", "77d3…"]}

`osdf ledger` commands

Initialize

Point the CLI at a ledger endpoint, choose a tenant/scope, and pin the log's public key and a starting checkpoint to trust:

bash

osdf ledger init \  --endpoint https://osdfsystems.com/api/ledger \  --tenant tenant-7f3a \  --scope enterprise \  --trust-key osdf-log-key-2026

This writes ~/.config/osdf/ledger.toml (override with --config, or the OSDF_LEDGER_ENDPOINT / OSDF_LEDGER_TENANT environment variables):

toml

[ledger]endpoint = "https://osdfsystems.com/api/ledger"tenant   = "tenant-7f3a"scope    = "enterprise" [ledger.trust]key_id    = "osdf-log-key-2026"# Pinned checkpoint; consistency-checked on every subsequent call.tree_size = 184203root_hash = "9f3a1c4e…b27d"

Manage pinned trust material later with osdf ledger trust-config.

Anchor an artifact

Anchoring submits the digest of a package - never its contents - and appends it to the log. Use the dedicated command or the --anchor flag on verify:

bash

# Anchor a digest and record the returned proofosdf ledger anchor contract.osdf # …or anchor as part of verificationosdf verify contract.osdf --anchor

Under the hood the CLI computes digest = SHA-256(canonical package bytes) and POSTs it:

bash

curl -X POST https://osdfsystems.com/api/ledger/anchor \  -H "content-type: application/json" \  -d '{ "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "artifact": "contract_8832.osdf", "scope": "enterprise" }'

json

{  "entry": { "id": "led_184204_4b1c9a", "type": "ledger_anchor", "result": "Anchored", "…": "…" },  "leafIndex": 184203,  "inclusionProof": ["2c7f…", "a90b…"],  "checkpoint": { "treeSize": 184204, "rootHash": "5d2e…f00a", "…": "…" }}

Retrieve and verify proofs

bash

# Inspect a stored inclusion proof for a ledger idosdf ledger proof led_184204_4b1c9a # Verify a local file against the current checkpoint rootosdf ledger verify contract.osdf # Prove the log only grew between two checkpointsosdf ledger consistency --from 184000 --to 184204 # Print the current signed checkpointosdf ledger checkpoint

A successful osdf ledger verify recomputes the package digest, fetches the inclusion proof and checkpoint, and recomputes the root from the audit path:

text

Ledger verification Overall: PASS Checkpoint  [PASS] Checkpoint signature recognized (key osdf-log-key-2026)  [PASS] Consistency with pinned checkpoint (184000 -> 184204) Inclusion  [PASS] Leaf hash matches package digest  [PASS] Audit path reconstructs checkpoint root    leaf_index 184203 of tree_size 184204 Witnesses  [PASS] 3 witness cosignatures verified

How verification works

The proof math is published as a tiny, dependency-free, isomorphic helper (@/lib/ledger/merkle) so a client, CLI, or third party can verify proofs without trusting the server. Inclusion verification recomputes the root from the leaf and audit path and compares it to the checkpoint:

import { leafHash, verifyInclusion } from "@/lib/ledger/merkle"; // 1. The leaf commits to the entry hash (digest of the canonical entry).const leaf = leafHash(entry.proof.entryHash); // 2. Recompute the root from the audit path and compare to the checkpoint.const ok = verifyInclusion({  leafHash: leaf,  leafIndex: proof.leafIndex,  treeSize: proof.treeSize,  proof: proof.auditPath,  root: checkpoint.rootHash,}); if (!ok) throw new Error("inclusion proof failed - do not trust this entry");

Consistency proofs are verified the same way with verifyConsistency, which recomputes both the old and new roots from a single proof and the two tree sizes. Independent witness cosignatures over the checkpoint detect a log attempting to present a split view to different clients.

From demo to production

The public endpoint serves synthetic telemetry, but the contract is the production contract. A real deployment changes only the data source and trust material:

The synthetic signing key and witness cosignatures become a real Ed25519 log key and independent witness operators.
POST /api/ledger/anchor authenticates submitters, validates the digest against policy, and rate-limits - rather than accepting any digest.
tree_size converges with lifetimeEntries once every entry is materialized.

Continue to the Ledger API reference.

Ledger & CLI

How the tree works

Proof API

Get the current checkpoint

Fetch an entry + inclusion proof

Fetch a consistency proof

osdf ledger commands

Initialize

Anchor an artifact

Retrieve and verify proofs

How verification works

From demo to production

`osdf ledger` commands