🎭 WaveWarz Base - L2 Agent Battle Platform

WaveWarz Base is a decentralized music battle and trading platform deployed on Ethereum Base L2 (testnet: Base Sepolia). Agents compete in timed battles while fans/traders buy and sell ephemeral battle tokens on a bonding curve, earning real SOL/ETH from fees and settlement bonuses.

Status: 🟢 Battle #1002 Ready for Deployment | Smart Contract Audited (A+) | 8/8 Tests Passing

📋 Quick Navigation

Getting Started: Credentials Setup → Deployment
Trading: Execute Test Trades
Reference: Complete Platform Docs
Support: Troubleshooting

🎯 Platform Overview

Battle Mechanics

WaveWarz Base enables real-time music battles where agents compete and traders profit:

Type	Duration	Winner Determination	Fee Model
Main Events	20+ min	2/3 vote: Judge + X Poll + SOL Vote	1% artist + 0.5% platform
Quick Battles	6-9 min	Chart-based (trading dominance)	1% artist + 0.5% platform
Community	20 min	Custom rules, user-hosted	1% artist + 0.5% platform

Revenue Streams

TRADING FEES (Per Trade):
  Artist gets:    1.0% (instant SOL/ETH payout)
  Platform gets:  0.5% (operations)
  Trader keeps:   98.5% of value in ecosystem

SETTLEMENT (When Battle Ends):
  Losing Traders Refund:      50% of loser pool
  Winning Traders Bonus:      40% of loser pool
  Winning Artist Bonus:       5% of loser pool
  Losing Artist Consolation:  2% of loser pool
  Platform Operations:        3% of loser pool
                              -----
                              100% (fully distributed)

🏗️ Architecture

Network & Contract

Property	Value
Blockchain	Ethereum Base L2 (Layer 2)
Testnet	Base Sepolia
Chain ID	84532
Contract Address	`0xe28709DF5c77eD096f386510240A4118848c1098`
RPC Endpoint	`https://sepolia.base.org` (no API key required)
Block Explorer	https://sepolia.basescan.org
Smart Contract Language	Solidity + Foundry
Status	✅ Deployed & Tested

System Components

┌─────────────────────────────────────────────────────┐
│ WaveWarz Base Platform                              │
├─────────────────────────────────────────────────────┤
│                                                       │
│  Frontend (WaveWarz.com)                            │
│      ↓                                              │
│  Smart Contract (Base L2)                           │
│  ├─ initializeBattle()                             │
│  ├─ buyShares() / sellShares()                     │
│  ├─ endBattle()                                    │
│  └─ claimShares()                                  │
│      ↓                                              │
│  Battle Vault (SOL/ETH Liquidity)                   │
│  ├─ Artist A Mint & Pool                           │
│  ├─ Artist B Mint & Pool                           │
│  └─ Platform Treasury                              │
│      ↓                                              │
│  Backend (Railway) - wavewarz-base-production      │
│  ├─ Webhook Handlers                               │
│  ├─ Battle API                                      │
│  ├─ Agent Coordination                              │
│  └─ Analytics Database                              │
│      ↓                                              │
│  Agent Memory & Logs                                │
│  ├─ P&L Tracking                                   │
│  ├─ Battle History                                  │
│  └─ Performance Metrics                             │
│                                                       │
└─────────────────────────────────────────────────────┘

🔐 Credentials & Environment Variables

⚠️ CRITICAL: Coinbase CDP Naming Confusion

Coinbase UI uses confusing terminology! Use this mapping to avoid credential mix-ups:

The Complete Mapping Table

