Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (87 loc) · 4.69 KB

CONTRIBUTING.md

File metadata and controls

120 lines (87 loc) · 4.69 KB
Raw

Contributing to Freighter Backend (V1)

TypeScript backend service powering the Freighter wallet. Provides indexing, subscriptions, feature flags, notifications, token balances, and pricing data.

For the Stellar organization's general contribution guidelines, see the Stellar Contribution Guide.

Prerequisites

Tool Version Install
Node.js >= 25.3.0 nodejs.org or nvm install 25
Yarn >= 1.22.5 npm install --global yarn
Docker Latest docker.com (for Redis)

Getting Started

Quick Setup with an LLM

If you use an LLM-powered coding assistant, you can automate the setup. The repo includes a quick start guide (LLM-QUICK-START.md) that checks your environment, installs missing tools, configures .env, and verifies the build.

Point your LLM assistant at LLM-QUICK-START.md and ask it to follow the steps.

If you don't use an LLM assistant, follow the manual setup below.

Manual Setup

git clone https://github.com/stellar/freighter-backend.git
cd freighter-backend
cp .env-EXAMPLE .env    # Then fill in values (see below)
yarn install
yarn start              # Dev mode (uses in-memory store, no Redis needed)

For production mode (requires Redis):

docker compose up -d    # Starts Redis Stack on port 6379
yarn build:prod
node build/index.js

Environment Variables

Copy .env-EXAMPLE to .env. For local development with yarn start, most variables can be left as not-set — the app uses an in-memory store by default.

Required for full functionality:

Variable Purpose How to obtain
MODE development or production Set to development for local dev
HOSTNAME Server hostname localhost
REDIS_PORT Redis port 6379 (Docker Compose default)
REDIS_CONNECTION_NAME Redis connection name Any string (e.g., freighter-dev)

Optional — features degrade gracefully:

Variable Purpose Notes
AUTH_EMAIL / AUTH_PASS Mercury indexer auth Only needed if USE_MERCURY=true
SENTRY_KEY Error tracking Leave as not-set for local dev
BLOCKAID_KEY Transaction scanning Leave as not-set for local dev
COINBASE_API_KEY/SECRET Pricing data Leave as not-set for local dev
FREIGHTER_HORIZON_URL Stellar Horizon endpoint Defaults to public Horizon if unset

Key Commands

yarn start              # Dev mode (in-memory store)
yarn build:prod         # Production build (webpack)
yarn test               # Jest unit tests
yarn test:ci            # Jest CI mode

Code Conventions

  • Formatting: Prettier + ESLint (extends @stellar/eslint-config)
  • Pre-commit hooks: pretty-quick --staged + lint-staged (ESLint fix)
  • Framework: Fastify v5 with CORS, Helmet, rate-limiting
  • Logging: Pino
  • Monitoring: Prometheus metrics via prom-client

Testing

yarn test               # Run all tests
yarn test:ci            # CI mode

Jest with ts-jest preset, Node test environment.

Pull Requests

  • Branch from main
  • Commit messages: action verb in present tense
  • All tests must pass
  • Code must be formatted (pre-commit hooks handle this)

CI runs on every PR: build + test (runTests.yaml).

Related Repositories

Security

  • Never log API keys, auth credentials, or user data
  • Rate limiting is enforced via Fastify plugin — don't bypass
  • Report vulnerabilities via the Stellar Security Policy — not public issues