ORACLE — Solv Labs, Inc. PBC

Offline verification of ORACLE governance records.

An ORACLE deployment signs a record every time it makes a governance decision about an agent action — whether the action was allowed to proceed, or blocked before it executed. This package lets anyone check those records independently: with a public key, a JSON file, and no network.

This package verifies records. It does not produce them; signing happens inside an ORACLE deployment.

pip install solv-oracle
# save the record from the worked example below as demo_deny.json, then:
oracle-verify demo_deny.json \
  --pubkey 525021424ccfedfd75219311841e58794b9ff0a4a0a3388203b39451634e1e02

VALID  type=deny  id=pfx_doc0000000000ex

That is reproducible end to end. (A pip install places the library and the oracle-verify command, not the example files; those ship in the source distribution under examples/.)

Exit codes: 0 every record verified · 1 a record was found and its signature did not verify · 2 usage error, unreadable input, or a record too malformed to judge.

The 1/2 split is deliberate. "This signature is invalid" and "this is not a well-formed record" are different claims, and a verifier that conflates them is telling you something it does not know.

Why offline matters

A governance claim you can only check by asking the party who made it is not a governance claim. These records are signed, so the check is arithmetic: recompute the canonical form, verify the Ed25519 signature, done. No server is contacted, no vendor is trusted, and the two modules that do it are about 200 lines you can read in a sitting.

Two record types

Run Manifest — a decision about an action that executed. The signature covers fields 0–13: the execution and policy identifiers, the input/output/observable hashes, the violation vector, the risk signal, the confidence, the trust stage, and the action taken.

PREFLIGHT_DENY — a decision about an action that was blocked before execution. There is no run to describe, so the record carries the proposed action, the policy it was checked against, the solver verdicts that rejected it, and the variables extracted from the proposal.

oracle-verify detects which one it is from the record's contents. Records are often stored inside a larger envelope — a run log, a session ledger — so the document is searched to a bounded depth, through arrays as well as objects.

Every record found is verified and reported with the JSON path it was found at, and the exit code reflects the worst result. Nothing is silently selected: if a document holds several records you see all of them, so a decoy cannot hide a genuine record behind it.

As a library

from solv_oracle.verify import verify_manifest, verify_deny

verify_manifest(manifest_dict, pubkey)   # -> True | False
verify_deny(deny_dict, pubkey)           # -> True | False

Public keys are accepted as a hex string, raw 32 bytes, PEM, or an Ed25519PublicKey. Both functions return False for a bad signature and raise KeyError for a record missing a signed field — a malformed record is a different thing from a record that fails to verify.

What is and isn't covered

verify_deny performs two independent checks: that record_hash recomputes from the record's own attested fields, and that the signature over it is valid. Editing any attested field breaks the first; forging the hash to match still fails the second.

Fields deliberately outside the deny preimage are timestamp, preflight_latency_ms, preflight_llm_result, preflight_ar_detail, and is_synthetic — observational metadata, excluded so that the same governance decision hashes identically across runs. That list is exhaustive, exported as UNATTESTED_FIELDS, and asserted against a shipped signed record in the test suite so it cannot drift from the code.

A valid signature vouches for none of them. is_synthetic in particular is unsigned, so an automated consumer must not use it to tell a demonstration record from a production one. Only signed fields carry that weight.

And be precise about what a signature is worth at all. It establishes that the holder of the key issued this record and that it has not been altered since. It does not establish that a solver ran, that a policy was formally verified, or that the recorded verdicts are true — those are the issuer's assertions, and the signature binds the issuer to them. That is the whole of what verification proves, and it is worth a great deal, but it is not more than that.

For Run Manifests the signature covers the decision core, not the extended pricing and diagnostic fields (multiplier, alpha_L, loss_estimate, and similar). Those can be edited without invalidating the signature. If your use case depends on them, they need a separate integrity mechanism. This is stated plainly because a verifier that implies more coverage than it has is worse than no verifier.

Manifest-level hash fields such as manifest_hash are not recomputed by this package.

