Verifiable Agent Audit Trails: a Filecoin storage backend + public verifier for AI-agent evidence

**Project Name:** Verifiable Agent Audit Trails: a Filecoin storage backend + public verifier for AI-agent evidence

**Proposal Category:** `Developer and data tooling`

**Individual or Entity Name:** Emmanuel Akanji

**Proposer:** `manny-uncharted`

**Project Repo(s):**
- https://github.com/Veridex-Protocol/agents-treasury (evidence layer the code this grant extends)
- A new standalone repo for the public verifier library + CLI will be created under https://github.com/Veridex-Protocol

**(Optional) Filecoin ecosystem affiliations:** Yes, disclosing for transparency. Emmanuel Akanji is a **Protocol Labs Developer Guild (PLDG)** contributor, with work across **Storacha** and **Akave** (Filecoin warm-storage / decentralized-database protocols) and the Python libp2p networking stack. We also applied to **Filecoin ProPGF Batch 3** (not funded; the reviewer suggested exploring smaller-scale alignment, which prompted this Open Grant).

**(Optional) Technical Sponsor:** None yet.

**Do you agree to open source all work you do on behalf of this RFP under the MIT/Apache-2 dual-license?:** Yes

---

# Project Summary

AI agents are beginning to move real money and take consequential actions. Enterprises and regulated teams will not deploy autonomous agents without a **durable, tamper-evident record** of what each agent did and why retained for years and independently verifiable for audits and disputes. Generic object storage and IPFS pinning cannot attest to durability or retention; **Filecoin's verifiable, paid storage can.** This is the gap we close.

Veridex already produces the exact artifact this needs. For every agent action, our runtime emits a cryptographically **signed evidence bundle** the agent's reasoning, the policy verdict, approvals, and the on-chain payment reference. The signing format, deterministic content addressing, three-stage integrity check, and tamper detection exist and pass tests today against an in-memory client (`packages/agents-treasury/src/evidence/FilecoinEvidenceStore.ts`).

This grant funds the **open-source Filecoin backend and public verifier** that make Filecoin the system of record for those bundles: real, retention-locked storage deals built on the **Synapse SDK / Filecoin Warm Storage Service** (already available and testable on Filecoin testnet), each bundle's deal reference anchored to its originating on-chain payment, and a standalone, dependency-light verifier (library + CLI) that lets **anyone** re-check a bundle without Veridex or any proprietary middleware. Our hosted service, relayer, and portals are explicitly **out of scope** – this proposal is the reusable public-good core only.

Importantly, this is not a proof of concept. The storage client and verifier will be engineered to **production-grade standards** from day one: robust error handling, retry logic for deal submission, comprehensive logging, and security best practices. Post-grant, transitioning from testnet to mainnet requires only configuration changes (endpoint, contract address). The result is infrastructure that teams can confidently adopt for real-world, compliance-grade audit trails.

## Impact

The pain point: the single biggest blocker to enterprises adopting autonomous, money-moving agents is liability "prove what your agent did, and that it was authorized, six months later." Today there is no defensible, long-horizon substrate for that proof. Solving it unlocks a class of storage demand that is **non-discretionary (compliance-driven) and recurring (per-action)** precisely the paid, on-chain, real-customer usage the 2026 Filecoin Network Strategy targets. The risk of not getting it right is that this data defaults to centralized object storage, and Filecoin misses a fast-growing, durable, verifiable-by-design workload native to the agent economy.

Why Filecoin specifically (not IPFS or other decentralized storage): the value here is **paid, retention-guaranteed, verifiable storage**, not just content-addressing. Each deployed agent emits a steady stream of small, high-value bundles that must be retained for years and retrievable on demand for disputes. That is a Filecoin storage-deal workload with WORM/retention semantics something pinning cannot attest to. Unlike permanent-storage networks (e.g., Arweave), Filecoin’s programmable, retention-defined deals with built-in WORM and on-chain verifiability provide exactly the compliance-grade audit trail semantics enterprises require, without the uncertainty of indefinite perpetual storage. We build directly on Filecoin Onchain Cloud rails (Synapse SDK / Warm Storage Service) and aggregate small bundles into economically sensible deals.

Success looks like: any Filecoin developer building agent infrastructure can adopt an open client library to write signed evidence to Filecoin under a retention policy, and any third party can independently verify a bundle from public docs and a CLI reproducing the content-integrity and signature checks, with tampered bundles failing. Beyond Veridex, the verifier and storage client are reusable by any team that needs verifiable audit trails on Filecoin (e.g., a DAO governance bot storing verifiable votes).

## Technical Approach

The core flow:

