Skip to content

README.md

Latest commit

 

History

History
240 lines (177 loc) · 8.56 KB

README.md

File metadata and controls

240 lines (177 loc) · 8.56 KB

GasDock Sample App

A demo application showcasing the GasDock SDK - enabling cross-chain transactions where you execute on one chain while paying with tokens on another.

What This Demo Shows

This sample app demonstrates:

  1. UserOperation preparation on Base Sepolia (transaction execution chain)
  2. Permit2 payment on Optimism Sepolia, Arbitrum Sepolia, or Polygon Amoy (token payment chains)
  3. Automatic UserOp execution after payment confirmation with paymaster sponsorship

Key Features:

  • Execute transactions on Base Sepolia while paying with tokens from Optimism, Arbitrum, or Polygon
  • Multi-chain payment flexibility - choose which testnet to pay from
  • Smart account creation using Circle Modular Wallets (ERC-4337)
  • Gasless transactions via paymaster sponsorship
  • Permit2 signature-based token approvals
  • Automatic token allocation for testing

The Flow

Sequence Diagram

Sample App Flow

Prerequisites

  • Node.js 18+ and pnpm
  • MetaMask or compatible Web3 wallet
  • API keys from Gelato (bundler) and Pimlico (paymaster)

Contract Addresses

This sample app uses pre-deployed demo contracts with access control disabled, allowing anyone to settle payments:

Contract Chain Address
MockToken Base Sepolia 0xdaE3E3df2F746B2c859eb2453266D5c84B20281A
SettlementEscrow Base Sepolia 0xCC87454AaaFD9c11691206DDd4593Be953f81155
SettlementEscrow Polygon Amoy 0x925BA1462587a924aDE115A5E15ABE8F3714AB6C
SettlementEscrow Arbitrum Sepolia 0x925BA1462587a924aDE115A5E15ABE8F3714AB6C
SettlementEscrow Optimism Sepolia 0x925BA1462587a924aDE115A5E15ABE8F3714AB6C

For production deployments with access control, see the main README.md.

Quick Start

# 1. Run setup (builds SDK, installs deps, creates .env files)
pnpm run setup

# 2. Configure your API keys in the created .env files:
#    - Edit .env.local (sample app)
#    - Edit ../relay-server/.env (relay server)

# 3. Start both servers
pnpm run start:all

Open http://localhost:3000 in your browser.

Setup Details

What pnpm run setup does:

  1. Builds the GasDock SDK (required dependency)
  2. Installs relay-server dependencies and creates .env from .env.example
  3. Installs sample app dependencies and creates .env.local from .env.example

Required API Keys

You need to configure these in both .env.local and ../relay-server/.env:

Key Where to get it
Bundler API Key app.gelato.network
Paymaster API Key dashboard.pimlico.io
Allocator Private Key Any funded wallet (for token allocation)
Relayer Private Key Any funded wallet (for relay-server)

Manual Setup (Alternative)

If you prefer to set up manually instead of using pnpm run setup:

# Build SDK
cd ../sdk && pnpm install && pnpm build

# Setup relay-server
cd ../relay-server && pnpm install && cp .env.example .env

# Setup sample app
cd ../sample && pnpm install && cp .env.example .env.local

# Edit both .env files with your API keys

# Start relay-server (terminal 1)
cd ../relay-server && pnpm dev

# Start sample app (terminal 2)
cd ../sample && pnpm dev

Connect Your Wallet

  • Ensure MetaMask is installed
  • Click "Connect Wallet"
  • Approve the connection request
  • The app will automatically create a smart account for you

User Guide

Step 1: Prepare UserOperation (Base Sepolia)

