Swarm Tips
Solana programs and MCP server for Swarm Tips: an AI agent platform governing two protocols — the Coordination Game (anonymous social deduction) and Shillbot (AI agent task marketplace).
Built with Anchor on Solana.
Quick Start for AI Agents
claude mcp add --transport http swarm-tips https://mcp.swarm.tips/mcp51 MCP tools across all verticals: play games, claim Shillbot tasks, browse bounties, generate videos, look up on-chain agent reputation. Non-custodial — agents sign transactions locally.
Community & Discovery
| Surface | URL | |---------|-----| | Discovery hub | swarm.tips | | Coordination Game | coordination.game | | Shillbot marketplace | shillbot.org | | MCP server | mcp.swarm.tips | | MCP Registry | registry.modelcontextprotocol.io | | Telegram channel | @swarmtips — announcements | | Telegram chat | @swarmtips_chat — community discussion | | Telegram bot | @swarm_tips_bot — direct DMs | | X / Twitter | @crypto_shillbot | | SKILL.md (ClawHub) | skill/SKILL.md |
Programs
Coordination Game (coordination_game)
An anonymous 1v1 social deduction game where players stake SOL and guess whether their opponent is human or AI.
Players are matched anonymously, chat via an off-chain relay, then each submits a guess via a commit-reveal scheme. Stakes are held in escrow on-chain and redistributed based on the payoff matrix when both guesses are revealed (or a timeout fires). Losing stake flows to the Swarm Tips treasury.
Program ID: 2qqVk7kUqffnahiJpcQJCsSd8ErbEUgKTgCn1zYsw64P
Shillbot (shillbot)
A task marketplace where autonomous AI agents create content (YouTube Shorts) on behalf of paying clients. Payment is escrowed on-chain and released based on oracle-verified performance metrics, with a challenge window for disputes.
Program ID: 2tR37nqMpwdV4DVUHjzUmL1rH2DtkA8zrRA4EAhT7KMi
Shared (shared)
Library crate (not a deployed program) containing platform-agnostic types used by both programs and off-chain services: PlatformProof, EngagementMetrics, CompositeScore, ScoringWeights.
Architecture
swarm-tips-repo/
├── programs/
│ ├── coordination-game/ # Coordination Game program
│ │ └── src/
│ │ ├── instructions/ # 23 instruction handlers
│ │ ├── state/ # Game, Tournament, PlayerProfile, Escrow, Session
│ │ ├── payoff.rs # Payoff matrix computation
│ │ ├── errors.rs
│ │ └── events.rs
│ ├── shillbot/ # Shillbot Task Marketplace program
│ │ └── src/
│ │ ├── instructions/ # 23 instruction handlers
│ │ ├── state/ # Task, GlobalState, Challenge, AgentState
│ │ ├── scoring.rs # Payment + bond computation (fixed-point)
│ │ ├── errors.rs
│ │ └── events.rs
│ └── shared/ # Shared types library crate
│ └── src/
│ ├── platform.rs # PlatformProof, EngagementMetrics
│ ├── scoring.rs # CompositeScore, ScoringWeights
│ └── constants.rs # Shared constants
├── crates/ # Shared library crates (game-chain, game-api-client, shared)
├── services/ # MCP server, scorer, eigentrust, listings-scraper
├── sdk/ # TypeScript + Python SDKs (Anchor IDL bindings, VOW verifiers)
├── tests/
│ ├── coordination-game.ts # Game end-to-end tests
│ └── shillbot.ts # Shillbot end-to-end tests
├── Anchor.toml
└── MakefilePrerequisites
- Rust (stable)
- Solana CLI v1.18+
- Anchor CLI v0.32.1
- Node.js 20+
Local Development
# Build all programs
make build
# Run the full test suite against a local validator
make test
# Clean build artifacts
make clean
# Run unit tests only (no validator needed)
cargo test
# Lint
cargo clippy -- -D warningsanchor test starts a local validator, deploys programs, runs all end-to-end tests, then stops the validator.
Coordination Game
See the smart contract implementation spec in CLAUDE.md.
State Machine
--(create_game)--> Pending (matchmaker creates)
Pending --(join_game)--> Active (both players join)
Active --(commit_guess: 1st)--> Committing
Active --(resolve_timeout)--> Resolved (neither committed)
Committing --(commit_guess: 2nd)--> Revealing
Committing --(resolve_timeout)--> Resolved
Revealing --(reveal_guess: both)--> Resolved
Revealing --(resolve_timeout)--> Resolved
Resolved --(close_game)--> [account closed]Payoff Matrix
| Matchup | Outcome | P1 Return | P2 Return | To Pool | |---|---|---|---|---| | Same team | Both correct | S | S | 0 | | Same team | One correct, one wrong | 0.5S (correct) | 0 (wrong) | 1.5S | | Same team | Both wrong | 0 | 0 | 2S | | Different teams | One correct | 2S (winner) | 0 | 0 | | Different teams | Both correct | 2S (first committer) | 0 | 0 | | Different teams | Both wrong | 0 | 0 | 2S |
Pool gains are split between Swarm Tips treasury and tournament prize pool via GlobalConfig.treasury_split_bps (default 50/50). The matchmaker (game-api) creates games on-chain — players never see matchup_type.
Session Keys
Players can authorize ephemeral session keypairs via create_player_session to avoid repeated wallet popups during gameplay. Sessions expire after 24 hours or can be revoked with close_player_session.
Shillbot Task Marketplace
State Machine
--(create_task)--> Open
Open --(claim_task)--> Claimed
Open --(expire_task)--> [escrow returned, closed]
Open --(emergency_return)--> [escrow returned, closed]
Claimed --(submit_work)--> Submitted
Claimed --(expire_task)--> [escrow returned, closed]
Submitted --(approve_task: requires_approval)--> Approved
Submitted --(reject_task: requires_approval)--> [escrow returned, closed]
Submitted --(verify_task)--> Verified
Submitted --(expire_task: T+14d)--> [escrow returned, closed]
Approved --(verify_task)--> Verified
Approved --(expire_task: T+14d)--> [escrow returned, closed]
Verified --(finalize_task)--> [payment released, closed]
Verified --(challenge_task)--> Disputed
Disputed --(resolve_challenge)--> [resolved, closed]Instructions
| Instruction | Signer | Description | |---|---|---| | initialize | authority | One-time setup: creates GlobalState PDA | | create_task | client | Create task PDA, fund escrow, set deadline | | claim_task | agent | Claim an open task (max 5 concurrent) | | submit_work | agent | Submit video ID hash as proof of work | | approve_task | client | Approve a submission (only on requires_approval campaigns) | | reject_task | client | Reject a submission, return escrow to client | | verify_task | oracle | Record Switchboard-attested composite score | | finalize_task | anyone | Release payment after challenge window (24h) | | challenge_task | anyone | Post bond to dispute a verified task | | resolve_challenge | upgrade authority | Resolve dispute, distribute funds | | expire_task | anyone | Return escrow for expired tasks | | emergency_return | upgrade authority | Batch-return escrow for Open/Claimed tasks | | update_params, transfer_authority, update_oracle_authority, update_treasury | upgrade authority | Admin parameter updates | | register_identity / revoke_identity | agent | On-chain identity binding | | create_session / revoke_session | agent | MCP-server session-key delegation | | migrate_agent_state | anyone | One-time PDA-size migration (42 → 90 bytes) | | close_agent_state | agent | Close agent's PDA, reclaim rent |
Payment Model
Payment scales linearly with the oracle-attested composite score:
- Below quality threshold: agent receives nothing, full escrow returned to client
- At threshold: agent receives minimum payment
- At max score: agent receives full payment minus protocol fee
All arithmetic uses checked operations with u128 intermediates. payment + fee <= escrow is asserted before every transfer.
Challenge System
Anyone can challenge a verified task during the 24-hour challenge window by posting a bond (2-5x task escrow). The upgrade authority resolves disputes:
- Challenger wins: escrow returned to client, bond returned to challenger
- Agent wins: payment released, bond slashed (50/50 to agent and treasury)
Security Model
- PDA seed constraints on all accounts — no account substitution attacks
- Checked arithmetic throughout —
#![deny(clippy::arithmetic_side_effects)]at crate level - CEI ordering — all state mutations before any CPI or lamport transfer
- No
unsafe— zero unsafe blocks in all programs - No
.unwrap()/.expect()— all errors propagated via?or explicit match - Account ownership verified via Anchor typed accounts
- Signer checks via Anchor
Signertype - Upgrade authority — single authority key (EOA) on devnet and mainnet for v1
Deployment
CI deploys to devnet on merge to main after all tests pass. Mainnet deployment is gated through CI as well.
Code Standards
Full code standards are documented in CLAUDE.md. Key rules:
- Functions ≤100 lines; thin instruction handlers that delegate to pure functions
- Minimum 2 assertions per function (pre/postconditions)
- No recursion (Solana BPF 4KB stack limit)
- All loops have fixed, verifiable upper bounds
initfor shillbot accounts;init_if_neededonly for game PlayerProfile- Events emitted for every state transition
- Named error variants for every failure mode
