Skip to content

database

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

database

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
conf
conf
 
 
sql-pool-indexer
sql-pool-indexer
 
 
sql-solana
sql-solana
 
 
sql
sql
 
 
README.md
README.md
 
 

README.md

Here we document the current state of the database. The history of these changes lives in the sql folder which contains all migrations. This document shows the schema and the purpose of the tables.

Code that directly interfaces with the database through SQL queries lives in the database. This crate is often wrapped into higher level components by consumers.

With a live database information for all tables can be retrieved with the \d command and information for a specific table with \d MyTable.

Some tables only store data emitted via smart contract events. Because we only have a single deployment of the GPv2Settlement settlement contract shared across staging and production environments events related to staging and production orders and settlements will be present in both the staging and production databases. CoWSwapEthFlow we actually deployed twice so events related to the staging environment should only show up in the staging DB and likewise for production. It's also important to note that we only index events from blocks that we are certain will not get reorged. That means specifically that events will be indexed with a block delay of at least 64.

app_data

Associates the 32 bytes contract app data with the corresponding full app data.

See here for more details. In this table the contract app data is either the old unixfs based scheme, or the new keccak scheme. The new scheme can be validated by keccak-256 hashing the full app data, which should produce the contract app data. The old scheme cannot be validated.

Column Type Nullable Details
contract_app_data bytea not null 32 bytes. Referenced by orders.app_data.
full_app_data bytea not null Is utf-8 but not stored as string because the raw bytes are important for hashing.
creation_timestamp timestamptz not null when the entry was created or when column was added (DEFAULT NOW() for new and 1970-01-01 for historical data)

Indexes:

  • "app_data_pkey" PRIMARY KEY, btree (contract_app_data)

auction_prices

Stores the native price of a token in a given auction. Used for computations related to CIP-20.

Column Type Nullable Details
auction_id bigint not null in which auction this price was provided
token bytea not null address of the token the price refers to
price numeric not null the atoms of ETH that can be bought with 1 atom of the token

Indexes:

  • PRIMARY KEY: btree(auction_uid, token)

auctions (and auctions_id_seq counter)

Contains only the current auction to decouple auction creation in the autopilot from serving it in the orderbook. A new auction replaces the current one and uses the value of the auctions_id_seq sequence and increase it to ensure that auction ids are unique and monotonically increasing.

Column Type Nullable Details
id bigint not null other tables refer to this as auction_id
json jsonb not null serialized version of the auction. Technically the format is unspecified. The only requirement is that whatever format the autopilot stores can be parsed by the orderbook.

Indexes:

  • PRIMARY KEY: btree(id)

competition_auctions

Contains all auctions for which a valid solver competition exists.

Column Type Nullable Details
id bigint not null other tables refer to this as auction\_id
block bigint not null the block number on top of which the auction was created
deadline bigint not null the block number until which all winning solutions are expected to be settled on-chain.
order_uids bytea[] not null orders that are part of the auction
price_tokens bytea[] not null native price tokens
price_values numeric[] not null native price values, mapped one-to-one with price\_tokens
surplus_capturing_jit_order_owners bytea[] not null surplus capturing jit order owners that are part of the auction
penalty_caps_native numeric[] nullable caps on the penalty a solver can incur for winning an order but failing to execute it, in native token wei, mapped one-to-one with order\_uids; null for auctions created before this column existed or while penalties were disabled

Indexes:

  • PRIMARY KEY: btree(id)
  • competition_auction_deadline: btree(deadline)
  • competition_auctions_order_uids_gin: gin(order_uids)

ethflow_orders

EthFlow orders get created with the very generic ICoWSwapOnchainOrders smart contract interface. However this interface doesn't return all the information that is required for EthFlow orders. This extra data is stored here whereas the generic data is stored in onchain_placed_orders.

Column Type Nullable Details
uid bytea not null other tables refer to this as order_uid
valid_to bigint not null unix timestamp in seconds when the order expires (the native timestamp format in the EVM)

Indexes:

  • PRIMARY KEY: btree(uid)
  • ethflow_user_valid_to: btree(valid_to)