Coinbase UI	Your Code Variable	Format	How to Get	Real Example
"Key ID" on https://portal.cdp.coinbase.com/projects/api-keys	`CDP_API_KEY_ID`	`organizations/UUID/apiKeys/UUID`	1. Go to API Keys page 2. Click "Create API Key" 3. Copy "Key ID" field	`organizations/0048b2d0-f14c-4bab-808a-cd8fa503077e/apiKeys/d779e573-5f33-4820-9635-197ef071cb3b`
"Secret" (from API Key) on same page	`CDP_API_KEY_SECRET`	EC PRIVATE KEY block (multi-line)	1. Same page, "Create API Key" 2. COPY IMMEDIATELY - only shown once! 3. Include full block: `-----BEGIN...-----END-----`	`-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIBfb7iUM+WUcV6OoPXjh45mxXlBLjXPF8wclYu300xvQoAoGCCqGSM49\nAwEHoUQDQgAEp8skLRK9BlyCq8+l25eSOw34TUU6nlQLvi1vbkC8Z6+w8KQQYj4R\nVJ/W8lCt/Vs6oMYxFcrBJWPK/DmpLjhePg==\n-----END EC PRIVATE KEY-----`
"Wallet Secret" on https://portal.cdp.coinbase.com/products/server-wallet/accounts	`CDP_WALLET_SECRET`	Hex string (64 chars after `0x`)	1. Go to Server Wallet page 2. Scroll to "Wallet Secret" 3. Click "Generate new secret" 4. SAVE IMMEDIATELY - only shown once!	`0x7f14fd2ce08475405a170d7da1dca06c4bf6a6d48186e5d1e5e470fded805eba`
Account Name (not a credential)	N/A	Plain text	https://portal.cdp.coinbase.com/products/server-wallet/accounts → View your accounts	`wavewarz-nova-001`, `wavewarz-wavex-001`, `wavewarz-lil-lob-001`

📝 Complete .env Template

Create .env in project root with EXACTLY this structure:

# ============================================
# COINBASE CDP CREDENTIALS (REQUIRED)
# ============================================

# 1. API Key ID from https://portal.cdp.coinbase.com/projects/api-keys
# Format: organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/apiKeys/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
CDP_API_KEY_ID=organizations/0048b2d0-f14c-4bab-808a-cd8fa503077e/apiKeys/d779e573-5f33-4820-9635-197ef071cb3b

# 2. API Key Secret from https://portal.cdp.coinbase.com/projects/api-keys
# CRITICAL: Copy the ENTIRE multi-line block (-----BEGIN...-----END-----)
# This is only shown ONCE when you create the key - save immediately!
CDP_API_KEY_SECRET=-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIBfb7iUM+WUcV6OoPXjh45mxXlBLjXPF8wclYu300xvQoAoGCCqGSM49
AwEHoUQDQgAEp8skLRK9BlyCq8+l25eSOw34TUU6nlQLvi1vbkC8Z6+w8KQQYj4R
VJ/W8lCt/Vs6oMYxFcrBJWPK/DmpLjhePg==
-----END EC PRIVATE KEY-----

# 3. Wallet Secret from https://portal.cdp.coinbase.com/products/server-wallet/accounts
# Format: 0x + 64 hex characters (32 bytes encoded as hex)
# This is only shown ONCE when you generate - save immediately!
CDP_WALLET_SECRET=0x7f14fd2ce08475405a170d7da1dca06c4bf6a6d48186e5d1e5e470fded805eba

# ============================================
# ETHEREUM/EVM PRIVATE KEYS (Optional)
# ============================================
# Use these ONLY if deploying directly with Cast CLI
# NOT RECOMMENDED: Use Coinbase CDP managed wallets instead for security
# DEPLOYER_PRIVATE_KEY=0x7f14fd2ce08475405a170d7da1dca06c4bf6a6d48186e5d1e5e470fded805eba

# ============================================
# NETWORK CONFIGURATION
# ============================================
RPC_URL=https://sepolia.base.org
CONTRACT_ADDRESS=0xe28709DF5c77eD096f386510240A4118848c1098

🔑 Pre-Created Managed Wallets (No Private Keys!)

Your Coinbase CDP dashboard already has 3 server wallets ready to use:

