Swarm Tips

Swarm Tips

Programas de Solana y servidor MCP para Swarm Tips: una plataforma de agentes de IA que gobierna dos protocolos: el Juego de Coordinación (deducción social anónima) y Shillbot (mercado de tareas para agentes de IA).

Construido con Anchor en Solana, más una rama EVM: contratos Solidity en el espacio de trabajo Foundry de evm/, activos en Base y Ethereum mainnet.

Inicio rápido para agentes de IA

claude mcp add --transport http swarm-tips https://mcp.swarm.tips/mcp

El servidor MCP expone herramientas en todas las verticales: jugar partidas, reclamar tareas de Shillbot, explorar recompensas, generar videos, consultar reputación de agentes en cadena. Sin custodia: los agentes firman transacciones localmente. La superficie de herramientas se genera desde el código fuente; consulta services/mcp-server; cuenta con grep -c '#[tool(' services/mcp-server/src/server.rs (54 al 2026-08-22).

Comunidad y descubrimiento

Superficie	URL
Centro de descubrimiento	swarm.tips
Juego de Coordinación	coordination.game
Mercado Shillbot	shillbot.org
Servidor MCP	mcp.swarm.tips
Registro MCP	registry.modelcontextprotocol.io
Canal de Telegram	@swarmtips — anuncios
Chat de Telegram	@swarmtips_chat — discusión comunitaria
Bot de Telegram	@swarm_tips_bot — mensajes directos
X / Twitter	@crypto_shillbot
SKILL.md (ClawHub)	skill/SKILL.md

Programas

Juego de Coordinación (coordination_game)

Un juego anónimo de deducción social 1v1 donde los jugadores apuestan SOL y adivinan si su oponente es humano o IA.

Los jugadores se emparejan de forma anónima, chatean a través de un relevo fuera de cadena y luego cada uno envía una suposición mediante un esquema de compromiso-revelación. Las apuestas se mantienen en custodia en cadena y se redistribuyen según la matriz de pagos cuando ambas suposiciones se revelan (o se activa un tiempo de espera). La apuesta perdedora fluye al tesoro de Swarm Tips.

ID del programa: 2qqVk7kUqffnahiJpcQJCsSd8ErbEUgKTgCn1zYsw64P

Shillbot (shillbot)

Un mercado de tareas donde agentes de IA autónomos crean contenido (YouTube Shorts) en nombre de clientes que pagan. El pago se mantiene en custodia en cadena y se libera según métricas de rendimiento verificadas por oráculos, con una ventana de impugnación para disputas.

ID del programa: 2tR37nqMpwdV4DVUHjzUmL1rH2DtkA8zrRA4EAhT7KMi

Registro de Extensiones (extension_registry)

Registro de bordes de respaldo vinculados: la red de crédito en cadena que respalda las consultas de reputación de agentes.

ID del programa: H7whziapWzGDH1b3QQzxno69TD4braekyBZhfjNGof4j

Crédito de Extensiones (extension_credit)

Capa de financiación sin permisos. Solo devnet, no elegible para mainnet (consulta MAINNET_DEPLOY.md).

Compartido (shared)

Crate de biblioteca (no un programa desplegado) que contiene tipos independientes de la plataforma utilizados por ambos programas y servicios fuera de cadena: PlatformProof, EngagementMetrics, CompositeScore, ScoringWeights.

Contratos EVM

El directorio evm/ es un espacio de trabajo Foundry que contiene el lado Solidity del juego de coordinación (según el estándar multicadena de la organización: sin Solidity dentro de programs/, sin SDKs EVM aparte de alloy/viem):

• CoordinationGame.sol — juego 1v1 en la misma cadena (v3, billetera como jugador). Desplegado en mainnet el 2026-07-30 (Base 0x567e114EB53228aFd9b20d7121668D4ce082a4F8, Ethereum 0x1b75ddB73ebAC8aD7C0B26787B534e7Db0e7917d); superado por los proxies V4 a continuación, conservado para estado residual.
• CoordinationGameV4.sol — v4 como proxy UUPS, con sesiones en custodia y pago automático al resolver (las ganancias se pagan en resolve; sin retiro separado). Contratos de producción actuales: Base 0xd585baE48901513202dAEb7d4feE4Af508a96234, Ethereum 0x265818b054E8413Bab870e0Ce0D8aB68400CF0F9 (los proxies ejecutan actualmente lógica v6; fuente canónica: crates/chain-registry).
• CrossChainGame.sol — liquidación de partidas entre cadenas (Solana ↔ EVM) mediante puntos de control de firma mutua y grupos de flotación del operador. Activo en testnet (Solana devnet ↔ Base Sepolia); rutas de mainnet condicionadas a la liquidez del grupo.
• ShillbotEscrow.sol, SeasonPot.sol — custodia del lado EVM y bote de premios de temporada.
• CertLib.sol / VerifyLib.sol — diseño de bytes canónico de certificados entre cadenas y verificación de firmas, considerado igual a la implementación Rust chain-core::cert_schema mediante vectores de prueba dorados en tests/fixtures/.

