celestiaorg / celestiaorg/docs

docs: document heavy RPC concurrency limits after celestia-app adoption

Open
#2,579 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.