docs(solidity,upgrade): document amsterdam, eip-2935 and block.basefee

[gzliudan]

Proposed changes

docs/solidity.md stops at Osaka: nothing tells a contract author that the Amsterdam fork now has a switch here, or that --evm-version amsterdam artifacts cannot be deployed or run. It also states the gas price floor twice - under ## Special variables, and again in a standalone ## Gas price section - when the floor and block.basefee are the same number.

docs/upgrade.md has the reverse gap: its ## Prague / EIP-2935 section tells an operator that the history contract is deployed by the system call and that an upgrading node backfills recent parent hashes into the ring buffer. Neither is what ProcessParentBlockHash does, and neither is what EIP-2935 specifies, and what the contract lets a contract read is written down nowhere.

Summary

 docs/solidity.md
+  ## Prague / EIP-2935        # NEW: what a contract can read
+  Amsterdam column in the activation table, plus note 7 on the `amsterdam` target
+  EIP-7954: 24,576/49,152 today, 65,536/131,072 once Amsterdam is active
-  ## Gas price                # the floor, said a second time
+  the floor moves under ### block.basefee, which it equals
+  note 5 loses its "Prague is not active yet" premise
+  the tier table gains a second testnet row for Gas2500x, where the floor becomes 625 GWei

 docs/upgrade.md
-  hard-wrapped paragraphs, lists flattened onto the bullet's own line
+  one line per paragraph; the presence-tracking sub-items, the six upgrade steps
+  and the four network choices are lists again
+  the EIP-2935 section states how the contract reaches the state, on this chain and
+  upstream, and that the window starts with a single entry
+  the fork declaration rule covers amsterdamBlock, not pragueBlock alone

Eight commits, one subject each:

1. docs(upgrade): normalise the wrapping and structure of the upgrade notes - 278 lines leave and 129 arrive, and the file goes to one line per paragraph, so an edit to a paragraph later shows up as a diff on that paragraph instead of across the lines it happened to span. The same pass restores structure the wrapping had flattened: the presence-tracking bullets carry their four labelled sub-items as sub-items (73 such lines), the six steps of the chain-config procedure are a list, and each of the four networks is one bullet with its startup flag and its notes. Fenced blocks, tables and list indentation are untouched.
2. docs(solidity): rewrite the gas price notes against block.basefee - the floor sentence, the per-network table and the eth_gasPrice advice move under ### block.basefee, and the standalone ## Gas price section goes away. The table names the base fee next to the floor, because they are the same number. The sentence also records the exemption for the block-signer and randomize system contracts, and the file loses the blank line the removed section had left at the end.
3. docs(solidity): rewrap the notes and document the amsterdam evm version - an Amsterdam column that is TBD on every network, a note recording that 0.8.36 began exposing the target and that 0.8.37 added block.slotnum and slotnum() behind --evm-version amsterdam (still experimental, not the compiler default), and the EIP-7954 code and initcode limits, which are gated on Amsterdam rather than Osaka. This is also where the rest of the file moves to one line per paragraph, and the new column is padded to the row width so the activation table stays aligned.
4. docs(solidity): document the prague eip-2935 history contract - a ## Prague / EIP-2935 section for the contract-facing half: the address, the 8191-block window, that blockhash is unchanged and still answers for 256 blocks only, that reading an older hash means calling the contract, that a number outside the window reverts rather than returning zero, and that a slot inside the window which was never written reads back as zero.
5. docs(upgrade): correct the eip-2935 deployment and backfill notes - the section said an upgrading node backfills recent parent hashes. Block processing instead deploys the contract at the activation block, writes that block's parent hash into one slot, and adds one more per block, so every other slot reads back as zero until 8,191 blocks have passed - which is what EIP-2935 states under its activation scenarios. The section also records the upstream route, where the account is created by the presigned deployment transaction the EIP specifies and clients carry no deployment code of their own, and the two further local deviations in failure handling and in the state budget upstream adds to system calls from Amsterdam on.
6. docs(solidity): drop the stale prague premise from note 5 - the note still asked the reader to imagine Prague activating "in the future", while the table in the same file has carried devnet at 50000 all along.
7. docs(solidity): add the testnet gas2500x tier to the base fee table - the table named one tier fork per network, but testnet also sets Gas2500xBlock at 83600000, where the floor moves from 12.5 GWei to 625 GWei. The prose already described the transition; the table an operator looks up did not. The tier gets its own testnet row rather than a second fork on one row.
8. docs(upgrade): generalise the fork declaration requirement - the section named Prague alone, but amsterdamBlock joins the same rule: it is part of the built-in backfill set and is not inherited by custom-network hydration, so it needs the same explicit declaration.

Commits 1 and 5 to 8 are the layout pass and the corrections that follow from it: commit 1 holds every layout change to docs/upgrade.md, and no later commit there touches layout.

Merge order

