⚡ ZAP — Zero-Knowledge Agent Payouts

📋 Table of Contents

• What is ZAP?

• Problem & Solution

• Architecture Overview

• MetaMask Integration

  • Smart Accounts (ERC-7702)

  • Advanced Permissions (ERC-7715)

  • Delegations (ERC-7710)

• 1Shot API Integration

• Venice AI Integration

• zkTLS + AVS Validation

• Smart Contracts

• Deployed Contracts

• Project Structure

• Complete User Flow

• Setup Guide

• Tech Stack

• Testing Guide

What is ZAP?

ZAP (Zero-Knowledge Agent Payouts) is a fully decentralized GitHub bounty platform that enables repository owners to fund open-source issues and allows developers to automatically claim rewards the moment their pull requests are merged — all verified trustlessly on-chain.

ZAP eliminates the middleman from open-source compensation by combining:

Deployed on Ethereum Sepolia (Ethereum L2 testnet).

🔍 Problem & Solution

The Problem

Open-source contributors face significant friction when it comes to getting paid for their work. Manual, trust-based bounty systems are slow, opaque, and costly.

The ZAP Solution

🏗️ Architecture Overview

🦊 MetaMask Integration

ZAP leverages three cutting-edge MetaMask EIPs to deliver a seamless, gasless, and permission-controlled user experience. Each standard plays a distinct role in the ZAP workflow.

Smart Accounts (ERC-7702)

What it is: ERC-7702 allows a standard Ethereum EOA (Externally Owned Account) to temporarily behave as a smart contract account by delegating its code to a smart contract implementation. This enables smart contract capabilities — like batch transactions and gas sponsorship — without requiring users to migrate to a new wallet address.

How ZAP uses it:

ZAP upgrades a contributor's MetaMask EOA to a smart account on-the-fly when they connect their wallet. This unlocks:

• Gasless transactions — ZAP sponsors gas via a Paymaster, so contributors never need ETH to claim bounties

• Batch operations — multiple on-chain actions (approve + claim) are bundled into a single UserOperation

• ERC-4337 bundler compatibility — ZAP submits UserOps to a bundler that handles mempool management

Interaction flow:

User connects MetaMask → ZAP detects EOA → ERC-7702 delegation applied →
EOA now has smart account capabilities → UserOps submitted gaslessly

Why it matters: Without ERC-7702, every GitHub contributor would need ETH just to claim their bounty — a UX nightmare that kills adoption. ZAP removes this barrier entirely.

Advanced Permissions (ERC-7715)

What it is: ERC-7715 is a permission framework that allows dapps to request scoped, time-bound permissions from a MetaMask wallet. Instead of asking users to sign every transaction, dapps can be pre-authorized to perform specific actions within defined parameters.

How ZAP uses it:

When a bounty creator sets up a bounty, ZAP requests a one-time permission via ERC-7715 to:

• Spend up to a specific mUSD amount (capped at the bounty value)

• Execute payouts only to verified claimants

• Operate within a defined time window (bounty expiry)

// ERC-7715 permission request exampleconst permission = await metamask.request({method: 'wallet_grantPermissions',params: [{
    expiry: bountyExpiry,
    signer: { type: 'account', data: { id: zapContractAddress } },
    permissions: [{
      type: 'native-token-transfer',
      data: { allowance: bountyAmount }
    }]
  }]
});

Why it matters: Bounty creators don't have to be online when a PR is merged. ERC-7715 pre-authorizes ZAP to trigger the payout autonomously — enabling true automation without custodying funds.

Delegations (ERC-7710)

What it is: ERC-7710 introduces a delegation framework where a smart account can delegate specific execution rights to another account or contract, with fine-grained caveats (conditions that must be met for the delegation to be valid).

How ZAP uses it:

ZAP uses ERC-7710 delegations to allow the 1Shot API server wallet to redeem permissions on behalf of users:

• Bounty creators delegate payout execution rights to the ZAP AVS operator

• The delegation includes a caveat: only pay if a valid zkTLS proof is submitted

• The AVS operator calls redeemDelegation() once validation passes

Bounty Creator (delegator) ──delegates──► ZAP AVS Operator (delegate)
                                          │
                                          ├─ Caveat: valid zkTLS proof required
                                          ├─ Caveat: recipient must be PR author
                                          └─ Caveat: amount ≤ bounty value

Why it matters: ERC-7710 is the glue that makes fully automated payouts possible without compromising security. The delegation is cryptographically enforced — the AVS operator cannot abuse the delegation even if compromised.

💳 1Shot API Integration

What it is: 1Shot API provides a managed server-side wallet infrastructure that enables automated, scheduled, and batch blockchain transactions without requiring a hot wallet on ZAP's backend servers.

How ZAP uses it:

