# Solvers

English | [Português](README.pt-BR.md)

**Solvers is a marketplace of AI specialists ("solvers") that plug into Claude and ChatGPT through a single MCP connector.**
A solver is a data package, not code: method steps with checklists, a knowledge base, templates and evals. Buying one
mints a **license NFT (Metaplex Core)** into the buyer's Solana wallet. Reviews, credits, guarantees (escrow), staking and
license resale all live on-chain. Creators publish solvers and earn from every sale. Buyers can also pay by Pix
(Mercado Pago) or SODAX, and the platform pays all network fees, so users need no SOL.

## Live on devnet

| | |
|---|---|
| Storefront | https://solvers.wondervelop.com |
| MCP connector | `https://solvers.wondervelop.com/mcp` (OAuth with dynamic client registration + PKCE) |
| Program (Anchor) | [`DW6UzJDR9X388f6keJSLXz7WgRVJFntbvonSskRrWNaW`](https://explorer.solana.com/address/DW6UzJDR9X388f6keJSLXz7WgRVJFntbvonSskRrWNaW?cluster=devnet) |
| Network | Solana **devnet** today, mainnet planned |

Docs: package format [PACKAGE_SPEC.md](PACKAGE_SPEC.md) · creator workflow [docs/creator-guide.md](docs/creator-guide.md) ·
plain-language tour of the whole system [docs/concepts-guide.md](docs/concepts-guide.md) · full original spec
[INSTRUCTIONS.md](INSTRUCTIONS.md) (Portuguese).

## How it works

1. The user connects the Solvers connector once in Claude or ChatGPT and signs in (email login, embedded wallet).
2. The assistant calls `find_solver` / `list_my_solvers`, then `activate_solver`. Access is checked against the on-chain license
   (or a free trial, or a guarantee, or a free platform solver).
3. The assistant follows the solver's method step by step (`next_step`), uses its knowledge base (`search_knowledge`) and
   templates (`get_template`), and submits a deliverable (`submit_deliverable`) that a Docker sandbox can verify.
4. Reviews, credits and escrowed guarantees are settled by the Anchor program. Creators can withdraw earnings privately
   (opt-in, mainnet only, via Cloak; see [docs/cloak-privacidade.md](docs/cloak-privacidade.md), in Portuguese).

The connector exposes 15 tools: `list_my_solvers`, `find_solver`, `get_purchase_link`, `activate_solver`, `preflight_check`,
`next_step`, `search_knowledge`, `run_tool`, `get_template`, `get_memory`, `save_memory`, `forget_memory`,
`submit_deliverable`, `escalate_to_creator`, `list_open_guarantees`.

## Repository layout

```
programs/solvers         Anchor 1.2 program (licenses, credits, reviews, escrow, stake, resale), tested with LiteSVM
packages/shared          Zod data contract and pure rules shared by server and web
packages/solvers-client  TypeScript client generated by Codama from the Anchor IDL
packages/chain           Transaction building/sending (platform is fee payer), events, Metaplex Core
packages/api-client      Typed API client used by the web app
apps/server              Node 22 + Express: store API, MCP connector, OAuth, indexer, creator flow, jobs
apps/web                 Next.js storefront, library, creator dashboard, admin review (Privy login)
agents/                  Solver packages (only the examples are included here, see below)
scripts/                 Chain bootstrap, end-to-end scripts, evals
infra/                   PM2, nginx and deploy scripts
docs/                    Design notes and runbooks (mostly Portuguese)
```

## Key design decisions

| Topic | Decision | Why |
|---|---|---|
| Fees | The platform is the fee payer of every transaction | Non-crypto users, email login |
| Minimum price | Every purchase (license, credit pack, guarantee) is >= `min_price` (5 USDC) | Covers the rent the platform pays |
| License caps | Enforced by the program, not the server: `purchase_license` needs the `supply_cap` PDA and fails with `SoldOut`; a creator can only raise the cap, and resale/transfer never frees a slot | The limit is verifiable on-chain |
| Reviews | One license proves exactly one review (`license_review` PDA); the price is pinned at purchase (`expected_price`) | Fixes from the security review |
| Guarantees | Automatic release deadline per step (`passed_at + review_window`) | Several steps with independent deadlines |
| Free trial | Limited uses per wallet per solver, tracked off-chain | Not part of the program |
| Resale | Peer-to-peer, non-custodial, with a creator royalty ([docs/resale.md](docs/resale.md)) | Devnet; mainnet depends on legal terms |
| Ratings | Labelled "internal team test", never "verified". `update_version` resets the on-chain score | Honest labelling |
| SBPF | Built with `--arch v1` | Devnet/mainnet accept v0-v2 deploys |
| Hosting | One domain: web on `/`, server on `/api`, `/mcp`, `/oauth`, `/.well-known` | No CORS, same-site session cookie |

## Running locally

Requirements: Node 22+, pnpm 10, Postgres 16 with pgvector. The Rust program only builds in WSL/Linux with the Solana CLI and Anchor 1.2.

```bash
pnpm install
pnpm --filter @solvers/shared --filter @solvers/client --filter @solvers/chain build

# program (WSL/Linux)
bash scripts/chain/build-program.sh        # anchor build --arch v1 + copies the IDL
bash scripts/chain/test-program.sh         # LiteSVM tests
bash scripts/chain/local-validator.sh      # local validator with the program and Metaplex Core

# network + server
cd scripts && npx tsx src/bootstrap-chain.ts          # test USDC mint + Config
cd apps/server && cp ../../infra/.env.example .env     # adjust for localnet
pnpm --filter @solvers/server dev
pnpm --filter @solvers/web dev                         # web on :3000

pnpm typecheck && pnpm test
```

End-to-end scripts (server running): `cd scripts && npx tsx src/e2e-purchase.ts && npx tsx src/e2e-api.ts && npx tsx src/e2e-mcp.ts && npx tsx src/e2e-full.ts`.
Development keys and `.env*` files live outside git.

## About this repository

This is a **public export** of the project's private working repository. The paid solver packages
(`agents/*`, except `agents/_exemplos` and `agents/criador-de-solvers`) are not included. The package format is fully
documented in [PACKAGE_SPEC.md](PACKAGE_SPEC.md), and `agents/criador-de-solvers` (free, platform-owned) is a complete
reference package.

## License

Source-available under the **Functional Source License, Version 1.1, ALv2 Future License** ([LICENSE](LICENSE), [NOTICE](NOTICE)).
You may read, run, modify and redistribute the code for any purpose except a **Competing Use**: offering a commercial
product or service that substitutes for Solvers. Each version automatically becomes Apache-2.0 two years after it is published.
Copyright 2026 Raphael Pereira.