DOCSEARCHbyAlgolia
Submit Docs

Safe Transaction Service

repository·main·Indexed 42 days ago

https://github.com/safe-global/safe-transaction-service

A service that tracks transactions sent via Safe contracts using event indexing and JSONRPC tracing. It provides automatic transaction detection, endpoints for off-chain signature collection, and pending transaction monitoring. Supports production deployment via tracing mode or L2 event indexing (version 3.0.0+), and includes tools for reindexing ERC20, ERC721, and ERC4337 UserOperations.

Tokens
9.1K
Snippets
44
Records
50
Agent score
53%

What's inside Safe Transaction Service

  1. Set up Safe Transaction Service for development

    main

    To set up a local development environment, use uv to manage dependencies and virtual environments. Follow these steps:

    1. Install uv.
    2. Sync dependencies and activate the virtual environment:
      uv sync --group dev --frozen
source .venv/bin/activate
    3. Install pre-commit hooks and configure the environment:
      pre-commit install -f
cp .env.dev .env
    4. Run tests:
      ./run_tests.sh

    To run end-to-end (e2e) tests, you must export the following environment variables:

    export ETHEREUM_MAINNET_NODE="https://erigon-node-mainnet.dev/"
export ETHEREUM_4337_BUNDLER_URL="https://eth-sepolia.g.alchemy.com/v2/$API_KEY"
./run_tests.sh
    uv sync --group dev --frozen
source .venv/bin/activate
pre-commit install -f
cp .env.dev .env
./run_tests.sh

  3. Load default Safe Contracts Metadata

    main

    To load default Safe contract information (descriptions and logos), use one of the following methods:

    Method 1: Environment Variable Set ENABLE_SAFE_SETUP_CONTRACTS=1 in your environment.

    Method 2: Management Command Run the following command:

    python manage.py setup_safe_contracts --force-update-contracts

  5. Set up production using event indexing (L2 mode)

    main

    Since version 3.0.0, the service can use event indexing when the SafeL2 version is used. This is recommended for networks where transaction fees are not a concern, as it removes the need for a tracing node. Only contracts from v1.3.0 onwards with L2 events will be indexed.

    1. Copy the L2 sample environment file:
      cp .env.l2.sample .env
    2. Edit the .env file:
      • Set ETHEREUM_NODE_URL (e.g., a Polygon public node).
      • Set a strong DJANGO_SECRET_KEY.
    3. Build and start the service:
      docker-compose build --force-rm
docker-compose up
    
```bash
cp .env.l2.sample .env
# Edit .env to set ETHEREUM_NODE_URL and DJANGO_SECRET_KEY
docker-compose build --force-rm
docker-compose up

  6. Set up production using tracing mode

    main

    Tracing mode is the recommended configuration for production. It requires a node with the JSONRPC-trace-module enabled.

    1. Copy the tracing sample environment file:
      cp .env.tracing.sample .env
    2. Configure the following required parameters in .env:
      • DJANGO_SECRET_KEY: A strong key.
      • ETHEREUM_NODE_URL: The HTTP/S address of an Ethereum node (can be the same as the tracing URL).
      • ETHEREUM_TRACING_NODE_URL: The HTTP/S address of an OpenEthereum node with tracing enabled.
    3. (Optional) If you prefer to rely on trace_block instead of trace_filter for internal transaction indexing, set:
      • ETH_INTERNAL_NO_FILTER=1
    4. Build and start the service:
      docker-compose build --force-rm
docker-compose up

    Once running, the service is available at localhost:8000. You can verify the setup with:

    curl 'http://localhost:8000/api/v1/about/'

    Task queue status can be checked at http://localhost:5555/.

    cp .env.tracing.sample .env
# Configure DJANGO_SECRET_KEY, ETHEREUM_NODE_URL, and ETHEREUM_TRACING_NODE_URL
docker-compose build --force-rm
docker-compose up

# Verify setup
curl 'http://localhost:8000/api/v1/about/'

  7. Set up a custom network

    main

    To support a new network, you can follow these steps:

    1. Deploy Contracts: Deploy Safe contracts using the deployment instructions.
    2. Register Network: Provide a PR adding the deployment block number and the address to safe-eth-py. Note that the address is the same for every network.
      • For the PR to be accepted, the network must be listed on ethereum-lists/chains.
      • Only ProxyFactory and GnosisSafeL2 must be configured. Add +L2 to the Safe L2 contract versions to enable event indexing.
    3. Admin Panel Alternative: If you cannot wait for a PR, you can configure the network manually via the admin panel under Master Copies and Proxy Factories.

    Recommendation: Use event indexing for every network where transaction fees are not relevant to avoid the need for a tracing node.

  8. Deploy the Safe Transaction Service using Docker Compose

    main

    The project provides a docker-compose.yml file to orchestrate the full stack of the Safe Transaction Service. The stack includes an Nginx reverse proxy, a web service, Celery workers (indexer, contracts/tokens, and scheduler), a Redis cache, a RabbitMQ message broker, a PostgreSQL database, and optional services like Ganache for local blockchain development and Flower for Celery monitoring.

    docker-compose up

  9. Setup Transaction Service required tasks via setup_service command

    main

    Run the setup_service management command to initialize the required Celery periodic tasks and configure Safe contract addresses (Master Copies and Proxy Factories) for the current network.

    This command performs the following actions:

    1. Cleans up old tasks: Removes any existing PeriodicTask entries that start with safe_transaction_service to prevent duplicates.
    2. Registers periodic tasks: Re-creates the standard set of background tasks (e.g., checking reorgs, indexing events, processing internal transactions) using django-celery-beat.
    3. Configures Safe addresses:
      • Sets up SafeMasterCopy singletons (addresses for core Safe contracts).
      • Sets up ProxyFactory addresses.
      • If the network is not in the local MASTER_COPIES or PROXY_FACTORIES lists, it attempts to fetch default addresses directly from the blockchain.
    4. Initializes ERC20/721 indexing: Ensures the IndexingStatus for ERC20/721 events is correctly synchronized with the deployment blocks of known Safe Master Copies.
    python manage.py setup_service

  10. Use Docker profiles for Ganache and Flower

    main

    To keep the default deployment lightweight, certain services are assigned to specific Docker profiles. You must explicitly enable these profiles to run them:

    • Ganache (Local blockchain): Use the develop profile.
    • Flower (Celery monitoring): Use the debug profile.

    To run with a profile, use:

    docker-compose --profile develop up

  12. Fix indexing issues

    main

    If transactions or asset transfers (ERC20/721) are missing from the API, you may need to run maintenance commands. It is recommended to run these inside tmux on either the web or worker instances.

    General Fix

    To attempt an automatic fix for missing transactions:

    python manage.py check_index_problems

    Note: This does not fix token-related transactions (ERC20/721) and may take a long time as it compares database data with blockchain data for every Safe.

    Manual Reindexing

    If you know the block number where issues began, manual reindexing is much faster:

    For Master Copies (Safes):

    python manage.py reindex_master_copies --from-block-number X --addresses 0x111 0x222

    (The --addresses argument is optional; providing specific Safe addresses makes the process significantly faster).

    For ERC20/ERC721 Transfers:

    python manage.py reindex_erc20 --from-block-number X --addresses 0x111 0x222
    # Automatic fix (slow, excludes tokens)
python manage.py check_index_problems

# Fast manual reindex for Safes
python manage.py reindex_master_copies --from-block-number X --addresses 0x111 0x222

# Fast manual reindex for ERC20/721
python manage.py reindex_erc20 --from-block-number X --addresses 0x111 0x222