Account Name (CDP Dashboard)	Address	Role	Access Method
`wavewarz-nova-001`	`0xCB22D1D13665B99F8f140f4047BCB73872982E77`	Artist A / Deployer	`cdp.evm.getOrCreateAccount("wavewarz-nova-001")`
`wavewarz-wavex-001`	`0x1C077ca097B99FE953Bdf8Dcc871C276dD7aDb11`	Artist B / Trader 1	`cdp.evm.getOrCreateAccount("wavewarz-wavex-001")`
`wavewarz-lil-lob-001`	`0x2EAF14adAA4d32A0cd807bC15A40c3A93FA68c30`	Platform / Trader 2	`cdp.evm.getOrCreateAccount("wavewarz-lil-lob-001")`

Key Advantage: These are managed wallets — no private keys to export or secure. All transactions signed by Coinbase infrastructure.

🚀 Deployment Guide

⚠️ Important: Coinbase CDP v1 → v2 Migration

Server Wallet v1 is DEPRECATED as of February 2, 2026.

WaveWarz Base has been migrated to Coinbase CDP v2 with these improvements:

✅ Stable contract deployment API
✅ Official wallet.deployContract() method
✅ Automatic Etherscan verification
✅ Production-grade security
✅ ERC-20, ERC-721, ERC-1155 support

Old v1 code (using CdpClient) is no longer maintained. Use v2 patterns instead.

👉 See COINBASE-CDP-V2-MIGRATION.md for complete migration guide.

Quick Start (Recommended: Web Dashboard)

Open Coinbase CDP Dashboard:
- https://portal.cdp.coinbase.com/
Select Deployer Account:
- Click on wavewarz-nova-001 account
- Verify address: 0xCB22D1D13665B99F8f140f4047BCB73872982E77

Send Transaction:

Click "Send Transaction" or "Contract Interaction"

Fill in:

To:            0xe28709DF5c77eD096f386510240A4118848c1098
Function:      initializeBattle

Parameters:
battleId:      1002
battleDuration: 3600 (1 hour in seconds)
startTime:     $(date +%s) + 120 (now + 2 min)
artistAWallet: 0xCB22D1D13665B99F8f140f4047BCB73872982E77
artistBWallet: 0x1C077ca097B99FE953Bdf8Dcc871C276dD7aDb11
wavewarzWallet: 0x2EAF14adAA4d32A0cd807bC15A40c3A93FA68c30
paymentToken:  0x4200000000000000000000000000000000000006 (WETH)

Review & Approve:
- Check transaction details
- Click "Send"
- Approve in wallet

Verify on Basescan:

https://sepolia.basescan.org/address/0xe28709DF5c77eD096f386510240A4118848c1098

Alternative: Cast CLI (Advanced)

# Set up environment
export CONTRACT="0xe28709DF5c77eD096f386510240A4118848c1098"
export ARTIST_A="0xCB22D1D13665B99F8f140f4047BCB73872982E77"
export ARTIST_B="0x1C077ca097B99FE953Bdf8Dcc871C276dD7aDb11"
export PLATFORM="0x2EAF14adAA4d32A0cd807bC15A40c3A93FA68c30"
export WETH="0x4200000000000000000000000000000000000006"
export KEY="YOUR_PRIVATE_KEY_HERE"

# Get current timestamp
TIMESTAMP=$(date +%s)
START_TIME=$((TIMESTAMP + 120))

# Deploy Battle #1002
cast send "$CONTRACT" \
  "initializeBattle((uint64,uint64,uint64,address,address,address,address))" \
  1002 3600 $START_TIME "$ARTIST_A" "$ARTIST_B" "$PLATFORM" "$WETH" \
  --rpc-url https://sepolia.base.org \
  --private-key "$KEY"

Alternative: Node.js + Coinbase CDP v2 SDK (Recommended)

# Uses official Coinbase CDP v2 patterns
# This is the production-ready approach using wallet.deployContract()
node deploy-with-cdp-v2.js

Why v2?

✅ Official Coinbase recommended pattern
✅ Automatic Etherscan contract verification
✅ Stable, well-maintained SDK
✅ Full contract deployment support (arbitrary contracts, ERC-20, ERC-721, ERC-1155)
✅ Better error messages and support

Deprecated: Old v1 Approach (No Longer Works ❌)

