Update mempool docs by danieljperry · Pull Request #1034 · Chia-Network/chia-docs

danieljperry · 2026-06-18T08:09:15Z

Note

Low Risk
Documentation and navigation only; no runtime or consensus code changes.

Overview
Replaces the monolithic architecture/mempool page with a Mempool doc category (intro, fees, block-creation, time-locks, rbf, fast-forward, isd, updates, migration) wired in sidebars.js.

Much of the former page is moved into those files; block-creation, fast-forward, isd, time-locks, and rbf gain new implementation-focused detail (e.g. create_block_generator2(), FF/dedup rules, pending/conflict caches, RBF fast-forward rule). Inbound links in costs, block-rewards, cryptocurrency-intro, and faq (plus matching zh-Hans pages) now target the new slugs such as /mempool/intro and /mempool/fees.

^{Reviewed by Cursor Bugbot for commit 228a663. Bugbot is set up for automated code reviews on this repo. Configure here.}

BrandtH22 · 2026-06-18T22:43:52Z

@danieljperry I am still reviewing the content itself but noticed we are removing the mempool page and instead having a mempool/intro page.

We should either have that intro page be at the mempool (no /intro) url or we will want to add a redirect to ensure the link chia-blockchain/architecture/mempool/ does not break (redirect to chia-blockchain/architecture/mempool/intro/)

BrandtH22 · 2026-06-23T15:48:51Z

+slug: /chia-blockchain/architecture/mempool/block-creation
+---
+
+When the farmer makes a block, they will select the highest fee-per-cost transactions from the mempool until they reach the maximum block size. These spend bundles are combined into one large spend bundle, which is guaranteed to be valid, since all spend bundles in the mempool must spend disjointed coins.


Should we indicate this is default behavior of the reference farmer? (other farmers might have different transaction selection logic like hpool not allowing 0 mojo transactions)

This was briefly mentioned in the intro section, but I will make it even clearer.

BrandtH22 · 2026-06-23T15:50:02Z

+
+When the farmer makes a block, they will select the highest fee-per-cost transactions from the mempool until they reach the maximum block size. These spend bundles are combined into one large spend bundle, which is guaranteed to be valid, since all spend bundles in the mempool must spend disjointed coins.
+
+Coin spends cannot impact other coin spends, which is a very nice property of UTXO systems, and allows parallelization of validation and block creation. The aggregate spend bundle also has one aggregate signature, which is a combination of every signature from every transaction in that block.


This seems incorrect, coin spends can assert one another requiring others occur and there are other ways in which coins interact and can impact one another (ex. oracles)

I think it's just worded poorly. I'll update it.

BrandtH22 · 2026-06-23T15:50:59Z

+
+Coin spends cannot impact other coin spends, which is a very nice property of UTXO systems, and allows parallelization of validation and block creation. The aggregate spend bundle also has one aggregate signature, which is a combination of every signature from every transaction in that block.
+
+For performance reasons, the chia-blockchain codebase currently creates only smaller blocks (less than 50% of the maximum size) in order to keep the blockchain smaller and easier to run. This "throttle" is likely to be removed in future versions, after additional optimizations have been performed.


This is not accurately portrayed, we are at max block fill now but the mempool only accepts transactions that are less than 50% of a block (per transaction not in total)

Will remove.

BrandtH22 · 2026-06-23T16:21:06Z

+
+### Picking transactions
+
+The mempool data structure maintains all mempool items ordered by fee per cost, highest fee first.


This seems to duplicate the information above

BrandtH22 · 2026-06-23T16:21:52Z

+
+This logic is implemented in [chia/full_node/mempool.py](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/full_node/mempool.py) in `create_block_generator()`.
+
+Since Q2 2025, we use a new algorithm (`create_block_generator2()`) which interleaves picking transactions and serializing them (in compressed form). This way, we have a good understanding of the exact cost of the block and can keep filling it with more transactions if the previous ones compressed well.


We should have the version and if it was height bound include the height at thich this was enforced

I'll add the version, but it wasn't enforced at a specific block (it is outside of consensus).

BrandtH22 · 2026-06-23T17:20:01Z

