Skip to content

shreyas-sovani/Alpha-Foundry

BranchesTags

Repository files navigation

Alpha Foundry

Token-gated arbitrage intelligence. Encrypted on IPFS. Pay-per-decrypt.

Live App Sepolia Lighthouse

Launch App → · Demo Video · Contracts · Get Tokens

Demo

Watch the demo

Full walkthrough: claiming tokens, connecting wallet, burning DADC, decrypting live arbitrage data.

What This Does

You're a trader looking for arbitrage opportunities across DEX pools. The data is valuable — you don't want bots scraping it for free.

Alpha Foundry solves this by building an encrypted data pipeline where every access costs real tokens:

  1. Monitors DEX swaps on Ethereum mainnet (Uniswap V3 USDC/WETH pool via Blockscout API)
  2. Detects price deltas that signal arbitrage opportunities using a 24-hour rolling window
  3. Encrypts everything using Lighthouse's native Kavach encryption (threshold BLS cryptography)
  4. Gates access with ERC20 tokens — Lighthouse checks balanceOf(wallet) >= 1 DADC before serving any decryption key
  5. Burns tokens on every unlock — 1 DADC transferred to 0xdead before each decrypt, destroyed permanently

Think of it as a Bloomberg Terminal for on-chain arbitrage data, but encrypted on IPFS and unlocked with crypto tokens. 100 tokens = exactly 100 uses, then you need more.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      User Browser                            │
│  ┌────────────────────────────────────────────────────────┐  │
│  │           Next.js Frontend (Vercel)                    │  │
│  │  • Connect MetaMask wallet                             │  │
│  │  • Check DADC balance → show "X decrypts available"    │  │
│  │  • Burn 1 DADC → transfer to 0xdead                    │  │
│  │  • Sign auth message → request decryption key          │  │
│  │  • Download + decrypt JSONL locally                    │  │
│  │  • Display arbitrage data with analytics               │  │
│  └───────────┬────────────────────────────────────────────┘  │
└──────────────┼───────────────────────────────────────────────┘
               │
               ├──────────► Sepolia Testnet
               │             ├── DataCoin.balanceOf() — access check
               │             ├── DataCoin.transfer(0xdead, 1e18) — burn
               │             └── Faucet.claimTokens() — get 100 DADC
               │
               ├──────────► Lighthouse Storage
               │             ├── getAuthMessage() → sign with wallet
               │             ├── fetchEncryptionKey() → verify ERC20 balance
               │             ├── decryptFile() → serve encrypted CID
               │             └── Key shards distributed across 5 nodes
               │
┌──────────────┼───────────────────────────────────────────────┐
│              ▼                                                │
│      Python Worker (Railway)                                  │
│  ┌─────────────────────────────────────────────────────┐     │
│  │  1. Poll Blockscout REST API (Uniswap V3 swaps)     │     │
│  │  2. Normalize amounts (token decimals, USD est.)     │     │
│  │  3. Enrich with analytics (delta vs MA, MEV flags)   │     │
│  │  4. Compute rolling 24h price window (min/max/mean)  │     │
│  │  5. Package as JSONL with timestamps                 │     │
│  │  6. Encrypt via Lighthouse SDK (Kavach)              │     │
│  │  7. Apply ERC20 access condition (DADC >= 1)         │     │
│  │  8. Upload to IPFS (distributed key shards)          │     │
│  │  9. Auto-cleanup old files (keep only latest)        │     │
│  │  10. Serve metadata via HTTP (/metadata, /health)    │     │
│  └─────────────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────────┘
               │
               ├──────────► Ethereum Mainnet RPC
               │             └── Uniswap V3 swap events
               │
               └──────────► Lighthouse API
                             ├── uploadEncrypted()
                             └── applyAccessCondition()

How It Works (Step by Step)

Backend Pipeline

The Python worker (apps/worker/run.py) runs a continuous loop every 15 seconds:

  1. Fetch swaps — BlockscoutRESTClient queries the Blockscout API for recent Uniswap V3 swap events on the target pool, paginating up to 5 pages per cycle
  2. Deduplicate — DedupeTracker keeps a set of seen transaction hashes across restarts (persisted to state/dedupe.json)
  3. Normalize — transform.py decodes raw swap amounts using token decimals, resolves pool tokens from hardcoded pool mappings
  4. Estimate USD values — Stablecoin amounts used directly; WETH amounts multiplied by a reference ETH price (Chainlink feed or fallback)
  5. Enrich with analytics — Each row gets: delta vs 5-swap moving average, price impact vs rolling median, MEV warning flags (>2 stddev deviation), emoji markers for notable swaps
  6. Rolling price buffer — RollingPriceBuffer maintains a 24-hour sliding window per token pair, calculating min/max/mean prices. Persisted to state/price_buffer.json
  7. Write JSONL — Enriched rows written to a timestamped .jsonl file with schema version headers
  8. Encrypt + upload — LighthouseNativeEncryption runs Lighthouse's uploadEncrypted() via Node.js subprocess, then applies an ERC20 access condition: balanceOf(userAddress) >= 1 DADC on Sepolia chain ID 11155111
  9. Auto-cleanup — LighthouseCleanup lists all uploaded files, deletes everything except the latest CID and permanently protected CIDs. Uses Lighthouse CLI for reliable deletion
  10. Serve metadata — ReadOnlyHTTPServer exposes /metadata (latest CID, row count, freshness) and /health on port 8787

