Skip to main content

Transaction management

Transaction management automates tasks related to:

  • Creating transactions, including crafting transaction data, managing gas, managing nonces, and signing transactions.
  • Sending transactions to a chain.
  • Post-processing mined transactions, including catching receipts and decoding event logs.

Orchestrate handles nonce assignment internally enabling the maximal theoretical throughput in transactions per second (TPS) for a single account.

Use the SDK or REST API to send transactions. Sending transactions generates and sends Protobuf messages to Apache Kafka. Orchestrate receives the Protobuf messages and manages the full transaction lifecycle.

Gas price policies​

Orchestrate allows you to define a gas price policy for transactions. For example, you can set the priority of a transaction, and set a retry policy.

note

You cannot set a gas price policy when sending raw transactions.

Orchestrate provides an example of using the SDK to create a gas price policy.

Transaction priority​

Orchestrate allows you to set the transaction priority if a gas price is not specified. Use the SDK or REST API to set the transaction priority when submitting the transaction.

important

Don't specify a priority on networks that enforce a minimum gas price. This ensures the user doesn't submit a transaction with a gas price lower than the minimum accepted by the Ethereum client.

The following priorities are available:

  • very high - 2.5 gwei as priority fee (+40% gas price in legacy transactions)
  • high - 2.0 gwei as priority fee (+20% gas price in legacy transactions)
  • medium - (default) 1.5 gwei as priority fee (gas price in legacy transactions)
  • low: 1.0 gwei as priority fee (-20% gas price in legacy transactions)
  • very low - 0.5 gwei as priority fee ( -40% gas price in legacy transactions)

Transaction retry policy​

Transactions can remain pending for a long time, for example if the gas price for the transaction is too low, or the network has a high load.

You can create a retry policy based on the gas price when sending transactions using the SDK or REST API.

important

We recommend using a retry policy when sending transactions on Ethereum Mainnet.

Orchestrate provides the following policy options:

OptionDescription
intervalInterval to wait before retrying pending transactions. For example, 30s means 30 seconds, 2m means 2 minutes. Must be greater than or equal to 1s for the policy to be created.
incrementPriority fee (or gas price in legacy transactions) percentage increase for each retry. For example, 0.05 means an increment of 5% on every retry, 0.1 means 10%, 1 means 100%. Policy creation fails if limit divided by increment is greater than 10.
limitMaximum priority fee (or gas price) limit. For example, 0.5 means a 50% limit on the transaction gas price. The retry policy will no longer execute once the limit is reached. Policy creation fails if limit divided by increment is greater than 10.

The following rules apply to the retry policy:

  • interval must be greater than or equal to 1s (1 second).
  • The maximum number of retries is 10, meaning if limit divided by increment is greater than 10, then the policy creation fails.
  • The policy creates a child job belonging to the same schedule for each retry where the priority fee (or gas price) is incremented.
  • The policy sends the same job transaction to the blockchain if the gas has not been incremented during a retry.

The following are retry policy suggestions for sending transactions on Mainnet, where there's an average waiting time of 8–9 blocks for transactions using priority medium.

"gasPricePolicy": {
  "priority": "medium",
  "retryPolicy": {
    "increment": 0.05,
    "interval": "2m",
    "limit": 0.2
  }
},

Transactions are sent using the recommended gas price, and are re-sent every two minutes incrementing the initial gas price by 5%, up to a maximum of 20%.