+
+The mempool is a required facet of Chia due to the decentralized nature of the blockchain. Transaction blocks occur approximately every 52 seconds, and it's impossible to predict who will win a block. Therefore, all transactions must be broadcast to the whole network and stored locally until they are confirmed. Additionally, it is normal to have more pending transactions than can fit in a single block, so the mempool also acts as a queue for inclusion into the blockchain.
+
+For more information about the mempool, see our [blog post](https://www.chia.net/2024/01/12/getting-to-know-the-mempool-and-transaction-fees/) on this subject.


Should this link to the other pages being added too?

BrandtH22 · 2026-06-23T17:21:30Z

@@ -0,0 +1,81 @@
+---
+title: Identical Spend Deduplication
+slug: /chia-blockchain/architecture/mempool/isd


should this slug be more url friendly? (/chia-blockchain/architecture/mempool/identical-spend-deduplication)

BrandtH22 · 2026-06-23T17:26:14Z

+
+### Replacement
+
+A spend that supports Dedup is not considered in conflict with an existing spend of the same coin that also supports Dedup. The new spend must also use the exact same solution as the existing spend. The mempool implementation checks that the solution `bytes` are identical.


Dedup is capitalized here but not in other instances

BrandtH22 · 2026-06-23T17:27:42Z

@@ -0,0 +1,36 @@
+---
+title: Replace by Fee
+slug: /chia-blockchain/architecture/mempool/rbf


SHould we also make this slug url friendly? (replace-by-fee instead of rbf)

BrandtH22 · 2026-06-23T17:31:03Z

+slug: /chia-blockchain/architecture/mempool/updates
+---
+
+After a new block is added to the blockchain, all full nodes must look at the coins that were spent in that new block, and remove them from the mempool. The full node does not need to reapply every transaction again, since Chia coin spends are deterministic and sandboxed (see the [Coin Set Intro page](/chia-blockchain/coin-set-model/intro) for more information). The full node only needs to look at the spent coins in the new block, and if there are any transactions that spend one of those coins, they are removed from the mempool. This means the mempool can be very large, the codebase can be simple, and high performance can be achieved.


For how little is on this page should it just be added to the overview page?

BrandtH22

Also block-formation-basics.md in the chia academy docs has the old mempool link and should be updated

BrandtH22 · 2026-06-23T17:40:22Z

+```yaml
+full_node:
+  block_creation: 1 # Enable new algorithm
+  block_creation_timeout: 30 # 30 second timeout


The default is 2 seconds not 30: https://github.com/Chia-Network/chia-blockchain/blob/0d5a394cf996a49626e009b3f8ac10ed645b74c3/chia/util/initial-config.yaml#L330

BrandtH22 · 2026-06-23T17:41:22Z

+The full conditions for replace by fee are:
+
+1. The new spend bundle needs to include at least all the spends in the original one (the super set rule)
+2. The new spend bundle needs to pay a higher fee per cost than the original one (and higher than the [minimum fee required for inclusion](https://docs.chia.net/chia-blockchain/architecture/mempool/#fee-required-for-inclusion))


This link needs to be updated for the changes in this pr

BrandtH22 · 2026-06-23T17:42:08Z

+
+### Transaction Deduplication
+
+Starting in Chia 2.5.5, the mempool automatically detects and deduplicates identical spend transactions. When multiple transactions attempt to spend the same coin with identical parameters, only one will be kept in the mempool, reducing memory usage and improving overall performance.


I believe ISD was added in 1.8.2 and 2.5.5 upgraded that logic

Update mempool docs

228a663

danieljperry deployed to Review 1034 June 18, 2026 08:14 — with GitHub Actions View deployment

BrandtH22 requested changes Jun 23, 2026

View reviewed changes

BrandtH22 reviewed Jun 23, 2026

View reviewed changes


		When the farmer makes a block, they will select the highest fee-per-cost transactions from the mempool until they reach the maximum block size. These spend bundles are combined into one large spend bundle, which is guaranteed to be valid, since all spend bundles in the mempool must spend disjointed coins.

		Coin spends cannot impact other coin spends, which is a very nice property of UTXO systems, and allows parallelization of validation and block creation. The aggregate spend bundle also has one aggregate signature, which is a combination of every signature from every transaction in that block.


		Coin spends cannot impact other coin spends, which is a very nice property of UTXO systems, and allows parallelization of validation and block creation. The aggregate spend bundle also has one aggregate signature, which is a combination of every signature from every transaction in that block.

		For performance reasons, the chia-blockchain codebase currently creates only smaller blocks (less than 50% of the maximum size) in order to keep the blockchain smaller and easier to run. This "throttle" is likely to be removed in future versions, after additional optimizations have been performed.


		### Picking transactions

		The mempool data structure maintains all mempool items ordered by fee per cost, highest fee first.


		This logic is implemented in [chia/full_node/mempool.py](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/full_node/mempool.py) in `create_block_generator()`.

		Since Q2 2025, we use a new algorithm (`create_block_generator2()`) which interleaves picking transactions and serializing them (in compressed form). This way, we have a good understanding of the exact cost of the block and can keep filling it with more transactions if the previous ones compressed well.


		The mempool is a required facet of Chia due to the decentralized nature of the blockchain. Transaction blocks occur approximately every 52 seconds, and it's impossible to predict who will win a block. Therefore, all transactions must be broadcast to the whole network and stored locally until they are confirmed. Additionally, it is normal to have more pending transactions than can fit in a single block, so the mempool also acts as a queue for inclusion into the blockchain.

		For more information about the mempool, see our [blog post](https://www.chia.net/2024/01/12/getting-to-know-the-mempool-and-transaction-fees/) on this subject.


		### Replacement

		A spend that supports Dedup is not considered in conflict with an existing spend of the same coin that also supports Dedup. The new spend must also use the exact same solution as the existing spend. The mempool implementation checks that the solution `bytes` are identical.


		### Transaction Deduplication

		Starting in Chia 2.5.5, the mempool automatically detects and deduplicates identical spend transactions. When multiple transactions attempt to spend the same coin with identical parameters, only one will be kept in the mempool, reducing memory usage and improving overall performance.

Uh oh!

Conversation

danieljperry commented Jun 18, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BrandtH22 commented Jun 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BrandtH22 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

danieljperry commented Jun 18, 2026 •

edited by cursor Bot

Loading