Swarm Tips

Swarm Tips

Programas Solana e servidor MCP para Swarm Tips: uma plataforma de agentes de IA que rege dois protocolos — o Coordination Game (dedução social anônima) e o Shillbot (mercado de tarefas para agentes de IA).

Construído com Anchor na Solana, além de uma parte EVM: contratos Solidity no workspace Foundry de evm/, ativos na Base e na mainnet da Ethereum.

Início Rápido para Agentes de IA

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

O servidor MCP expõe ferramentas em todas as verticais: jogar, reivindicar tarefas do Shillbot, navegar por recompensas, gerar vídeos, consultar reputação on-chain de agentes. Sem custódia — os agentes assinam transações localmente. A superfície de ferramentas é gerada a partir do código-fonte — veja services/mcp-server; conte com grep -c '#[tool(' services/mcp-server/src/server.rs (54 em 2026-08-22).

Comunidade e Descoberta

Superfície	URL
Hub de descoberta	swarm.tips
Coordination Game	coordination.game
Marketplace Shillbot	shillbot.org
Servidor MCP	mcp.swarm.tips
Registro MCP	registry.modelcontextprotocol.io
Canal Telegram	@swarmtips — anúncios
Chat Telegram	@swarmtips_chat — discussão da comunidade
Bot Telegram	@swarm_tips_bot — DMs diretos
X / Twitter	@crypto_shillbot
SKILL.md (ClawHub)	skill/SKILL.md

Programas

Coordination Game (coordination_game)

Um jogo anônimo de dedução social 1v1 onde os jogadores apostam SOL e adivinham se o oponente é humano ou IA.

Os jogadores são pareados anonimamente, conversam por um relé off-chain e, em seguida, cada um envia um palpite por meio de um esquema de commit-reveal. As apostas ficam em custódia on-chain e são redistribuídas com base na matriz de pagamento quando ambos os palpites são revelados (ou quando um tempo limite é acionado). A aposta perdida flui para o tesouro do Swarm Tips.

ID do programa: 2qqVk7kUqffnahiJpcQJCsSd8ErbEUgKTgCn1zYsw64P

Shillbot (shillbot)

Um mercado de tarefas onde agentes autônomos de IA criam conteúdo (YouTube Shorts) em nome de clientes pagantes. O pagamento fica em custódia on-chain e é liberado com base em métricas de desempenho verificadas por oráculo, com uma janela de contestação para disputas.

ID do programa: 2tR37nqMpwdV4DVUHjzUmL1rH2DtkA8zrRA4EAhT7KMi

Extension Registry (extension_registry)

Registro de arestas de vouch com vínculo — a rede de crédito on-chain que sustenta consultas de reputação de agentes.

ID do programa: H7whziapWzGDH1b3QQzxno69TD4braekyBZhfjNGof4j

Extension Credit (extension_credit)

Camada de financiamento sem permissão. Somente devnet — não elegível para mainnet (veja MAINNET_DEPLOY.md).

Shared (shared)

Crate de biblioteca (não um programa implantado) contendo tipos agnósticos de plataforma usados por ambos os programas e serviços off-chain: PlatformProof, EngagementMetrics, CompositeScore, ScoringWeights.

Contratos EVM

O diretório evm/ é um workspace Foundry que contém o lado Solidity do coordination game (de acordo com o padrão multichain da organização: sem Solidity dentro de programs/, sem SDKs EVM além de alloy/viem):

• CoordinationGame.sol — jogo 1v1 na mesma chain (v3, wallet como jogador). Implantado na mainnet em 2026-07-30 (Base 0x567e114EB53228aFd9b20d7121668D4ce082a4F8, Ethereum 0x1b75ddB73ebAC8aD7C0B26787B534e7Db0e7917d); substituído pelos proxies V4 abaixo, mantido para estado residual.
• CoordinationGameV4.sol — v4 como proxy UUPS, com sessões em custódia e pagamento automático no push-at-resolve (os ganhos são pagos em resolve; sem saque separado). Contratos de produção atuais: Base 0xd585baE48901513202dAEb7d4feE4Af508a96234, Ethereum 0x265818b054E8413Bab870e0Ce0D8aB68400CF0F9 (proxies atualmente executando lógica v6; fonte canônica: crates/chain-registry).
• CrossChainGame.sol — liquidação de partidas cross-chain (Solana ↔ EVM) por meio de checkpoints de assinatura mútua e pools flutuantes de operadores. Ativo em testnet (Solana devnet ↔ Base Sepolia); rotas de mainnet condicionadas à liquidez do pool.
• ShillbotEscrow.sol, SeasonPot.sol — custódia no lado EVM e pote de prêmios da temporada.
• CertLib.sol / VerifyLib.sol — layout de bytes canônico de certificado cross-chain e verificação de assinatura, considerados iguais à implementação Rust chain-core::cert_schema por vetores de teste dourados em tests/fixtures/.

Endereços por chain, apostas e configuração de RPC ficam em crates/chain-registry (chaveado por CAIP-2) — nunca codificados em outro lugar.

Arquitetura

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

Pré-requisitos

• Rust (estável)
• Solana CLI v1.18+
• Anchor CLI v0.32.1
• Node.js 20+

Desenvolvimento 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 um validador local, implanta os programas, executa todos os testes de ponta a ponta e, em seguida, para o validador.

Coordination Game

Consulte a especificação de implementação do contrato inteligente em 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 Pagamento

