{"path":"docs/wiki/Getting-Started.md","size":7374,"locked":false,"binary":false,"truncated":false,"content":"# Getting Started\n\nThis guide covers local development for the Mappers Protocol stack: prerequisites, workspace installation, service startup, database setup, and validation.\n\n## Prerequisites\n\n| Tool                                                        | Supported baseline                                    | Purpose                         |\n| ----------------------------------------------------------- | ----------------------------------------------------- | ------------------------------- |\n| [Rust](https://rustup.rs/)                                  | Stable plus the Anchor-compatible toolchain           | Smart contract compilation      |\n| [Solana CLI](https://docs.solanalabs.com/cli/install)       | 1.18-compatible                                       | Cluster management and keypairs |\n| [Anchor CLI](https://www.anchor-lang.com/docs/installation) | Compatible with the repository’s Anchor configuration | Program build and tests         |\n| [Node.js](https://nodejs.org/)                              | 22 or newer                                           | Workspace tools and services    |\n| [pnpm](https://pnpm.io/)                                    | 11 or newer                                           | Root workspace package manager  |\n| [PostgreSQL](https://www.postgresql.org/)                   | 14 or newer                                           | API server database             |\n\n## Quick Start\n\n```bash\ngit clone https://github.com/mrphatom/mappers_contract.git\ncd mappers_contract\npnpm install\npnpm run typecheck:libs\npnpm run build\npnpm run typecheck:oracle\npnpm run test:oracle\n```\n\nThe repository uses one root `pnpm-lock.yaml`. The Oracle is a workspace package, and `pnpm install` is the supported installation command for the complete repository. The root preinstall guard rejects npm and yarn installs.\n\n## Repository Structure\n\n```text\nmappers_contract/\n|-- programs/project_mappers/     Anchor smart contract (Rust)\n|-- oracle/                       Off-chain verification service (workspace)\n|-- apps/api-server/              Express 5 REST API\n|-- apps/dashboard/               React 19 frontend\n|-- lib/                          SDK, database, schemas, and generated clients\n|-- tests/                        Anchor integration tests\n|-- scripts/                      Devnet and integration scripts\n|-- docs/wiki/                    Version-controlled wiki source\n```\n\n## Running Smart Contract Tests\n\n```bash\npnpm run test:anchor\n# Equivalent direct command:\nanchor test\n```\n\nThe test suite runs against localnet by default and covers job initialization, settlement, cancellation, validation errors, PDA derivation, and terminal-state protections. A Devnet run can be selected with `anchor test --provider.cluster devnet` when the required wallet and environment are available.\n\n## Running the API Server\n\nCreate a PostgreSQL database and configure the connection string before starting the API:\n\n```bash\ncreatedb mappers_dev\nexport DATABASE_URL=\"postgresql://localhost:5432/mappers_dev\"\nexport ORACLE_URL=\"http://localhost:3001\"\n```\n\nPush the current Drizzle schema from the root workspace:\n\n```bash\ncd lib/db\npnpm run push\ncd ../../apps/api-server\npnpm run dev\n```\n\nThe API listens on port 3000 by default. `ORACLE_URL` must be an explicitly configured HTTP(S) URL accepted by the API’s job-processing path.\n\n## Running the Dashboard\n\n```bash\ncd apps/dashboard\npnpm run dev\n```\n\nThe Vite development server uses port 5173 by default. The dashboard expects the API server at its configured local URL.\n\n## Running the Oracle\n\nThe Oracle is now a first-class member of the root pnpm workspace:\n\n```bash\ncp oracle/.env.example oracle/.env\ncd oracle\npnpm run dev\n```\n\nThe Oracle service requires the following environment values:\n\n| Variable               | Description                                              |\n| ---------------------- | -------------------------------------------------------- |\n| `SOLANA_RPC_URL`       | Solana RPC endpoint                                      |\n| `PROGRAM_ID`           | Mappers program address                                  |\n| `ORACLE_PRIVATE_KEY`   | Base58-encoded Oracle authority keypair; never commit it |\n| `HELIUS_GRPC_ENDPOINT` | Yellowstone gRPC streaming endpoint                      |\n| `GEMINI_API_KEY`       | Google Gemini credentials                                |\n| `ANTHROPIC_API_KEY`    | Anthropic Claude credentials                             |\n\nThe Oracle exposes health, job-tracking, and submission endpoints on its configured port, commonly 3001. Use `pnpm run typecheck:oracle` and `pnpm run test:oracle` from the repository root for its strict checks and test suite.\n\n## Workspace Commands\n\nRun these from the repository root:\n\n| Command                          | Description                                    |\n| -------------------------------- | ---------------------------------------------- |\n| `pnpm install`                   | Install all workspace dependencies             |\n| `pnpm install --frozen-lockfile` | Reproduce CI installation exactly              |\n| `pnpm run typecheck:libs`        | Typecheck shared libraries                     |\n| `pnpm run typecheck`             | Typecheck libraries, apps, scripts, and Oracle |\n| `pnpm run build`                 | Typecheck and build all packages               |\n| `pnpm run typecheck:oracle`      | Strictly typecheck Oracle                      |\n| `pnpm run test:oracle`           | Run the Oracle Vitest suite                    |\n| `pnpm run test:anchor`           | Run Anchor integration tests                   |\n| `pnpm exec prettier --check .`   | Check repository formatting                    |\n\n## Code Generation\n\nThe OpenAPI contract lives in `lib/api-spec/`. After changing it, regenerate the shared Zod schemas and React Query hooks:\n\n```bash\ncd lib/api-spec\npnpm run codegen\n```\n\nGenerated files in `lib/api-zod/` and `lib/api-client-react/` should not be edited manually.\n\n## End-to-End Devnet Flow\n\nStart the Oracle in one terminal, then run the integration script from another:\n\n```bash\n# Terminal 1\ncd oracle && pnpm run dev\n\n# Terminal 2\npnpm exec ts-node scripts/e2e-devnet.ts\n```\n\nThe flow requires a funded Devnet wallet, valid RPC and gRPC endpoints, Oracle credentials, and the deployed program ID.\n\n## Deployment\n\n| Network      | Program ID                                     | Status       |\n| ------------ | ---------------------------------------------- | ------------ |\n| Devnet       | `52yt1gCbPeiKP4JYjUVKmMJSgBMMcUx8xRGqozMKX2Mu` | Live         |\n| Mainnet-Beta | TBD                                            | Not deployed |\n\n## Troubleshooting\n\nIf installation fails, confirm that pnpm 11 is active and remove stale `node_modules` directories before retrying. Do not restore `oracle/package-lock.json`; the root pnpm lockfile is authoritative. If library typechecking fails, run `pnpm run typecheck:libs` first because the application packages consume those project references. If the Oracle does not detect jobs, verify the gRPC endpoint, program ID, RPC endpoint, and Oracle key. If the API cannot reach the Oracle, validate that `ORACLE_URL` is a complete HTTP(S) URL.\n\nSee [Architecture](Architecture.md), [Development Guide](Development-Guide.md), and [Release Notes](Release-Notes.md) for the next level of detail.\n"}