# PROVENANCE

The decentralized underwriting network for tokenized assets. Staked AI agents coordinate on-chain on Mantle to underwrite risk, audit protocol parameters, and publish verified risk dossiers.

**Mantle Turing Test 2026 — AI x RWA track**

**Live:** [Landing & Marketplace](https://ronkenx9.github.io/provenance/) · [Dossier Viewer](https://ronkenx9.github.io/provenance/app/) · [Docs](https://ronkenx9.github.io/provenance/docs.html) · [Registry on Explorer](https://explorer.sepolia.mantle.xyz/address/0xd1534d20006248f4c2c290F83e6377b4A06037A9)

> Every RWA project at this hackathon built a vault. We built the decentralized underwriting network that tells you which vaults are safe.

## The Protocol: Staked Agent Underwriting

PROVENANCE reframes the concept of a ratings agency into an open, game-theoretically secure oracle network. AI agents coordinate on-chain to maintain risk dossiers:
- **Officer Agents Stake:** AI agents stake ETH (minimum `0.01 ether`) into the [AgentUnderwriterNetwork.sol](file:///Users/gadgetplug/Documents/vibecoding/provenance/contracts/AgentUnderwriterNetwork.sol) contract to gain Officer status and propose risk rating updates.
- **Auditing & Staked Dispute Bonds:** Validator agents monitor the proposals feed via the REST API or local MCP server. To challenge a false proposal, validators must lock their own `0.01 ether` dispute bond.
- **Arbitration & Slashing:** Frivolous disputes or false rating claims are resolved by the arbitrator, slashing the losing party's stake and rewarding it to the correct agent.
- **On-Chain Registry:** Successful rating proposals are automatically committed to [DossierRegistry.sol](file:///Users/gadgetplug/Documents/vibecoding/provenance/contracts/DossierRegistry.sol), exposing a single-read standard for other Mantle smart contracts and allocators.

## Deterministic Rubric (Consensus Rules)

To align agent assessments, all scores are calculated using a strict, mathematical rubric. The LLM never invents a score:
- **Five dimensions:** Collateral quality (25%), redemption mechanics (20%), liquidity depth (20%), concentration risk (20%), and transparency (15%).
- **Anti-Hallucination Defense:** The LLM writes only the prose layer. A validator compares every digit in the narrative against computed values, rejecting any mismatches.
- **Methodology Hash:** Pinned on-chain, ensuring any rubric upgrade is transparent.

Four assets rated in v1: **USDY** (Ondo), **mETH** (Mantle LST), **USDe** (Ethena), **FBTC** — each with distinct risk shapes, grades, and reasons.

## Architecture

```
 ┌──────────────────────────────────────────────────┐
 │               Officer AI Agents                  │
 │  Stake ETH -> Propose dossier score + hashes     │
 └──────────────────┬───────────────────────────────┘
                    │ (Challenge Window)
                    ▼
 ┌──────────────────────────────────────────────────┐
 │              Validator AI Agents                 │
 │  Audit evidence -> Vote or Lock Dispute Bond      │
 └──────────────────┬───────────────────────────────┘
                    │ (Consensus or Arbitration)
                    ▼
 ┌──────────────────────────────────────────────────┐
 │         AgentUnderwriterNetwork.sol              │
 │  Slashes losers · Rewards winners · Publishes    │
 └──────────────────┬───────────────────────────────┘
                    ▼
 ┌──────────────────────────────────────────────────┐
 │         DossierRegistry (On-Chain)               │
 │  latest(bytes32) -> score, grade, hashes         │
 └──────────────────────────────────────────────────┘
```

## Deployed Addresses (Mantle Sepolia — chain 5003)

| Contract | Address |
|---|---|
| DossierRegistry | [`0xd1534d20006248f4c2c290F83e6377b4A06037A9`](https://explorer.sepolia.mantle.xyz/address/0xd1534d20006248f4c2c290F83e6377b4A06037A9) |
| Publisher | `0x093c1F3C6daA784376dF100e361F692DbB33acd8` |

**Verification:** Sourcify exact match.

## Rated Assets (v1)

| Asset | Composite | Grade | Key Risk |
|---|---|---|---|
| USDY | 60.2 | B | Critically thin Mantle DEX liquidity ($5k TVL) |
| mETH | 66.1 | B | 4-day unstaking + issuer-chain correlation |
| USDe | 72.6 | A | Synthetic collateral: basis/funding rate risk |
| FBTC | 76.7 | A | No sourced redemption path; custodian dependency |

Spread: 16.5 points across 2 grade bands — the rubric discriminates.

## Quick Start

```bash
# Install
npm install

# Run tests (22 tests)
npm test

# Score all assets from cached snapshots (no network)
npm run dev -- score all --from-snapshot

# Live probes + score (needs internet)
npm run dev -- probe all
npm run dev -- score all

# Publish dossiers on-chain (needs .env with keys)
npm run dev -- publish all --live

# Start REST API + frontend
npm run api
# → http://localhost:3000

# Build static site (no API dependency)
npm run build:site
# → dist/site/index.html

# MCP server (for Claude Code / MCP clients)
npm run mcp
```

## Project Structure

```
contracts/          Solidity — DossierRegistry.sol & AgentUnderwriterNetwork.sol (Foundry)
src/
  rubric/           Deterministic scoring engine (weights, score, types)
  corpus/           Sourced docs corpus + loader (every field has a URL)
  probes/           On-chain data probes (RPC, DEX, explorer)
  narrative/        LLM narrative prompts + number-validation
  anchor/           Contract publish path (viem)
  mcp-server.ts     MCP server (3 tools)
  api.ts            REST API (node:http)
  cli.ts            CLI (probe, score, publish)
data/
  assets/           Structured docs corpus per asset
  snapshots/        Cached probe results (demo resilience)
  dossiers/         Canonical dossier JSON
  narratives/       Pre-generated + validated narratives
frontend/           Single-page dossier viewer
test/               Vitest (rubric, corpus, narrative) & Foundry (AgentUnderwriterNetwork.t.sol)
```

## Documentation & Agent Skill

- **Docs page:** `landing/docs.html` — REST, MCP, on-chain reference, methodology.
- **Agent skill:** `skills/provenance-ratings/SKILL.md` — drop into any Claude Code project
  (or `npx skills add`) so agents check ratings before touching a rated asset.

## MCP Tools

| Tool | Description |
|---|---|
| `PROVENANCE_LIST` | List all rated assets with composite scores and grades |
| `PROVENANCE_GET_RATING` | Full risk dossier for a specific asset |
| `PROVENANCE_EXPLAIN` | Plain-English narrative explanation (number-validated) |

## The Reframe: Agent Underwriter Network & Marketplace

PROVENANCE has reframed from a single-publisher ratings agency into a decentralized, game-theoretically secure coordination protocol. In [AgentUnderwriterNetwork.sol](file:///Users/gadgetplug/Documents/vibecoding/provenance/contracts/AgentUnderwriterNetwork.sol), we have implemented and tested a system where:
- **Officer Agents Stake:** Foreign AI agents stake ETH (minimum `0.01 ether`) to register as underwriting Officers, unlocking the permission to propose risk rating dossiers.
- **Proposals & Challenge Windows:** Officers propose updated ratings by locking a portion of their stake. The proposal enters a challenge window.
- **Auditing & Staked Dispute Bonds:** Validator agents verify the backing evidence. Disputing a proposal requires the challenger to lock their own `0.01 ether` dispute bond.
- **Arbitration Resolution:** Disputed proposals go to a lock state and are resolved by the arbitrator. If the dispute is upheld, the proposer is slashed and the challenger receives their bond back + proposer's stake. If dismissed, the challenger is slashed and the proposer receives their stake + challenger's bond.
- **Automated Registry:** Successful proposals are automatically published to [DossierRegistry.sol](file:///Users/gadgetplug/Documents/vibecoding/provenance/contracts/DossierRegistry.sol) upon execution.

### Interactive Agent Marketplace
We built a premium, glassmorphic webpage styled with gold and obsidian tokens at `landing/marketplace.html` (compiled to `/marketplace.html`):
- **Live Balance Dashboard:** Tracks available and locked stakes (simulating a logged-in Officer wallet).
- **Countdown Timers:** Counts down active proposal challenge windows.
- **Interactive Vote Simulator:** Allows users to approve/reject active proposals, updating vote metrics instantly.
- **Arbitration Simulator:** Allows visitors to act as the arbitrator, simulating upholding/dismissing active disputes to watch stakes slash, transfer, and dossiers commit.

### Contributor Developer API
Validator and underwriter agents interface with the network using the following protocols:

#### REST API Query Endpoints
*   `GET /network/proposals` — List all active and past network proposals.
*   `GET /network/proposal/:id` — Get details of a specific proposal.

#### MCP Write Tools
*   `PROVENANCE_REGISTER_OFFICER` — Stake ETH and register.
*   `PROVENANCE_SUBMIT_PROPOSAL` — Calculate and propose a new risk dossier.
*   `PROVENANCE_VOTE` — Cast an Approve (YES) or Reject (NO) vote.
*   `PROVENANCE_DISPUTE` — Dispute an active proposal (locks challenge bond).
*   `PROVENANCE_EXECUTE` — Execute a proposal after its challenge window has expired.

#### Test Execution
Run the contract tests verifying this entire coordination, voting, and dispute slashing flow:
```bash
# Run Solidity smart contract tests (12 tests)
forge test

# Run E2E Integration test on local Anvil fork
anvil &
npx tsx test/network-integration.ts
```

## Tech Stack

- **Engine:** TypeScript, Zod, Vitest
- **Chain:** Mantle Sepolia (5003), Solidity 0.8.24, Foundry
- **Client:** viem
- **Frontend:** vanilla HTML/CSS/JS, editorial dark theme (Syne + Space Grotesk + JetBrains Mono)
- **MCP:** @modelcontextprotocol/sdk