{"path":"README.md","size":12608,"locked":false,"binary":false,"truncated":false,"content":"# Mappers Protocol\n\n> On-chain freelance settlement infrastructure for Solana, combining programmable escrow with an off-chain dual-model verification oracle.\n\nMappers is an open-source decentralized escrow protocol for freelance and milestone-based work. Client funds are locked in deterministic Solana vault accounts and released or refunded through explicit on-chain state transitions. The Oracle middleware observes jobs, evaluates submitted artifacts through independent Gemini and Claude verdicts, and signs a settlement transaction only when the configured consensus policy is satisfied.\n\n**Current release:** [v0.1.0](https://github.com/mrphatom/mappers_contract/releases/tag/v0.1.0)\n\n**Program ID (Devnet):** `52yt1gCbPeiKP4JYjUVKmMJSgBMMcUx8xRGqozMKX2Mu`\n\n[![CI](https://github.com/mrphatom/mappers_contract/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mrphatom/mappers_contract/actions/workflows/ci.yml)\n[![Anchor Program](https://github.com/mrphatom/mappers_contract/actions/workflows/anchor.yml/badge.svg?branch=main)](https://github.com/mrphatom/mappers_contract/actions/workflows/anchor.yml)\n[![Security Audit](https://github.com/mrphatom/mappers_contract/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/mrphatom/mappers_contract/actions/workflows/security.yml)\n[![CodeQL](https://github.com/mrphatom/mappers_contract/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/mrphatom/mappers_contract/actions/workflows/codeql.yml)\n\n## How It Works\n\n```text\nClient / Dashboard\n        | API requests and signed transactions\n        v\nAPI Server (Express 5 + PostgreSQL)\n        | job metadata and deliverable submission\n        v\nOracle Middleware (Node.js)\n        | Helius Yellowstone gRPC event stream\n        | Gemini + Claude verification\n        v\nAnchor Escrow Program (Rust)\n  |-- GigEscrow PDA: job state and metadata\n  |-- Vault PDA: locked SOL\n        |\n        +--> release_payment or cancel_job\n```\n\nA client initializes a job and funds its vault. The Oracle listens for the on-chain job, receives the freelancer’s deliverable through the application flow, and requests independent structured verdicts from Gemini and Claude. Agreement above the configured thresholds allows the Oracle to submit the corresponding settlement instruction. A disagreement or sub-threshold result remains eligible for human arbitration rather than moving funds automatically.\n\n## Repository Structure\n\nMappers is a **pnpm 11 workspace monorepo**. The Oracle is a first-class workspace package and shares the root `pnpm-lock.yaml`; npm and yarn installation are intentionally rejected.\n\n```text\nmappers_contract/\n|\n|-- programs/project_mappers/     Anchor smart contract (Rust)\n|-- oracle/                       Off-chain verification service (workspace)\n|\n|-- apps/\n|   |-- api-server/               Express 5 REST API\n|   |-- dashboard/                Vite + React 19 frontend\n|\n|-- lib/\n|   |-- sdk/                      @mappers-protocol/sdk\n|   |-- db/                       Drizzle schema and migrations\n|   |-- api-zod/                  Shared Zod validation schemas\n|   |-- api-spec/                 OpenAPI specification and code generation\n|   |-- api-client-react/         Generated TanStack Query hooks\n|\n|-- tests/                        Anchor integration tests\n|-- scripts/                      Devnet and integration scripts\n|-- docs/wiki/                    Version-controlled wiki source\n|-- mappers_whitepaper.md         Protocol design and economic model\n|-- CHANGELOG.md                  Human-readable release history\n```\n\n## Technology Stack\n\n| Layer                   | Technology                                              |\n| ----------------------- | ------------------------------------------------------- |\n| Smart contract          | Rust, Anchor program crate 0.30.1                       |\n| Solana tooling          | Solana 1.18-compatible toolchain; Anchor CLI in CI      |\n| TypeScript client/tests | `@coral-xyz/anchor` 0.32.1, TypeScript, ts-mocha        |\n| API server              | Express 5, Drizzle ORM, PostgreSQL, Pino                |\n| Frontend                | Vite, React 19, TanStack Query, Tailwind CSS, shadcn/ui |\n| Oracle runtime          | Node.js, Helius Yellowstone gRPC, Vitest                |\n| Verification models     | Google Gemini API and Anthropic Claude API              |\n| Package manager         | pnpm 11 workspaces                                      |\n| Security tooling        | `cargo audit`, `pnpm audit`, CodeQL, Dependabot         |\n| License                 | MIT                                                     |\n\n## Getting Started\n\n### Prerequisites\n\nInstall the following tools before starting local development:\n\n- [Node.js](https://nodejs.org/) 22 or newer.\n- [pnpm](https://pnpm.io/) 11 or newer.\n- [Rust](https://rustup.rs/), [Solana CLI](https://docs.solanalabs.com/cli/install), and an Anchor CLI compatible with the program crate.\n- [PostgreSQL](https://www.postgresql.org/) 14 or newer for the API server and database package.\n\n### Install and Validate\n\nRun these commands from the repository root:\n\n```bash\npnpm install\npnpm run typecheck:libs\npnpm run typecheck\npnpm run build\npnpm run typecheck:oracle\npnpm run test:oracle\npnpm run test:anchor\n```\n\n`pnpm install` is the only supported root installation command. The repository contains one authoritative workspace lockfile. Do not create or restore `oracle/package-lock.json`.\n\n### Run the API Server\n\nThe API server expects a PostgreSQL connection string and a valid Oracle URL.\n\n```bash\nexport DATABASE_URL=\"postgresql://localhost:5432/mappers_dev\"\nexport ORACLE_URL=\"http://localhost:3001\"\ncd apps/api-server\npnpm run dev\n```\n\nTo push the current Drizzle schema to a development database:\n\n```bash\ncd lib/db\npnpm run push\n```\n\n### Run the Dashboard\n\n```bash\ncd apps/dashboard\npnpm run dev\n```\n\nThe Vite development server uses port 5173 by default. Configure the API base URL using the dashboard’s environment configuration when the API is not running on its default local address.\n\n### Run the Oracle\n\nThe Oracle is installed and run through the root pnpm workspace:\n\n```bash\ncp oracle/.env.example oracle/.env\ncd oracle\npnpm run dev\n```\n\nThe service requires environment-specific credentials and endpoints. Typical values include `SOLANA_RPC_URL`, `PROGRAM_ID`, `ORACLE_PRIVATE_KEY`, `HELIUS_GRPC_ENDPOINT`, `GEMINI_API_KEY`, and `ANTHROPIC_API_KEY`. Keep private keys and API credentials outside version control.\n\n### Run the Anchor Program\n\n```bash\nanchor build\npnpm run test:anchor\n```\n\nThe default Anchor test script uses `tsconfig.anchor.json` and the repository’s pinned TypeScript test tooling. CI also installs the compatibility Rust toolchain required by the Anchor IDL build.\n\n## Smart Contract\n\nThe `programs/project_mappers` program manages a job through three instructions:\n\n| Instruction                                | Caller           | Effect                                                                  |\n| ------------------------------------------ | ---------------- | ----------------------------------------------------------------------- |\n| `initialize_job(job_id, amount, duration)` | Client           | Creates the escrow and vault PDAs, validates the job, and deposits SOL. |\n| `release_payment()`                        | Client or Oracle | Pays the stored freelancer and closes the escrow.                       |\n| `cancel_job()`                             | Oracle           | Refunds the stored client and closes the escrow.                        |\n\nThe program uses separate state and vault PDAs, stores canonical bumps, enforces a 32-byte job-ID seed boundary, protects terminal states from double spending, and returns account rent to the client when an escrow closes. The Devnet deployment is recorded in `Anchor.toml` and the deployment table below.\n\n## Oracle Consensus\n\nThe Oracle exposes a Node.js service for job tracking, artifact submission, and verification. It listens to the configured Helius Yellowstone gRPC endpoint and uses the program IDL to interpret escrow activity. The verification implementation remains a dual-model policy: Gemini and Claude produce independent structured verdicts, and divergent or sub-threshold outcomes are not automatically settled.\n\nThe protected consensus implementation is `oracle/src/verification.ts`. Model credentials are supplied only through environment variables; no credentials belong in the repository.\n\n## API and Dashboard\n\nThe API server in `apps/api-server/` provides job registration, status, submission, statistics, health, and Oracle-proxy routes. Request and response validation is generated from the OpenAPI specification in `lib/api-spec/`, with shared Zod schemas and typed React Query hooks consumed by the dashboard.\n\nThe dashboard in `apps/dashboard/` provides job overviews, job details, settlement metadata, aggregate statistics, and Oracle health visibility. It is a Vite-built React 19 application styled with Tailwind CSS and shadcn/ui.\n\n## CI/CD and Dependency Automation\n\nThe repository has five required validation workflows: [CI](.github/workflows/ci.yml), [Anchor Program](.github/workflows/anchor.yml), [Security Audit](.github/workflows/security.yml), [CodeQL](.github/workflows/codeql.yml), and [Semantic PR Title](.github/workflows/semantic-pr.yml). The repository also runs DCO validation, wiki synchronization, and Dependabot updates.\n\nDependabot updates the single root npm/pnpm workspace, the Cargo program, and GitHub Actions. The root workspace includes Oracle so its manifest and dependencies are updated through the same supported pnpm workspace model. A small set of dependencies with opaque upstream updater failures is explicitly ignored in `.github/dependabot.yml` and must be reviewed manually when newer versions are needed.\n\nThe release candidate for v0.1.0 was validated on main with clean local typecheck/build/Oracle tests and passing remote CI, Anchor, Security Audit, CodeQL, and Semantic PR Title workflows. See [`CHANGELOG.md`](CHANGELOG.md) for the release scope.\n\n## Documentation\n\nThe version-controlled wiki source is in [`docs/wiki/`](docs/wiki/), and the [GitHub Wiki](https://github.com/mrphatom/mappers_contract/wiki) is synchronized from those pages on pushes to `main`. Key pages include:\n\n- [Overview](docs/wiki/Home.md)\n- [Architecture](docs/wiki/Architecture.md)\n- [Getting Started](docs/wiki/Getting-Started.md)\n- [Development Guide](docs/wiki/Development-Guide.md)\n- [API Reference](docs/wiki/API-Reference.md)\n- [SDK Reference](docs/wiki/SDK-Reference.md)\n- [Release Notes](docs/wiki/Release-Notes.md)\n\nThe [whitepaper](mappers_whitepaper.md) describes the broader protocol design, economic model, and security analysis.\n\n## Deployment\n\n| Network      | Program ID                                     | Status       |\n| ------------ | ---------------------------------------------- | ------------ |\n| Devnet       | `52yt1gCbPeiKP4JYjUVKmMJSgBMMcUx8xRGqozMKX2Mu` | Live         |\n| Mainnet-Beta | TBD                                            | Not deployed |\n\n## Roadmap\n\n- [x] Anchor escrow program with dual PDA architecture.\n- [x] Devnet deployment.\n- [x] Oracle middleware with Helius streaming and dual-model verification.\n- [x] TypeScript SDK.\n- [x] Express 5 REST API and Drizzle database layer.\n- [x] React dashboard and generated API client libraries.\n- [x] Root pnpm workspace validation and protected CI/CD gates.\n- [ ] Production Oracle key management and operational runbooks.\n- [ ] Broader end-to-end devnet demonstration coverage.\n- [ ] Mainnet-Beta deployment and production monitoring.\n\n## Contributing\n\nCreate a short-lived branch from `main`, use pnpm for all JavaScript/TypeScript dependencies, and keep commits focused. Before opening a pull request, run:\n\n```bash\npnpm install --frozen-lockfile\npnpm run typecheck:libs\npnpm run build\npnpm run typecheck:oracle\npnpm run test:oracle\npnpm run test:anchor\npnpm exec prettier --check .\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [Development Guide](docs/wiki/Development-Guide.md) for repository conventions and review expectations.\n\n## License\n\nMappers Protocol is released under the [MIT License](LICENSE).\n\n## References\n\n- [Solana documentation](https://solana.com/docs)\n- [Anchor documentation](https://www.anchor-lang.com/docs)\n- [pnpm workspace documentation](https://pnpm.io/workspaces)\n- [GitHub Actions documentation](https://docs.github.com/actions)\n\n_Built on Solana. Open infrastructure for programmable work settlement._\n"}