Skip to content

MAGICBLOCK_INTEGRATION.md

Latest commit

 

History

History
267 lines (192 loc) · 8.31 KB

MAGICBLOCK_INTEGRATION.md

File metadata and controls

267 lines (192 loc) · 8.31 KB
Raw

MagicBlock Ephemeral Rollup Integration

Overview

GitWork integrates MagicBlock Ephemeral Rollups to provide instant bounty claims on Solana. When contributors claim their rewards, they receive payment in <500ms instead of 3-15 seconds, creating a Web2-like instant payment experience on Web3 infrastructure.

Key Achievement: 6-30x faster claim times with automatic fallback to base layer for guaranteed reliability.

What is MagicBlock?

MagicBlock is an ephemeral rollup solution for Solana that enables:

  • ⚡ Ultra-fast transactions: Sub-second finality
  • 💰 Lower costs: Minimal transaction fees
  • 🔌 Seamless integration: Works with existing Solana infrastructure
  • 🔄 Automatic settlement: Periodic commits to Solana base layer

Why We Chose MagicBlock

Traditional blockchain transactions take several seconds to confirm. For bounty claims, this creates friction:

  • Contributors wait 3-15 seconds for transaction confirmation
  • Poor user experience compared to Web2 payments
  • Higher transaction costs on base layer

MagicBlock solves this:

  • ✅ Instant claims in <500ms (6-30x faster)
  • ✅ Better UX - feels like instant payment
  • ✅ Lower costs - reduced transaction fees
  • ✅ Automatic fallback - never breaks, just slower if unavailable
  • ✅ Magic Router - intelligent transaction routing with single endpoint

GitWork creates ephemeral sessions when bounties become claimable, enabling contributors to receive payments almost instantly when they claim their reward.

How It Works

Backend Integration

  1. MagicBlock Service (src/services/magicblock.js)

    • Manages connections to MagicBlock ephemeral rollup
    • Creates and manages ephemeral sessions for bounties
    • Handles delegation/undelegation of accounts
    • Provides smart routing between ephemeral rollup and base layer

  2. Ephemeral Sessions

    • Created automatically when a bounty becomes "ready_to_claim"
    • Delegates escrow wallet to the ephemeral rollup
    • Enables instant claims with auto-commit functionality
    • Closed automatically after claim or cancellation

  3. Transaction Execution

    • Claims execute on ephemeral rollup for instant confirmation
    • Automatic fallback to base layer if ephemeral rollup unavailable
    • Smart connection management with health checks

Frontend Integration

  1. MagicBlock Context (gitwork-front/src/contexts/MagicBlockContext.jsx)

    • Provides MagicBlock connection state across the app
    • Manages wallet adapter with MagicBlock support
    • Health monitoring for ephemeral rollup availability

  2. UI Components

    • MagicBlockStatus: Shows current connection status
    • BountyCard: Displays instant claim badge for fast bounties
    • Visual indicators for MagicBlock-enabled transactions

Transaction Flow

1. Bounty Created → PR Merged → Status: ready_to_claim
   ↓
2. Ephemeral Session Created
   - Escrow wallet delegated to MagicBlock
   - Session valid for 24 hours
   ↓
3. Contributor Claims Bounty
   ↓
4. Magic Router Routes Transaction
   ├─→ Ephemeral Rollup: <500ms ⚡ (if session active)
   └─→ Base Layer: 1-3s 🐢 (fallback)
   ↓
5. Auto-Commit to Solana Base Layer
   - Every 5 transactions OR
   - When session closes

Configuration

Backend Environment Variables

Production (Mainnet)

# Enable MagicBlock Ephemeral Rollups
MAGICBLOCK_ENABLED=true

# Magic Router - Intelligent transaction routing
MAGICBLOCK_RPC_URL=https://rpc.magicblock.app

# Solana Mainnet
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# USDC Mainnet Address
USDC_MINT_ADDRESS=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Development (Devnet)

# Enable MagicBlock Ephemeral Rollups
MAGICBLOCK_ENABLED=true

# Magic Router Devnet - Auto-routing for development
MAGICBLOCK_RPC_URL=https://devnet-rpc.magicblock.app

