Axelar <-> Starknet messaging monorepo

Architecture

This project implements an event-driven microservice architecture with communication through message queues. The system is designed for high throughput and parallel processing:

• Event-Driven Design: All components communicate asynchronously through message queues (NATS or Google Cloud Pub/Sub)
• Microservice Architecture: Separate services handle different responsibilities (subscriber, ingester, gas collector, gas refunder)
• Parallel Processing: Multiple ingester instances can run simultaneously, each with its own wallet, enabling parallel Starknet transaction execution
• Scalability: The architecture supports horizontal scaling by deploying additional instances of any component

Key components:

• Subscriber: Monitors Starknet events and publishes them to message queues
• Ingester: Consumes events from queues and executes Starknet transactions
• Gas Collector: Handles gas collection operations on demand i.e. k8s cron job.
• Gas Refunder: Processes gas refund requests

Development environment setup

Prerequisites

• Rust toolchain
• cargo-make - cargo install cargo-make
• scarb - Cairo/Starknet build tool
• starkli - Starknet CLI tool
• jq - JSON processor
• Configured Starknet wallet/account
• nats-server - for running with NATS (default)

Setup

git submodule update --init --recursive

Building

Cairo lang

# List of available commands
cargo make starknet build
cargo make starknet test
cargo make starknet fmt
cargo make starknet fmt-check

Rust workspace crates

# Lint
cargo make check

# Check for unused deps
cargo make unused-deps

# Run the tests
cargo make test
cargo make coverage

# Check if the CI tasks will pass
cargo make local-ci

# Audit deps
cargo make audit

# Format the code
cargo make fmt

Configuration

Default config + deployed contracts are at relayer-config-example.toml

Note: The gateway and gas service contract addresses in this config file are kept up-to-date and are used by the xtask commands for contract deployment.

Infrastructure

For deploying the infrastructure using Terraform, see the Terraform README.

Xtask

The project includes an xtask utility for common development workflows. See the xtask README for detailed documentation on available commands.

Runnning project

Nats (default)

Make sure to start nats

nats-server -c nats.conf
cp relayer-config-example.toml relayer-config.toml

edit relayer-config.toml to include accurate data

and then just run binary

cargo r

Google Cloud Platform

1. Install gcloud cli
2. Init

gcloud init

3. Set default login

gcloud auth application-default login

4. Start relayer with gcp feature

cargo run --no-default-features --features gcp

This command will start the Axelar-Starknet relayer and run all components, including the Starknet subscriber and ingester, with the gcp feature enabled.

Running Starknet Components

Starknet Subscriber

The starknet-subscriber binary is responsible for subscribing to Starknet events and processing them. You can run it with the following commands:

Using NATS

cargo run --bin starknet-subscriber --no-default-features --features nats

Using Google Cloud Platform (GCP)

cargo run --bin starknet-subscriber --no-default-features --features gcp

Starknet Ingester

The starknet-ingester binary is responsible for ingesting tasks and events from Starknet. You can run it with the following commands:

Using NATS

cargo run --bin starknet-ingester --no-default-features --features nats

Using Google Cloud Platform (GCP)

cargo run --bin starknet-ingester --no-default-features --features gcp

Health Checks

Both the starknet-subscriber and starknet-ingester binaries include health check endpoints to ensure they are operational. These health checks validate the connectivity and functionality of the components, including the event queue publisher, task queue consumer, and state store.

To run the health checks, ensure the binaries are running and configured correctly. The health check server will expose endpoints that can be queried to verify the status of the components.