Network upgrades

Each entry below describes what changed in a StableChain release, why it matters, and whether you need to do anything. Releases are listed newest first. For binaries, commit hashes, and upgrade block heights, see the Mainnet version history and Testnet version history.

How to read these notes

A few terms appear throughout. Here is what they mean:

State-breaking upgrade: every node must run the new binary at the same block height, coordinated through a governance proposal. These releases have an upgrade height in the version history table. If you run a validator, you have to upgrade on schedule or your node stops following the chain.
Backward-compatible upgrade: the new binary works with the old one, so there is no coordinated cutover. These releases have no upgrade height. You can upgrade whenever it suits you by replacing the binary.
Gas waiver: a StableChain feature that lets a sponsor cover a transaction's fees, so the sender can transact without holding the gas token.
System transaction: a special transaction the protocol itself issues, rather than a regular user, to run internal operations.
Precompile: a built-in contract at a fixed address that runs native code instead of EVM bytecode, used for common operations that need to be fast.

To check which version your node runs:

stabled version

v1.3.1

v1.4.0 (upcoming)
Testnet

A performance and predictability release, currently live on Testnet as a release candidate and not yet on Mainnet. It groups four changes under two themes: making blocks process faster, and making transaction inclusion more predictable for priority traffic.

Initiative	Block stage	What changes	Intended result
Optimistic parallel execution (OPE)	Execution	Block-STM replaces sequential transaction execution.	Multicore execution, targeting approximately 10,000 TPS.
Selective RecheckTx	Post-commit mempool recheck	The node rechecks transactions only from accounts changed by the committed block.	Up to twice the sustained throughput in the measured best case, with 31–34% less node CPU use.
MemIAVL	State persistence	A memory-mapped snapshot and write-ahead log (WAL) replace the LevelDB-backed store.	Write amplification falls from 10–50 times to approximately one write.
2D nonce and guaranteed blockspace	Submission and block proposal	Independent nonce channels combine with reserved per-lane gas capacity.	Deterministic next-block inclusion for eligible VIP transactions.

These changes address different stages of one block lifecycle:

Submission: a 2D nonce lets an account submit transactions through independent nonce channels. A stuck transaction on one channel does not block the others.
Proposal: guaranteed blockspace divides a block into VIP, transaction-type, and normal lanes. Each lane has a reserved gas budget enforced during proposal and validation.
Execution: OPE runs transactions concurrently through Block-STM, then validates them against a fixed in-block order. Every node still produces the same state.
Commit: MemIAVL appends changes to a WAL against one memory-mapped snapshot. This avoids LevelDB compaction and its repeated disk writes.
Post-commit recheck: Selective RecheckTx uses the block's state-change delta to recheck only affected senders instead of scanning the full mempool.

Throughput changes

OPE moves transaction execution from one CPU core to multiple cores. Transactions execute optimistically, conflicts trigger re-execution, and the fixed transaction order preserves deterministic results.

Selective RecheckTx removes work after each commit. In a best-case test with 10,000 pending transactions from unique senders, throughput increased from 700 to 1,400 TPS. The projected improvement for more typical workloads is 1.5–1.7 times. CometBFT detects whether the application supports selective recheck and falls back to full recheck when it does not.

MemIAVL removes LevelDB from the state-store path. Writes become sequential WAL entries containing raw change sets. Reads become pointer lookups into the operating system's page cache. A separate VersionDB, backed by RocksDB, serves historical state older than the earliest retained snapshot.

Predictable inclusion

A 2D nonce gives each account multiple independent nonce channels. NonceKey selects the channel. NonceKey = 0 preserves the normal EVM-compatible sequence, while the protocol reserves the upper half of the uint64 range for its own use. MaxUint64 marks an unordered transaction, which uses TimeoutTimestamp for replay protection.

The release adds CustomTx, transaction type 0x3F, alongside existing EVM transaction formats. The protocol-reserved NonceKey range also identifies VIP-lane transactions.

Guaranteed blockspace divides each block into VIP, transaction-type, and normal lanes with separate gas quotas. Governance controls the lane parameters through one MsgUpdateParams proposal, and an accepted update takes effect in the next block. With no lane configuration, the chain behaves as one normal lane.