1. **Bundle creation** → a signed evidence object with deterministic content addressing (CID) is produced by the agent runtime.
2. **Client aggregation** → the production `FilecoinStorageClient` batches multiple small bundles (configurable threshold, e.g., 100 bundles or 5 MB window, whichever comes first) into a single deal payload to meet economic deal sizes while preserving per-bundle metadata.
3. **Storage deal** → the aggregated payload is sent to Filecoin via the Synapse SDK / Warm Storage Service, which handles deal-making, deal activation, and the `retentionSeconds` WORM parameter. The client includes **production-grade retry, timeout, and error-recovery logic** so failed deal submissions are handled gracefully.
4. **On-chain anchoring** → the resulting deal ID and CID are written back to the originating payment transaction (or an associated contract event), creating a provable, on-chain link between the business action and its audit record.
5. **Verification** → a third party uses the public verifier CLI to fetch the bundle by reference, re-derive its CID, and check the signature against the agent's on-chain identity; any tampering causes a failure exit code.

All components run on Filecoin testnet during the grant, but the code is written as production infrastructure. Moving to mainnet requires only a configuration swap (endpoint, contract address). The `FilecoinStorageClient` interface insulates the evidence layer from backend changes.

## Outcomes

Final deliverables (all MIT/Apache-2 dual-licensed):

1. **Production-grade Filecoin storage client** for signed evidence bundles, built on the Synapse SDK / Warm Storage Service through our existing injectable `FilecoinStorageClient` interface, with **small-bundle aggregation** (batching multiple bundles into a single deal to hit economic sizes while retaining per-bundle retrievability) and configurable **retention (WORM)** via the existing `retentionSeconds` deal hook. The client will follow production best practices: comprehensive unit/integration tests, structured logging, retry and backoff, and clear error semantics.
2. **On-chain deal ↔ payment-tx anchoring** – each stored bundle's deal reference is provably tied to the action that produced it, written as part of the on-chain transaction/event so the link is independently verifiable.
3. **Public verifier**: a dependency-light **library + `verify` CLI** that retrieves a bundle by reference and re-checks content hash and signature (fails on any mismatch), usable with no Veridex dependency. The CLI accepts `--bundle-cid`, `--signer-address`, and an optional `--gateway` parameter, and outputs a clear `VALID`/`INVALID` message with exit code. All cryptographic operations rely on the same standard signature scheme used by the agent's payment chain (no custom crypto). The verifier will also be built with production-quality error handling and documentation.
4. **Testnet integration suite in CI** and **reproducible developer docs** (publish → retrieve → verify-it-yourself). The docs will include a concrete example that any developer can run in minutes, demonstrating the same workflow that will later be used on mainnet.

How we measure success:
- Open-source code merged and CI green on Filecoin testnet.
- A third party, following only the public docs, stores a test bundle on Filecoin testnet, retrieves it by reference, and reproduces the integrity + signature verification; a tampered bundle fails.
- The verifier CLI runs standalone against a bundle produced by the storage client.

## Data Onboarding

This is a **developer-tooling / verifier** grant delivered on **Filecoin testnet**, so onboarding during the grant is primarily test and integration data – we are building the rails that enable durable onboarding, not running a production data pipeline. We are deliberately conservative here (evidence bundles are ~tens of KB each, so honest figures are modest):

- **Month 1:** < 100 MB CI/integration test bundles on testnet.
- **Month 3:** low single-digit GiB cumulative if early adopters exercise the backend on testnet; predominantly test/synthetic evidence.
- **Month 6:** grows with production/mainnet rollout and agent adoption **post-grant**, and a function of downstream agent deployment rather than a grant deliverable.
- **Month 12:** scales with per-agent bundle volume as deployments grow; not claimed as a within-grant guarantee.

## Adoption, Reach, and Growth Strategies

**Target audience:**
(1) developers building AI-agent and agent-payment infrastructure who need a defensible audit trail;
(2) regulated/enterprise teams that must retain and prove agent actions; and
(3) **any Filecoin app builder** who can reuse the standalone verifier library/CLI for verifiable storage – the tooling is not Veridex-specific. For instance, a DAO governance bot that stores voting proofs on Filecoin could use the same verifier without any Veridex dependency.

**First 10 users:** our own agent deployments, plus design partners currently integrating with Veridex who need audit retention (design-partner-stage, not committed customers), plus contributors in the **FIL-B developer community** and PLDG network we already work in.

**First 100 users:** publish the verifier as a standalone open-source package with a reproducible "verify-it-yourself" guide; write a reference integration another team can fork; and promote through `#fil-builders`, the FIL-B community, and hackathons such as PL Genesis. Because the verifier is dependency-light and Veridex-independent, adoption does not require adopting our whole stack.

## Development Roadmap

Two milestones, ~2.5 months, 2 people (Emmanuel Akanji - engineering lead, ~1.0 FTE; Emmanuel Appah - anchoring design + docs, ~0.3 FTE).