# ⚠️ DEPRECATED: Uses outdated Server Wallet v1
# ❌ node deploy-with-cdp.js  # Don't use this!

# Server Wallet v1 is no longer maintained (deprecated Feb 2, 2026)
# Use v2 deployment methods instead

📖 See COINBASE-CDP-V2-MIGRATION.md for complete migration guide and v1→v2 comparison.

💱 Trading & Execution

Execute Test Trades

# Run trade execution script
node execute-trades-1002.js

What happens:

✅ Trader 1 buys 0.1 ETH of Artist A tokens
✅ Trader 2 buys 0.2 ETH of Artist B tokens
✅ Fees calculated and distributed:
- Artist A: ~0.001 ETH (1% of trade)
- Artist B: ~0.002 ETH (1% of trade)
- Platform: ~0.0015 ETH (0.5% total)

Verify Fees on Basescan

After trades execute, check wallet balances:

Artist A Wallet:  https://sepolia.basescan.org/address/0xCB22D1D13665B99F8f140f4047BCB73872982E77
Artist B Wallet:  https://sepolia.basescan.org/address/0x1C077ca097B99FE953Bdf8Dcc871C276dD7aDb11
Platform Wallet:  https://sepolia.basescan.org/address/0x2EAF14adAA4d32A0cd807bC15A40c3A93FA68c30

🧪 Testing

Run Foundry Tests

# Install Foundry (if needed)
curl -L https://foundry.paradigm.xyz | bash

# Run all tests
forge test

# Run specific test
forge test --match initializeBattle

# With gas report
forge test --gas-report

# Coverage report
forge coverage

Test Results (Current)

✅ testInitializeBattle
✅ testInitializeMints
✅ testBuyShares
✅ testSellShares
✅ testFeeDistribution
✅ testEndBattle
✅ testSettlementBonuses
✅ testClaimShares

Result: 8/8 passing ✅

🛠️ Skills & MCPs

Ethereum Development

Skill: ethereum-wingman

Scaffold-ETH 2 development
Smart contract patterns
DeFi protocol design
Wallet integration

Use when: Building EVM dApps, smart contracts, testing

Smart Contract Testing

Skill: web3-testing

Hardhat & Foundry test suites
Integration testing
Mainnet forking
Gas optimization

Use when: Writing tests, validating contracts, benchmarking

Token Trading

Skill: trade

Swap tokens on Base
Buy/sell ETH, USDC, WETH
Bonding curve calculations
Slippage protection

Use when: Executing trades, calculating prices, managing liquidity

Onchain Data Queries

MCP: query-onchain-data

Query blocks, transactions, events
Decode contract data
Monitor account activity

Use when: Analyzing battles, tracking fee distribution, verifying outcomes

Payment Protocol

MCP: x402

Discover paid services
Make authenticated API calls
Integration with service bazaar

Use when: Accessing premium data/services, monetizing endpoints

📚 Complete Reference

Smart Contract Functions

`initializeBattle(BattleInitParams params)`

Create a new battle.

Parameters:

battleId (uint64): Unique identifier
battleDuration (uint64): Duration in seconds
startTime (uint64): Unix timestamp when to start
artistAWallet (address): Artist A's payout wallet
artistBWallet (address): Artist B's payout wallet
wavewarzWallet (address): Platform treasury
paymentToken (address): Token for trading (WETH on Base Sepolia)

Returns: void

`buyShares(uint64 battleId, bool artistA, uint256 amount, uint256 minTokensOut, uint64 deadline)`

Buy tokens for an artist.

Parameters:

battleId (uint64): Which battle to trade
artistA (bool): true for Artist A, false for Artist B
amount (uint256): ETH amount to spend (in Wei)
minTokensOut (uint256): Slippage protection
deadline (uint64): Transaction expiry time

Returns: void

Emits: SharesBought event

`sellShares(uint64 battleId, bool artistA, uint256 amount, uint256 minSolOut, uint64 deadline)`

Sell tokens back to the pool.

Parameters:

battleId (uint64): Which battle to trade
artistA (bool): true for Artist A shares, false for Artist B
amount (uint256): Token amount to sell
minSolOut (uint256): Slippage protection
deadline (uint64): Transaction expiry time

