Skip to main content

Troubleshoot Timeboost

This is a short guide on how response times work and how Express Lane transactions are sequenced, alongside common errors and best practices for using Timeboost. This guide assumes you have reviewed our guide on How to use Timeboost.

How response times work​

The response for a Transaction submission is returned only once the block containing the transaction is produced. For example, irrespective of the type of transaction (express lane or normal), if a transaction is sent to the Sequencer at t=0ms and it took 50ms to arrive at the sequencer (defined as time_to_arrive), then the expected response time is at least t=250ms since blocks are produced every 250ms. As another example, if a transaction is sent at t=220ms and the time_to_arrive was 50ms, then the response time for this transaction will be at t=500ms. The reason for this is because blocks are produced every 250ms and so in this second example, the transation's response is returned when the next block gets produced.

How express lane transactions are ordered into blocks​

The express lane time advantage is currently set to 200ms, while the current block creation time is 250ms. This means that if an express lane transaction and a normal transaction both arrive at the sequencer at the same time, but before 50ms have passed since the last block was produced, then both the transactions may appear in the same block, though the express lane transaction would be sequenced ahead of the normal transaction (assuming that the block's gas limit has not yet been reached).

Express lane transactions are processed in the order of their sequenceNumber, which is a field in every express lane transaction. The first expected sequence number for a new round is zero and increments for each accepted transaction. Note that an accepted transaction is defined as an express lane transaction submission where the sequencer returns an empty result with an HTTP status of 200. You can read more about how to submit express lane transactions in: How to submit transactions to the express lane.

Errors relating to the sequenceNumber​

The sequenceNumber field when submitting an express lane transaction is important because transactions with sequenceNumber=n can only be sequenced after all the transactions from sequenceNumber=0 to sequenceNumber=n-1 have been sequenced.

When it comes to submitting express lane transactions, different types of error responses may arise relating to the sequenceNumber. Below is a breakdown of the various error messages related to sequence numbers and the recommendation for avoiding them. Error messages are subject to change.

To illustrate how sequence numbers are used to accept or reject express lane transactions, assume first that the sequence number for a given round is n (i.e 0 to n-1 sequence numbers were accepted in this round) and there is some maximum allowed sequence number limit m that the sequencer can keep track of (for DoS protections).

If the sequence number for your express lane transaction is:

  • Less than n, then your transaction will be rejected because it has already accepted a transaction with that sequence number (error="SEQUENCE_NUMBER_TOO_LOW").
  • Exactly n, then your transaction will be accepted as soon as the sequencer receives it.
  • Greater than n but less than or equal to n + m, then your transaction will be buffered to be processed. Your transaction will only be accepted once transactions with the other sequence numbers arrive to fill in the “gap” between the sequencer number n and your transaction’s sequence number. You may receive a timeout error if the transactions within the gap arrive after the timeout (i.e., between n and your transaction’s sequence number). However, this doesn’t mean your transaction was rejected - it may eventually get processed. So we recommend checking the transaction receipts (error #1 below).
  • Greater than n + m, then your transaction will be rejected (error #2 below).

Timeboost's implementation of the above-described sequence number reordering buffer is intended to handle out-of-order delivery of transactions in the case of network delays (en route to the sequencer). This implementation is subject to change as we gather feedback from users.

Error 1: Timeout error​

"Accepted timeboost tx failed: Sequence number: %d (consumed), Transaction hash: %v, Error: Transaction sequencing hit timeout, result for the submitted transaction is not yet available: %w"

This means the transaction was received with a sequence number after the expected sequence number, and the transactions with prior sequence numbers were not received in time.

Using an example to illustrate this case, this error could arise where the sequencer has already sequenced an express lane transaction with sequenceNumber=3, but the express lane transaction that was submitted used sequenceNumber=5. Since sequenceNumber=4 has not yet been sequenced, the sequencer will respond by saying the result for the submitted transaction (with sequenceNumber=5) is “not yet available”.

Despite this error message, the transaction may still be processed if transactions with the missing prior sequence numbers are received. Check for the transaction receipt.

Error 2: Sequence number reaching the max allowed limit​

"message sequence number has reached max allowed limit. SequenceNumber: %d, Limit: %d", This means the sequenceNumber of the received transaction is ahead of the next expected sequence number by more than the limit. To resolve this, simply re-submit your transactions in sequential sequenceNumber order.

"Accepted timeboost tx failed: Sequence number: %d (consumed), Transaction hash: %v, Error: $some error unrelated to timeout$”
This type of error means that the underlying transaction of the express lane submission has errored for another reason, and the corresponding sequenceNumber has been consumed. A description of these other types of errors can be found in our guide about how to submit transactions to the express lane".

Other Errors​

Other errors should be self-explanatory - more details can be found on our page about How to submit transactions to the express lane.