> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primev.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Bid Structure

The bid payload sent to the internal mev-commit API is as follows:

| Key                   | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| `txHashes`            | Array of transaction hashes as strings                           |
| `amount`              | Bid amount in wei                                                |
| `blockNumber`         | L1 block number targeted for bid inclusion                       |
| `decayStartTimestamp` | Start timestamp for bid decay (in Unix milliseconds)             |
| `decayEndTimestamp`   | End timestamp for bid decay (in Unix milliseconds)               |
| `revertingTxHashes`   | Array of transaction hashes as strings that can revert           |
| `rawTransactions`     | Array of raw signed transaction payloads                         |
| `slashAmount`         | Amount to be slashed from provider stake in case of a failed bid |
| `bidOptions`          | One or more of the available options                             |

Only one out of the `txHashes` or `rawTransactions` need to be provided in the bid. If the `rawTransactions` is given, the `txHashes` are inferred from it.

```json Example bid theme={null}
{
    "txHashes": ["0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae", "0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf","0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff"],
    "amount": "100040",
    "blockNumber": 133459,
    "decayStartTimestamp": 1716935571901,
    "decayEndTimestamp": 1716935572901,
    "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"]
}
```

```json Example bid with raw transaction payloads theme={null}
{
    "rawTransactions": ["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0", "0x02f8748242682c841043362684104336318252089412b141665da4a5f617c759ad996ef91ad806a9c0880de0b6b3a764000080c001a0806552ed846808580eb896994825f07e73de2f42e2d3554f228284ecfaa89d9ca046d58b62ba565982fb07a64b436dd7a6c210b2f59c4fb2aee2cdd150ccf8bfaa"],
    "amount": "100040",
    "blockNumber": 133459,
    "decayStartTimestamp": 1716935571901,
    "decayEndTimestamp": 1716935572901,
    "revertingTxHashes": ["22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810"]
}
```

The final bid structure includes a hash and signature that is auto-constructed by your mev-commit bidder node and looks as follows.

```json theme={null}
{
   "txHash":"0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacae,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4eacaf,0549fc7c57fffbdbfb2cf9d5e0de165fc68dadb5c27c42fdad0bdf506f4effff",
   "bidAmount":277610,
   "revertingTxHashes":"22145ba31366d29a893ae3ffbc95c36c06e8819a289ac588594c9512d0a99810",
   "blockNumber":2703,
   "digest":"uU2p20f5KmehWqpuY1u+CbhcS8jNwdQAJQe2dh0Vnrk=",
   "signature":"nY6jYsGPxj6LVlSVQJbZcxvmRrw8Ym5rqOL1x0W/xPlJGBaF/ZzzjkxiioY/MDiRGvlflSWeoT0fh3aIJiJxAhw=",
   "decayStartTimestamp":1716935571901,
   "decayEndTimestamp": 1716935572901,
   "slashAmt":0,
   "rawTransactions":["0x02f8db82426882010c8410433624841043362f8303425094ea593b730d745fb5fe01b6d20e6603915252c6bf87016e03ce313800b864ce0b63ce0000000000000000000000000e94804eaa3c4c5355992086647f683f6f41ef1f000000000000000000000000000000000000000000000000000150e0786cc000000000000000000000000000000000000000000000000000000000000004e378c001a0ece6d13b20247abdc07d669c9186ee5a1ac9601db8c98a3323024ab299cb6662a01c20680efe4e0bb48a3a936b5ab27c741819f0ac567b12b34b230004b20b78a0"],
   "nikePublicKey": "04c631d017981efdc0c319b475de36389a10ede86fbbc9adcf573844a858ce8ddcddb41306eb9c34ec4ee9bc0234f7e30684bf389142437166d407e47974d5cbf7"
}
```

## Details on Bid Structure