# Solana Devnet
SOLANA_RPC_URL=https://api.devnet.solana.com

# USDC Devnet Address
USDC_MINT_ADDRESS=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

Frontend Environment Variables

# Enable/disable MagicBlock in frontend
VITE_USE_MAGICBLOCK=true

# MagicBlock RPC endpoint
VITE_MAGICBLOCK_RPC_URL=https://devnet-rpc.magicblock.app

About Magic Router

MagicBlock's Magic Router is a unified RPC endpoint that:

  • ✅ Automatically routes transactions to ephemeral rollup or Solana base layer
  • ✅ Intelligent delegation-based routing
  • ✅ Seamless fallback handling
  • ✅ Single endpoint configuration

Read more: Magic Router Blog

Features

Automatic Session Management

  • Sessions are created when bounties become claimable
  • 24-hour validity period with auto-commit every 5 transactions
  • Automatic cleanup after claims or cancellations

Smart Routing

The system intelligently routes transactions:

  • Ephemeral Rollup: For instant claims with active sessions
  • Base Layer: Fallback for deposits, refunds, or when rollup unavailable

Health Monitoring

  • Continuous health checks for MagicBlock availability
  • Automatic fallback to base layer on failures
  • No disruption to user experience

Benefits

For Contributors

  • ⚡ Instant Claims: Get your bounty in seconds, not minutes
  • 💰 Lower Fees: Reduced transaction costs
  • 🎯 Better UX: Seamless claiming experience

For Repo Owners

  • 🚀 Faster Payouts: Contributors receive funds immediately
  • 💎 Premium Experience: Stand out with cutting-edge tech
  • 📊 Better Metrics: Track ephemeral session usage

Implementation Details

Core Functions

MagicBlock Service (src/services/magicblock.js):

  • createEphemeralSession(bountyId, accounts) - Create ephemeral session for fast claims
  • closeEphemeralSession(sessionId) - Close session and commit to base layer
  • executeOnEphemeralRollup(sessionId, transaction) - Execute instant transactions
  • getSmartConnection() - Auto-routes to best available connection

Smart Connection Management:

  • Magic Router automatically handles delegation routing
  • Transparent fallback to base layer on failures
  • Health monitoring for optimal performance

Performance Metrics

  • Ephemeral Rollup Claims: < 500ms (instant)
  • Base Layer Fallback: 1-3s (standard)
  • Session Lifetime: 24 hours with auto-commit every 5 transactions

Testing & Verification

Quick Health Check

# Check MagicBlock connection status
curl http://localhost:3000/api/magicblock/health

# View active ephemeral sessions
curl http://localhost:3000/api/magicblock/sessions

Test Flow

  1. Create a bounty on a GitHub issue
  2. Fund the escrow wallet
  3. Merge a PR that fixes the issue
  4. Claim bounty → Instant confirmation via MagicBlock ⚡
  5. Check logs for ephemeral session activity

Disabling MagicBlock

If needed, set:

MAGICBLOCK_ENABLED=false

System automatically falls back to standard Solana base layer.

Troubleshooting

Automatic Fallback System

GitWork includes robust fallback mechanisms:

  • ✅ MagicBlock Unavailable: Automatically falls back to Solana base layer
  • ✅ Session Errors: Transactions proceed normally on base layer
  • ✅ No User Disruption: Fallback is transparent and seamless

Common Issues

Connection Failures:

  • Verify MAGICBLOCK_RPC_URL is correct
  • Check network connectivity
  • Test health endpoint

Slow Claims:

  • May indicate fallback to base layer (still works, just slower)
  • Check MagicBlock service status
  • Review logs for fallback warnings

Technical Stack

Dependencies:

  • @magicblock-labs/ephemeral-rollups-sdk v0.3.7+
  • @solana/web3.js v1.87.6+
  • Magic Router for intelligent transaction routing

Key Files:

  • src/services/magicblock.js - Core MagicBlock integration
  • src/services/bounty.js - Bounty lifecycle with ephemeral sessions
  • gitwork-front/src/contexts/MagicBlockContext.jsx - Frontend integration

Resources

⚡ Powered by MagicBlock Ephemeral Rollups - Making bounty claims instant!