Skip to content

gravity-bridge-backend

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

gravity-bridge-backend

README.md

Gravity Bridge Backend

TypeScript and Express API for the Gravity Bridge web client.

The backend serves bridge data, chain metadata, transaction-related data, and a health endpoint, while scheduled jobs keep cached data fresh in environments where those jobs are enabled.

This repository is prepared to be published as a standalone open-source backend:

  • runtime configuration is environment-driven
  • local development uses a disposable PostgreSQL container
  • scheduled jobs are disabled by default in local setup
  • the contributor verify path runs lint, tests, and a production build

Requirements

  • Node.js 20 (.nvmrc is included)
  • Yarn 1.x
  • Docker with Compose support

Quick Start

cp .env.example .env
yarn install
yarn dev:up
yarn start:dev

The API listens on http://localhost:6060 by default.

Health check:

GET /healthz

Local Frontend Integration

The default local CORS configuration allows the frontend at:

  • http://localhost:8080
  • http://127.0.0.1:8080

If you change the frontend port or host, update CORS_ALLOWED_ORIGINS in .env.

Environment

Copy .env.example and adjust values as needed.

The most important settings are:

Variable Purpose
PORT HTTP port for the API
NODE_ENV Node environment
DEPLOYMENT_STAGE Stage label used by the app
DATABASE_URL_LOCAL Local PostgreSQL connection string
DATABASE_URL_TEST Test database connection string
DATABASE_URL Primary runtime database connection string
ENABLE_SCHEDULED_JOBS Enables cron/import jobs
CORS_ALLOWED_ORIGINS Comma-separated allowed frontend origins
COINMARKETCAP_API_KEY Optional live market data integration
GETH_FALLBACK_NODE_URL Ethereum RPC fallback
GETH_NODE_FOR_VALI_MONITORING_URL Ethereum RPC for monitoring jobs
INFURA_API_KEY Optional provider integration
ALCHEMY_API_KEY Optional provider integration
ETHERSCAN_API_KEY Optional provider integration
ALTHEA_API_URL External Gravity data source
GRAVITY_NODE_* Gravity node RPC / REST / gRPC endpoints

Local development works without external API keys. Optional live checks stay out of the default test suite unless you explicitly run yarn test:external.

Scripts

Command What it does
yarn start:dev Starts the API with nodemon
yarn dev:up Starts the local PostgreSQL container
yarn dev:down Stops the local PostgreSQL container
yarn lint Runs ESLint
yarn test Runs unit, integration, and smoke tests
yarn test:external Runs opt-in live dependency checks
yarn build Compiles TypeScript to build/
yarn verify Starts local dependencies, runs lint, tests, and build

Verification

Run:

yarn verify

This is the default contributor verification command for the backend.

For more detail on the test buckets and local troubleshooting, see TESTING.md.

Project Layout

  • src/server: Express server bootstrap and routing
  • src/controllers: request handlers and API models
  • src/data: datasources and repositories
  • src/jobs: scheduled import and cache-refresh jobs
  • src/configs: environment-driven runtime configuration
  • src/models: shared API and chain data models
  • test/: unit, database integration, smoke, and opt-in external tests

Operational Notes

  • ./scripts/dev-up.sh waits for PostgreSQL readiness before returning
  • ./scripts/verify.sh automatically starts and stops the local database
  • scheduled jobs are skipped unless ENABLE_SCHEDULED_JOBS=true

Security Notes

  • do not commit .env files or production credentials
  • keep newly added infrastructure endpoints configurable through env vars
  • if any credentials ever existed in private history before publication, rotate them before pushing a public repository