| Property            | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| txnHash             | Array of transaction hashes represented as strings                                                        |
| bidAmount           | Amount to bid in wei                                                                                      |
| blockNumber         | L1 target block to have bid included                                                                      |
| decayStartTimestamp | Start timestamp for bid decay (in Unix milliseconds)                                                      |
| decayEndTimestamp   | End timestamp for bid decay (in Unix milliseconds)                                                        |
| bidDigest           | Hash of the bid                                                                                           |
| bidSignature        | Signed bidВigest = sign(bidDigest, signingKey)                                                            |
| nikePublicKey       | NIKE public key of the bidder, autogenerated for each bid                                                 |
| revertingTxHashes   | Array of transaction hashes as strings that can revert                                                    |
| rawTransactions     | Array of hexadecimal encoded raw signed transaction payloads                                              |
| slashAmount         | Amount to be slashed from provider stake (and directly transferred to the bidder) in case of a failed bid |
| bidOptions          | Position constraints or other available options                                                           |

### Details on Decay Parameters

The `decayStartTimestamp` and `decayEndTimestamp` parameters allow bidders to control the range over which their bid decays.

Due to inherent network delays, preconfirmation times can range between 50 to 250 milliseconds even if providers commit immediately after seeing the bid. To account for this, you might want to set your `decayStartTimestamp` approximately 300 milliseconds in the future. However, setting this delay is not mandatory and should be adjusted based on your strategic preferences for bid timing and pricing.
For more detailed information about the decay mechanism, refer to the [Bid Decay Page](/v1.2.x/concepts/bids/bid-decay-mechanism).

### Details on BidOptions

The `bidOptions` provides a way to put certain constraints on the transaction with respect to the block. Currently we have the position constraint option. This option allows users to configure the location of the transaction in the block. This could be an absolute index or percentile or gas percentile index of the block.

```proto theme={null}
message PositionConstraint {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      title: "Position Constraint"
      description: "Constraint on the position of the transaction in the block."
    }
  };
  enum Anchor {
    ANCHOR_UNSPECIFIED = 0;
    ANCHOR_TOP = 1; // Position is at the top of the block
    ANCHOR_BOTTOM = 2; // Position is at the bottom of the block
  }
  enum Basis {
    BASIS_UNSPECIFIED = 0;
    BASIS_PERCENTILE = 1; // Position is a percentile of the block size
    BASIS_ABSOLUTE = 2; // Position is an absolute position in the block
    BASIS_GAS_PERCENTILE = 3; // Position is a percentile of the gas used in the block
  }
  Anchor anchor = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Anchor position of the transaction in the block."
  }];
  Basis basis = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Basis for the position constraint."
  }];
  int32 value = 3 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Value of the position constraint. If anchor is TOP, this is the position from the top of the block. If anchor is BOTTOM, this is the position from the bottom of the block."
  }];
};

```

For example,

```json theme={null}
{
    anchor: ANCHOR_TOP,
    basis: BASIS_PERCENTILE,
    value: 10
}

```

would let the provider know that this transaction or bundle has to be in the top 10% of the block. If we get a commitment and the transaction is not in the top 10%, the provider will be slashed. Multiple constraints can be combined, in which case the transaction needs to satisfy all of them. In case of transaction bundles, a set of constraints is considered satisfied if each constraint is satisfied by at least one transaction in the bundle.

### Details on Encrypted Bid Structure

The bid structure is encrypted using an AES key, which the bidder P2P node generates at the start, and is then sent to the provider.

```json theme={null}
{
    "ciphertext": "5750d8af6296296f1147f5e11f47f253f376dea3fd5c2760cd82bd82a7066a8fe1c84f48a4e738d1df7c0e64f930c6b0b642800156e453a501c8b993951fcb50fe0b9fce4a2046838f499317a6018eb59abd5e84dbe3b7e296d4e0e70ef3bb221af7afe341908dbd02e8c91b4eff935b2697208f51ccacf5fe744c199afca687d85850a2e12a75433510dccda9258612348c586e971cc521486806ea25ec94d5fa7038beda3f532970e7b06198deef96677af3a6889c84d657585a9eefd224961f87a3353ad4ede4a7368e2e5bc9571d320a8a3be0f1e08e769f9bb2da6fb76c81cd"
}
```