Skip to content

Latest commit

 

History

History
134 lines (94 loc) · 5.35 KB

README.md

File metadata and controls

134 lines (94 loc) · 5.35 KB
Raw

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

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.

Production

You need to apply the migrations manually on the production database before starting the server. Migrations are backward compatible, so it's ok to apply them while the server is running with the old schema. You can apply the migrations by running the following command:

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

Subwallet Management

Express relay contract uses subwallets as a secure mechanism to relay bids without using the main relayer wallet which holds the funds. You can add the subwallets addresses to the config.yaml file under the subwallets key and use their private keys for the relayer:

chains:
  development:
    # rest of the chain configuration
    subwallets:
      - 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
      - 0xdecafdecafdecafdecafdecafdecafdecafdecaf

To sync the subwallets with the on-chain contracts you can run:

cargo run -- sync-subwallets

License

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