Skip to content

docs(validity): document nonce predicate and required block expiry - #2104

Draft
youssefea wants to merge 2 commits into
base:masterfrom
youssefea:docs/nonce-validity-predicate
Draft

youssefea wants to merge 2 commits into
base:masterfrom
youssefea:docs/nonce-validity-predicate

Conversation

@youssefea

@youssefea youssefea commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

What changed? Why?

base/base adds a nonce validity predicate in v1.5.0 (see ValidityPredicate::Nonce in crates/execution/txpool/src/validity.rs). This PR documents it:

  • Adds nonce (address, op, value) to the predicate tables on Predicates and Safety and Validity Transaction RPC.
  • Adds a Nonce Example to Predicates and Safety. It covers the protocol nonce, the 0 nonce for absent accounts, and what happens when a nonce moves past an upper bound (the transaction stays pending until its block_number bound passes).
  • Lists nonce on the Overview and Build a Validity Transaction pages.

It also fixes the RPC request example. Every submission must include a block_number upper bound within the 60-second window (enforced since v1.4.2, and already described under Expiry on Fees, Ordering, and Lifecycle), but the example had only a storage predicate, so the RPC would reject it as written.

Notes to reviewers

Draft until base/base 1.5.x reaches mainnet nodes. Please don't merge before then. Signed validity predicates and the fill-or-kill flag are feature-flag gated and will get separate comms, so this PR leaves them out.

An independent review by GPT-6 Astra checked the PR against base/base. Its changes are applied in the second commit:

  • The block_number value in the RPC and build-guide examples is marked as a placeholder, with instructions to set it from eth_blockNumber (latest + 10).
  • The nonce explanation now says it checks current protocol-nonce state only (not EIP-8130 channel nonces, deleted accounts read as 0) and does not prove that an earlier transaction succeeded.
  • The expiry note no longer says a nonce-mismatched transaction stays pending until the block bound. Base checks it again when the nonce changes, and a flashblock_index bound can end it earlier.

How has it been tested?

  • node scripts/lint-mdx.js on the changed files: 0 errors (7 existing highlight={} suggestions).
  • npm test: pass.
  • Checked predicate semantics against base/base main and the v1.5.0-rc.8 / v1.4.2 tags.

Screenshots

N/A (text and table changes only; no layout changes)

Generated with Toshi

Add the nonce validity predicate (base/base v1.5.0) to the predicate
tables, overview, and build guide, with an example and evaluation notes.
Add the mandatory block_number upper bound to the RPC request example,
which the RPC already rejects without one.
@cb-heimdall

Copy link
Copy Markdown
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
Sum 1

Explain that the block_number example value is a placeholder and how to
set it, clarify that the nonce predicate checks protocol nonce state
only, and correct the expiry behavior after a nonce mismatch.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants