This release includes significant changes accumulated since May 2025 while waiting for the Celestia App v4/v5 mainnet update. Please review all breaking changes carefully before upgrading.

TL;DR

šŸšØ This release breaks both API and config!

  • āš ļø API Breaking Changes
    • JSON integers now encoded as strings (Tendermint compatibility)
    • Blobstream root encoding switched to hex (plus pointer cleanups in Go API)
    • Gateway removed ā†’ use direct API; configure CORS as needed
    • Share Samples API now usesĀ heightĀ parameter instead of ExtendedHeader
    • Share encoding in Samples response changed toĀ base64 stringĀ (was object with data field)
  • šŸ¤šŸ» Data Retention Changes
    • Full Nodes: Pruning enabled by default (ā‰ˆ30 days)
    • Light Nodes: Sampling window reduced to 7 days
    • Use --archival to keep full history
    • Update config to remove pruning-related fields
  • āœØ API Enhancements ā€“ Configurable CORS, new client library, multi-endpoint tx submission
  • šŸŽ Faster GetRange ā€“ Uses shwap protocol for efficient partial retrieval
  • šŸŽļø Performance Boosts ā€“ Parallelized namespace data; optimized blob retrieval
  • šŸ„¾ Bootstrap Updates ā€“ Added 01node mainnet bootstrap; removed outdated nodes

šŸšØ Breaking Changes

šŸ—’ļø Configuration Breaking Changes

This release contains configuration breaking changes. Node operators must run the config update command before starting their node:

celestia <node_type> config-update --p2p.network  (or --node.store)

āš ļø API & JSON Compatibility

Changes:

  • Integer values in JSON responses are now encoded as strings for Tendermint compatibility
  • Example: ā€œheightā€: 67374 becomes ā€œheightā€: ā€œ67374ā€

Migration: Update JSON parsing logic to handle integers as strings in header, share range, and blob commitment proof endpoints.

Share API Consistency Improvements

Samples Method Signature Change

  • !fix(api/share) use height in Samples method byĀ @walldissĀ inĀ #4481

Changes:

  • SamplesĀ method now acceptsĀ heightĀ parameter directly
  • No longer requires passingĀ ExtendedHeader
  • Brings consistency with other share module methods

Migration:

// Before:
samples, err := client.Share.GetSamples(ctx, header)

// After:
samples, err := client.Share.GetSamples(ctx, height)

Share Encoding in Samples Response

  • !fix(api/share) encode share in sample json as base64 byĀ @walldissĀ inĀ #4480

Changes:

  • Shares inĀ GetSamplesĀ response now encoded as base64 strings
  • Previously encoded as objects withĀ dataĀ field
  • Matches encoding format used byĀ GetRowĀ and other methods

Migration:

// Before (v0.25.0-v0.25.1):
{
  "share": {
    "data": "AAAAAAA...base64..."
  },
  "proof": { ... }
}

// After (v0.25.2+):
{
  "share": "AAAAAAA...base64...",
  "proof": { ... }
}

Update JSON parsing to expect shares as direct base64 strings rather than nested objects.

āŒ Gateway Removal

Migration: If you were using the gateway, switch to direct API endpoints. Configure CORS policy using the new configurable CORS feature if needed.

šŸ…±ļø Blobstream API Changes

Changes:

  • DataRootTupleRoot: String encoding changed from base64 to hex bytes
  • DataRootTupleInclusionProof: Removed extra pointer (affects native Go API only, not JSON encoding)
  • GetDataRootTupleRoot: Removed extra pointer in returned value (affects native Go API only)
  • Blobstream API is now publicly documented

Migration:

  • Update code expecting base64 encoded roots to handle hex encoding
  • Go API users: Update code to handle direct values instead of pointers

āœØ GetRange efficiency improvements

Changes:

  • GetRange requests now use efficient P2P protocol instead of downloading entire EDS
  • Significant performance improvement for partial data retrieval

Migration: Update clients using range requests to use the new shwap protocol implementation.

āœØ API New Features + Enhancements

šŸ¤šŸ» Data Pruning Now Default

Changes:

  • Data pruning is now enabled by default (stores 30 days of data)
  • Sampling window reduced from 30 to 7 days
  • Archival nodes must use --archival flag to disable pruning
  • The pruner configuration field has been completely removed from node config files
  • Pruning behavior is now controlled exclusively via command-line flags

Migration:

  • Remove any pruner-related configuration from your config files
  • To run an archival node (disable pruning):Ā MUST useĀ -archivalĀ flagĀ when starting the node
  • All other nodes: Remove -experimental-pruning flag (pruning is now automatic)
  • Adjust monitoring for the new 7-day sampling window
  • Default behavior (without flag): Pruning enabled with 30-day retention

šŸ§Ŗ Testing Infrastructure

šŸš€ Performance Improvements

šŸ¦€ Rust Users ā€“ Required Upgrade

Rust ecosystemĀ must upgradeĀ to maintain RPC compatibility with v0.25.

Upgrade timeline:

  • If you doĀ notĀ useĀ header.GetRangeByHeight: upgrade immediately.
  • If youĀ doĀ use it: upgrade Rust crates & celestia-nodeĀ together.

šŸ”„ Bootstrap Nodes

:wrench: Bug Fixes

Addressing memory leak in light node (LN)

FULL CHANGELOG

New Contributors

Full Changelog: https://github.com/celestiaorg/celestia-node/compare/v0.24.1...v0.25.3