Actions:

  1. Connect Wallet

    • Connects your MetaMask wallet
    • Creates a Circle Modular smart account
    • Initializes bundler and paymaster clients

  2. Select Payment Chain

    • Choose which testnet to pay from: Optimism Sepolia, Arbitrum Sepolia, or Polygon Amoy
    • Each chain has its own token balance and Permit2 approval

  3. Automatic Token Allocation

    • The app automatically checks your token balance on the selected payment chain
    • If you have insufficient MockTokens, they're automatically minted to your wallet in the background
    • No manual action required - tokens are allocated seamlessly as needed

  4. Calculate Gas (Prepare UserOp)

    • Prepares the UserOperation for the transaction on Base Sepolia
    • Calculates gas costs (preVerificationGas, verificationGasLimit, callGasLimit)
    • Converts gas cost to equivalent token amount
    • Auto-populates the Permit2 payment amount

Step 2: Pay with Permit2 (Optimism/Arbitrum/Polygon)

Actions:

  1. Authorize Permit2 (one-time setup per chain)

    • Grants Permit2 contract permission to spend your tokens
    • Automatically switches network to your selected payment chain
    • Sets max allowance for seamless future transactions
    • Only needed once per token per chain

  2. Sign & Relay Permit2

    • Signs EIP-712 Permit2 message with the calculated token amount
    • Sends signature to relay server
    • Relay server broadcasts transaction on the payment chain
    • Automatically triggers UserOp execution after confirmation

What happens:

  • MetaMask prompts to switch to payment chain (Op/Arb/Polygon)
  • Sign Permit2 message (single popup)
  • Relay server submits transaction on-chain
  • Payment confirmed, proceeds to Step 3

Step 3: UserOperation Execution (Automatic)

After Permit2 payment succeeds, the UserOperation automatically executes:

  1. Signs UserOperation with your smart account
  2. Sends to bundler on Base Sepolia
  3. Paymaster sponsors gas fees
  4. Transaction executes on Base Sepolia

Status updates shown:

  • "Sending UserOperation on Base Sepolia…"
  • "UserOperation sent: [hash]"
  • "Waiting for confirmation…"
  • "UserOperation confirmed in block [number]"

UI Overview

Execution Chain Section (Base Sepolia)

  • Smart Account Address: Your Circle smart account address
  • Gas Estimate: Breakdown of gas costs (preVerificationGas, verificationGasLimit, callGasLimit)
  • UserOperation Hash: Transaction hash (shown after execution)

Payment Chain Section (Optimism/Arbitrum/Polygon)

  • Payment Chain Selector: Dropdown to choose Op Sepolia, Arb Sepolia, or Polygon Amoy
  • Wallet Address: Your connected EOA address
  • Token Balance: Current MockToken balance on selected payment chain
  • Permit2 Allowance: Amount Permit2 can spend (max after authorization)
  • Settlement Manager: Escrow contract address on selected payment chain
  • Token Address: MockToken (ERC20) contract address
  • Payment Receiver: Address receiving the payment
  • Amount: Token amount for payment (auto-calculated, editable)
  • Intent Hash: Cryptographic binding between payment and execution
  • Permit2 Tx Hash: Payment transaction hash

Status Panel

  • Real-time operation status and progress
  • Transaction confirmation updates
  • Error messages and troubleshooting hints

Supported Networks

Execution Chain (where transactions run)

  • Base Sepolia (84532) - UserOperations execute here

Payment Chains (where you pay with tokens)

  • Optimism Sepolia (11155420) - Pay with tokens from Optimism
  • Arbitrum Sepolia (421614) - Pay with tokens from Arbitrum
  • Polygon Amoy (80002) - Pay with tokens from Polygon

All chains use testnet deployments. See /contracts for contract addresses.

Project Structure

sample/
├── scripts/
│   ├── setup.js          # Setup script (builds SDK, creates .env files)
│   └── start.js          # Start script (runs relay-server + sample app)
├── src/
│   ├── pages/
│   │   ├── _app.tsx       # App wrapper with providers
│   │   └── index.tsx      # Main demo page
│   ├── utils/
│   │   ├── allocateTokens.ts   # Auto token allocation
│   │   └── checkBalances.ts    # Balance checking utilities
│   ├── assets/            # Contract ABIs
│   ├── config.ts          # Chain and contract config
│   └── wagmi.ts          # Wagmi configuration
├── .env.local            # Environment variables (created by setup)
└── package.json          # Dependencies

Learn More

GasDock Documentation

External Resources