Frontend Flow

The Next.js app (frontend/app/page.tsx) implements the full unlock flow:

  1. Connect wallet — ethers.BrowserProvider connects to MetaMask, reads chain ID, checks if on Sepolia (11155111)
  2. Check balance — Calls DataCoin.balanceOf(address) and Faucet.hasClaimed(address) to show current state
  3. Claim tokens (if needed) — Calls Faucet.claimTokens() to mint 100 DADC (one-time per address)
  4. Unlock & Decrypt — A 4-step process:
    • Step 1: Burn 1 DADC — DataCoin.transfer(0xdead, 1e18), wait for confirmation
    • Step 2: Get auth message — lighthouse.getAuthMessage(address)
    • Step 3: Sign message — signer.signMessage(message) via MetaMask popup
    • Step 4: Fetch key + decrypt — lighthouse.fetchEncryptionKey(cid, address, signature) then lighthouse.decryptFile(cid, key). Lighthouse internally verifies that the wallet's DADC balance (post-burn) is still ≥ 1
  5. Display data — Decrypted JSONL parsed and rendered with arbitrage analytics, swap details, price impact indicators

Why This Token Model Works

  • Lighthouse checks balanceOf(userAddress) >= 1 DADC on every decrypt attempt — this is enforced at the encryption layer, not by the frontend
  • The frontend burns 1 DADC before requesting the decryption key, so the user's balance drops
  • When balance reaches 0, Lighthouse denies the key automatically — no backend enforcement needed
  • Tokens are sent to 0x000000000000000000000000000000000000dEaD — they're gone forever
  • This creates genuine deflationary economics: fixed supply, decreasing on every use

Smart Contracts (Sepolia Testnet)

DataCoin (DADC)

Property Value
Address 0x8d302FfB73134235EBaD1B9Cd9C202d14f906FeC
Standard ERC20
Symbol DADC
Decimals 18
Total Supply 100,000,000,000 DADC
Created via 1MB.io factory with 10,000 LSDC lock
Creation Tx 0x0bf7c4da...

DataCoinFaucet

Property Value
Address 0xB0864079e5A5f898Da37ffF6c8bce762A2eD35BB
Function claimTokens() → mints 100 DADC to caller
Limit One claim per address (reverts with AlreadyClaimed on repeat)
Cooldown 1 hour (currently only single claim enforced)

The faucet contract calls dataCoin.mint(msg.sender, 100e18) and tracks claims via totalClaimed mapping. Source: contracts/DataCoinFaucet.sol.

Tech Stack

Layer Technology Role
Frontend Next.js 14 · ethers.js v6 · Tailwind · SWR Wallet connection, token burning, Lighthouse decrypt, live metadata polling
Encryption Lighthouse SDK (@lighthouse-web3/sdk) Kavach encryption with BLS threshold cryptography, ERC20 access conditions
Backend Python 3.12 · aiohttp · pydantic-settings Async worker loop with typed configuration
Blockchain Data Blockscout REST API · httpx · tenacity Swap event ingestion with retry/backoff, MCP-compatible client
Price Oracle Chainlink price feeds (fallback: swap inference) ETH/USD reference price for USD value estimation
Smart Contracts Solidity 0.8.20 ERC20 token (DataCoin) + Faucet on Sepolia
State JSON files (checkpointed) Block cursors, deduplication sets, rolling price buffers — all survive restarts
Infra Vercel (frontend) · Railway (backend via nixpacks) Auto-deploy from main branch

Project Structure

