This project is actively developed and will continue to evolve with full Filecoin storage integration and additional settlement capabilities.

Filecoin Agent Layer

A multi-chain agent payment layer using Filecoin for verifiable audit trails.

Overview

This project demonstrates how Filecoin can serve as a persistent audit layer for multi-chain agent payment workflows. It provides a proof-of-concept implementation that captures payment intents, generates content-addressable identifiers (CIDs), and enables settlement verification across different blockchain networks.

Key Features

• Intent Capture: FastAPI-based server for receiving and processing payment intents
• Content Addressing: Filecoin-style CID generation for immutable audit records
• Multi-Chain Settlement: Simulated settlement adapters for Base and Solana
• Audit Verification: Post-settlement verification against stored blueprints

Architecture

┌─────────────┐
│   Agent     │
│   Intent    │
└──────┬──────┘
       │
       v
┌─────────────────┐
│  Intent Server  │
│   (FastAPI)     │
└──────┬──────────┘
       │
       v
┌─────────────────┐     ┌──────────────┐
│    Filecoin     │────>│  Settlement  │
│  Storage (CID)  │     │   Adapters   │
└─────────────────┘     └──────┬───────┘
                               │
                               v
                        ┌──────────────┐
                        │  Audit       │
                        │  Verifier    │
                        └──────────────┘

Project Structure

filecoin-agent-layer/
├── agent_intent_server/    # Intent processing server
├── settlement_adapters/    # Chain-specific settlement logic
├── audit_verifier/         # Verification utilities
├── examples/               # Example intent files
├── tests/                  # Unit tests
├── docs/                   # Documentation
└── data/                   # Runtime data storage

Quick Start

Prerequisites

• Python 3.8+
• pip

Installation

# Clone the repository
git clone <repository-url>
cd filecoin-agent-layer

# Create virtual environment
python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Running the Server

# Start the intent server
uvicorn agent_intent_server.server:app --reload

# Server will be available at http://localhost:8000

Testing the API

# Health check
curl http://localhost:8000/health

# Submit an intent
curl -X POST http://localhost:8000/intent \
  -H "Content-Type: application/json" \
  -d @examples/intent_example.json

The response will include a CID for the stored blueprint:

{
  "cid": "bafk...",
  "status": "stored",
  "version": "0.1.0"
}

Usage

1. Submit Intent

curl -X POST http://localhost:8000/intent \
  -H "Content-Type: application/json" \
  -d @examples/intent_example.json

2. Execute Settlement

Using the returned CID from step 1:

# Base settlement
python settlement_adapters/base_adapter.py <CID>

# Solana settlement
python settlement_adapters/solana_adapter.py <CID>

3. Verify Settlement

# Verify Base settlement
python audit_verifier/verifier.py <CID> base

# Verify Solana settlement
python audit_verifier/verifier.py <CID> solana

Example verification output:

{
  "cid": "bafk...",
  "chain": "base",
  "matches_cid": true,
  "status_ok": true,
  "blueprint_present": true,
  "passed": true
}

Testing

Run the test suite:

pytest

Run with coverage:

pytest --cov=agent_intent_server --cov=settlement_adapters --cov=audit_verifier

Components

Intent Server

Accepts structured escrow intents and creates immutable blueprints stored with Filecoin-style CIDs.

Endpoints:

• GET /health - Health check
• POST /intent - Submit payment intent

Settlement Adapters

Simulate on-chain settlements while embedding Filecoin CIDs for auditability.

Supported Chains:

• Base
• Solana

Audit Verifier

Validates settlement events against stored blueprints to ensure integrity.

Development

Adding a New Chain

1. Create a new adapter in settlement_adapters/
2. Implement the execute_settlement(cid) function
3. Follow the existing pattern for event recording

API Documentation

When the server is running, visit:

• Interactive API docs: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc

Documentation

Additional documentation is available in the docs/ directory:

• Architecture Overview
• CID Lifecycle
• Settlement Flow

Future Enhancements

• Integration with real Filecoin storage providers
• Actual on-chain transactions for Base and Solana
• Enhanced risk management and validation
• Support for additional blockchain networks
• Real-time settlement monitoring
• Advanced audit trail queries

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.