**Milestone 1 - Production Filecoin storage client + deal anchoring (open source).** Replace the in-memory client with a production client on the **Synapse SDK / Warm Storage Service** (testnet‑ready, validated API) that makes and queues real storage deals, aggregates small bundles, and anchors each bundle's CID/deal reference to its originating on-chain payment transaction. Built with production error handling, retries, and thorough tests. Ship a **testnet integration suite in CI**. Roles: Akanji (impl + CI), Appah (anchoring design). ~1.5 months.

**Milestone 2 - Public verifier (library + CLI) + retention/WORM + docs (open source).** Ship a dependency-light verifier as a **library and CLI** (retrieve by reference → re-check content hash → verify signature), implement **retention/WORM** semantics via the `retentionSeconds` deal hook, and publish **reproducible developer docs**. The verifier and client will be ready for mainnet use with config changes only. Roles: Appah (verifier + retention), Akanji (docs + reproduce guide). ~1 month.

## Total Budget Requested

| Milestone # | Description | Deliverables | Completion Date | Funding |
|---|---|---|---|---|
| 1 | Production Filecoin storage client + deal anchoring | Synapse/Warm-Storage client with small-bundle aggregation; on-chain deal ↔ payment-tx anchoring; testnet CI integration suite | «FILL: submission date + ~6 weeks» | $28,000 |
| 2 | Public verifier + retention/WORM + docs | Dependency-light verifier library + `verify` CLI; WORM/retention via `retentionSeconds`; reproducible developer docs | «FILL: M1 + ~4 weeks» | $20,000 |
| | | | **Total** | **$48,000** |

*Funding reflects the heavier engineering effort and external API integration risk in M1 (live storage deals, aggregation logic, and on-chain anchoring). M2 is primarily library/CLI development and documentation.*

## Maintenance and Upgrade Plans

The evidence layer ships as part of Veridex regardless of this grant, so the Filecoin backend and verifier are maintained as a first-class part of our open-source `@veridex/agents-treasury` package. The `FilecoinStorageClient` is an injected interface, so we can track Onchain Cloud / Synapse / Warm Storage changes without breaking the verified core. The verifier is standalone by design (its own repository and npm package) and will accept community issues and PRs independently of Veridex. Transitioning from testnet to mainnet requires only configuration changes (provider endpoint, contract address); the same production-grade code paths are used in both environments.

---

# Team

## Team Members

- Emmanuel Akanji - Founder; protocol lead
- Emmanuel Appah - Co-founder, anchoring design

## Team Member LinkedIn Profiles

- Emmanuel Akanji - https://www.linkedin.com/in/emmanuel-akanji-o
- Emmanuel Appah - https://www.linkedin.com/in/emmanuel-appah-53a5a8207

## Team Website

https://www.veridex.network

## Relevant Experience

PLDG (Protocol Labs Developer Guild) contributors with hands-on Filecoin-stack work: Storacha and Akave (warm storage / decentralized database on Filecoin rails) and the Python libp2p networking stack. Prior Filecoin hackathon experience (two Filecoin hackathon wins). Shipped, verifiable track record: published npm packages `@veridex/sdk`, `@veridex/agents-treasury`, `@veridex/agentic-payments`, `@veridex/agents` and others (`https://www.npmjs.com/org/veridex`). The Filecoin evidence store is already implemented, open-source, and tested (8 passing tests) – this grant productionizes it on Filecoin. Emmanuel Appah: 8+ years TypeScript / systems engineering; led DeFi at Obscura Finance.

## Team code repositories

- https://github.com/Veridex-Protocol/agents-treasury (evidence layer)
- https://github.com/Veridex-Protocol (org - SDKs, contracts, runtime)

---

# Additional Information

- **How did you learn about the Open Grants Program?** Through the Filecoin ProPGF Batch 3 process the reviewer suggested there may be alignment at a smaller scale, which pointed us to Open Grants.
- **Best email for grant discussion:** omoebun52@gmail.com
- **Additional context:** This is deliberately the open-source public-good core, decoupled from our hosted service; completion depends only on merged open-source code and a reproducible testnet demo, not on external-customer conversion. All claims are testnet-scoped; we make no mainnet or production-revenue claims within the grant horizon. However, the codebase itself is built as production infrastructure, so that teams can deploy it to mainnet immediately after the grant with no rewrite.

Start with packages/agents-treasury/src/evidence/FilecoinEvidenceStore.ts and the existing tests to understand the current evidence-store interface and integrity checks. Then map the proposed Synapse SDK/Warm Storage client, aggregation, payment anchoring, verifier CLI, retention, and testnet CI against the proposal milestones. Done means the listed storage, verification, documentation, and integration outcomes are implemented and CI is green.

Written by the indexing model from the issue text.