celestiaorg / celestiaorg/docs
docs: document heavy RPC concurrency limits after celestia-app adoption
- Dominant language
- MDX
- Stars
- 183
- Forks
- 423
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 19
Description
## Context
[`celestia-core` PR #3240](https://github.com/celestiaorg/celestia-core/pull/3240) adds a process-wide concurrency limit for memory-intensive RPC requests. The new `[rpc].max_concurrent_heavy_requests` setting defaults to `20` and gates endpoints including `data_root_inclusion_proof` and `prove_shares`, which are documented on the Blobstream proof queries page.
When the limit is saturated:
- URI/GET requests return HTTP `503 Service Unavailable`.
- JSON-RPC and WebSocket requests return a JSON-RPC error.
- gRPC requests return `ResourceExhausted`.
The change is merged to `celestia-core` main but is not in v0.40.8. As of August 27, 2026, `celestia-app` also still pins `celestia-core` v0.40.8.
## Blocker
Do not publish the new behavior as currently available until a `celestia-app` release includes a `celestia-core` version containing PR #3240.
## Documentation scope
- [ ] Confirm the first `celestia-app` release containing `celestia-core` PR #3240.
- [ ] Update `app/build/blobstream/proof-queries/page.mdx` with overload behavior and retry guidance using exponential backoff and jitter.
- [ ] Update the RPC configuration section of `app/operate/consensus-validators/consensus-node/page.mdx` with `[rpc].max_concurrent_heavy_requests`.
- [ ] Document the default of `20`, that `0` selects the built-in default, and that a negative value disables the limit and is not recommended.
- [ ] Explain that raising the limit increases peak memory usage and should be sized and monitored against available RAM.
- [ ] Run `yarn lint` and `yarn build` before merging.
## Upstream references
- https://github.com/celestiaorg/celestia-core/pull/3240
- https://github.com/celestiaorg/celestia-core/releases/tag/v0.40.8
- https://github.com/celestiaorg/celestia-app/blob/main/go.mod
Contributor guide
Research direction
Check celestia-core PR #3240, its v0.40.8 release, and celestia-app's go.mod to confirm the first app release containing the change. Update app/build/blobstream/proof-queries/page.mdx and app/operate/consensus-validators/consensus-node/page.mdx with the documented limits, overload responses, retry guidance, and memory warning. Run yarn lint and yarn build; done when the release dependency is confirmed and both pages accurately describe the available behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- grpc
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100