Local development

Use Node.js 24, npm, and Foundry with support for the Solidity version pinned in contracts/foundry.toml. Run the following commands from a checkout of the application repository, not this documentation repository.

Install and build

npm ci --prefix contracts --ignore-scripts
npm ci --prefix backend
npm ci --prefix frontend
forge build --root contracts

The project has separate package manifests and lockfiles for contracts, backend, and frontend. Initial contract compilation may download the pinned compiler.

Run against an existing deployment

Prepare backend configuration:

cd backend
cp .env.example .env

Edit that local file with your dedicated RPC endpoint, the intended chain, a verified community factory, and its deployment block. Set the public API origin and exact browser origins. See configuration and operations for required and optional fields.

npm run dev

In another terminal, from the application repository:

cd frontend
cp .env.example .env
npm run dev

The normal local values are VITE_API_URL=http://localhost:8787 and VITE_ROBINHOOD_CHAIN_ID=46630. Open the frontend URL printed by the server, usually http://localhost:3000.

The frontend chain, backend chain, wallet network, and deployment addresses must agree. Standard backend startup requires a configured RPC and factory; it does not substitute a shared public RPC. A disconnected API produces an error in the interface.

Browser wallet trial on testnet

The explicit trial command supports wallet-based deployment on Robinhood testnet:

npm --prefix backend run trial

Run the frontend separately, then use Testnet setup or the creation preparation action. Keep the trial service running while using locally hosted metadata.

Property	Trial behavior
Network	Testnet only, chain ID 46630
API listener	127.0.0.1:8787
RPC	Process ROBINHOOD_RPC_URL when supplied; otherwise the public testnet endpoint
Deployments	Community factory, two valueless demo tokens, native factory, then native trading router as required
Signing	The browser wallet signs each missing deployment
Persistence	Saved transaction references and separate index/media state under the trial data directory

The first four deployments establish the base/native launch setup; ETH trading can require a fifth transaction for the trading router. Confirmed deployments are reused. Rejection stops the sequence until the user resumes it. The demo faucet tokens have no supplied DEX liquidity, so use them for in-kind tests rather than assuming they support an ETH launch.

Trial setup GET routes return a process control token. Setup POSTs require X-RRR-Trial-Token and accept only the compiled deployment inputs and verifiable receipts. These are local development routes, not production provisioning endpoints.

If restoreBlocked is true, repair connectivity or recover the saved session and restart. The service deliberately preserves saved deployment references. Choosing a new TRIAL_DATA_DIR starts an independent trial; it does not recover the previous one.

Validate application changes

These commands mirror the repository’s validation workflow:

forge build --root contracts --sizes
forge test --root contracts --offline
node contracts/scripts/export-abis.mjs
npm --prefix backend run typecheck
npm --prefix backend test
npm --prefix frontend run lint
npm --prefix frontend run typecheck
npm --prefix frontend test
npm --prefix frontend run build

When a contract changes, review the regenerated files in contracts/abi. CI checks that ABI exports match the committed versions.

For end-to-end local fixtures, stop any service using the required local ports and run:

node --experimental-strip-types backend/scripts/local-integration.mjs
node --experimental-strip-types backend/scripts/trial-integration.mjs

The first script runs the actual frontend protocol functions through the HTTP API and an ephemeral Anvil chain. It covers signed metadata, approvals, creation, indexing, minting, redemption, pending-receipt recovery, claims, closure, and gateway restrictions. The trial integration script exercises the wallet deployment setup against local fixtures. Neither requires funding a public-network account.

Fork smoke scripts are separate from these deterministic fixtures. Check each script’s inputs and deployment assumptions before using a live RPC. Passing local tests does not establish current public-network liquidity or successful browser-wallet execution.

Common setup failures

Symptom	What to check
Backend refuses to start	Required environment fields, chain ID, reachable historical RPC, contract bytecode and venue bindings
Browser requests return 403	ALLOWED_ORIGINS must include the exact frontend origin, including its port
Frontend and backend networks differ	Both chain variables, rebuilt frontend assets, and wallet network
Trial reports missing artifacts	Run forge build --root contracts before starting the trial
Existing data directory is rejected	It is bound to another chain, factory set, or deployment block; use the correct directory
A recent basket has no quote yet	Check the selected quote block and retry when provider state catches up