solana-developer-platform: Instructions file for Codex

Solana Developer Platform

This file is the canonical agent guide for this repository.

Repo layout

• apps/sdp-api: Node.js API deployed to Cloud Run, OpenAPI source, route handlers, Postgres/Redis integrations
• apps/sdp-web: dashboard application
• apps/sdp-docs: public documentation site and generated API reference
• packages/sdp-types: shared runtime types and shared product constants
• packages/sdp-design-tokens: shared design tokens (CSS custom properties, Tailwind theme mapping) and the refresh theme scope; see its README
• packages/sdp-ui: the dashboard's UI primitives (@sdp/ui) over @solana/design-system and the design tokens; apps/sdp-web/src/components/ui/* re-exports them; see its README

Source of truth

• Public API contract: apps/sdp-api/src/openapi/**
• Public docs navigation: apps/sdp-docs/content/docs/meta.json
• Generated API docs: apps/sdp-docs/content/docs/reference/api/**
• AI discovery resources: apps/sdp-docs/public/llms.txt and apps/sdp-docs/public/llms-full.txt

Generated files

Do not hand-edit generated artifacts. Regenerate them with the owning script.

• OpenAPI JSON: pnpm -C apps/sdp-api openapi:generate
• Route actions inventory (apps/sdp-api/src/openapi/route-actions.generated.json): pnpm -C apps/sdp-api route-actions:generate
• API playground catalog: pnpm generate:api-playground
• API reference docs: pnpm -C apps/sdp-docs generate:api
• AI discovery resources: pnpm -C apps/sdp-docs generate:ai

Public vs internal surfaces

Public docs and AI artifacts should mirror the supported public surface only.

• Public API families are the ones the deployment's release channel runs (SDP_RELEASE_CHANNEL; prod runs stable, stage beta, dev experimental), so no deployment documents a route it refuses with 403. Every surface derives from the module stages in packages/sdp-types/src/release-channels.ts and the route inventory in apps/sdp-api/src/routes/route-modules.ts; never hand-maintain another list or move content to hide a module.
  • Public OpenAPI: createPublicOpenApiDocument({ releaseChannel }) in apps/sdp-api/src/openapi/spec.ts drops other modules' routes, and openapi/release-channel-values.ts drops their enum values, examples and oneOf branches from shared schemas (classify a new wallet-binding permission or wallet purpose there; an action's owner comes from the registry in packages/sdp-types/src/actions.ts). The API serves /openapi.json and /llms.txt for its own channel at runtime.
  • Docs site, API reference, Postman and llms*.txt: the docs build reads SDP_RELEASE_CHANNEL (required on Vercel, set per environment like sdp-web; the Dockerfile build arg defaults to experimental). The API writes what the channel publishes (modules and ramp providers, Earn's hold included) to a manifest the docs build reads. Gates follow module declarations: a page about one module takes module: <module> frontmatter (or rampProvider: <provider>), shared pages never name a module, and lists of modules, providers or operations are generated blocks (see apps/sdp-docs/CLAUDE.md, "Release Channels"). Committed generated artifacts are built at experimental (an unset channel), so CI drift checks see every module; CI also checks links on stable.
  • API playground: the committed catalog holds every channel's operations with their module; the dashboard filters it, and the hand-authored forms, by its own channel.
• earn is held out of every public surface until launch (PRO-2038), independently of its release-channel stage: EARN_PUBLIC_SURFACE_PUBLISHED in apps/sdp-api/src/openapi/spec.ts drops the family from the public OpenAPI document, and the API reference, Postman collection, playground catalog and AI files regenerate from it. Flipping it back is a PRO-1872 security sign-off PR. The internal document and the runtime are unchanged, except GET /v1/projects/{projectId}/provider-availability, which omits Earn entries while the flag is false so the response matches the public document.
• Hidden/internal families stay out of public AI resources unless product policy changes: admin, onboarding, auth, organizations, members, api-keys
• Earn has two access tiers. Only strategy catalogue reads, deposit and withdrawal previews, withdrawal-route discovery, and unsigned instant deposit/direct-withdrawal builds may be keyless. Queued request and cancellation builds, submits, tenant reads, programs, custody routes, and the aggregate movement feed always require authentication. Keep this matrix aligned across the router, the internal OpenAPI document and the Embedded Yield guide, which is unpublished until PRO-2038 and lives at apps/sdp-docs/content/unpublished/guides/embedded-yield.mdx, outside the built content/docs tree.
• Promoting a route into the public OpenAPI document is a security-relevant scope change, not a docs edit: the PR needs a named security sign-off. For earn the pinned list in apps/sdp-api/src/openapi/spec.test.ts enforces this (see apps/sdp-api/src/routes/earn/CLAUDE.md, "Public OpenAPI promotion").