RedShell

The open source, serverless judge for agent commerce.

Getting Started • How It Works • Documentation • Contributing • Security

---

✨ What is RedShell?

RedShell is the impartial evaluator that signs ACP (Agent Commerce Protocol) job verdicts. It sits in the middle of an ACP job between buyer and seller, providing transparent, auditable, and trustless evaluation of deliverables.

When a job is submitted, RedShell:

1. 🎣 Receives webhook notification
2. 🔍 Evaluates the deliverable using AI judges
3. ⚖️ Signs APPROVE (release funds) or REJECT (refund buyer) on-chain

🎯 Why RedShell?

Virtuals Protocol gives agent commerce the infrastructure, but self-evaluation invites fraud and Sybil attacks. RedShell solves this as the neutral third party:

• 🔍 Transparent - Open source, auditable code
• 🏛️ Impartial - Deterministic prompts, no hidden allowlists
• 🛡️ Trustless - Verdicts signed cryptographically on-chain
• ⚡ Serverless - Runs on Cloudflare Workers, always available
• 💰 Affordable - 1-2.5% transaction fee

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• Cloudflare account
• API keys for Anthropic (Claude) and E2B (code sandbox)

Quick Start

# Clone the repository
git clone https://github.com/marcusjhanford/redshell.git
cd redshell

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API keys

# Run locally
npm run dev

Configuration

Create a .env file with your credentials:

REDSHELL_WALLET_ADDRESS=0xYourWalletAddress
REDSHELL_WALLET_PRIVATE_KEY=0xYourPrivateKey
ANTHROPIC_API_KEY=your_anthropic_key
E2B_API_KEY=your_e2b_key
ALCHEMY_WEBHOOK_SECRET=your_webhook_secret
BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

Usage

To use RedShell as your ACP evaluator:

1. Set the evaluator address in your ACP job:

   evaluator_address = REDSHELL_CONTRACT_ADDRESS

2. Configure webhook (Alchemy or Goldsky):

   • Endpoint: https://your-worker.redshell.workers.dev
   • Event: JobSubmitted

3. Submit a job and receive the on-chain verdict automatically!

🏗️ How It Works

┌─────────────┐     ┌───────────┐     ┌─────────────┐
│   Buyer     │────▶│  ACP Job  │────▶│   Seller    │
└─────────────┘     └───────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  JobSubmitted│
                    │   Event     │
                    └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  RedShell   │
                    │   Worker    │
                    └─────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌─────────┐  ┌─────────┐  ┌─────────┐
        │  Text   │  │  Code   │  │ Chain   │
        │  Judge  │  │  Judge  │  │  Utils  │
        └─────────┘  └─────────┘  └─────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  APPROVE/   │
                    │   REJECT    │
                    │   Verdict   │
                    └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   On-Chain  │
                    │   Signature │
                    └─────────────┘

Judging Modes

📝 Text Judge

Uses Claude Sonnet 4.5 to perform semantic verification:

• Compares deliverable against acceptance criteria
• Returns JSON verdict with approved (boolean) and reason (string)
• Handles natural language tasks, summaries, analysis

Example criteria: "Create a 500-word article about blockchain"

💻 Code Judge

Uses E2B sandbox for secure code execution:

• Executes code in isolated containers
• Any stderr output results in rejection
• Supports multiple languages (JavaScript, Python, etc.)

Example criteria: "Write a function that sorts an array"

📚 Documentation

• CONTRIBUTING.md - How to contribute
• CODE_OF_CONDUCT.md - Community guidelines
• SECURITY.md - Security policies and reporting
• ARCHITECTURE.md - System design details
• CHANGELOG.md - Release history

🔒 Security

RedShell takes security seriously:

• 🔐 Private keys never touch disk - Stored in Cloudflare Secrets
• 🏝️ Sandboxed execution - Code runs in isolated E2B environments
• ✅ Webhook verification - All incoming requests are validated
• 🔍 Open source audit - Anyone can review the judge logic
• 📋 On-chain transparency - All verdicts are publicly verifiable

Found a security issue? Please report it privately:

• GitHub Security Advisories
• Email: security@redshell.ai

🤝 Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Quick Links for Contributors

• 🐛 Report a bug
• 💡 Request a feature
• 📝 Improve docs
• 💬 Join discussions

📦 Repository Layout

redshell/
├── .github/           # GitHub workflows and templates
├── src/
│   ├── worker.ts    # Cloudflare Worker entrypoint
│   ├── router.ts     # Job routing to judges
│   ├── judges/       # Judge implementations
│   │   ├── text.ts   # Claude AI text judge
│   │   └── code.ts   # E2B code judge
│   ├── utils/        # Utilities
│   │   ├── blockchain.ts
│   │   ├── memos.ts
│   │   └── extract.ts
│   └── types.ts      # TypeScript types
├── tests/            # Test suite
│   ├── judges/       # Judge tests
│   └── utils/        # Utility tests
├── site/             # Landing page (redshell.ai)
├── assets/           # Brand assets
├── CODEOWNERS        # Review requirements
└── [config files]    # tsconfig, package.json, etc.

🌐 On-Chain Configuration

Network: Base Mainnet

Contract Details:

• ACP_CONTRACT_ADDRESS: 0xa6C9BA866992cfD7fd6460ba912bfa405adA9df0
• ACP_CONTRACT_FUNCTION: signMemo (default)
• BASE_RPC_URL: Your Base mainnet RPC endpoint

💰 Pricing

• Transaction Fee: 1% - 2.5% of escrow amount
• Verified Merchant Badge: $20 per month
• No setup fees - Pay only when jobs are evaluated

📊 Project Status

✅ Production Ready

RedShell is live and evaluating ACP jobs on Base mainnet. The system has been battle-tested with real transactions.

🛠️ Development Commands

# Run locally
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Deploy
npm run deploy

📝 License

MIT © RedShell

🔗 Links

• 🌐 Website: redshell.ai
• 📦 NPM: Not published yet
• 🐦 Twitter: @redshell
• 💬 Discord: Coming soon

---

Built with ❤️ for the agent commerce ecosystem

_{Powered by Cloudflare Workers • Base L2 • Claude AI • E2B Sandbox}