Merkle Patricia Forestry Service (MPFS)

MPFS is a Cardano-native service for managing verifiable key-value stores using Merkle Patricia Forestry (MPF) data structures on-chain.

Overview

MPFS enables:

• Verifiable Data Storage: Store key-value pairs (facts) with cryptographic proofs of inclusion/exclusion
• On-chain Validation: All modifications are validated by Cardano smart contracts
• Decentralized Knowledge: Build dApps, knowledge bases, and collaborative platforms with immutable history

Architecture

┌─────────────┐     ┌─────────────────┐     ┌────────────────┐
│   Client    │────▶│   MPFS Service  │────▶│    Cardano     │
│  (Wallet)   │     │  (TypeScript)   │     │   Blockchain   │
└─────────────┘     └─────────────────┘     └────────────────┘
                            │
                    ┌───────┴───────┐
                    ▼               ▼
            ┌───────────┐   ┌───────────────┐
            │  Indexer  │   │  Trie Manager │
            │ (Ogmios)  │   │    (MPF)      │
            └───────────┘   └───────────────┘

Quick Start

Using Docker

docker pull ghcr.io/cardano-foundation/mpfs/mpfs:v1.1.0

See the deployment guide for full setup instructions.

From Source

git clone https://github.com/cardano-foundation/mpfs
cd mpfs/off_chain
npm install
npx tsx src/service/signingless/main.ts --port 3000 \
    --provider yaci --yaci-store-host http://localhost:8080 \
    --ogmios-host http://localhost:1337 \
    --database-path ./mpfs.db \
    --since-slot 94898393 \
    --since-block-id ef94934f8eb129ebf07eeaab007b81ecb1bc58b121d19ac0ffe81f928bf56cc

Development with Nix

nix develop

This provides all development tools including:

• Node.js and npm
• Aiken (smart contract language)
• Cardano node and CLI tools
• mkdocs for documentation

Documentation

Full documentation is available at cardano-foundation.github.io/mpfs.

Building Docs Locally

nix develop
mkdocs serve

Then open http://localhost:8000 in your browser.

Project Structure

mpfs/
├── on_chain/           # Aiken smart contracts
│   └── validators/     # Cage validator and types
├── off_chain/          # TypeScript service
│   └── src/
│       ├── service/    # HTTP API (signingless/signingful)
│       ├── transactions/ # Transaction builders
│       ├── indexer/    # Chain event indexer
│       └── trie/       # MPF trie management
├── docs-mkdocs/        # Documentation (mkdocs)
└── flake.nix           # Nix development environment

API

A public preprod instance is available at mpfs.plutimus.com.

See the API Reference for full documentation.

Key Endpoints

Endpoint	Description
GET /tokens	List all MPF tokens
GET /token/{id}	Get token state and requests
GET /token/{id}/facts	Get all facts in a token
GET /transaction/{addr}/boot-token	Create a new token
POST /transaction/{addr}/request-insert/{id}	Request to insert a fact
GET /transaction/{addr}/update-token/{id}	Process pending requests

Dependencies

• Yaci Store - Address to UTxO mapping
• Ogmios - Chain event tracking
• Cardano Node - Blockchain access

Code Tracking

We use Radicle for decentralized code tracking:

rad:zpZ4szHxvnyVyDiy2acfcVEzxza9

See Also

• HAL - Cardano Foundation
• Merkle Patricia Forestry Library
• Cardano Foundation
• About Cardano

License

Apache 2.0