> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/engineering-guide/10-development.md). # Development [← Contracts and APIs](/nytshift-docs/engineering-guide/09-contracts-and-apis.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Testing and verification →](/nytshift-docs/engineering-guide/11-testing-and-verification.md) The development workflow is local-first and deterministic. Most tests require no network, wallet, venue credential or signer. Connected audits are separate and explicit. ## Prerequisites | Tool | Baseline | | ------- | ------------------------------------------------------------------------------------------ | | Node.js | 24 or newer | | pnpm | 11.7.0 via Corepack | | Python | Environment compatible with `services/execution-py/pyproject.toml` | | Git | Clean exact-commit workflows are required for public release artifacts | | OS | Windows is supported for development; public artifacts are built and verified on Linux x64 | ## Bootstrap ```powershell corepack enable pnpm install Copy-Item .env.example .env.local pnpm preflight pnpm contracts:check pnpm typecheck pnpm test ``` Do not populate signing keys to work on the UI, public market data, paper engine, contracts or agents. Leave: ```dotenv EXECUTION_MODE=disabled ALLOW_MAINNET=false ARCUS_EXECUTION_MODE=disabled ARCUS_ALLOW_MAINNET=false NIGHTSHIFT_ARCUS_WITHDRAWAL_MODE=disabled NIGHTSHIFT_ARCUS_WITHDRAWAL_ALLOW_MAINNET=false ``` Secrets and private keys never belong in `.env.example`, tracked `.env` files, browser code, tests, fixtures, screenshots or logs. ## Run the product ### Development servers ```powershell pnpm dev ``` `pnpm dev:mock` exists for explicitly labelled Robinhood Chain mock development only. Production rejects mock RHC mode. ### Supervised local production ```powershell pnpm local:init pnpm local:start pnpm local:status pnpm local:health pnpm local:stop ``` The supervisor binds loopback, validates safe production settings, monitors `/api/health` and does not revive a failed build as if it were healthy. ## Typical change sequence 1. Read `AGENTS.md`, `START_HERE.md` and the relevant ticket/runbook. 2. Locate the canonical contract and state owner. 3. Inspect current tests before editing. 4. Change shared types/contracts before producers and consumers. 5. Implement one vertical slice with explicit degraded/blocked behavior. 6. Add deterministic tests for success, malformed input, upstream failure, stale state and replay/ambiguity where relevant. 7. Run proportional local gates during iteration. 8. Run the complete handoff gates before release. 9. Update normative docs/runbooks when behavior or operational boundaries change. ## TypeScript conventions * Parse external input at the boundary; do not cast provider JSON into authority. * Prefer pure domain functions in packages/services over route-local business logic. * Model unavailable, stale, partial and ambiguous states explicitly. * Use exact decimal strings for capital boundaries. * Preserve venue/symbol/market identity in types and cache keys. * Keep browser preferences versioned, bounded and non-authoritative. * Do not log raw account/provider payloads from contract failures. ### Terminal compatibility-route budgets The legacy `/terminal` route remains available while customer workflows migrate to `/app/*`, but it must stay decomposed. The reviewed ceilings are 30 lines for the wrapper, 1,400 for the composition controller, 1,200 for the presentational workspace, 800 for an action module, 700 for a data/operator module and 30 React hooks per state-domain hook. These are regression ceilings, not targets: new product work belongs in a narrower route workspace or domain module. Budget changes require an explicit architecture rationale and full terminal E2E evidence. Terminal modules call the registered market, account, profile, execution, agent, operator or RHC browser client. A successful response must satisfy its registered shared schema or bounded endpoint contract before state observes it. An unregistered route fails with `API_RESPONSE_CONTRACT_UNREGISTERED`; malformed success payloads fail with `API_RESPONSE_CONTRACT_INVALID`. ## Python signer conventions * Signer routes bind loopback and require internal authentication. * Validate all request fields again in Python. * Use `Decimal`/integer quantization before SDK conversion. * Persist idempotency/action claims before network I/O. * Refuse unsafe schema/integrity/WAL state. * Never automatically resubmit an unknown outcome. * Keep Arcus and Hyperliquid account/key/network scopes separate. ## Adding a public API route 1. Define or select a generated response contract. 2. Validate query/path/body before provider work. 3. Use the shared official-origin runtime and byte/concurrency limits. 4. Normalize at the adapter edge. 5. Validate before serialization. 6. Attach version/contract headers. 7. Return fixed errors without raw upstream bodies. 8. Add route tests for malformed input, provider failure, contract failure and privacy exclusions. ## Adding venue data Do not begin from a component. Begin from identity and provenance: * authoritative venue documentation/source; * exact instrument identity and metadata cardinality; * supported network and settlement asset; * snapshot and stream semantics; * nonce/sequence recovery rules; * time/freshness budget; * precision/quantization; * which consumers may use the observation; * explicit behavior on schema drift. Then land adapter → contract → producer → consumer → tests. ## Local durable state Application stores default under `~/.nightshift`. Paths can be overridden only where documented and must remain outside tracked source. Public application backups and signer cold backups are intentionally separate. Stop the relevant supervisor before restore. ## Debugging order When a UI value is unavailable, trace it in this order: 1. live catalog identity; 2. provider transport/health; 3. runtime validation; 4. temporal/reference classifier; 5. consumer projection; 6. API contract serialization; 7. browser context/sequence guard; 8. renderer state. This avoids “fixing” a presentation symptom by bypassing the data authority that rejected it. Continue with [Testing and verification](/nytshift-docs/engineering-guide/11-testing-and-verification.md), then consult [START\_HERE.md](https://github.com/Nytshift/nytshift/tree/agent/nightshift-paper-db-live-readiness/START_HERE.md) for the current release boundary. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nytshift.gitbook.io/nytshift-docs/engineering-guide/10-development.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.