On Ramp Contracts 🚀

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

📚 Table of Contents

• Overview
• Architecture
• Project Structure
• Getting Started
  • Prerequisites
  • Installation Steps
• Deployment Instructions
• Configuration
• Setting up xChain Client
• Usage
• Additional Resources
• Contributing
• License

🌍 Overview

The cross-chain data bridge (aka, onramp contracts) allows applications on one blockchain (source chain) to store and retrieve data on the Filecoin decentralized network. This means that any blockchain can leverage Filecoin's decentralized storage capabilities for:

• Cross-Chain Compatibility: Supports multiple L1 and L2 networks.
• Verifiable Data Storage: Utilizes Filecoin's robust storage network.
• Modular Architecture: Easily extendable to support additional networks and functionalities.

Our onramp contracts act as a bridge between various blockchains (like Linea, Avalanche, and Arbitrum) and Filecoin storage. The framework consists of:

✅ 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, 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.

Getting Started

Prerequisites

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

Installation Steps

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 Instructions

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 linea-sepolia

Other supported networks:

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

🔧 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 linea-sepolia

Running Full Deployment in One Command

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

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

The cross-chain data bridge requires running xChain client to process the storage requests and storages proof between the source chain and Filecoin.

1️⃣ Set Up Forge

forge install

2️⃣ Install & Use Go 1.22.7

gvm install go1.22.7
gvm use go1.22.7

3️⃣ Build OnRamp Tools

cd contract-tools/xchain
go build

4️⃣ Generate Cross-Chain Keys

geth account new --keystore ~/onramp-contracts/xchain_key.json

Configure environment:

export XCHAIN_KEY_PATH=~/onramp-contracts/xchain_key.json/UTC--2024-10-01T21-31-48.090887441Z--your-address
export XCHAIN_PASSPHRASE=password
export XCHAIN_ETH_API="ws://127.0.0.1:1234/rpc/v1"
export MINER_ADDRESS=t01013

Usage

1. Start the xChain server:

./contract-tools/xchain/xchain_server

2. Upload data using the client tool:

./contract-tools/client.bash <file> <token_address> <token_id>

Additional Resources

• Demo Application Repository
• 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.