Documentation

Technical overview and quick start for the Data Provenance toolkit.

How It Works

Data Provenance stores cryptographic proofs of data existence, ownership, and lineage on Swarm with optional on-chain anchoring on Base Sepolia (testnet).

Core Concepts

Provenance Receipt — SHA-256 hash + metadata + timestamp, stored on Swarm. Your file never leaves the browser — only the hash is stored.

Gateway Notarization — The provenance gateway timestamps and cryptographically signs the receipt (EIP-191).

On-Chain Anchor — Hash registered on the DataProvenance smart contract (Base Sepolia). Permanent, blockchain-level immutability. Optionally links to the Swarm storage reference.

Architecture

The toolkit consists of multiple components working together:

Browser (dataprovenance.app)
  │ SHA-256 hash (client-side)
  ▼
SDK (@datafund/swarm-provenance)
  │
  ├──▶ Gateway (provenance-gateway.datafund.io)
  │      ├─ Store to Swarm (with notary signing)
  │      └─ Stamp management
  │
  └──▶ Blockchain (Base Sepolia)
         └─ DataProvenance smart contract
            (hash anchoring + storageRef linking)

Full architecture and component documentation: github.com/datafund/provenance →

Gateway REST API

Base URL: provenance-gateway.datafund.io/api/v1/

These are endpoints on the Provenance Gateway, not on this app. The app calls these via the SDK.

POST/api/v1/data/

Upload data to Swarm. Supports notary signing via ?sign=notary.

GET/api/v1/data/{reference}

Download data by Swarm reference.

POST/api/v1/stamps/

Purchase postage stamp for storage.

GET/api/v1/stamps/

List available stamps with TTL and utilization.

GET/api/v1/notary/info

Check notary signing availability.

Full API docs: Gateway OpenAPI →

MCP Server

15 tools for AI agents (Claude, Cursor, any MCP-compatible agent).

// claude_desktop_config.json
{
  "mcpServers": {
    "data-provenance": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "ghcr.io/datafund/swarm-provenance-mcp"]
    }
  }
}

Full docs: github.com/datafund/swarm_provenance_MCP →

TypeScript SDK

Client library for browser and Node.js. Handles hashing, upload, download, chain anchoring.

npm install @datafund/swarm-provenance

import { ProvenanceClient, sha256Hex } from '@datafund/swarm-provenance';
import { ChainClient, fromEip1193Provider } from '@datafund/swarm-provenance/chain';

const client = new ProvenanceClient({ payment: 'free' });
const hash = sha256Hex(fileBytes);
const result = await client.upload(proof, { raw: true, sign: 'notary' });

Full docs: github.com/datafund/swarm_provenance_SDK →

Python CLI

Command-line tool for uploading, downloading, and managing provenance files.

git clone https://github.com/datafund/swarm_provenance_CLI
cd swarm_provenance_CLI
pip install -e .

Note: pip package not yet published. Install from source.

Full docs: github.com/datafund/swarm_provenance_CLI →

Embeddable <script> tag for content verification badges. See the widget page for preview and documentation.

Smart Contracts

All contracts are deployed on Base Sepolia (testnet). Source: github.com/datafund/ConsentsBasedDataProvenance →

Current (V4)

Contract	Network	Address	Features
DataProvenance	Base Sepolia	`0x3945aDfd5Df9ab2F5cB4Ca0eb3D4384CC3650322`	storageRef + setStorageRef

Previous versions

Version	Contract	Network	Address	Notes
V3	DataProvenance	Base Sepolia	`0xb309dDe00819668ac74075813108659d4332D2cC`	storageRef without setStorageRef
V2	DataProvenance	Base Sepolia	`0xD4a724CD7f5C4458cD2d884C2af6f011aC3Af80a`	Pre-storageRef
V1	DataProvenance	Base Sepolia	`0x9a3c6F47B69211F05891CCb7aD33596290b9fE64`	Standalone, pre-TransformationLink

SWIP Spec

The Swarm-Based Data Provenance Framework is specified as a SWIP (Swarm Improvement Proposal).

SWIP-37: Swarm-Based Data Provenance Framework →