ethflow_refunds

For orders buying some token with native ETH users temporarily transfer ownership of their ETH to the ethflow contract. When their order expires the refunder service automatically returns the ETH to the user. The table stores data about the transactions that refunded expired orders.

Column Type Nullable Details
order_uid bytea not null order that got refunded
block_number bigint not null in which block the order got refunded
tx_hash bytea not null hash of the transaction that refunded the order

Indexes:

  • PRIMARY KEY: btree(order_uid)

flyway_schema_history

We use flyway to do migrations of our database schema. This table contains metadata for flyway to know which and when migrations have been applied. Since this table only contains data managed by flyway and we didn't encounter any need to take a closer look at it we'll just refer to the flyway docs.

interactions

The settlement contract allows associating user provided interactions to be executed before and after an order. This table stores these interactions and associates them with the respective orders.

Column Type Nullable Details
order_uid bytea not null order that this interaction belongs to
index integer not null index indicating in which interactions should be executed in case the same order has multiple interactions (ascending order)
target bytea not null address of the smart contract this interaction should call
value numeric not null amount of ETH this interaction should send to the smart contract
data bytea not null call data that contains the function selector and the bytes passed to it
execution enum not null in which phase the interaction should be executed

Indexes:

  • PRIMARY KEY: btree(order_uid, index, execution)

invalidations

Stores data of OrderInvalidated events emitted by invalidateOrder() of the settlement contract.

Column Type Nullable Details
block_number bigint not null block in which the event was emitted
log_index bigint not null index in which the log was emitted
order_uid byteai not null order that got invalidated

Indexes:

  • PRIMARY KEY: btree(block_number, log_index)
  • invalidations_order_uid: btree(order_uid, block_number, log_index)

last_indexed_blocks

Stores the last block that was indexed for a given contract. On restarts the system continues indexing events after the last stored block for the related contract. contract could be something like a readable name, an address, or a combination of the two. Should it ever become necessary events can be re-indexing by:

  1. shutting down the autopilot
  2. setting block_number of the relevant contract to the desired block in the past
  3. restarting the autopilot
Column Type Nullable Details
contract text not null event index this row keeps track of (e.g. settlements)
block_number bigint not null last block that was successfully indexed for the contract (last indexed event could be way older than this if the tracked contract emits events very rarely)

Indexes:

  • PRIMARY KEY: btree(contract)

onchain_order_invalidations

Stores data of OrderInvalidation events emitted by the ICoWSwapOnchainOrders interface.

Column Type Nullable Details
block_number bigint not null block in which the event was emitted
log_index bigint not null index in which the log was emitted
uid byteai not null order that got invalidated

Indexes:

  • PRIMARY KEY: btree(uid)
  • invalidation_event_index: btree(block_number, log_index)

onchain_placed_orders

Stores data of OrderPlacement events emitted by the ICoWSwapOnchainOrders interface plus some metadata.

Column Type Nullable Details
uid bytea not null order that got created also known as order_uid
sender bytea not null user that created the order with the smart contract
is_reorged boolean not null if the backend detects that a block creating an order got reorged it gets invalidated with this flag
block_number bigint not null block in which the order was created
log_index bigint not null index in which the OrderPlacement event was emitted
placement_error enum nullable what error happened when placing the order

Indexes:

  • PRIMARY KEY: btree(uid)
  • event_index: btree(block_number, index)
  • order_sender: hash(sender)
  • okay_onchain_orders: btree(uid) WHERE placement_error IS NOT NULL

order_events

Stores timestamped events throughout an order's life cycle. This information is used to get detailed metrics on a per order basis.

Column Type Nullable Details
order_uid bytea not null order this event belongs to
timestamp timestamptz not null when the event was registered
label enum not null which event happened exactly
reason enum nullable why the order was filtered or marked invalid (only set for filtered and invalid labels)

Indexes:

  • order_events_by_uid: btree(order_uid, timestamp)

order_execution

Contains metainformation for trades, required for reward computations that cannot be recovered from the blockchain and are not stored in a persistent manner somewhere else. Protocol fee tokens/amounts are stored in the same order as fee policies in fee_policies table.

