EarnX Protocol

African Trade Finance on Arbitrum

Closing Africa's $120B trade finance gap through tokenized agricultural invoices on Arbitrum.

EarnX is a DeFi protocol that tokenizes verified African agricultural export invoices on Arbitrum. It connects Nigerian cocoa exporters, Ethiopian coffee growers, and Ghanaian cashew producers with global DeFi liquidity — with gasless onboarding and sub-cent transaction costs.

Live Demo: earnx-arbitrum.vercel.app

Table of Contents

• The Problem

• How It Works

• Architecture

• Smart Contracts

• Deployed Contracts

• Frontend

• Protocol Integrations

• Getting Started

• Testing on Arbitrum Sepolia

• Project Structure

• Market Validation

• Roadmap

• License

The Problem

Africa's SME financing gap stands at $331 billion annually. Trade finance supports only 25% of merchandise trade in ECOWAS countries versus 60-80% globally. A Nigerian cocoa exporter shipping $50,000 in beans waits 60-90 days for payment while local banks charge 15-30% interest — if they approve the loan at all.

80% of African SMEs have zero access to formal financing, yet they represent 90% of businesses and 40-50% of GDP.

How It Works

1. Exporter submits an invoice — gasless via ERC-4337 Paymaster (zero ETH needed)

2. Pyth Network prices the commodity — real-time cocoa/coffee/cashew pricing with confidence intervals

3. Verifier approves the invoice — risk scoring and APR assignment based on commodity volatility

4. DeFi investors fund with USDC — risk-adjusted APR from 8-15%

5. Exporter receives working capital — instant liquidity at sub-cent transaction costs

6. Settlement distributes returns — investors receive principal + yield automatically on-chain

Architecture

┌────────────────────────────────────────────────────────────────┐
│               Frontend (React + Vite + Tailwind)               │
│  Landing | Dashboard | Marketplace | Exporter | Investor | ... │
└────────────────────┬───────────────────────┬───────────────────┘
                     │                       │
          ┌──────────▼──────────┐  ┌────────▼──────────┐
          │  Arbitrum Sepolia    │  │  Pyth Hermes API  │
          │  ┌────────────────┐ │  │  - Coffee/USD     │
          │  │ EarnXProtocol  │ │  │  - Cocoa/USD      │
          │  │ (UUPS Proxy)   │ │  │  - Cotton/USD     │
          │  ├────────────────┤ │  │  - Sugar/USD      │
          │  │ InvoiceNFT     │ │  └───────────────────┘
          │  │ (ERC-721 + SVG)│ │
          │  ├────────────────┤ │  ┌───────────────────┐
          │  │ EarnXVault     │ │  │  IPFS (Pinata)    │
          │  │ (ERC-4626)     │ │  │  Document Storage  │
          │  ├────────────────┤ │  └───────────────────┘
          │  │ EarnXPaymaster │ │
          │  │ (ERC-4337)     │ │
          │  └────────────────┘ │
          │  Native USDC        │
          └─────────────────────┘

Smart Contracts

Key Technical Features

• Pyth Confidence-Based Risk Scoring — Wider price confidence intervals indicate higher commodity volatility, resulting in higher APR for investors. A novel use of Pyth's confidence data.

• UUPS Upgradeable — Protocol can evolve without migrating state.

• On-Chain SVG NFT Metadata — Invoice NFTs render on-chain visualizations without external dependencies.

• ReentrancyGuard + Pausable — Defense-in-depth security model.

• Role-Based Access — EXPORTER_ROLE, VERIFIER_ROLE, UPGRADER_ROLE via OpenZeppelin AccessControl.

Deployed Contracts

Network: Arbitrum Sepolia (Chain ID: 421614)

Frontend

Live at: earnx-arbitrum.vercel.app

Built with React 19, TypeScript, Vite, Tailwind CSS v4, Wagmi v2, and RainbowKit.

Pages

Frontend Features

• Wallet Connection — MetaMask, WalletConnect, Coinbase Wallet, and more via RainbowKit

• On-Chain Event Scanning — Portfolio and history data sourced directly from blockchain events (no subgraph required)

• IPFS Document Upload — Trade documents uploaded to IPFS via Pinata with on-chain hash verification

