Documentation.

PROVENANCE publishes deterministic, on-chain-anchored risk dossiers for tokenized assets. Three ways to consume a rating: REST for apps, MCP for agents, and the registry contract for anything that can read Mantle.

Registry 0xd153…37A9Mantle Sepolia 5003Rubric v1.0.0

Quickstart

git clone https://github.com/ronkenx9/provenance && cd provenance
npm install
npm test                              # 22 tests
npm run dev -- score all --from-snapshot   # offline, deterministic
npm run api                           # REST + viewer on :3000

REST API

Endpoint	Returns
`GET /ratings`	all assets — composite, grade, per-dimension summary
`GET /rating/:asset`	full dossier: dimensions, factors, flags, narrative, registry link
`GET /narrative/:asset`	validated plain-English narrative only
`GET /health`	service status

$ curl localhost:3000/rating/USDY
{
  "symbol": "USDY",
  "composite": 60.2,
  "grade": "B",
  "dimensions": [
    { "dimension": "collateral", "score": 90, "effectiveWeight": 38.5,
      "factors": ["base 90 for backing type tbills", …] },
    { "dimension": "concentration", "score": null, "unknown": true,
      "factors": ["no sourced inputs — dimension flagged unknown"] }
  ],
  "flags": ["dimension 'concentration' UNKNOWN — weight redistributed"],
  "narrative": "USDY receives a composite score of 60.2…"
}

Asset ids: USDY · mETH · USDe · FBTC (case-insensitive).

MCP Server

Stdio server for Claude Code or any MCP client:

$ claude mcp add provenance -- npm --prefix /path/to/provenance run mcp

Tool	Args	Returns
`PROVENANCE_LIST`	—	all assets: symbol, composite, grade, flag count
`PROVENANCE_GET_RATING`	`{ asset }`	full dossier JSON
`PROVENANCE_EXPLAIN`	`{ asset }`	validated narrative — why the score is what it is

On-chain Registry

DossierRegistry at 0xd1534d20006248f4c2c290F83e6377b4A06037A9 (Mantle Sepolia 5003, Sourcify exact_match). No PROVENANCE infrastructure required — read it directly:

# latest rating for USDY
$ cast call 0xd1534d20006248f4c2c290F83e6377b4A06037A9 \
    "latest(bytes32)" $(cast keccak "USDY") \
    --rpc-url https://rpc.sepolia.mantle.xyz

Function	Notes
`latest(bytes32 assetId)`	one-call agent read → `(score×10, grade, dossierHash, methodologyHash, atBlock, version)`
`history(bytes32 assetId)`	every published version
`versionCount(bytes32)`	number of versions
`assetIdOf(string)`	helper — `keccak256(bytes(symbol))`
`publishDossier(…)`	publisher-gated; emits `DossierPublished`

Integrity model: dossierHash = sha256 of the canonical dossier JSON. methodologyHash = sha256 of weights + scorer source — a rubric change is a new methodology, visible on-chain. Never a silent edit.

Methodology

Composite 0–100 from five dimensions. The LLM never produces a score.

Dimension	Weight	Inputs
Collateral quality	25	backing type · attestation freshness · collateral ratio
Redemption mechanics	20	on-chain path · notice period · realized volume
Liquidity depth	20	DEX TVL vs cap · cost to exit $100k
Concentration risk	20	top-10 holders · single points of failure · bridges
Transparency	15	attestation cadence · verified contracts · docs completeness

Grade bands: AA 85+ · A 70–84 · B 50–69 · C 30–49 · D <30.

The unknown rule

A dimension without independently sourced inputs scores nothing: it is flagged unknown, its weight is redistributed across scored dimensions, and the flag is printed on the dossier and anchored on-chain. Withholding data lowers certainty visibly — silence is penalized, never neutral. Unverifiable claims earn the conservative floor and an annotation (PROXY / SECONDARY SOURCE / CONSERVATIVE FLOOR).

Narratives

The plain-English layer is LLM-written and machine-validated: every numeral in the prose must match a value in the computed record or the narrative is rejected and regenerated (max 3 attempts, then hard failure). Hype vocabulary is banned. A deliberately corrupted narrative fails the test suite.

Limitations

Limit	Detail
Coverage	v1 rates exactly four assets: USDY, mETH, USDe, FBTC
Anchor chain	registry on Mantle Sepolia (testnet); asset measurement on Mantle mainnet
Attester trust	published attestations trusted at document level; signed attestations / PoR oracles are roadmap
Ratings ≠ advice	dossiers describe risk structure; they are not investment recommendations