Column Type Nullable Details
order_uid bytea not null which order this trade execution is related to
auction_id bigint not null in which auction this trade was initiated
reward double not null revert adjusted solver rewards, deprecated in favor of CIP-20
executed_fee numeric not null fee taken for execution of the trade
executed_fee_token bytea not null token in which the executed fee is taken
block_number bigint not null block in which the order was executed
protocol_fee_tokens bytea[] not null tokens in which the protocol fees are taken
protocol_fee_amounts numeric[] not null amounts of protocol fees taken, aligned protocol_fee_tokens array

Indexes:

  • PRIMARY KEY: btree(order_uid, auction_id)
  • order_creation_timestamp: btree(creation_timestamp)
  • order_owner: hash(owner)
  • order_quoting_parameters: btree(sell_token, buy_token, sell_amount)
  • order_valid_to: btree(valid_to)
  • user_order_creation_timestamp: btree(owner, creation_timestamp DESC)
  • user_valid_to: btree(valid_to)
  • version_idx: btree(settlement_contract)

order_quotes

Quotes that an order was created with. These quotes get stored persistently and can be used to evaluate how accurate the quoted fee predicted the execution cost that actually happened on-chain.

Column Type Nullable Details
order_uid bytea not null order that this quote belongs to
gas_amount double not null estimated gas used by the quote used to create this order with
gas_price double not null gas price at the time of order creation
sell_token_price double not null ether-denominated price of sell_token at the time of quoting. The ether value of x sell_tokens is x * sell_token_price.
sell_amount numeric not null sell_amount of the quote used to create the order with
buy_amount numeric not null buy_amount of the quote used to create the order with
solver bytea not null public address of the solver that provided this quote
verified boolean not null information if quote was verified
metadata json not null additional data associated with the quote in json format
creation_timestamp timestamptz not null when the entry was created (DEFAULT NOW() for new and 1970-01-01 for historical data)
auction_id bigint nullable the auction competition that was the basis for this quote, the limit price of fast path executions will be derived from this competition

Indexes:

  • PRIMARY KEY: btree(order_uid)
  • order_quotes_creation_timestamp: btree(creation_timestamp)

orders

Contains all relevant signed data of an order and metadata that is important for correctly executing the order with the GPv2Settlement smart contract.

Column Type Nullable Details
uid bytea not null 56 bytes identifier composed of a 32 bytes hash over the order data signed by the user, 20 bytes containing the owner and 4 bytes containing valid_to.
owner bytea not null address who created this order and where the sell_token will be taken from, note that for ethflow orders this is the CoWSwapEthFlow smart contract and not the user that actually initiated the trade
creation_timestamp timestamptz not null when the order was created
sell_token bytea not null address of the token that will be sold
buy_token bytea not null address of the token that will be bought
sell_amount numeric not null amount in sell_token that should be sold at most
buy_amount numeric not null amount of buy_token that should be bought at least
valid_to timestamptz not null point in time when the order can no longer be settled as signed by the user.
fee_amount numeric not null amount in sell_token the owner agreed upfront as a fee to be taken for the trade
kind enum not null trade semantics of the order
partially_fillable bool not null determines if the order can be executed in multiple smaller trades or if everything has to be executed at once (fill-or-kill)
signature bytea not null signature provided by the owner stored as raw bytes. What these bytes mean is determined by signing_scheme
cancellation_timestamp timestamptz nullable when the order was cancelled. If the timestamp is null it means the order has not been cancelled yet
receiver bytea nullable address that should receive the buy_tokens. If this is null the owner will receive the buy tokens
app_data bytea not null arbitrary data associated with this order but per design this is an IPFS hash which may contain additional meta data for this order signed by the user
signing_scheme enum not null what kind of signature was used to proof that the owner actually created the order
settlement_contract bytea not null address of the contract that should be used to settle this order
sell_token_balance enum not null defines how sell_tokens need to be transferred into the settlement contract
buy_token_balance enum not null defined how buy_tokens need to be transferred back to the user
class enum not null determines which special trade semantics will apply to the execution of this order
true_valid_to bigint not null UNIX timestamp at which order is no longer executable. For regular orders it is the same value as valid_to. Some orders may have multiple valid_to values, such as ethflow: which is initially signed with u32::MAX. Their true validity comes from the Settlement contract's events which is used for liveness checks.
valid_from bigint nullable earliest UNIX timestamp (in seconds) at which the order may enter a batch auction. Taken from the order's app-data (validFrom). NULL means no lower bound, i.e. the order is eligible immediately (the default for all existing orders).