• Real-Time Pyth Prices — Live commodity price feeds displayed on the dashboard

• Settlement Preview — Exporters see exact repayment amount, yield breakdown, and investor count before settling

• Risk Grading — A-E grades mapped from 0-100 risk scores following RWA marketplace standards

• Responsive — Mobile-optimized with adaptive layouts for all screen sizes

Protocol Integrations

Getting Started

Prerequisites

• Node.js >= 18

• MetaMask or compatible wallet

• Arbitrum Sepolia testnet ETH (faucet)

Smart Contracts

# Clone the repository
git clone https://github.com/big14way/earnxarbitruim.git
cd earnxarbitruim

# Install contract dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your private key and RPC URLs

# Compile contracts
npm run compile

# Deploy to Arbitrum Sepolia
npm run deploy:sepolia

Frontend

# Navigate to frontend
cd frontend

# Install dependencies
npm install

# Configure environment (optional — for IPFS document uploads)
cp .env.example .env
# Edit .env with your Pinata JWT

# Start development server
npm run dev

# Build for production
npm run build

Environment Variables

Root .env (smart contracts):

frontend/.env (optional):

Testing on Arbitrum Sepolia

1. Get testnet ETH — Use the Arbitrum Sepolia faucet

2. Connect wallet — Open the live demo and connect with MetaMask (Chain ID: 421614)

3. Mint test USDC — Use the Faucet page or interact with MockUSDC directly

4. Submit an invoice — Go to the Exporter tab, fill in invoice details, upload documents, and submit

5. Verify the invoice — Switch to Admin tab and verify the invoice (requires VERIFIER_ROLE)

6. Invest in the invoice — Go to Marketplace or Investor tab, approve USDC, and invest

7. Settle the invoice — As the exporter, go to Exporter tab, review the settlement preview, and settle

8. Check portfolio — View investment positions, yields, and P&L in the Portfolio tab

Tip: Use two different wallet addresses (e.g., two MetaMask accounts) to test the full exporter-investor flow and see real USDC movement between participants.

Project Structure

earnx-arbitrum/
├── contracts/
│   ├── EarnXProtocol.sol           # Core protocol (UUPS Proxy)
│   ├── InvoiceNFT.sol              # Invoice tokenization (ERC-721)
│   ├── EarnXVault.sol              # Yield vault (ERC-4626)
│   ├── EarnXPaymaster.sol          # Gas sponsorship (ERC-4337)
│   ├── interfaces/
│   │   └── ISiloRouter.sol         # Silo Finance integration
│   └── mocks/
│       └── MockUSDC.sol            # Test stablecoin
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── layout/             # Navbar, TransactionLog
│   │   │   ├── pages/              # All page components
│   │   │   └── ui/                 # Card, StatCard, StatusBadge, DocumentUpload
│   │   ├── config/                 # ABIs, contract addresses, wagmi config
│   │   ├── hooks/                  # useTransactionLog, useTransactionHistory
│   │   ├── lib/                    # Formatting, gas estimation, IPFS, Pyth
│   │   ├── App.tsx                 # Main app with tab routing
│   │   └── main.tsx                # Entry point
│   ├── vercel.json                 # Vercel SPA config
│   └── package.json
├── scripts/
│   └── deploy.js                   # Arbitrum deployment script
├── hardhat.config.js               # Solidity 0.8.24, optimizer enabled
├── package.json
└── README.md

Market Validation

Roadmap

• Smart contract development and deployment (Arbitrum Sepolia)

• Frontend with wallet integration (RainbowKit + Wagmi)

• Pyth Network oracle integration for commodity pricing

• IPFS document upload and on-chain verification

• RWA marketplace with risk grading and yield previews

• Investor portfolio with on-chain event scanning

• Settlement preview with exact repayment calculation

• Production deployment on Vercel

• Arbitrum Foundation Grant application

• STEP 2.0 credit strategy inclusion

• Subgraph deployment for indexed event queries

• Mainnet deployment with first Nigerian cocoa exporter pilot

License

MIT

Built for the founders, farmers, and financiers closing Africa's $120B trade finance gap.

Powered by Arbitrum | Priced by Pyth Network | Lent by Silo Finance | Settled in USDC