Eligible VIP transactions receive deterministic next-block inclusion when validators behave honestly and the network remains synchronous. Read Guaranteed blockspace for the lane and nonce model.

Node rollout

MemIAVL changes the state store, so node operators must migrate their existing data. The recommended method is a local snapshot export and restore. Benchmarks measured an average of 19.4 seconds of downtime per validator. A parallel restore variant reduced that average to approximately 2.6 seconds.

Validators can migrate in round-robin order to preserve at least two-thirds of voting power. Follow the network-specific upgrade instructions rather than treating the benchmark procedure as a fixed runbook.

Deferred work

Gas-waiving transaction-type lane: a zero-gas lane needs trusted mempool admission control. Without it, an attacker could submit unlimited free transactions.
Sender-matching optimization: a later release may let full nodes send precomputed sender addresses with transactions, avoiding repeated signature recovery during block proposal.

v1.3.1
Current

A backward-compatible patch and the current Mainnet version. It ships with no coordinated upgrade height, so node operators can adopt it by replacing the binary at any time.

v1.3.0

A security-focused, state-breaking upgrade that also made the gas waiver feature more flexible. The gas waiver change lets new partners such as wallets and exchanges be onboarded through a governance proposal later, instead of requiring another state-breaking upgrade each time.

Who needs to act: all node operators upgrade at the scheduled height. See the Mainnet version history for the exact height.

Security improvements:

Non-public JSON-RPC namespaces are no longer registered, and signing APIs are enabled only when AllowInsecureUnlock=true.
Gas waiver inputs are hardened: addresses must use the EIP-55 canonical format, query inputs are length- and format-restricted, and wrapper type, chain-id, and EIP-7702 inner-transaction validation are strengthened.
System transactions are now validated against the to address and method selector, not just the from address. This closes a path that could trigger fee-free execution.
The Prague precompile address range is added to the blocked-address list, and unknown precompile methods now require query gas.

Bug fixes and stability:

Corrected gas accounting for failed stateful precompile calls.
Resolved a refund-disable state leak after an ERC-20 internal call failure.
Fixed precompile warm-set tracking and COINBASE opcode behavior.
Aligned EIP-7702 authorization rollback with the spec.
Fixed system transaction responses that reported from=0x0, feeHistory error logging, and chain-id consistency in historical full-transaction responses.

v1.2.2

A backward-compatible, optional upgrade that aligns StableChain with the official upstream consensus release and cleans up two query behaviors.

Who needs to act: no one is required to. This upgrade needs no governance proposal. Node operators can adopt it by replacing the binary whenever convenient.

Changes:

Upgraded CometBFT to the official v0.38.21. This follows the security patch shipped earlier in v1.1.4 and lets external partners verify the exact consensus version the network runs.
Removed a duplicate log index in gas waiver transaction queries.
Added safeguards to RPC responses for system-transaction queries.

v1.2.1

A backward-compatible hotfix that remediated two issues which, if exploited, could halt the chain.

Who needs to act: validators are required to upgrade. For other node operators, including RPC providers, the upgrade is optional. It needs no governance proposal.

Fixes:

Closed a system-transaction spoofing path where a user could set MsgEthereumTx.From == 0x1 to bypass authentication and call a system-only precompile, then use the spoofed transaction to repeatedly force ProcessProposal to reject blocks and stall consensus.
Fixed a mempool-poisoning chain-halt where ExtensionOptionsWaiver transactions could pass CheckTx but cause ProcessProposal to reject the entire block.

Earlier releases

Detailed release notes start at v1.2.1. For v1.2.0 and earlier, including the genesis release, see the version history tables for binaries, commit hashes, and upgrade heights:

Mainnet version history: every Mainnet version with its binary and upgrade height.
Testnet version history: every Testnet version, including release candidates.

Where to go next

Upgrade a node: Follow the step-by-step procedure to move your node to a new version.
Mainnet version history: Look up commit hashes, binaries, and upgrade heights for every Mainnet release.
Mainnet information: Get the chain ID, RPC endpoints, and current network parameters.