@axiomatic_oracle/verifier

TypeScript/JavaScript SDK to independently verify p1 Proof-of-Valuation (PoVal) attestations (and selected legacy formats) published on Algorand.

Given a transaction ID, it:

1. Fetches the transaction via an Algorand Indexer.
2. Extracts and decodes the note.
3. Re-canonicalizes the JSON (JCS/ACJ-style).
4. Recomputes the SHA-256.
5. Applies lightweight validation rules (schema, hash, timestamp).
6. Returns a structured result you can plug into your own logic.

It is designed to work with notes produced by:

- @axiomatic_oracle/proofkit (Node),
- axiomatic_proofkit (Python),
- and compatible Axiomatic Oracle integrations.

---

Who is this for?

Use @axiomatic_oracle/verifier if you:

- Need to verify PoVal attestations issued on Algorand.
- Build Node-based back-ends, dashboards, explorers or audit tools.
- Want to validate p1 notes (and selected legacy formats) directly from the chain.

If you need to create and publish p1 attestations, see
@axiomatic_oracle/proofkit (Node) or axiomatic_proofkit (Python).

---

Typical use cases

1. RWA dashboards & explorers
- Given a txid, show whether a PoVal attestation is valid and fresh.
- Display v, u, ts, hashes and model metadata to end users.

2. Risk / compliance engines
- Check that incoming PoVal proofs are well-formed, hash-consistent and within your time window.
- Combine verified, reason, mode and timestamps into your risk policies.

3. Back-office audit tooling
- Periodically verify a set of PoVal transactions.
- Export structured verification results for further analysis.

---

Installation

``bash
npm install @axiomatic_oracle/verifier
`

Requirements:

* Node.js 18+ or a runtime providing:

* fetch
* TextDecoder
* crypto.subtle or a compatible SHA-256 implementation.

If you run on older Node.js versions, you will need to polyfill fetch and related globals.

---

Indexer and explorer defaults

Default Indexer (Algonode):

* mainnet: https://mainnet-idx.algonode.cloud
* testnet: https://testnet-idx.algonode.cloud
* betanet: https://betanet-idx.algonode.cloud

Default Explorer (Pera):

* mainnet: https://explorer.perawallet.app/tx/{txid}
* testnet: https://testnet.explorer.perawallet.app/tx/{txid}

You can override indexerUrl if you run your own infrastructure.

---

Quickstart: verify a p1 from Node.js

`ts
import "dotenv/config";
import { verifyTx } from "@axiomatic_oracle/verifier";

async function main() {
const txid = process.argv[2];
if (!txid) {
console.error("Usage: node verify_p1.js ");
process.exit(1);
}

const network = (process.env.ALGORAND_NETWORK || "testnet").trim();
const indexerUrl =
process.env.INDEXER_URL ||
(network === "mainnet"
? "https://mainnet-idx.algonode.cloud"
: "https://testnet-idx.algonode.cloud");

const res = await verifyTx({
txid,
network,
indexerUrl,
// Example policy: accept p1 issued within the last hour,
// and up to 5 minutes in the future (clock skew).
maxSkewPastSec: 3600,
maxSkewFutureSec: 300,
});

console.log(JSON.stringify(res, null, 2));
}

main().catch((err) => {
console.error(err);
process.exit(1);
});
`

Use a txid produced by @axiomatic_oracle/proofkit or axiomatic_proofkit
on the same network.

---

API surface

From @axiomatic_oracle/verifier:

* verifyTx(options) → Promise
* toJcsBytes(obj) – canonical JSON encoder
* sha256Hex(bytes) – SHA-256 helper
* jcsSha256(obj) – convenience helper

`ts
export type Network = "testnet" | "mainnet" | "betanet";

export interface VerifyResult {
verified: boolean;
reason?: string | null;
mode: "p1" | "legacy" | "unknown";
noteSha256?: string;
rebuiltSha256?: string;
confirmedRound?: number;
explorerUrl?: string;
note?: any;
}
`

---

Result semantics

$3

`json
{
"verified": true,
"mode": "p1",
"reason": null,
"noteSha256": "...",
"rebuiltSha256": "...",
"confirmedRound": 57318625,
"explorerUrl": "https://testnet.explorer.perawallet.app/tx/...",
"note": {
"s": "p1",
"a": "re:EUR",
"mv": "v2",
"mh": "",
"ih": "...",
"v": 550000,
"u": [520000, 580000],
"ts": 1762609210
}
}
`

$3

`json
{
"verified": false,
"mode": "p1",
"reason": "ts_out_of_window",
"noteSha256": "...",
"rebuiltSha256": "...",
"explorerUrl": "..."
}
`

Meaning: the attestation is well-formed and hash-consistent, but ts is outside
the allowed window (maxSkewPastSec / maxSkewFutureSec).

$3

`json
{
"verified": false,
"mode": "unknown",
"reason": "unsupported_or_empty_note",
"explorerUrl": "..."
}
`

$3

If the note matches selected legacy formats (ref, schema_version, etc.), the verifier will return:

`json
{
"verified": true,
"mode": "legacy",
"reason": null,
"note": { "ref": "...", "schema_version": "..." }
}
`

This allows you to keep backward compatibility while progressively migrating to p1.

---

Canonical JSON helpers

You can also use the bundled helpers to validate your own canonicalization:

`ts
import { toJcsBytes, jcsSha256 } from "@axiomatic_oracle/verifier";

const obj = { b: 2, a: 1 };
const bytes = toJcsBytes(obj);
const hash = await jcsSha256(obj);

console.log(hash);
`

They implement the same JCS/ACJ-style normalization used by the p1 verifier
and the ProofKit SDKs.

---

Security and policy notes

* @axiomatic_oracle/verifier does not execute any business logic for you.
* Treat its output as structured signals:

* verified, reason, mode,
* hashes, timestamps, explorer/indexer links,
* the decoded note`.
* You are expected to layer your own risk / policy logic on top:

* which models and asset tags are allowed,
* which issuers (addresses) you trust,
* how strict your time windows should be.

This is an early-access verifier: feedback and issues are very welcome.