Privacy-preserving audit trails for governed AI agents.

TrustTrace is a hackathon prototype that captures AI tool-use activity, turns the compliance-relevant parts into verifiable proof material, anchors a compact commitment on a Midnight localnet contract, and presents different disclosure views for chat users, enterprise admins, and auditors.

The core idea is simple: auditors should be able to verify that an AI action followed policy without seeing the private prompt, user identity, account metadata, or raw model output.

• A role-based React app for chat users, enterprise admins, and auditors.
• A local Node API that turns chat activity into trace records.
• Merkle disclosure packages for auditor and enterprise views.
• A Compact proofvault contract that stores the latest committed audit root on Midnight localnet.
• Live verification steps that recompute disclosed-field hashes, verify Merkle paths, compare the committed root, and read the Midnight ledger state.

This is a demo implementation. It is designed to show the privacy and verification workflow, not to be a production compliance system.

TrustTrace
|-- frontend/              React + TypeScript + Vite app
|-- scripts/               Node API, proof helpers, deploy/commit scripts
|   |-- src/api/           HTTP handlers and disclosure views
|   |-- src/proof/         Merkle and trace-proof utilities
|   `-- src/generated/     Synced Compact contract bindings
|-- contract/              Midnight Compact proofvault contract
|   `-- src/proofvault.compact
|-- DEMO_RUNBOOK.md        End-to-end local demo instructions
`-- MIDNIGHT_SETUP.md      Midnight/localnet setup notes

• Node.js 20+
• npm
• Midnight Compact toolchain for contract compilation
• midnight-local-dev for the full chain-backed demo
• A funded localnet wallet seed for deploys and commits

If you only want to inspect the frontend, Node and npm are enough.

The frontend can run without deploying the contract or API. This is the fastest way to inspect the interface. Chain-backed proof creation requires the full local demo below.

cd frontend
npm install
npm run dev

Open the Vite URL shown in the terminal, usually:

http://127.0.0.1:5173/

Available app flows:

• Chat user: governed chat with a proof panel.
• Enterprise admin: trace investigation and operational detail views.
• Auditor: compliance disclosure and verification workflow.

The full demo requires Midnight localnet, a deployed proofvault contract, the TrustTrace API, and the frontend.

Run each snippet in this section from the repository root unless the step says otherwise.

In a separate terminal:

git clone https://github.com/midnightntwrk/midnight-local-dev.git
cd midnight-local-dev
npm install
npm start

Expected local services:

node:         http://127.0.0.1:9944
indexer:      http://127.0.0.1:8088/api/v4/graphql
proof server: http://127.0.0.1:6300

Create scripts/.env:

WALLET_SEED=<valid 24-word BIP39 mnemonic or hex seed>

Then prepare the local account file:

cd scripts
npm install
npm run write-local-accounts
npm run get-address

Use midnight-local-dev option 1 to fund the account from scripts/accounts.local.json.

cd contract
npm install
npm run compile
npm run build

cd ../scripts
npm run deploy

This writes scripts/deployment.json, which the API and commit scripts use.

cd scripts
npm run api

The API listens on:

http://127.0.0.1:8787

Optional health check:

curl http://127.0.0.1:8787/health

Create frontend/.env.local:

VITE_TRUSTTRACE_API_URL=http://127.0.0.1:8787

Then run:

cd frontend
npm install
npm run dev

The demo API is implemented with Node's built-in HTTP server.

GET  /health
POST /api/chat
GET  /api/traces
GET  /api/traces/:traceId?view=auditor
GET  /api/traces/:traceId?view=enterprise
GET  /api/auditor/traces/:traceId/verify-stream

Generated traces are stored locally in scripts/data/traces.json. That directory is ignored by git.

Frontend:

cd frontend
npm run dev
npm run build
npm run lint

Contract:

cd contract
npm run compile
npm run build

Scripts/API:

cd scripts
npm run get-address
npm run deploy
npm run commit
npm run proof-demo
npm run api
npm run build

TrustTrace separates private trace data from public proof material.

1. The chat flow creates a trace with private fields, policy fields, and chain metadata.
2. Disclosure packages reveal only the fields allowed for the current role.
3. Each revealed field includes a salt, leaf hash, and Merkle proof.
4. The auditor verifier recomputes the disclosed leaves and root locally.
5. The API compares that root against the root committed through the proofvault contract.
6. Private values remain off-chain.

The Compact contract is intentionally small:

commit(Bytes<160>) -> persistentHash payload -> vaultRoot
currentRoot()      -> latest root
updateCount()      -> number of commits

For the polished end-to-end flow, follow DEMO_RUNBOOK.md. The short version:

1. Start localnet.
2. Fund the local wallet.
3. Compile and deploy contract/src/proofvault.compact.
4. Start the API.
5. Start the frontend.
6. Create a chat trace.
7. Open the auditor view and run proof verification.
8. Compare the auditor and enterprise views for the same trace.

If PowerShell blocks npm.ps1, run commands with npm.cmd:

npm.cmd run build

If commits fail with missing wallet or deployment errors:

• Confirm scripts/.env contains WALLET_SEED.
• Confirm scripts/deployment.json exists.
• Confirm the wallet was funded through midnight-local-dev option 1.
• Confirm localnet services are still running on ports 9944, 8088, and 6300.

If the frontend only shows seed traces, the API is down or has no generated traces yet. Start npm run api, create one chat trace, then refresh the auditor or enterprise page.

TrustTrace is a prototype for demonstrating privacy-preserving AI governance. The current implementation uses local files for trace storage and a local Midnight deployment for proof anchoring.

No production database, hosted backend, authentication provider, or persistent enterprise key management is included yet.