├── apps/
│   └── worker/                              # Python backend (Railway)
│       ├── run.py                           # Main loop: poll → transform → enrich → encrypt → upload → cleanup
│       ├── lighthouse_native_encryption.py  # Kavach encryption + ERC20 access conditions via Node.js subprocess
│       ├── lighthouse_cleanup.py            # Auto-delete old Lighthouse files, protect latest + permanent CIDs
│       ├── blockscout_client.py             # MCP-first async client with session management
│       ├── blockscout_rest.py               # REST fallback client with pagination + retry
│       ├── transform.py                     # Swap normalization, token resolution, amount decoding
│       ├── state.py                         # DedupeTracker, RollingPriceBuffer, PreviewStateTracker
│       ├── chainlink_price.py               # ETH/USD price feed (Chainlink + swap inference fallback)
│       ├── http_server.py                   # /metadata and /health endpoints (port 8787)
│       ├── settings.py                      # Pydantic settings from env vars (poll interval, window size, etc.)
│       └── requirements.txt
│
├── frontend/                                # Next.js app (Vercel)
│   ├── app/
│   │   ├── page.tsx                         # Full unlock flow: connect → claim → burn → sign → decrypt → display
│   │   ├── layout.tsx                       # Root layout with metadata
│   │   └── globals.css                      # Tailwind base styles
│   ├── types/
│   │   └── window.d.ts                      # MetaMask ethereum provider types
│   ├── next.config.js
│   ├── tailwind.config.js
│   └── package.json
│
├── contracts/
│   └── DataCoinFaucet.sol                   # One-time claim faucet (100 DADC per wallet)
│
├── scripts/
│   ├── createDEXArbDataCoin.js              # 1MB.io factory token creation
│   ├── deployFaucet.js                      # Faucet deployment script
│   ├── mintTokens.js                        # Manual token minting
│   ├── testFaucet.js                        # Faucet integration test
│   ├── lighthouse_upload.py                 # Standalone upload test
│   ├── verify_lighthouse_protection.py      # Access control verification
│   └── verify_demo.py                       # End-to-end demo data generator
│
├── infra/
│   └── autoscout/                           # Block explorer configuration
│
├── Dockerfile                               # Container build
├── requirements.txt                         # Python dependencies
├── package.json                             # Root JS dependencies (token scripts)
└── metadata.json                            # Token metadata (IPFS-pinned)

Run Locally

Prerequisites

  • Python 3.12+
  • Node.js 18+ (required for Lighthouse CLI)
  • MetaMask wallet on Sepolia testnet
  • Lighthouse API key (files.lighthouse.storage)

Backend (Worker)

cd apps/worker
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
npm install -g @lighthouse-web3/sdk

# Required env vars
export BLOCKSCOUT_MCP_BASE="https://eth-sepolia.blockscout.com/api/v2"
export CHAIN_ID=11155111
export LIGHTHOUSE_API_KEY="your_key"
export LIGHTHOUSE_WALLET_PRIVATE_KEY="0x..."
export DATACOIN_CONTRACT_ADDRESS="0x8d302FfB73134235EBaD1B9Cd9C202d14f906FeC"

python run.py

Expected output:

✓ Blockscout REST client initialized
✓ Lighthouse encryption configured (wallet: 0x...)
✓ HTTP server started on http://0.0.0.0:8787
✓ Fetched 47 swaps from Uniswap V3 USDC/WETH
✓ Enriched 47 rows (3 MEV warnings, 12 new)
✓ Lighthouse upload successful: QmXXX...
✓ Access condition applied: DADC >= 1 on chain 11155111
✓ Auto-cleanup: deleted 3 old files, 1 remaining

Frontend

cd frontend
npm install

export NEXT_PUBLIC_DATACOIN_ADDRESS="0x8d302FfB73134235EBaD1B9Cd9C202d14f906FeC"
export NEXT_PUBLIC_FAUCET_ADDRESS="0xB0864079e5A5f898Da37ffF6c8bce762A2eD35BB"
export NEXT_PUBLIC_CHAIN_ID=11155111
export NEXT_PUBLIC_METADATA_API="http://localhost:8787"

npm run dev
# → http://localhost:3000

Deploy

Backend → Railway

  1. Connect repo to Railway
  2. Set environment variables: 
    BLOCKSCOUT_MCP_BASE=https://eth-sepolia.blockscout.com/api/v2
CHAIN_ID=11155111
LIGHTHOUSE_API_KEY=...
LIGHTHOUSE_WALLET_PRIVATE_KEY=0x...
DATACOIN_CONTRACT_ADDRESS=0x8d302FfB73134235EBaD1B9Cd9C202d14f906FeC
  3. Deploy — Railway auto-detects via nixpacks
  4. Verify — check logs for ✅ Lighthouse upload successful

Frontend → Vercel

  1. Connect repo to Vercel
  2. Set NEXT_PUBLIC_* environment variables
  3. Deploy — auto-deploys from main
  4. Live at alpha-foundry.vercel.app

Configuration Reference

Key settings in apps/worker/settings.py (all via env vars):

Variable Default Description
WORKER_POLL_SECONDS 15 Seconds between swap fetch cycles
WINDOW_MINUTES 2 Lookback window for recent swaps
BLOCK_LOOKBACK 100 Max blocks to scan per cycle
MAX_PAGES_PER_CYCLE 5 Pagination limit per Blockscout request
PREVIEW_ROWS 8 Rows included in preview metadata
ROLLING_WINDOW_SIZE 1000 Max rows in the rolling JSONL file
REFERENCE_ETH_PRICE_USD 2500.0 Fallback ETH price if Chainlink unavailable

Built With

Lighthouse · 1MB.io · Blockscout · Chainlink · Railway · Vercel · ethers.js

License

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

About

Alpha-Foundry 🏆 winner ETHGlobal's ETHOnline - Lighthouse partner track

alpha-foundry.vercel.app

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages