🚀 CrossChain Data Bridge

Bringing decentralized storage to every blockchain! This project enables dApps to store data on Filecoin from multiple L1/L2 networks using cross-chain data onramp smart contracts.

📚 Table of Contents

• Overview
  • Architecture
• Getting Started
  • Installation
  • Deployment
  • Configuration
• Setting up xChain Client
  • Usage
• Additional Resources
• Contributing
• License

🌍Overview

The CrossChain Data Bridge(aka, onramp contracts) enables applications on various blockchains (source chains) to store and retrieve data directly on the Filecoin decentralized storage network.

Features

• ⚡ Cross-Chain Compatibility – Supports multiple L1 & L2 networks.
• 🔐 Verifiable Storage – Leverages Filecoin's decentralized storage with built-in verification.
• 🧩 Modular Design – Easily extendable to integrate additional blockchains and components.

Our contracts act as a bridge between source chains (e.g., Linea, Avalanche, Arbitrum) and Filecoin.

• Source Chains (L1/L2 networks)

  • OnRampContract – Handles cross-chain storage requests & verification, and user payments.
  • AxelarBridge – Bridges messages via Axelar

• Filecoin (Storage Destination)

  • DealClientAxl – Receives deal notification from Filecoin builtIn actor, sends proof back to source chain.

Architecture

The cross-chain data bridge works through two main components deployed across chains:

1. Onramp Contracts:

   • Source Chain Contracts: Onramp.sol & Oracle.sol
   • Destination Chain Contract (Filecoin): Prover.sol

2. xChain Client: Monitoring storage requests from the source chain, aggregating data, and facilitating deal-making with storage providers or deal engines.

You can refer to a dataBridgeDemo to learn how to interact with onramp contract to onboard data from other L1 to Filecoin.

🚀 Getting Started

Prerequisites

• Node.js and npm installed
• Go 1.22.7 or later
• Access to test tokens for your chosen source chain
• Test FIL for Filecoin Calibration network

---

Installation

1️⃣ Clone & Install Dependencies

git clone https://github.com/FIL-Builders/onramp-contracts.git
cd onramp-contracts
npm install --force

2️⃣ Configure Environment Variables

• Copy .env.example to .env
• Set the private key of your deployer wallet:

DEPLOYER_PRIVATE_KEY=your-private-key
NETWORK=testnet   # Change to "mainnet" if deploying to mainnet

3️⃣ Compile Smart Contracts

npx hardhat compile

---

Deployment

⚠️ Ensure you have sufficient test tokens on both chains before deploying.

Step 1: Deploy Filecoin Contracts

Deploys the DealClientAxl contract on Filecoin to handle storage transactions.

npx hardhat deploy --tags Filecoin --network filecoin

Step 2: Deploy Source Chain Contracts

Deploys OnRampContract & AxelarBridge on your chosen L1/L2 source chain.

Example for Linea:

npx hardhat deploy --tags SourceChain --network avalanche

Other supported networks:

npx hardhat deploy --tags SourceChain --network arbitrum-sepolia
npx hardhat deploy --tags SourceChain --network linea-sepolia

---

Configuration

Step 3: Wire Filecoin with Source Chains

Automatically detects all deployed source chains and configures DealClientAxl:

npx hardhat deploy --tags ConfigFilecoin --network filecoin

Step 4: Configure Source Chains

Sets up cross-chain messaging:

npx hardhat deploy --tags ConfigSourceChain --network avalanche

Running Full Deployment in One Command

npx hardhat deploy --tags Filecoin --network filecoin && \
npx hardhat deploy --tags SourceChain --network avalanche && \
npx hardhat deploy --tags ConfigFilecoin --network filecoin && \
npx hardhat deploy --tags ConfigSourceChain --network avalanche

🛠 Setting Up the Off-Chain Components (xChain Client)

The bridge requires running the xChain client to process storage requests and proofs between chains.

👉 Follow the installation guide to build and run it.

Usage

1️⃣ Start the xChain server:

./xchainClient daemon --config ./config/config.json --chain avalanche --buffer-service --aggregation-service

2️⃣ Upload data using the client tool:

./xchainclient client offer-file --chain avalanche --config ./config/config.json <file_path> <payment-addr> <payment-amount>

3️⃣ Check deal status:

./xchainClient client dealStatus <cid> <offerId>

📖 Additional Resources

• Under the Hood: Architecture and Prototype of Cross-Chain Data Storage
• Demo app on Avalanche
• xChain Client Documentation
• Shashank's Guide
• Filecoin Deals Repo

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.