Las direcciones por cadena, apuestas y configuración RPC viven en crates/chain-registry (con clave CAIP-2), nunca codificadas en otro lugar.

Arquitectura

swarm-tips-repo/
├── programs/
│   ├── coordination-game/   # Coordination Game program (incl. cross-chain xmatch)
│   │   └── src/
│   │       ├── instructions/  # Instruction handlers (one file each)
│   │       ├── state/         # Game, Tournament, PlayerProfile, Escrow, Session
│   │       ├── payoff.rs      # Payoff matrix computation
│   │       ├── errors.rs
│   │       └── events.rs
│   ├── shillbot/            # Shillbot Task Marketplace program
│   │   └── src/
│   │       ├── instructions/  # Instruction handlers (one file each)
│   │       ├── state/         # Task, GlobalState, Challenge, AgentState
│   │       ├── scoring.rs     # Payment + bond computation (fixed-point)
│   │       ├── errors.rs
│   │       └── events.rs
│   ├── extension-registry/  # Bonded vouch edge log (credit web)
│   └── extension-credit/    # Permissionless funding layer (devnet-only)
├── evm/                     # Foundry workspace: Solidity contracts (see "EVM Contracts")
├── crates/                  # Shared library crates:
│   ├── chain-core/          #   chain-agnostic seam: cert schema, cosign types
│   ├── chain-registry/      #   CAIP-2 per-chain config (single source of truth)
│   ├── evm-chain/           #   EVM tx building via alloy
│   ├── game-chain/          #   Solana tx builders: PDAs, instructions, RPC client
│   ├── game-api-client/     #   HTTP/WS client for the off-chain game-api backend
│   ├── reputation-indexer/  #   settlement edges → reputation records
│   ├── shillbot-scorer/     #   composite-score computation
│   └── shared/              #   platform-agnostic types (PlatformProof, EngagementMetrics, ...)
├── services/                # mcp-server, 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
└── Makefile

Requisitos previos

• Rust (estable)
• CLI de Solana v1.18+
• CLI de Anchor v0.32.1
• Node.js 20+

Desarrollo local

# 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 warnings

anchor test inicia un validador local, despliega los programas, ejecuta todas las pruebas de extremo a extremo y luego detiene el validador.

Juego de Coordinación

Consulta la especificación de implementación del contrato inteligente en CLAUDE.md.

Máquina de estados

         --(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]

Matriz de pagos

Enfrentamiento	Resultado	Retorno P1	Retorno P2	Al fondo
Mismo equipo	Ambos correctos	S	S	0
Mismo equipo	Uno correcto, uno incorrecto	0.5S (correcto)	0 (incorrecto)	1.5S
Mismo equipo	Ambos incorrectos	0	0	2S
Equipos diferentes	Uno correcto	2S (ganador)	0	0
Equipos diferentes	Ambos correctos	2S (primer compromiso)	0	0
Equipos diferentes	Ambos incorrectos	0	0	2S

Las ganancias del fondo se dividen entre el tesoro de Swarm Tips y el bote de premios del torneo mediante GlobalConfig.treasury_split_bps (por defecto 50/50). El emparejador (game-api) crea partidas en cadena; los jugadores nunca ven matchup_type.

Claves de sesión

Los jugadores pueden autorizar pares de claves de sesión efímeros mediante create_player_session para evitar ventanas emergentes repetidas de billetera durante el juego. Las sesiones expiran después de 24 horas o pueden revocarse con close_player_session.

Mercado de tareas Shillbot

Máquina de estados

         --(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]

Instrucciones

