auction-server

Auction Server

The Auction Server is a service that manages the auction process for the ExpressRelay protocol. It receives bids from searchers, groups them based on the permission key, sorts them, and submits the winning bids to the Express Relay contract using the relayer's private key.

Auctions for each permission key with at least a single bid will be conducted every block (current version has a fixed interval instead of per block):

• Bids will be sorted by a simple heuristic that tries to maximise the profit for the protocols
• The winning bids will be submitted on-chain
• On a successful submission:
  • All the bids involved in the auction will become finalised
• On an unsuccessful submission:
  • Bids will remain in a pending state and will be evaluated again in the next round of auction along with any new bids received in the meantime

⚠️ Auction server will make the best effort to only submit bids that will not revert on-chain but there is no guarantee. This means that a bid can become public without actual execution

⚠️ Bids can be submitted on-chain multiple times. The searcher is responsible for implementing security precautions to avoid replay attacks.

⚠️ Any sort of RPC staleness, network issues, networks forks, etc. can cause the auction server to:

• Submit a bid that will revert on-chain
• Not submit a bid that would have succeeded on-chain
• Submit a bid multiple times
• Create a suboptimal bundle of bids

Relayer is responsible for monitoring the health of these dependencies and landing the correct bids on-chain.

⚠️ Any information regarding the bids will remain private until the bid is submitted on-chain. From that point we consider the winning bids public and publish this information to other searchers too. Losing bids information will remain private forever (similar to a sealed-bid auction).

Build & Test

This package uses Cargo for building and dependency management. Simply run cargo build and cargo test to build and test the project. We use sqlx for database operations, so you need to have a PostgreSQL server running locally. Check the Migration section for more information on how to setup the database.

Blockchains are configured in config.yaml. You can use config.sample.yaml as a template.

Local Development

To start an instance of the webserver for local testing, you first need to perform a few setup steps:

1. Edit config.yaml to point to the desired blockchains and Express Relay contracts. You can use config.sample.yaml as a template.
2. Generate a secret key to be used for relaying the bids. The Express Relay contract should be deployed with this address as the relayer.

Once you've completed the setup, simply run the following command, using the secret from step (2).

cargo run -- run --subwallet-private-key <subwallet-private-key-in-hex-format>

This command will start the webservice on localhost:9000. You can check the documentation of the webservice by visiting http://localhost:9000/docs.

The webservice will try to export open telemetry traces to localhost:4317. You can customize the exporter endpoint by setting the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

You can run a local all in one jaeger instance to collect these traces by running:

docker run --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:1.63.0

And access the jaeger UI at http://127.0.0.1:16686.

DB & Migrations

Development

1. Postgres Database

sqlx checks the database schema at compile time, so you need to have the database schema up-to-date before building the project. You can create a .env file similar to the .env.example file and set DATABASE_URL to the URL of your PostgreSQL database. This file will be picked up by sqlx-cli and cargo scripts when running the checks.

In the current folder, install sqlx-cli by running cargo install sqlx-cli. Then, run the following command to apply migrations:

sqlx migrate run

We use revertible migrations to manage the database schema. You can create a new migration by running:

sqlx migrate add -r <migration-name>

Since we don't have a running db instance on CI, we use cargo sqlx prepare to generate the necessary info offline. This command will update the .sqlx folder. You need to commit the changes to this folder when adding or changing the queries.

2. ClickHouse Migrations

For ClickHouse, update the relevant environment variables (CLICKHOUSE_URL, CLICKHOUSE_NAME, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD) in your local .env file.

Then run migrations using:

env $(grep -v '^#' .env | xargs) cargo run migrate-clickhouse

You can spin up a local ClickHouse instance using Docker:

docker run -d \
  -p 18123:8123 \
  -p 19000:9000 \
  -e CLICKHOUSE_PASSWORD=clickhouse \
  --name some-clickhouse-server \
  --ulimit nofile=262144:262144 \
  clickhouse/clickhouse-server

Production

Before starting the server in production, you must apply database migrations manually.

Migrations are backward-compatible, so it's safe to run them while an older version of the server is still live.

---

1. Apply SQL Database Migrations

Run the following command with the actual database URL:

cargo run -- migrate --database-url <database-url>

2. Apply ClickHouse Migrations

To run ClickHouse migrations, use the migrate-clickhouse command with the actual variables:

cargo run -- migrate-clickhouse --clickhouse-url <clickhouse-url> --clickhouse-name <clickhouse-name> --clickhouse-user <clickhouse-user> --clickhouse-password <clickhouse-password>

• Auction server source code is licensed under the BUSL-1.1.