> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/transactions/mempool.md).

# Transaction Pool

Transaction pool admission, gossip, and block-build selection

The mempool is an in-memory list on `Blockchain.mempool` (see `blockchain/core/blockchain.go`). It accepts validated transactions across the JSON-RPC, REST, and P2P-gossip ingress paths and feeds them to the block builder.

## Admission pipeline

Every ingress path funnels into `Blockchain.AddTransaction(tx)`. The checks below run in order; the first failure rejects the tx.

```
1. Authorization-tx fast path
   if tx.Type in {ECDSAAuthorization, ECDSARevocation}:
     route to addAuthTransactionLocked() — no balance/gas checks
     (gas-free, signed by Dilithium master key)

2. Signature verification
   if tx.SignatureType == ECDSAAuthorized:
     verifyAuthorizedECDSA(tx)
   else:
     tx.Verify()                  // Dilithium

3. Nonce policy
   currentNonce = bc.getNonce(tx.From)
   reject if tx.Nonce < currentNonce              // already used
   accept if tx.Nonce >= currentNonce             // future allowed

4. Gas envelope
   reject if tx.Gas > MaxGasPerBlock              // 30,000,000

5. Balance pre-flight
   reject if balance < value + gas × gasPrice

6. Minimum gas price
   reject if gasPrice < MinGasPrice               // 1 gwei

7. Type-specific routing
   transfer / contract_deploy / contract_call → mempool
   contract_deploy logs metadata for block builder
```

Source: `blockchain/core/blockchain.go::AddTransaction`, roughly lines 692–810.

## Why future nonces are allowed

Following Ethereum geth's pool policy, a transaction with `nonce > currentNonce` is queued. The block builder will not include a tx whose predecessor is missing, but holding it in the pool means the wallet's "send 5 txs in a row" workflow never deadlocks on out-of-order arrivals.

```
Wallet sends:    [n=5] [n=6] [n=7]
P2P arrival:     [n=7] [n=5] [n=6]
Mempool state:   {5: queued, 7: queued}     ← then 6 arrives
                 {5,6,7: ready}
Block builder:   includes 5, 6, 7 in next block
```

## Eviction

Transactions leave the mempool by:

| Reason                                   | Code path                                       |
| ---------------------------------------- | ----------------------------------------------- |
| Included in a block                      | `removeFromMempool(tx.Hash)` from block-applier |
| Replaced by same-nonce, higher gas-price | (planned)                                       |
| Pool full + timeout                      | (planned — not enforced in current alpha)       |

The current implementation has no hard size cap; on-disk metrics (`MempoolSize`, `TransactionsInMempool` from `blockchain/metrics`) feed the dashboard so operators can spot growth.

## Querying the pool

```bash
# REST
curl http://localhost:8546/api/v1/execution/mempool

# Returns
{
  "success": true,
  "count": 3,
  "transactions": [
    {
      "hash": "0xfa7a76...",
      "from": "0x...",
      "to":   "0x...",
      "value": "100000000000000000000",
      "gas": 21000,
      "gas_price": "10000000000",
      "nonce": 17,
      "signature": "<base64 dilithium>",
      "public_key": "<base64 dilithium>"
    }
  ]
}
```

```bash
# JSON-RPC (Ethereum-shape)
curl -X POST http://localhost:8545 -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"txpool_status","params":[],"id":1}'
```

## Gossip

Validated transactions are forwarded to the libp2p GossipSub topic `/quantumwing/txs/v1`. Peers running `blockchain/p2p/network.go` receive each broadcast, run the same `AddTransaction` pipeline, and re-gossip new entries. Duplicates are filtered by `tx.Hash` before re-broadcast.

See [../networking/message-propagation.md](/quantumwing/networking/message-propagation.md) for the gossip protocol details.

## Block-build selection

When the validator is selected for slot `S`, the beacon requests pending transactions:

```
GET /api/v1/engine/getPendingTransactions
```

The execution layer returns mempool entries sorted by:

1. `Nonce` ascending **per sender** (sequential ordering required).
2. `GasPrice` descending across senders (highest fee first).
3. Submission order as a tiebreaker.

The validator packs as many txs as fit under `MaxGasPerBlock`, signs the block, and submits it back. Included txs are removed from the local mempool when `engine_newPayload` arrives.

## Failure modes

| Symptom                                | Likely cause                                        |
| -------------------------------------- | --------------------------------------------------- |
| `nonce too low`                        | Wallet has stale nonce; refresh via `qw_getNonce`   |
| `insufficient balance for value + gas` | Faucet drip not yet credited                        |
| `gas price below minimum`              | Hardcoded 1 gwei floor                              |
| `gas limit ... exceeds protocol max`   | `tx.Gas > 30M`                                      |
| `invalid transaction signature`        | Hash mismatch — usually wallet+chain `chainID` skew |
| `malformed tx.Value`/`tx.GasPrice`     | Wei value not a base-10 string                      |

## Code paths

* `blockchain/core/blockchain.go::AddTransaction` — admission
* `blockchain/core/blockchain.go::GetMempool` — read API
* `blockchain/core/blockchain.go::removeFromMempool`
* `blockchain/p2p/network.go` — gossip wire
* `blockchain/api/jsonrpc/` — `qw_*` and `eth_*` ingress
* `cmd/execution/main.go::handleSendTransaction` — REST ingress

## Related

* [signing.md](/quantumwing/transactions/signing.md) — pre-image, signature schemes
* [format.md](/quantumwing/transactions/format.md) — `Transaction` struct
* [gas-fees.md](/quantumwing/transactions/gas-fees.md) — fee math
* [eip1559.md](/quantumwing/transactions/eip1559.md) — base/priority fee fields
* [../networking/message-propagation.md](/quantumwing/networking/message-propagation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/transactions/mempool.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.