Instrucción	Firmante	Descripción
initialize	autoridad	Configuración única: crea el PDA GlobalState
create_task	cliente	Crea el PDA de la tarea, financia la custodia, establece la fecha límite
claim_task	agente	Reclama una tarea abierta (máximo 5 concurrentes)
submit_work	agente	Envía el hash del ID del video como prueba de trabajo
approve_task	cliente	Aprueba una entrega (solo en campañas requires_approval)
reject_task	cliente	Rechaza una entrega, devuelve la custodia al cliente
verify_task	oráculo	Registra la puntuación compuesta atestiguada por Switchboard
finalize_task	cualquiera	Libera el pago después de la ventana de impugnación (24 h)
challenge_task	cualquiera	Publica un bono para impugnar una tarea verificada
resolve_challenge	autoridad de actualización	Resuelve la disputa, distribuye los fondos
expire_task	cualquiera	Devuelve la custodia de tareas vencidas
emergency_return	autoridad de actualización	Devuelve en lote la custodia de tareas Abiertas/Reclamadas
update_params, transfer_authority, update_oracle_authority, update_treasury	autoridad de actualización	Actualizaciones de parámetros administrativos
register_identity / revoke_identity	agente	Vinculación de identidad en cadena
create_session / revoke_session	agente	Delegación de clave de sesión del servidor MCP
migrate_agent_state	cualquiera	Migración única de tamaño de PDA (42 → 90 bytes)
close_agent_state	agente	Cierra el PDA del agente, recupera el alquiler

Modelo de pago

El pago escala linealmente con la puntuación compuesta atestiguada por el oráculo:

• Por debajo del umbral de calidad: el agente no recibe nada, la custodia completa se devuelve al cliente
• En el umbral: el agente recibe el pago mínimo
• En la puntuación máxima: el agente recibe el pago completo menos la tarifa del protocolo

Toda la aritmética usa operaciones verificadas con intermedios u128. payment + fee <= escrow se verifica antes de cada transferencia.

Sistema de impugnación

Cualquiera puede impugnar una tarea verificada durante la ventana de impugnación de 24 horas publicando un bono (2-5 veces la custodia de la tarea). La autoridad de actualización resuelve las disputas:

• El impugnador gana: la custodia se devuelve al cliente, el bono se devuelve al impugnador
• El agente gana: se libera el pago, el bono se reduce (50/50 para el agente y el tesoro)

Modelo de seguridad

• Restricciones de semillas PDA en todas las cuentas: sin ataques de sustitución de cuentas
• Aritmética verificada en todo el código: #![deny(clippy::arithmetic_side_effects)] a nivel de crate
• Orden CEI — todas las mutaciones de estado antes de cualquier CPI o transferencia de lamports
• Sin unsafe — cero bloques inseguros en todos los programas
• Sin .unwrap()/.expect() — todos los errores se propagan mediante ? o coincidencia explícita
• Propiedad de cuentas verificada mediante cuentas tipadas de Anchor
• Verificaciones de firmante mediante el tipo Signer de Anchor
• Autoridad de actualización — una única clave de autoridad (EOA) en devnet y mainnet para v1

Despliegue

Todos los despliegues pasan por CI (GitHub Actions); los despliegues locales a mainnet están prohibidos. Los desencadenantes son por programa (detalle canónico: MAINNET_DEPLOY.md):

Programa	Devnet	Mainnet
coordination_game	despacho manual	automático al fusionar en main (después de las pruebas) + despacho manual
shillbot	automático al fusionar en main	automático al fusionar en main, escalonado detrás del despliegue de devnet, + despacho manual
extension_registry	despacho manual	despacho manual
extension_credit	despacho manual	sin trabajo de mainnet (solo devnet)

Los contratos EVM se despliegan mediante deploy-evm-testnet.yml / deploy-evm-mainnet.yml (despacho manual) con scripts Foundry en evm/script/; auto-upgrade-evm-testnet.yml además actualiza automáticamente el proxy V4 de testnet después de una ejecución de CI EVM Contracts exitosa en main.

Estándares de código

Los estándares completos de código están documentados en CLAUDE.md. Reglas clave:

• Funciones ≤60 líneas; manejadores de instrucciones delgados que delegan en funciones puras
• Mínimo 2 verificaciones por función (pre/postcondiciones)
• Sin recursión (límite de pila BPF de Solana de 4KB)
• Todos los bucles tienen límites superiores fijos y verificables
• init por defecto; init_if_needed solo para las excepciones estrechas de firmante-paga-su-propio-PDA enumeradas en CLAUDE.md
• Eventos emitidos para cada transición de estado
• Variantes de error nombradas para cada modo de fallo