Indexes:

  • PRIMARY KEY: btree(uid)
  • order_cancellation_timestamp: btree(cancellation_timestamp)
  • order_creation_timestamp: btree(creation_timestamp)
  • order_owner: hash(owner)
  • order_quoting_parameters: btree(sell_token, buy_token, sell_amount)
  • order_sell_buy_tokens: btree(sell_token, buy_token)
  • user_order_creation_timestamp: btree(owner, creation_timestamp DESC)
  • version_idx: btree(settlement_contract)
  • orders_true_valid_to: btree(true_valid_to)
  • orders_valid_from: btree(valid_from) WHERE valid_from IS NOT NULL
  • orders_owner_covering: btree(owner) INCLUDE (uid, kind, buy_amount, sell_amount, fee_amount, buy_token, sell_token)
  • orders_owner_class_valid_composite: btree(owner, class, true_valid_to DESC) WHERE cancellation_timestamp IS NULL

fee_policies

Contains all relevant data of fee policies applied to orders during auctions.

Column Type Nullable Details
auction_id bigint not null unique identifier for the auction
order_uid bytea not null 56 bytes identifier linking to the order in the orders table
application_order serial not null the order in which the fee policies are inserted and applied
kind PolicyKind not null type of the fee policy, defined in the PolicyKind enum
surplus_factor double precision percentage of the surplus for fee calculation; value is between 0 and 1
surplus_max_volume_factor double precision cap for the fee as a percentage of the order volume; value is between 0 and 1
volume_factor double precision fee percentage of the order volume; value is between 0 and 1
price_improvement_factor double precision percentage of the price improvement over the best quote received during order creation; value is between 0 and 1
price_improvement_max_volume_factor double precision cap for the fee as a percentage of the order volume; value is between 0 and 1

Indexes:

  • PRIMARY KEY: composite key(auction_id, order_uid, application_order)

Enums

  • PolicyKind

    Enum for the kind column in fee_policies table.

    Values:

    • surplus: The fee is based on the surplus achieved in the trade.
    • priceimprovement: The fee is based on a better executed price than the top quote.
    • volume: The fee is based on the volume of the order.

presignature_events

Stores data of PreSignature events. This is a mechanism where users can supply a signature for an order_uid even before creating the original order in the backend. These events can give or revoke a signature.

Column Type Nullable Details
block_number bigint not null block in which the event was emitted
log_index bigint not null index in which the event was emitted
owner bytea not null owner of the order
order_uid bytea not null order for which the signature was given or revoked
signed boolean not null specifies if an a signature was given or revoked

Indexes:

  • PRIMARY KEY: btreebtree(block_number, log_index)
  • most_recent_with_orderuid: btree (order_uid, block_number DESC, log_index DESC)
  • presignature_owner: hash(owner)

quotes (and quotes_id_seq counter)

Stores quotes in order to determine whether it makes sense to allow a user to create an order with a given fee_amount. Quotes are short lived and get deleted when they expire. ids are unique and increase monotonically.

Column Type Nullable Details
sell_token bytea not null address of the token that should be sold
sell_amount numeric not null amount that should be sold at most
buy_token bytea not null address of token that should be bought
buy_amount numeric not null amount that should be bought at least
expiration_timestamp timestamptz not null when the quote should no longer be considered valid. Invalid quotes will get deleted shortly
order_kind enum not null trade semantics for the quoted order
gas_amount double not null estimation of gas used to execute the order according to the quote
gas_price double not null gas price at the time of quoting
sell_token_price double not null price of sell_token in ETH. Since fees get taken in the sell token the actual fee will be computed with sell_token_price * gas_amount * gas_used.
id bigint not null unique identifier of this quote
quote_kind enum not null quotekind for which this quote is considered valid
solver bytea not null public address of the solver that provided this quote
verified boolean not null information if quote was verified
metadata json not null additional data associated with the quote in json format
auction_id bigint nullable the auction competition that was the basis for this quote, the limit price of fast path executions will be derived from this competition

