# Jito bundles

> Jito-format bundles sent with `sendBundle` and relayed to the Jito Block Engine, with their limits and how keys take turns.

Source: https://docs.constant-k.com/rpc/bundles/

`sendBundle` sends a bundle in the Jito format through the endpoint, and constant-k relays it to the Jito Block Engine in the same region (Frankfurt, New York, Amsterdam). It is included in the Operator, Blade Runner and Nexus plans, not in the Free plan. It is served on the `rpc-<region>` hostnames, not on the `staked-rpc-<region>` or Neon Zero hostnames.

The methods are [sendBundle](https://docs.constant-k.com/rpc/http/sendbundle/), [simulateBundle](https://docs.constant-k.com/rpc/http/simulatebundle/), [getBundleStatuses](https://docs.constant-k.com/rpc/http/getbundlestatuses/) and [getInflightBundleStatuses](https://docs.constant-k.com/rpc/http/getinflightbundlestatuses/).

## How a bundle lands

A bundle is 1 to 5 signed transactions. They run in order and land together, or none land. If one transaction fails, none land, and a failed bundle costs nothing.

The bundle must pay a tip of at least 1,000 lamports to a Jito tip account, inside one of its transactions. The tip goes to Jito and the leader, not to constant-k.

A bundle lands only when the current leader runs a Jito or BAM client. The `encoding` parameter takes `base58` by default; `base64` is recommended.

## Limits

| Limit                  | Applies to                       | Value                                                                                                                                                                                                                                                                                                   |
| :--------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Plan bundle rate       | Your key, per region             | `sendBundle` requests: Operator 1 every 2 s, Blade Runner 2/s, Nexus 5/s. A request over the rate returns HTTP `429`, `Rate limit exceeded (sendBundle: <rate>)`, with `Retry-After` and `X-Retry-After-Ms`.                                                                                            |
| Plan transaction limit | Your key, per region             | Each transaction in a bundle counts as one send: Operator 15/s, Blade Runner 50/s, Nexus 200/s. Bundle transactions share this limit with `sendTransaction`.                                                                                                                                            |
| Plan bundle limit      | Your key, per region             | `simulateBundle`, `getBundleStatuses` and `getInflightBundleStatuses` together: Operator 5/s, Blade Runner 25/s, Nexus 100/s. `simulateBundle` runs in the region and does not use the relay rate.                                                                                                      |
| Landing rate           | Your key, per region             | When fewer than half of a key's recent bundles land, its `sendBundle` rate and its share of the relay fall with it, down to a tenth of the plan's at 0%. The plan rate returns as bundles land. Recent bundles count most: a bundle sent 30 minutes ago counts half. See [Landing rate](#landing-rate). |
| Relay rate             | Every key in the region together | Set by Jito; today 5 bundle requests per second per region. Bundle status calls count against it too.                                                                                                                                                                                                   |

`getSignatureStatuses` on the transaction signatures checks whether a bundle landed without using the relay rate.

## Taking turns

The relay rate is shared, so keys take turns at it.

* When only one key is sending bundles in a region, it gets every opening, and the relay never sits idle while that key is waiting.
* When several keys want the relay at the same moment, openings are shared in proportion to each plan's bundle rate (Nexus 5, Blade Runner 2, Operator 1 every 2 s) times the key's landing factor. Of the keys waiting, the next opening goes to the one furthest behind its share.
* A refused request returns HTTP `429`, code `-32005`, `Bundle relay busy: fair share at this site, retry in <N> ms`, with the headers `Retry-After` (seconds) and `X-Retry-After-Ms`.
* `X-Retry-After-Ms` is the earliest moment the key can be served. A key that sends more than its share gets no extra openings.
* A refused request does not count against the plan's transaction limit.
* A bundle that cannot go out yet waits at the relay for up to 1 second and is sent the moment its turn comes. It is refused only when its turn does not come within that time.

## Landing rate

Jito raises the region's relay rate when more of the relayed bundles land, so the relay favours keys whose bundles land.

| Item           | Value                                                                                                                                                                                                                                                                                                                                                                        |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Landed         | The bundle's first transaction shows up without an error on the region's node within 90 seconds.                                                                                                                                                                                                                                                                             |
| Counted from   | 20 checked bundles. Before that the key keeps the full plan rate.                                                                                                                                                                                                                                                                                                            |
| Starts over    | After 24 hours with no bundle in the region. The key then has the full plan rate again for its next 20 checked bundles. A shorter pause keeps the landing rate.                                                                                                                                                                                                              |
| Landing factor | The landing rate divided by 50%, between 0.1 and 1. At 50% or more it is 1.                                                                                                                                                                                                                                                                                                  |
| Applies to     | The key's `sendBundle` rate and its share of the relay, per region.                                                                                                                                                                                                                                                                                                          |
| Simulation     | At a landing factor of 1, bundles are not simulated: landed bundles show they work, and a bundle never waits for a simulation. Under 1, every bundle is simulated on the region's current state before the relay, and a bundle that fails simulation is refused with a chance of 1 minus the factor: half at 0.5, nine in ten at 0.1. A refused bundle counts as not landed. |
| Headers        | Every `sendBundle` answer carries `X-Bundle-Landing-Rate` (percent) and `X-Bundle-Rate-Factor` once the rate counts.                                                                                                                                                                                                                                                         |

A bundle refused after its simulation returns HTTP `400`, `Simulation failed: <error>. Fewer than half of your recent bundles landed in this region, so bundles that fail simulation can be refused`. The same bundle sent again gets the same answer.

A request over the reduced rate returns HTTP `429`, `Rate limit exceeded (sendBundle: <rate>). The rate is reduced because <N>% of your recent bundles landed in this region; at 50% or more the plan rate returns`, with `Retry-After` and `X-Retry-After-Ms`.

## Sending well

* One bundle per opportunity. Copies of one trade sent together use up the region's relay rate, and at most one of them can land.
* An exact copy of a bundle (the same transactions in the same order) sent to the same region within 60 seconds is refused with `Duplicate bundle` and is not relayed again. It still counts against the plan's transaction limit.
* Versions of the same trade from one key are sent once. A version is the same payer and the same instructions with a different tip, priority fee, compute unit limit or blockhash. Only the version with the best score goes to Jito: the score is the tip plus the priority fee, divided by the requested compute units, the way Jito and BAM rank bundles. The other versions are refused with `Superseded`, and so is any version of that trade sent within 2 seconds after one went out.
* The `X-Retry-After-Ms` value replaces a fixed backoff.
* Landing is checked with `getSignatureStatuses`.
* The tip and the priority fee, over the requested compute units, set the bundle's place in the Jito auction. A compute unit limit close to what the transaction uses beats a bigger tip with a loose limit. A transaction with no limit is charged the default of 200,000 compute units per instruction. The relay does not change the tip.
* A bundle can be checked first with `simulateBundle`. Its transactions run in order on the region's current state, and each one sees the changes of the ones before it.
* Bundles land more often with a recent blockhash, a compute unit limit close to the units used, a tip that matches the current auction, and one bundle per opportunity. Bundles that land keep the key's full rate.