Integration architecture:

AVS Validation passes
        │
        ▼
ZAP Backend calls 1Shot API
        │
        ▼
1Shot API signs + broadcasts UserOp
        │
        ▼
Bundler submits to Ethereum Sepolia
        │
        ▼
ZAP Bounty Contract releases funds to contributor

Why it matters: Without 1Shot API, ZAP would need to run a hot wallet on its servers — a serious security risk. 1Shot API decouples transaction signing from application logic, making ZAP's backend stateless and more secure.

🤖 Venice AI Integration

What it is: Venice AI is a privacy-preserving AI API that provides LLM inference without logging or storing user data. ZAP integrates Venice AI across four distinct features.

How ZAP uses it:

1. 🔍 PR Quality Analysis

When a contributor submits a claim, Venice AI analyzes the linked pull request:

• Code quality score (0–100)

• Security risk flags (hardcoded secrets, vulnerable dependencies)

• Completeness check against the bounty issue description

• Fraud detection (copy-paste detection, bot-generated code flags)

2. 📝 AI Bounty Description Generator

Repository owners describe their issue in plain English, and Venice AI generates:

• A structured, developer-friendly bounty description

• Acceptance criteria checklist

• Estimated effort level

• Recommended reward amount based on complexity

3. 🖼️ Bounty Preview Image Generator

Venice AI's image generation creates a unique social preview image for each bounty, used in:

• OpenGraph previews when bounties are shared on social media

• In-app bounty cards for visual differentiation

4. 💬 ZAP AI Chat Assistant

An embedded chat interface powered by Venice AI helps users:

• Understand how to create or claim bounties

• Debug transaction failures

• Get recommendations on bounty amounts

• Query their own bounty history in natural language

Why it matters: Venice AI's privacy-first approach ensures contributor data and PR contents are never stored or used for training. This is critical for enterprise repositories with sensitive codebases.

🔐 zkTLS + AVS Validation

zkTLS Proofs