Indexes:

  • PRIMARY KEY: btree(id)
  • quotes_token_expiration: btree (sell_token, buy_token, expiration_timestamp DESC)

proposed_solutions

All solutions reported by solvers, that were part of a solver competition. A solver competition can have more than one winner.

Column Type Nullable Details
auction_id bigint not null auction for which the solution was proposed
uid bigint not null unique id of the proposed solution within a single auction
id numeric not null id of the proposed solution as reported by the solver
solver bytea not null solver submission address
is_winner boolean not null specifies if a solver that proposed this solution is required to execute the solution
filtered_out boolean not null specifies whether the solution was filtered out during the initial fairness checks of the winner selection
score numeric not null score of a solution, based on a scoring criteria used at the time of competition
price_tokens bytea[] not null tokens used in a solution, for which uniform prices are provided
price_values numeric[] not null uniform prices for all tokens in price\_tokens list

Indexes:

  • PRIMARY KEY: btree(auction_id, uid)

proposed_trade_executions

Contains all order executions for proposed solutions.

Column Type Nullable Details
auction_id bigint not null auction for which the order was executed
solution_uid bigint not null uid from proposed\_solutions
order_uid bigint not null id of the order
executed_sell numeric not null the effective amount that left the user's wallet including all fees
executed_buy numeric not null the effective amount the user received after all fees

Indexes:

  • PRIMARY KEY: btree(auction_id, solution_uid, order_uid)

proposed_jit_orders

Solvers report orders they solved on each competition. Orders that don't exist in the orderbook (i.e. private liquidity orders or surplus capturing jit orders), are considered JIT orders and saved in this table.

Column Type Nullable Details
auction_id bigint not null auction for which the order was executed
solution_uid bigint not null uid from proposed\_solutions
order_uid bigint not null id of the order
sell_token numeric not null the effective amount that left the user's wallet including all fees
buy_token numeric not null the effective amount the user received after all fees
limit_sell numeric not null limit sell amount of the order
limit_buy numeric not null limit buy amount of the order
side enum not null trade semantics of the order

Indexes:

  • PRIMARY KEY: btree(auction_id, solution_uid, order_uid)

reference_scores

Stores the reference score per solver, defined as the total score of the auction if the reference solver had not participated.

Column Type Nullable Details
auction_id bigint not null id of the auction the scores belong to
solver bytea not null public address of the winning solver
reference_score numeric not null reference score value

Indexes:

  • PRIMARY KEY: btree(auction_id, solver)

settlements

Stores data and metadata of Settlement events emitted from the settlement contract.

Column Type Nullable Details
block_number bigint not null block in which the settlement happened
log_index bigint not null index in which the event was emitted
solver bytea not null public address of the executing solver
tx_hash bytea not null transaction hash in which the settlement got executed
auction_id bigint nullable corresponding auction ID that initiated the settlement
solution_uid bigint nullable corresponding winning solver's solution UID, which is also used to identify settlements from the current environment
gas_used numeric(78, 0) nullable gas consumed by the settlement transaction, read from the transaction receipt
effective_gas_price numeric(78, 0) nullable gas price actually paid per unit of gas (in wei), read from the transaction receipt

The total on-chain cost of a settlement is gas_used * effective_gas_price. Both columns are populated by the autopilot's settlement observer and are only set for settlements observed after the migration that added them; historical rows were not backfilled, so consumers (e.g. the orderbook attributing gas cost to individual trades and orders) must handle NULL.

Indexes:

  • PRIMARY KEY: btree(block_number,log_index)
  • settlements_tx_hash: hash(tx_hash)
  • settlements_auction_id: btree(auction_id)

