Provenance

Demo

About

Provenance is a research-stage application on Ethereum Sepolia that runs a fund whose capital allocation rewards deterministic, recomputable trading process rather than raw profit and loss. It links four concerns into one pipeline. Identity and authority. ENSv2 names identify each trading agent and control who is authorized to trade. Execution flows through Aqua and a custom SwapVM opcode that check authority and trade limits at fill time. Revoking an agent's authority blocks its next fill, so permissioning is enforced on-chain rather than in application logic. Evidence and scoring. A Substreams oracle indexes public execution events and converts them into reward vectors. Bounded Rust predicates score hedge efficacy, slippage, mandate respect, and price freshness from that indexed evidence, so a third party can recompute an agent's score from public chain data rather than trusting a reported number. Allocation. An allocator reallocates capital toward agents with strong verified process using structured LLM intents, a relative-ranking judge, discounted EXP3-style bandit allocation, drift-based retirement, and drawdown controls. Presentation and reproducibility. A Next.js frontend shows fund equity, verified process scores, agent allocations, reward history, and hire/promote/retire activity, with a cursor-revealed frosted hero, Framer Motion transitions, and static fallbacks for reduced motion and missing WebGL. A replay panel compares two runs over the same block range and shows payload previews and hashes when live replay evidence exists. Structure and status. The repo is a pnpm workspace on Node 22 with packages for backend, frontend, ENS, execution, oracle, config, shared code, and a subgraph, plus a Foundry Solidity contracts package including AuthoritySwapVMRouter. A demo mode runs the full dashboard with synthetic, clearly labeled rewards and no blockchain transactions, requiring no RPC credentials, funded wallet, LLM key, Postgres, Foundry, or Rust. Live Sepolia deployment, hosted-provider verification, package publication, and recorded reproducibility evidence still require external setup and remain the main gaps between the demo and a fully live system.

How it's made

Provenance is a pnpm workspace on Node 22 split into packages for contracts, backend, frontend, oracle, ENS, execution, config, shared code, and a subgraph. The smart contracts are Solidity 0.8.30 built and tested with Foundry, and include an ENSv2Authority that reads agent authorization from ENS names, an AgentAuthorityManager and adapter, a FundIdentityRegistry, an AgentDesk, PriceMarks, a ProgramFactory, and an AuthoritySwapVMRouter that wraps a custom SwapVM opcode so authority and trade limits are checked at fill time. Execution builds on 1inch tooling — the Aqua SDK, SwapVM SDK, and solidity-utils — with OpenZeppelin contracts underneath. The reward oracle is a Rust crate compiled to a wasm32 Substreams module using the substreams and substreams-ethereum crates, prost for protobuf, and sha3 for hashing, so it indexes public execution events into deterministic reward vectors that anyone can recompute. A companion subgraph (schema plus manifest, built with the Graph CLI) exposes indexed data for the dashboard. The backend is plain TypeScript run through tsx on a raw node:http server, with modules for the agent registry, the EXP3-style allocator, the LLM policy, runtime, a store, and a stream module that pushes updates over Server-Sent Events (text/event-stream). The policy layer calls any OpenAI-compatible chat-completions endpoint through configurable LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL env vars rather than hardcoding a provider, and demo mode substitutes synthetic labeled rewards so nothing hits the chain or an LLM. The frontend is Next.js 16 with React 19, Tailwind v4, Framer Motion, and wallet connectivity through wagmi, viem, and RainbowKit, with TanStack Query for data. Deployment config is present for both Vercel and Render (render.yaml), and Postgres was dropped in favor of a local file-based SQLite database to keep the demo dependency-free. The whole thing runs end to end locally without RPC credentials, a funded wallet, an LLM key, Foundry, or Rust — those are only needed to go live on Sepolia.