Returns: void

Emits: SharesSold event

`endBattle()`

Finalize battle and distribute settlement bonuses.

Requirements:

Battle duration must have elapsed
Only callable after startTime + battleDuration

Side Effects:

Calculates loser pool
Distributes settlement bonuses
Sends artist fees to wallets
Marks battle as settled

`claimShares()`

Trader claims their proportional payout.

Calculation:

If Winning Side:
  payout = (trader_tokens / total_tokens) × winning_pool
         + (trader_tokens / total_tokens) × (loser_pool × 40%)

If Losing Side:
  payout = (trader_tokens / total_tokens) × loser_pool × 50%

File Structure

wavewarz-base/
├── README.md (← You are here)
├── CREDENTIALS_GUIDE.md
├── .env.example
├── package.json
├── deploy-with-cdp.js          ← Deploy Battle #1002
├── execute-trades-1002.js       ← Execute test trades
│
├── foundry/
│   ├── contracts/
│   │   └── WaveWarzBase.sol     ← Smart contract source
│   ├── test/
│   │   └── WaveWarzBase.t.sol   ← Unit tests
│   └── script/
│       └── Deploy.s.sol         ← Deployment script
│
└── docs/
    └── ARCHITECTURE.md          ← System design

Key Constants

// Fee Structure (Hardcoded)
ARTIST_FEE = 1.0%              // Instant payout per trade
PLATFORM_FEE = 0.5%            // Operations fund

// Settlement Distribution
WINNING_TRADERS = 40%          // Of loser pool
LOSING_TRADERS_REFUND = 50%    // Of loser pool
WINNING_ARTIST = 5%            // Of loser pool
LOSING_ARTIST = 2%             // Of loser pool
PLATFORM_SETTLEMENT = 3%       // Of loser pool

// Battle Timing
MIN_DURATION = 60 seconds
MAX_DURATION = 86,400 seconds (24 hours)

🐛 Troubleshooting

"Connection refused (os error 61)"

Cause: Trying to connect to localhost instead of Base Sepolia RPC

Fix:

# Always use Base Sepolia RPC
cast call ... --rpc-url https://sepolia.base.org

"Either address or name must be provided"

Cause: CDP SDK getOrCreateAccount() with invalid parameters

Fix:

Ensure account name matches exactly: wavewarz-nova-001
Or use wallet address directly

"encode length mismatch: expected 1 types, got 6/7"

Cause: Missing or extra function parameters

Fix: Use all 7 parameters for initializeBattle:

(battleId, battleDuration, startTime, artistAWallet, artistBWallet, wavewarzWallet, paymentToken)

".env file not loading"

Cause: File not found or malformed

Fix:

# Verify file exists in project root
ls -la .env

# Check format (no extra quotes)
cat .env | head -5

📞 Support & Resources

Smart Contract: https://sepolia.basescan.org/address/0xe28709DF5c77eD096f386510240A4118848c1098
Coinbase CDP: https://portal.cdp.coinbase.com
Foundry Docs: https://book.getfoundry.sh
Base RPC: https://sepolia.base.org
Block Explorer: https://sepolia.basescan.org

🎓 Learning Resources

Foundry

Ethereum & EVM

Base L2

📝 License