This branch assumes #2756 (feat(core,params): add the amsterdam fork switch) and #2757 (fix(core,params): move the eip-7954 code size raise to amsterdam) have landed first. The text says the Amsterdam fork switch exists and that the fork is unscheduled, and it states the EIP-7954 limits as gated on Amsterdam - all three are true only after those two, which carry no docs/ change of their own.

Evidence

• Before: docs/upgrade.md 709 lines, hard-wrapped; docs/solidity.md 103 lines, no Amsterdam, no EIP-2935 section, the floor stated twice.
  After: 564 and 80 lines; docs/upgrade.md keeps its 8 fences on both sides, and docs/solidity.md goes from 15 table rows to 16 - the extra one is the second testnet tier.

Commit 1 changes layout only. Take the two revisions as token streams, list markers and whitespace stripped, and 22 tokens leave while 12 arrive - exactly the six step letters a.-f., replaced by the list numbering, and the four … notes: labels, replaced by Startup: labels with the note text as sub-items. No word of the notes is lost:

git show 3894de05f^:docs/upgrade.md | sed 's/^[ \t]*-[ \t]*//' | tr -s '[:space:]' '\n' | grep -v '^$' > /tmp/before
git show 3894de05f:docs/upgrade.md  | sed 's/^[ \t]*-[ \t]*//' | tr -s '[:space:]' '\n' | grep -v '^$' > /tmp/after
diff /tmp/before /tmp/after   # 22 tokens out, 12 in

The rest states what the code does. The floor is params.GetMinGasPrice (params/gas.go:146), which resolves through tierGasPrice - common.DefaultMinGasPrice, 0.25 GWei at common/constants.go:19, times 50 or 2500 - and core/txpool/validation.go:308 rejects anything priced below it with ErrUnderMinGasPrice, except transactions to the block-signer and randomize system contracts. The block numbers in the table are Gas50xBlock/Gas2500xBlock in params/config_networks.go (80370000, 56828700, 83600000, 1385100). BLOCKHASH is untouched in core/vm/instructions.go:432, where everything outside the last 256 blocks answers zero.

The EIP-2935 section follows the specification. HistoryStorageCode (params/protocol_params.go:214) is byte-identical to upstream go-ethereum's; its get reverts when the requested number is at or past the current block or more than 8191 blocks behind it, and otherwise returns the stored slot, which is zero for a slot that was never written. EIP-2935's activation scenarios say the same - at activation the ring holds the fork block's parent hash only and every other slot is 0 - and its Deployment section creates the account with a presigned transaction, sender 0x3462413Af4609098e1E27A490f554f260213D685, transaction hash 0x67139a552b0d3fffc30c0fa7d0c20d42144138c8fe07fc5691f09c1cce632e15. ProcessParentBlockHash (core/state_processor.go:717) instead deploys the code itself when it is missing, which is also where the local catch-up backfill lives.

No Go change anywhere in the branch. git diff --name-only dev-upgrade...HEAD -- '*.go' is empty, which is also why no test run applies - there is no executable path to exercise.

make all                  # clean
gofmt -l, goimports -l    # no output

Merge Danger

Door: two-way

Documentation only. No wire format, header layout, storage layout, RPC surface or consensus rule is touched, and reverting restores the previous text exactly.

Blast Radius: documentation

docs/solidity.md loses its top-level ## Gas price heading, so a deep link to that anchor stops resolving; nothing in this repository links to it (git grep 'solidity.md#' is empty). Both files end up with a ## Prague / EIP-2935 section - the Solidity one covers what a contract can read, the upgrade one how the contract reaches the state - and neither points at the other, which is deliberate: they are read by different audiences and the anchors are identical, so a cross-reference could not be made unambiguous without renaming a heading.

Types of changes

• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Changes that don't change source code or tests
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• revert: Revert something
• style: Changes that do not affect the meaning of the code
• test: Adding missing tests or correcting existing tests

Impacted Components

• Consensus
• Account
• Network
• Geth
• Smart Contract
• External components
• Not sure (Please specify below)

No component applies: the change is confined to docs/.

Checklist

• This PR has sufficient test coverage (unit/integration test) OR I have provided reason in the PR description for not having test coverage
• Tested on a private network from the genesis block and monitored the chain operating correctly for multiple epochs.
• Provide an end-to-end test plan in the PR description on how to manually test it on the devnet/testnet.
• Tested the backwards compatibility.
• Tested with XDC nodes running this version co-exist with those running the previous version.
• Relevant documentation has been updated as part of this PR
• N/A

The test-coverage item is answered with the reason rather than a test: the branch contains no .go change, so there is no executable path to cover.

The four network-facing items are not applicable. No network schedules Amsterdam and every live network also leaves osakaBlock unset, so there is no chain to run from genesis, no epoch to observe, no end-to-end plan to give, and no cross-version behaviour to compare - the change is text.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2cf9a882-c1f2-49ca-bc53-27f937f02fba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}