settlement_executions

Contains data for each settlement execution of an auction. To check if the auction was settled on-chain, refer to the settlements table.

Column Type Nullable Details
auction_id bigint not null id of the auction the settlement execution belongs to
solver bytea not null public address of the winning solver that executed the settlement
solution_uid bigint not null corresponding winning solver's solution UID
start_timestamp timestamptz not null when the settlement execution started
end_timestamp timestamptz nullable when the settlement execution ended
start_block bigint not null block in which the settlement execution started
end_block bigint nullable block in which the settlement execution ended
deadline_block bigint not null latest block at which the settlement execution should have ended
outcome text nullable outcome of the settlement execution

Indexes:

  • PRIMARY KEY: btree(auction_id, solver, solution_uid)
  • settlement_executions_time_range_index: btree(start_timestamp, end_timestamp)

trades

This table contains data of Trade events issued by the settlement contract after a successful settlement.

Column Type Nullable Details
block_number bigint not null block in which the event happened
log_index bigint not null index in which the event was emitted
order_uid bytea not null trade filled this order partially or completely
sell_amount numeric not null amount of sell_token that got taken from the order owner
buy_amount numeric not null amount of buy_token received by the order owner
fee_amount numeric not null fee amount in sell_token that got taken in this trade. Note that this amount refers to all or a portion of the static fee_amount the user signed during the order creation.
gas_cost numeric nullable this trade's share of its settlement's gas cost in wei (estimated as gas_used * gas_price), rounded down. NULL for settlements observed before the migration that added it.

Indexes:

  • PRIMARY KEY: btree(block_number, log_index)
  • trade_order_uid: btree (order_uid, block_number, log_index)
  • trades_covering: btree(order_uid) INCLUDE (buy_amount, sell_amount, fee_amount)

jit_orders

JIT orders stored here are orders that were settled outside of the competitition Auction. This means both regular JIT orders that protocol is not aware of, as well as regular user orders that were not listed in the Auction can appear in this table.

Column Type Nullable Details
block_number bigint not null block in which the event happened
log_index bigint not null index in which the event was emitted
uid bytea not null 56 bytes identifier composed of a 32 bytes hash over the order data signed by the user, 20 bytes containing the owner and 4 bytes containing valid_to.
owner bytea not null address who created this order and where the sell_token will be taken from, note that for ethflow orders this is the CoWSwapEthFlow smart contract and not the user that actually initiated the trade
creation_timestamp timestamptz not null when the order was created
sell_token bytea not null address of the token that will be sold
buy_token bytea not null address of the token that will be bought
sell_amount numeric not null amount in sell_token that should be sold at most
buy_amount numeric not null amount of buy_token that should be bought at least
valid_to timestamptz not null point in time when the order can no longer be settled
fee_amount numeric not null amount in sell_token the owner agreed upfront as a fee to be taken for the trade
kind enum not null trade semantics of the order
signature bytea not null signature provided by the owner stored as raw bytes. What these bytes mean is determined by signing_scheme
receiver bytea nullable address that should receive the buy_tokens. If this is null the owner will receive the buy tokens
app_data bytea not null arbitrary data associated with this order but per design this is an IPFS hash which may contain additional meta data for this order signed by the user
signing_scheme enum not null what kind of signature was used to proof that the owner actually created the order
sell_token_balance enum not null defines how sell_tokens need to be transferred into the settlement contract
buy_token_balance enum not null defined how buy_tokens need to be transferred back to the user
class enum not null determines which special trade semantics will apply to the execution of this order

Indexes:

  • PRIMARY KEY: btree(block_number, log_index)
  • jit_order_creation_timestamp: btree(creation_timestamp)
  • jit_order_owner: hash(owner)
  • jit_order_uid: hash(uid)
  • jit_user_order_creation_timestamp: btree(owner, creation_timestamp DESC)
  • jit_event_id: btree(block_number, log_index)

The pool-indexer service uses its own per-network database, not these shared DBs. Its tables (pool_indexer_checkpoints, uniswap_v3_pools, uniswap_v3_pool_states, uniswap_v3_ticks) and migrations live in sql-pool-indexer/.

