Skip to content

More BSTM Updates #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Eric-Warehime merged 1 commit into from
Mar 30, 2026
+31 −0
Merged

More BSTM Updates #268

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions sdk/next/experimental/blockstm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,37 @@ Block-STM implements a form of optimistic concurrency control to enable parallel

Block-STM is currently only integrated into the `FinalizeBlock` phase of execution, meaning the code path is never accessed until the block is agreed upon in consensus. It is possible that the algorithm may be extended in the future to support different execution models, but as of right now it expects a complete block and returns its result after the entire block has been executed. For this reason, Block-STM is expected to produce identical results to serial execution. In other words, the `AppHash` produced by Block-STM's parallel execution should be equal to the `AppHash` produced by the default serial transaction runner.

## Safe Deployment Practices

Given the Block-STM executor is a general purpose parallel execution engine, we recommend a phased rollout with
extensive
testing for each application individually.
Comment on lines +34 to +36
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Accidental line break splits intro sentence

The word extensive is orphaned on its own line, which appears to be an editing artifact. While most Markdown renderers will collapse this into a single space, it reads awkwardly in source and could confuse future editors.

Suggested change
Given the Block-STM executor is a general purpose parallel execution engine, we recommend a phased rollout with
extensive
testing for each application individually.
Given the Block-STM executor is a general-purpose parallel execution engine, we recommend a phased rollout with extensive testing for each application individually.

(Also note: "general-purpose" should be hyphenated when used as a compound modifier before a noun.)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!


* _Phased Rollout_

Since parallel execution is purely a performance optimization, applications should expect to calculate the same
AppHash when using Block-STM as they would when serial execution is enabled via the default TxRunner. This allows teams
to turn on parallel execution for a fraction of their nodes--API nodes instead of validators or on a portion of a
distributed validator cluster for example.

Running with a mixed fleet of parallel and serial execution for an extended time should minimize blast radius in the
event that a failure occurs.

* _Message Type Support_

We have done testing on as many of the core SDK message types as possible, but given the Cosmos SDK allows arbitrary
message creation it will be impossible to validate all message types that exist and all combinations of workflows.
Each team integrating Block-STM in production should validate their own message types for both correctness and performance.

NOTE: We specifically have __not__ validated support for CosmWasm message types run using Block-STM. Run independent
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Use ** for emphasis instead of __

Double-underscores for bold (__not__) can behave inconsistently in some MDX parsers, particularly when surrounded by non-whitespace characters. The ** syntax is more portable and consistent with the rest of the document.

Suggested change
NOTE: We specifically have __not__ validated support for CosmWasm message types run using Block-STM. Run independent
NOTE: We specifically have **not** validated support for CosmWasm message types run using Block-STM. Run independent

validation before enabling if your chain uses CosmWasm.

* _Caching Risks_

Block-STM works via dependency tracking within the SDK's `MultiStore` interface. Any data which could cause stateful
changes to execution that lives outside the store poses the biggest risk for indeterminism. We recommend in general
avoiding the use of cached data, in memory stores, or persisting any state outside the scope of a `Store`.
Comment on lines +38 to +61
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Bullet content not indented under list items

In Markdown/MDX, a blank line after a list item followed by non-indented text breaks the association — the paragraphs render as standalone text outside the list rather than as continuations of each bullet. This means readers may not visually connect each heading (_Phased Rollout_, _Message Type Support_, _Caching Risks_) with its explanatory paragraph.

To keep content inside the list item, indent the paragraphs with at least two spaces:

* _Phased Rollout_

  Since parallel execution is purely a performance optimization, applications should expect to calculate the same
  AppHash when using Block-STM as they would when serial execution is enabled via the default TxRunner. ...

* _Message Type Support_

  We have done testing on as many of the core SDK message types as possible, ...

* _Caching Risks_

  Block-STM works via dependency tracking within the SDK's `MultiStore` interface. ...

Alternatively, use ### subheadings instead of italic bullets for each sub-topic, which is more consistent with the rest of the document's structure.


## App Integration

Integration of parallel execution is abstracted into two interfaces: `DeliverTxFunc` and `TxRunner`.
Expand Down