Safe Client Gateway

Motivation

The Safe Client Gateway serves as a bridge for the Safe{Wallet} clients (Android, iOS, Web).

It provides UI-oriented mappings and data structures for easier integration with several Safe{Core} services. In essence, it works as a bridge between the frontend and backend, ensuring smooth, efficient data exchange.

Documentation

• Client Gateway OpenAPI specification
• Deploying the service

Requirements

• Node.js v24.11.0 'Krypton' LTS (Node.js Release Schedule) – https://nodejs.org/en/
• Docker Compose – https://docs.docker.com/compose/

Installation

Optional: If you have NVM installed, you can run nvm use in the root folder of the project to use the recommended Node version set for this project.

We use Yarn as the package manager for this project. Yarn is bundled with the project so to use it run:

corepack enable && yarn install

The project requires some ABIs that are generated after install. In order to manually generate them, run:

yarn generate-abis

Development with Dev Containers

If you have Docker and the VS Code/Cursor Dev Containers extension installed, you can develop the project without installing Node, Yarn, or any of the backing services on your host:

1. Open the repository in VS Code/Cursor.
2. Run Dev Containers: Reopen in Container from the command palette.

On first build the container will install dependencies with yarn install --immutable (which also generates the required ABIs via the postinstall hook).

The following services start automatically alongside the dev container: Postgres (db), Postgres test DB (db-test), Redis (redis), and RabbitMQ (rabbitmq). The web, nginx, and pgadmin services from docker-compose.yml are NOT auto-started; if you need them, run them from the host with:

docker compose up <service>

Note: both db and db-test run with SSL enabled, so before you reopen in container — or any time you run docker compose up db/db-test from the host — make sure the self-signed key has owner-only permissions (see Running the services).

VS Code/Cursor installs the Biome, Claude Code, and ChatGPT extensions automatically inside the container.

Setup your env

We recommend using what is available in the .env.sample file:

cp .env.sample .env

Then uncomment the variables you need and edit your .env file with your configuration values.

Please review the required API keys in the .env file and ensure you have created the necessary keys for the services you plan to use.

Environment Variable Configuration

Configuration Files:

1. .env.sample.json: The source of truth for all environment variables

   • Contains variable names, descriptions, default values, and required status
   • Structured as an array of JSON objects
   • Version-controlled and validated

2. .env: Your local configuration (not in version control)

   • Copy variables from .env.sample.json as needed
   • Set required variables and override defaults

For Developers Adding New Environment Variables:

1. Add your variable to .env.sample.json:

   {
     "name": "MY_NEW_VARIABLE",
     "description": "Description of what this variable does",
     "defaultValue": "default-value",
     "required": false
   }

2. Add to Zod schema in configuration.schema.ts (if validation needed):

   MY_NEW_VARIABLE: z.string().optional(),

3. Use in configuration.ts:

   myNewVariable: process.env.MY_NEW_VARIABLE || 'default-value',

4. When you commit, the pre-commit hook will validate that all variables are documented

Manual Commands:

# Generate .env file from required variables
yarn env:generate

# Generate .env file (force overwrite existing)
yarn env:generate:force

# Generate or update .env file (creates if missing, updates if exists)
yarn env:generate:update

# Validate that all env vars are documented (verbose)
yarn env:validate

# Validate silently (Only exit if there is an error)
yarn env:validate:silent

Running the services

Both the db and db-test Postgres containers run with SSL enabled using a self-signed certificate stored in db_config/test/. Postgres refuses to start if the private key is group- or world-readable, so before launching either container (whether from the host or via the dev container) restrict the key to the owner:

# disallow any access to world or group
chmod 0600 db_config/test/server.key

This only needs to be done once per checkout (and again after a fresh git clone).

Running the app

1. Start Redis instance. By default, it will start on port 6379 of localhost.

docker compose up -d redis

If you run the service locally against a local Safe{Wallet} instance,

• set TX_SERVICE_API_KEY to a valid key to avoid hitting the Transaction Service rate limit
• set CGW_ENV=development
• set ALLOW_CORS=true

To generate a key, go to:

• Tx Service staging
• Tx Service production

2. Start the Safe Client Gateway

# development
yarn run start

# watch mode
yarn run start:dev

# production mode
yarn run start:prod

Test

The unit test suite contains tests that require a database connection. This project provides a db-test container which also validates the support for SSL connections.

Make sure the self-signed certificate key has the right permissions (see Running the services), then start the db-test container:

# start the db-test container
docker compose up -d db-test

# unit tests
yarn run test

# e2e tests
docker-compose up -d redis rabbitmq && yarn run test:e2e

# test coverage
yarn run test:cov

Linter and Style Guide

We use Biome as a linter and Prettier as a code formatter. You can run yarn run lint to execute Biome and yarn run format to execute Prettier.

These checks can be automatically executed using Git hooks. If you wish to install the provided git hooks:

yarn install
yarn husky install

Database Migrations

Database migrations are configured to execute automatically. To disable them, set the following environment variables:

RUN_MIGRATIONS=false
DB_MIGRATIONS_EXECUTE=false

For migrations to be generated automatically, the entity file must follow this structure and naming convention:

src/**/entities/*.entity.db.ts

The file should be located in the src folder, inside an entities directory. The filename should follow the format {FILE_NAME}.entity.db.ts, where {FILE_NAME} is replaced with your desired name.

Licensing

This repository contains code developed under two different ownership and licensing regimes, split by a defined cut-over date.

• Up to and including February 16, 2026 Code is © Safe Ecosystem Foundation and licensed under the MIT License. The final SEF-owned MIT snapshot is tagged as: sef-mit-final
• From February 17, 2026 onward New development is © Safe Labs GmbH and licensed under the Functional Source License, Version 1.1 (MIT Future License).

Users who require a purely MIT-licensed codebase should base their work on the sef-mit-final tag. The historical MIT-licensed code remains MIT and is not retroactively relicensed.

For full details, see LICENSE.md and NOTICE.md.