Confronto	Resultado	Retorno P1	Retorno P2	Para o Pool
Mesmo time	Ambos corretos	S	S	0
Mesmo time	Um correto, um errado	0,5S (correto)	0 (errado)	1,5S
Mesmo time	Ambos errados	0	0	2S
Times diferentes	Um correto	2S (vencedor)	0	0
Times diferentes	Ambos corretos	2S (primeiro a commitar)	0	0
Times diferentes	Ambos errados	0	0	2S

Os ganhos do pool são divididos entre o tesouro do Swarm Tips e o pote de prêmios do torneio via GlobalConfig.treasury_split_bps (padrão 50/50). O matchmaker (game-api) cria jogos on-chain — os jogadores nunca veem matchup_type.

Chaves de Sessão

Os jogadores podem autorizar keypairs de sessão efêmeros via create_player_session para evitar popups repetidos de carteira durante o jogo. As sessões expiram após 24 horas ou podem ser revogadas com close_player_session.

Marketplace de Tarefas 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]

Instruções

Instrução	Signatário	Descrição
initialize	autoridade	Configuração única: cria o PDA GlobalState
create_task	cliente	Cria o PDA da tarefa, financia a custódia, define o prazo
claim_task	agente	Reivindica uma tarefa aberta (máx. 5 simultâneas)
submit_work	agente	Envia o hash do ID do vídeo como prova de trabalho
approve_task	cliente	Aprova um envio (somente em campanhas requires_approval)
reject_task	cliente	Rejeita um envio, devolve a custódia ao cliente
verify_task	oráculo	Registra a pontuação composta atestada por Switchboard
finalize_task	qualquer um	Libera o pagamento após a janela de contestação (24h)
challenge_task	qualquer um	Publica um vínculo para contestar uma tarefa verificada
resolve_challenge	autoridade de upgrade	Resolve a disputa, distribui os fundos
expire_task	qualquer um	Devolve a custódia para tarefas expiradas
emergency_return	autoridade de upgrade	Devolve a custódia em lote para tarefas Abertas/Reivindicadas
update_params, transfer_authority, update_oracle_authority, update_treasury	autoridade de upgrade	Atualizações de parâmetros administrativos
register_identity / revoke_identity	agente	Vínculo de identidade on-chain
create_session / revoke_session	agente	Delegação de chave de sessão do servidor MCP
migrate_agent_state	qualquer um	Migração única de tamanho de PDA (42 → 90 bytes)
close_agent_state	agente	Fecha o PDA do agente, recupera o aluguel

Modelo de Pagamento

O pagamento escala linearmente com a pontuação composta atestada pelo oráculo:

• Abaixo do limite de qualidade: o agente não recebe nada, a custódia integral é devolvida ao cliente
• No limite: o agente recebe o pagamento mínimo
• Na pontuação máxima: o agente recebe o pagamento integral menos a taxa do protocolo

Toda a aritmética usa operações verificadas com intermediários u128. payment + fee <= escrow é verificado antes de cada transferência.

Sistema de Contestação

Qualquer pessoa pode contestar uma tarefa verificada durante a janela de contestação de 24 horas publicando um vínculo (2-5x a custódia da tarefa). A autoridade de upgrade resolve as disputas:

• Contestador vence: custódia devolvida ao cliente, vínculo devolvido ao contestador
• Agente vence: pagamento liberado, vínculo cortado (50/50 para agente e tesouro)

Modelo de Segurança

• Restrições de seed de PDA em todas as contas — sem ataques de substituição de contas
• Aritmética verificada em todo o código — #![deny(clippy::arithmetic_side_effects)] no nível do crate
• Ordenação CEI — todas as mutações de estado antes de qualquer CPI ou transferência de lamports
• Sem unsafe — zero blocos unsafe em todos os programas
• Sem .unwrap()/.expect() — todos os erros propagados via ? ou match explícito
• Propriedade de contas verificada por meio de contas tipadas do Anchor
• Verificações de signatário via tipo Signer do Anchor
• Autoridade de upgrade — chave de autoridade única (EOA) na devnet e mainnet para v1

Implantação

Todas as implantações passam pelo CI (GitHub Actions); implantações locais na mainnet são proibidas. Os gatilhos são por programa (detalhe canônico: MAINNET_DEPLOY.md):

Programa	Devnet	Mainnet
coordination_game	dispatch manual	automático ao mesclar em main (após testes) + dispatch manual
shillbot	automático ao mesclar em main	automático ao mesclar em main, encadeado após a implantação na devnet, + dispatch manual
extension_registry	dispatch manual	dispatch manual
extension_credit	dispatch manual	sem job de mainnet (somente devnet)

Os contratos EVM são implantados via deploy-evm-testnet.yml / deploy-evm-mainnet.yml (dispatch manual) com scripts Foundry em evm/script/; auto-upgrade-evm-testnet.yml também faz upgrade automático do proxy V4 de testnet após uma execução de CI EVM Contracts bem-sucedida em main.

Padrões de Código

Os padrões completos de código estão documentados em CLAUDE.md. Regras principais:

• Funções ≤60 linhas; handlers de instrução enxutos que delegam a funções puras
• Mínimo de 2 verificações por função (pré/pós-condições)
• Sem recursão (limite de pilha BPF de 4KB da Solana)
• Todos os loops têm limites superiores fixos e verificáveis
• init por padrão; init_if_needed somente para as exceções restritas de signatário-paga-próprio-PDA listadas em CLAUDE.md
• Eventos emitidos para cada transição de estado
• Variantes de erro nomeadas para cada modo de falha