docs: document Bradbury's per-transaction gas ceiling

[ygd58]

Summary

Documents a real, currently-undocumented deployment blocker on TestnetBradbury: Python contracts above roughly 20KB of source are undeployable via any gas value, with no explanation anywhere in the docs, and eth_estimateGas actively misleads by returning a plausible-looking (but doomed) estimate.

Background

Root-caused through a multi-person community investigation in genlayer-cli#419:

• Bradbury enforces a fixed 16,777,216 (2^24) gas limit per transaction — a zksync-os runtime chain config value (DEFAULT_MAX_TX_GAS_LIMIT), added for EIP-7825 alignment.
• eth_estimateGas skips this check entirely (simulation-only), so it can return an estimate like 28–32M for a deployment that will actually be rejected at eth_sendRawTransaction with gas limit too high and no revert reason.
• A transaction signed close enough to the boundary can be accepted by the RPC and still run out of gas mid-execution — same ceiling, hit from the other side. Confirmed via debug_traceTransaction: an out-of-gas revert five frames deep, no reason string (explaining why the RPC gives no useful error either way).
• Python Intelligent Contracts need roughly 730 gas per byte of source to deploy, so the fixed 2^24 ceiling puts source contracts above ~20KB at risk of being undeployable, regardless of gas limit requested.

I did not root-cause this alone — crediting it explicitly in the doc. My own contribution was a systematic binary search narrowing the exact boundary (16,777,216 accepted, 16,777,217+ rejected); a separate contributor (eudomar500, credited in the linked issue) traced the exact upgrade transaction on the block explorer that introduced the cap and confirmed the mechanism via debug_traceTransaction.

Change

Added a "Known Limitations" section to deploying.mdx (the main deploy overview page), right after the existing Networks Overview section where Bradbury is already introduced. Covers:

• The exact ceiling and why eth_estimateGas doesn't catch it
• The ~730 gas/byte → ~20KB practical size implication
• Workarounds (split into multiple contracts; verify at the actual gas limit near the boundary rather than trusting the estimate)
• That this is a runtime chain config value the Bradbury admin can raise without a network fork — not permanently fixed

Testing

Verified the file compiles with the real @mdx-js/mdx compiler.

Summary by CodeRabbit

• Documentation
  • Added guidance on TestnetBradbury’s 16,777,216 gas-per-transaction limit, including why gas estimates may succeed even when transactions are rejected.
  • Documented that larger Python Intelligent Contracts may exceed the limit, along with workarounds such as splitting contracts and testing transactions at the intended gas limit. The guidance also notes that administrators can raise the limit.

[netlify]

✅ Deploy Preview for genlayer-docs ready!

Name	Link
🔨 Latest commit	b000c2c
🔍 Latest deploy log	https://app.netlify.com/projects/genlayer-docs/deploys/6ab3cf6ec4184b00085b45e3
😎 Deploy Preview	https://deploy-preview-566--genlayer-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 89f308bc-590d-4b6e-8c3e-062697581770

📥 Commits

Reviewing files that changed from the base of the PR and between 1cd8e2d and b000c2c.

📒 Files selected for processing (1)

• pages/developers/intelligent-contracts/deploying.mdx

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The deploying guide adds a Known Limitations section about Bradbury’s per-transaction gas ceiling. It describes gas estimation and transaction submission behavior, Python contract size considerations, workarounds, and a community investigation.

Changes

Bradbury gas ceiling documentation

Layer / File(s)	Summary
Gas ceiling limitation and workarounds pages/developers/intelligent-contracts/deploying.mdx	The guide documents the 16,777,216 gas ceiling, explains that gas estimates may not reflect the submission limit, describes possible rejection of larger Python contracts, and lists workarounds. It also cites a community investigation.

Priority: ⚪ Not assessed

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to b000c

The new guidance explains a deployment limit and its workarounds. No issue identified here prevents merging.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses the Conventional Commits format and clearly identifies the documentation change: documenting Bradbury's per-transaction gas ceiling.
Description check	✅ Passed	The description is complete and relevant. It explains the limitation, technical cause, impact, workarounds, investigation references, and validation performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}