What it is: zkTLS (Zero-Knowledge Transport Layer Security) allows a client to generate a cryptographic proof that a specific piece of data was returned by a TLS-authenticated server (e.g., GitHub's API), without revealing any session secrets or authentication tokens.

How ZAP uses it:

When a contributor claims a bounty, their browser extension generates a zkTLS proof that:

1. Proves they made an authenticated request to api.github.com

2. Proves the API returned a specific PR status (merged: true)

3. Proves the PR author matches their Ethereum address (linked via GitHub profile)

This proof is submitted on-chain — GitHub cannot be spoofed, and ZAP never touches the contributor's GitHub credentials.

EigenLayer AVS Validation

What it is: EigenLayer's Actively Validated Services (AVS) framework allows existing Ethereum validators to re-stake their ETH to provide economic security for off-chain computation. ZAP runs its own AVS that independently verifies zkTLS proofs before releasing bounty funds.

Validation flow:

1. Contributor submits zkTLS proof to ZAP contract
           │
           ▼
2. ZAP emits ValidationRequired event
           │
           ▼
3. EigenLayer AVS operators pick up the task
           │
           ▼
4. Each operator independently verifies the zkTLS proof
           │
           ▼
5. Operators submit BLS-aggregated signature (2/3 quorum required)
           │
           ▼
6. ZAP contract verifies aggregated signature
           │
           ▼
7. Bounty funds released to contributor

Why it matters: The AVS adds a decentralized trust layer on top of zkTLS. Even if the zkTLS oracle were compromised, the AVS operators provide an independent check — requiring economic collateral (restaked ETH) that would be slashed for dishonest behavior.

📜 Smart Contracts

ZAP Bounty Contract

The core contract manages the full lifecycle of bounties:

mUSD Token Contract

A testnet stablecoin used for bounty payments:

🔗 Deployed Contracts & Explorer Links

All contracts are deployed on Ethereum Sepolia.

Network: Ethereum Sepolia Testnet | Chain ID: 11155111

📁 Project Structure

zap/
├── contracts/                    # Solidity smart contracts
│   ├── ZAPBounty.sol             # Core bounty lifecycle contract
│   ├── MockUSD.sol               # mUSD testnet stablecoin
│   ├── ZAPAVSOperator.sol        # EigenLayer AVS operator contract
│   └── ZAPDelegationManager.sol  # ERC-7710 delegation logic
│
├── avs/                          # EigenLayer AVS validator node
│   ├── operator/                 # Operator node implementation
│   ├── aggregator/               # BLS signature aggregation
│   └── zkverifier/               # zkTLS proof verification
│
├── frontend/                     # Next.js frontend application
│   ├── app/                      # App router pages
│   │   ├── bounties/             # Bounty discovery & creation
│   │   ├── claim/                # Claim submission flow
│   │   └── dashboard/            # User dashboard
│   ├── components/
│   │   ├── metamask/             # MetaMask SDK components
│   │   ├── venice/               # Venice AI chat + analysis UI
│   │   └── bounty/               # Bounty cards & forms
│   └── lib/
│       ├── metamask.ts           # ERC-7702/7715/7710 helpers
│       ├── oneshot.ts            # 1Shot API client
│       ├── venice.ts             # Venice AI client
│       └── zktls.ts              # zkTLS proof generation
│
├── backend/                      # Node.js API server
│   ├── routes/                   # REST API endpoints
│   ├── services/
│   │   ├── avs.ts                # AVS task management
│   │   ├── oneshot.ts            # 1Shot API integration
│   │   └── github.ts             # GitHub API helpers
│   └── jobs/                     # Scheduled payout jobs
│
├── scripts/                      # Deployment & testing scripts
│   ├── deploy.ts                 # Contract deployment
│   ├── fund-faucet.ts            # mUSD faucet funding
│   └── test-e2e.ts               # End-to-end test flow
│
└── docs/                         # Additional documentation
    ├── ARCHITECTURE.md
    ├── AVS_SETUP.md
    └── API.md

🔄 Complete User Flow

For Bounty Creators (Repository Owners)

1. Connect MetaMask Wallet
   └─ ZAP applies ERC-7702 smart account upgrade (gasless from here)

2. Navigate to a GitHub Issue
   └─ Venice AI suggests a bounty amount based on issue complexity

3. Set Bounty Amount & Expiry
   └─ Venice AI generates a professional bounty description

4. Approve via ERC-7715
   └─ One-time permission granted: ZAP can pay up to X mUSD on your behalf

5. Create Bounty (gasless UserOp)
   └─ mUSD locked in ZAP contract
   └─ ERC-7710 delegation created for AVS operator
   └─ Bounty published on ZAP dashboard

For Contributors (Developers)

1. Connect MetaMask Wallet
   └─ ERC-7702 smart account upgrade applied

2. Browse Bounties or Find One Linked to an Issue

3. Fork Repo, Write Code, Open PR
   └─ (Off-chain, normal GitHub workflow)

4. PR Gets Merged by Repo Owner

5. Submit Claim on ZAP
   └─ Browser extension generates zkTLS proof of merge
   └─ Venice AI scores PR quality (must pass threshold)
   └─ Claim submitted to ZAP contract (gasless UserOp)

6. EigenLayer AVS Validates
   └─ Operators verify zkTLS proof independently
   └─ 2/3 quorum submits BLS-aggregated signature
   └─ Validation completes in ~2 minutes

7. 1Shot API Triggers Payout
   └─ Automated payout transaction broadcast
   └─ mUSD transferred to contributor's wallet
   └─ Notification sent via ZAP dashboard

⚙️ Setup Guide

Prerequisites

Installation

# Clone the repository
git clone https://github.com/your-org/zap
cd zap

# Install dependencies
pnpm install

# Copy environment variablescp .env.example .env

Environment Configuration

# .env
NEXT_PUBLIC_METAMASK_PROJECT_ID=your_metamask_project_id
ONESHOT_API_KEY=your_oneshot_api_key
VENICE_API_KEY=your_venice_api_key

# Contract addresses (Ethereum Sepolia)
NEXT_PUBLIC_ZAP_BOUNTY_ADDRESS=0x...
NEXT_PUBLIC_MUSD_ADDRESS=0x...
NEXT_PUBLIC_AVS_REGISTRY_ADDRESS=0x...

# Backend
DATABASE_URL=postgresql://...
PRIVATE_KEY=0x...  # Deployer key (never a hot wallet)

Deploy Contracts

# Compile contracts
forge build

# Deploy to Ethereum Sepolia
forge script scripts/deploy.ts \
  --rpc-url https://sepolia.infura.io/v3/YOUR_KEY \
  --broadcast \
  --verify

# Fund mUSD faucet
pnpm run fund-faucet

Run Locally

# Start frontend
pnpm run dev

# Start backend API
pnpm run server

# Start AVS operator node (separate terminal)
pnpm run avs:operator

Open http://localhost:3000

🛠️ Tech Stack

Blockchain & Smart Contracts

MetaMask & Wallet

AI & Privacy

Infrastructure

🧪 Testing Guide

Unit Tests (Contracts)

# Run all contract tests
forge test -vvv

# Run specific test file
forge test --match-path test/ZAPBounty.t.sol -vvv

# Gas report
forge test --gas-report

Integration Tests

# End-to-end test (requires local Anvil fork)
anvil --fork-url https://sepolia.infura.io/v3/YOUR_KEY

# Run E2E suite
pnpm run test:e2e

Manual Testing Checklist