SecureRPC Transaction and RPC Status and Responses

Status guidelines

SecureRPC Transaction and RPC Status and Responses

Transactions that you submit to OpenMEV won't be observable in the public mempool. We provide a flashbots-compatible status api endpoint for both end-users and integrators to use to populate / query user submissions for both transactions and bundles.

• PENDING - The transaction was received and is currently being submitted to miners

• INCLUDED - The transaction was included on-chain

• FAILED - The transaction was submitted for 25 blocks and failed to be included on-chain

• CANCELLED - The transaction was cancelled by the user and not included on-chain

• UNKNOWN - The transaction was not received

In order to receive a response from the status API you must provide a valid transaction hash to look up.

OpenMEV Status API is flashbots compatible, meaning it covers at least version 0.6+ of Flashbots API.

To check the status of your transactions query the OpenMEV API Endpoint. Response messages are formatted as follows:

{
  "status": "PENDING",
  "hash": "YOUR_TX_HASH",
  "maxBlockNumber": "latest",
  "transaction": {
    "from": "<SENDER>",
    "to": "<RECEIVER>",
    "gasLimit": "23000",
    "maxFeePerGas": "300",
    "maxPriorityFeePerGas": "10",
    "nonce": "42",
    "value": "1333333333337"
  }
}

// @see {@link https://github.com/manifoldfinance/libsushi/blob/master/src/SushiGuard/index.ts}
/**
 * @package OpenMevTxState
 * @version 2022.04
 * @see {@link docs.openmev.org}
 * @notice This is a flashbots-api compatible interface ( ~v0.6 )
 *
 * - UNCHECKED -> Tx status has not been checked and there's no information about it.
 * - PROCESSING -> Tx checks are in place until a resolution happens: OK, INDETERMINATE, ERROR.
 * - OK -> Relay received the Tx && all downstream miners accepted without complains && tx mined successfully
 * - INDETERMINATE -> Relay received correctly the Tx && at least one miner accepted the TX && TX potentially mineable
 * - ERROR -> Relay hasn't received the TX || none of the miners accepted the Tx || Tx was not mined successfully
 *
 */

export enum PrivateTxState {
  UNCHECKED = 'UNCHECKED',
  PROCESSING = 'PROCESSING',
  OK = 'OK',
  INDETERMINATE = 'INDETERMINATE',
  ERROR = 'ERROR',
}

export type RelayResponses = Record<string, RelayResponse>;

export interface RelayResponse {
  response: JsonRpcResponse<any>;
  error?: string;
}

export interface PrivateTxStatus {
  transactionHash: string;
  receivedAt: string;
  relayedAt?: string;
  minedAt?: string;
  relayFailure?: boolean;
  relayResponses?: RelayResponses;
}

| Code | Possible Return message | Description | | --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | 32700 | Parse error | Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. | | 32600 | Invalid Request | The JSON sent is not a valid Request object. | | 32601 | Method not found | The method does not exist / is not available. | | 32602 | Invalid params | Invalid method parameter(s). | | 32603 | Internal error | Internal JSON-RPC error. | | 32000 to -32099 | Server error. Reserved for implementation-defined server-errors. | |

| Code | Possible Return message | Description | | ---- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Unauthorized | Should be used when some action is not authorized, e.g. sending from a locked account. | | 2 | Action not allowed | Should be used when some action is not allowed, e.g. preventing an action, while another depending action is processing on, like sending again when a confirmation popup is shown to the user (?). | | 3 | Execution error | Will contain a subset of custom errors in the data field. See below. |

Custom error 3 can contain custom error(s) to further explain what went wrong.
They will be contained in the data field of the RPC error message as follows:

| Code | Possible Return message | Description | | ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 100 | X doesn’t exist | Should be used when something which should be there is not found. (Doesn’t apply to eth_getTransactionBy_ and eth_getBlock_. They return a success with value null) | | 101 | Requires ether | Should be used for actions which require somethin else, e.g. gas or a value. | | 102 | Gas too low | Should be used when a to low value of gas was given. | | 103 | Gas limit exceeded | Should be used when a limit is exceeded, e.g. for the gas limit in a block. | | 104 | Rejected | Should be used when an action was rejected, e.g. because of its content (too long contract code, containing wrong characters ?, should differ from -32602 - Invalid params). | | 105 | Ether too low | Should be used when a to low value of Ether was given. |

| Code | Possible Return message | Description | | ---- | ----------------------- | ----------------------------------------------------------------------- | | 106 | Timeout | Should be used when an action timedout. | | 107 | Conflict | Should be used when an action conflicts with another (ongoing?) action. |