Enums

executiontime

Value Meaning
pre interaction should be executed before sending tokens to the settlement contract
post interaction should be executed after receiving bought tokens from the settlement contract

onchainorderplacementerror

Value Meaning
quote_not_found order was created with an expired quote
invalid_quote the associated quote does not apply to the order
pre_validation_error basic pre order creation check failed (e.g. no 0 amounts)
disabled_order_class unused
valid_to_too_far_in_future unused
invalid_order_data unused
insufficient_fee the proposed fee is less than quoted fee
non_zero_fee the proposed fee is not zero
other some unexpected error happened

ordereventlabel

Value Meaning
created order was added to the orderbook
ready order was included in an auction and sent to solvers
filtered order was filtered from the auction and not sent to solvers
invalid order can not be settled on-chain (e.g. user is missing funds, PreSign or EIP-1271 signature is invalid, etc.)
executing order was included in the winning solution and is in the process of being submitted on-chain
considered order was in a valid solution
traded order was traded on-chain
cancelled user cancelled the order

orderfilterreason

Value Meaning
in_flight order already won a previous auction and is being settled on-chain
banned_user order owner is on the ban list
invalid_signature presign or EIP-1271 signature is not yet valid
unsupported_token sell or buy token is on the deny list
insufficient_balance owner does not have enough sell token balance or allowance
dust_order order value is too small to be worth settling
missing_native_price no native price available for the order's tokens

orderkind

Value Meaning
sell the order sells the entire sell_amount for at least the user signed buy_amount
buy the order buys the entire buy_amount for at most the user signed sell_amount

signingscheme

Value Meaning
presign User broadcasts a transaction onchain containing a signature of the order hash. Because this onchain transaction is also signed, it proves that the user indeed signed the order.
ethsign Standardized way to sign arbitraty bytes (EIP-191)
eip712 Standardized way to hash and sign structured data. (eip712)
eip1271 Owner of the order is a smart contract that implements EIP-1271. To verify that the order is allowed to execute we call the owner's isValidSignature(order_hash, signature) function and let it decide. Used to implement smart orders.

quotekind

We support different expiration times for orders with different signing schemes. This is because offline signed messages can immediately be validated but presign or eip-1271 signatures need to interact with the blockchain which may take time. This could be achieved by simply setting the appropriate expiration_timestamp in the quote. But we also want to prevent users from creating for example quick eip712 orders with long living quotes intended for eip1271 orders which might be way off by then so quotes also get tagged with this quotekind.

Value Meaning
standard Quote for eip712 or ethsign orders.
eip1271onchainorder Quote that accounts for gas used to verify signature with on-chain isValidSignature() call (see signingscheme::eip1271)
presignonchainorder Quote for presign orders.

selltokensource

Value Meaning
erc20 sell_tokens will be drawn from the users regular ERC20 token allowance (docs)
internal sell_tokens will be drawn from the balancer vault internal user balance (docs)
external sell_tokens will be drawn from the user's ERC20 token balance but relayed through the balancer vault (docs)

buytokendestination

Value Meaning
erc20 Bought tokens will be added to the ERC20 token balance of that user
internal Bought tokens will be added to the balancer vault internal balance of the user (docs)

orderclass

Value Meaning
market Short lived order that may receive surplus. Users agree to a static fee upfront by signing it.
liquidity These orders must be traded at their limit price and may not receive any surplus. Violating this is a slashable offence.
limit Long lived order that may receive surplus. Users sign a static fee of 0 upfront and either the backend or the solvers compute a dynamic fee that gets taken from the surplus (while still respecting the user's limit price!).

Notes on Migrations

Migrations that require a long running process must be done manually, this is due to the limitations the weekly release process imposes:

  • The deployment must complete under 5 minutes
  • The pod has a processDeadlineSeconds defaulting to 600 seconds

To avoid extending the process, we resort to manually applying complicated migrations.

The above also comes into play when dealing with indexes, as their construction with flyway may lock up rows, degrading SLI.