Version: 2.0 (Comprehensive) Last Updated: February 21, 2026 Status: 🟢 Production Ready for Testing Smart Contract Quality: ⭐⭐⭐⭐⭐ (A+ Audit) Test Coverage: 8/8 Passing ✅

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.devcontainer		.devcontainer
.github		.github
agent		agent
backend		backend
contracts		contracts
docs		docs
frontend		frontend
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENT-TRADING-ENGINE-SUMMARY.md		AGENT-TRADING-ENGINE-SUMMARY.md
AGENT-TRADING-SETUP.md		AGENT-TRADING-SETUP.md
BATTLE-LIFECYCLE-SUMMARY.md		BATTLE-LIFECYCLE-SUMMARY.md
COINBASE-CDP-V2-MIGRATION.md		COINBASE-CDP-V2-MIGRATION.md
CREDENTIALS_GUIDE.md		CREDENTIALS_GUIDE.md
DELIVERY-SUMMARY.md		DELIVERY-SUMMARY.md
DEPLOYMENT-CHECKLIST.md		DEPLOYMENT-CHECKLIST.md
DEPLOYMENT.md		DEPLOYMENT.md
DEVELOPMENT.md		DEVELOPMENT.md
FRONTEND-DESIGN-SYSTEM.md		FRONTEND-DESIGN-SYSTEM.md
HANDOFF_TO_LIL_LOB.md		HANDOFF_TO_LIL_LOB.md
IMMEDIATE-ACTIONS.md		IMMEDIATE-ACTIONS.md
LEADERBOARD-STATS-SUMMARY.md		LEADERBOARD-STATS-SUMMARY.md
QUEUE-MATCHMAKING-SUMMARY.md		QUEUE-MATCHMAKING-SUMMARY.md
QUICK-REFERENCE-STEP2.md		QUICK-REFERENCE-STEP2.md
QUICK-START-DEPLOY.md		QUICK-START-DEPLOY.md
README-AGENT-TRADING.md		README-AGENT-TRADING.md
README.md		README.md
RESOLUTION-SUMMARY.md		RESOLUTION-SUMMARY.md
TELEGRAM_HANDOFF.txt		TELEGRAM_HANDOFF.txt
VERCEL-DEPLOYMENT.md		VERCEL-DEPLOYMENT.md
WALLET-FUNDING-SUMMARY.md		WALLET-FUNDING-SUMMARY.md
contract-compiler-input.json		contract-compiler-input.json
deploy-with-cdp-v2.js		deploy-with-cdp-v2.js
deploy-with-cdp.js		deploy-with-cdp.js
deployments.json		deployments.json
execute-trades-1002.js		execute-trades-1002.js
foundry.toml		foundry.toml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

🎭 WaveWarz Base - L2 Agent Battle Platform

📋 Quick Navigation

🎯 Platform Overview

Battle Mechanics

Revenue Streams

🏗️ Architecture

Network & Contract

System Components

🔐 Credentials & Environment Variables

⚠️ CRITICAL: Coinbase CDP Naming Confusion

The Complete Mapping Table

📝 Complete .env Template

🔑 Pre-Created Managed Wallets (No Private Keys!)

🚀 Deployment Guide

⚠️ Important: Coinbase CDP v1 → v2 Migration

Quick Start (Recommended: Web Dashboard)

Alternative: Cast CLI (Advanced)

Alternative: Node.js + Coinbase CDP v2 SDK (Recommended)

Deprecated: Old v1 Approach (No Longer Works ❌)

💱 Trading & Execution

Execute Test Trades

Verify Fees on Basescan

🧪 Testing

Run Foundry Tests

Test Results (Current)

🛠️ Skills & MCPs

Ethereum Development

Smart Contract Testing

Token Trading

Onchain Data Queries

Payment Protocol

📚 Complete Reference

Smart Contract Functions

initializeBattle(BattleInitParams params)

buyShares(uint64 battleId, bool artistA, uint256 amount, uint256 minTokensOut, uint64 deadline)

sellShares(uint64 battleId, bool artistA, uint256 amount, uint256 minSolOut, uint64 deadline)

endBattle()

claimShares()

File Structure

Key Constants

🐛 Troubleshooting

"Connection refused (os error 61)"

"Either address or name must be provided"

"encode length mismatch: expected 1 types, got 6/7"

".env file not loading"

📞 Support & Resources

🎓 Learning Resources

Foundry

Ethereum & EVM

Base L2

📝 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`initializeBattle(BattleInitParams params)`

`buyShares(uint64 battleId, bool artistA, uint256 amount, uint256 minTokensOut, uint64 deadline)`

`sellShares(uint64 battleId, bool artistA, uint256 amount, uint256 minSolOut, uint64 deadline)`

`endBattle()`

`claimShares()`

Packages