One further limit, on the manifest format itself. The signed preimage is the fields joined by commas, with no escaping or length prefixing. A signature therefore pins the concatenation, not the field boundaries: a value that itself contains a comma can be re-split across adjacent fields to yield a different manifest with the same valid signature. Deny records are unaffected — their preimage is canonical JSON, where strings are quoted and escaped. If you consume manifests programmatically, treat adjacent trailing fields as unpinned.

Where the public key comes from

Use a key you obtained independently of the record — published in a document of record, registered on-chain, or handed to you out of band. The key in the worked example below is published here for that purpose: it is the key that signed Solv Labs' M3 pilot governance records, and the signed evidence in the M3 submission pack verifies against this same key.

Do not use a public key carried inside the record you are verifying. A record that supplies its own key proves only that it is internally consistent, which is not the question you are asking.

Worked example

The record below was signed by the same ORACLE key that signed Solv Labs' M3 pilot governance records. Save it as demo_deny.json and check it yourself (it ships in the source distribution as examples/demo_deny.json):

{
  "record_id": "pfx_doc0000000000ex",
  "record_type": "PREFLIGHT_DENY",
  "schema_version": "1.1",
  "timestamp": "2026-07-27T00:00:00Z",
  "preflight_policy_id": "00000000-0000-0000-0000-000000000000",
  "preflight_action_description": "Pay 500.00 USDC to an unlisted payee on Base mainnet, chain eip155:8453. [DOCUMENTATION EXAMPLE \u2014 not a production decision]",
  "preflight_result": "UNSAT",
  "preflight_check_id": "00000000-0000-0000-0000-000000000000",
  "preflight_proof_id": "",
  "preflight_latency_ms": 0,
  "preflight_z3_result": "UNSAT",
  "preflight_ar_result": "UNSAT",
  "preflight_llm_result": "UNSAT",
  "preflight_ar_detail": "action violates policy rules",
  "agent_id": "",
  "policy_version": "",
  "trust_stage": 0,
  "is_synthetic": true,
  "extracted_variables": {
    "purchaseAmountUSD": 500.0
  },
  "record_hash": "0x077e45d4240fca0126bdf8b36951c48e6cfb85c72aa68b2555adb4b5168ea180",
  "signature": "f9a5c1061c48f208de6e2be46990c69fc1dc3a5b03ac36aea3195babbcc1f97694201004bb74dd04cdcb476389e8a95aaa0e65021571431ffb7baeceab003c0e"
}

oracle-verify demo_deny.json \
  --pubkey 525021424ccfedfd75219311841e58794b9ff0a4a0a3388203b39451634e1e02

VALID  type=deny  id=pfx_doc0000000000ex

The [DOCUMENTATION EXAMPLE] marker sits inside preflight_action_description, which is part of the signed preimage — it cannot be stripped without breaking the signature. That is the same technique ORACLE uses to bind a planned probe to its own record.

Read that claim narrowly. The marker is what a human reads, and it is protected. The is_synthetic flag, which is what a program would read, is not signed and can be flipped without invalidating anything. If you are consuming these records automatically, key off the signed description, not the flag.

Try editing any attested field — preflight_result, the amount in the action description, the policy id — and run it again. It will report INVALID.

Requirements

Python 3.10+. One runtime dependency: cryptography.

solv-oracle is an umbrella distribution. Capabilities live in their own subpackages and are imported explicitly, so installing one never pulls in the dependencies of another. solv_oracle.verify is the only capability in this release.

Tests

The test suite ships in the source distribution (.tar.gz), not the wheel, so a plain pip install does not put it on disk. Unpack the sdist, then:

# from inside the unpacked sdist directory
pip install -e ".[dev]"    # installs this copy of the package, plus pytest
python -m pytest tests/ -q

pip install "solv-oracle[dev]" would resolve from the package index instead, which tests whatever is published rather than the source you are holding.

The suite runs standalone — no ORACLE deployment, no network, no credentials. To check the package against your own signed evidence, point SOLV_ORACLE_VERIFY_VECTORS at a directory of {"pubkey": "...", "record": {...}} JSON files.

License

MIT. Copyright (c) 2026 Solv Labs, Inc. PBC.