feat: Add `useCache` optional param to `getLatestBlock()` #340

jiexi · 2025-10-07T17:49:38Z

Adds useCache param option to getLatestBlock() which ignores the cache block number value in state when false. Defaults: true

These changes are needed to enable a way for the blockRef middleware
to correctly fetch and return the most recent block number when the BlockTracker isn't polling by avoiding the cache, but also while ensuring that we don't refetch the block number if it is not stale yet.

See: https://consensyssoftware.atlassian.net/browse/NWNT-615

Note

Adds optional useCache to getLatestBlock() (defaults true) to bypass cache when needed, refines running/non-running fetch logic with rate limiting, updates tests, and documents in changelog.

Core (src/PollingBlockTracker.ts)
- getLatestBlock({ useCache = true } = {}): supports cache bypass; when running, waits for next latest event; when not running, fetches immediately via _updateLatestBlock() and rate-limits by delaying pending promise cleanup to pollingInterval.
- _updateLatestBlock() now returns the latest block string instead of void.
- checkForLatestBlock(): marked deprecated in JSDoc; now updates and returns latest via getLatestBlock().
Tests (src/PollingBlockTracker.test.ts)
- Add comprehensive cases for useCache: false across not-running and running states, including concurrency and timing.
Docs
- Update CHANGELOG.md under Unreleased to note the new useCache option and behavior.

^{Written by Cursor Bugbot for commit aa0f910. This will update automatically on new commits. Configure here.}

jiexi · 2025-10-07T17:52:57Z

src/PollingBlockTracker.ts

-        const latestBlock = await this._fetchLatestBlock();
-        this._newPotentialLatest(latestBlock);
+        const latestBlock = await this._updateLatestBlock();


~~this logic is equivalent. I've only DRY'ed it~~

This logic is almost equivalent. It fixes a bug where the value from _fetchLatestBlock() was being returned (and resolved) even if this._newPotentialLatest() may not have actually set the block number as the newest in state.

Hmm, I'm not sure I'm following. _fetchLatestBlock just makes a request, it does not update this._currentBlock. That happens in _newPotentialLatest. But we resolve the #pendingLatestBlock promise after we update _currentBlock anyway. So... shouldn't your code be equivalent?

Maybe you could create a failing test?

The difference is that previously, we always used latestBlock from this._fetchLatestBlock. Even if it's not the latest block.

Whereas now we set latestBlock to the return value of _updateLatestBlock which returns this._currentBlock, which is always the latest block.

latestBlock is now always latest, whereas before it was technically possible it was set to an older block (if, somehow, we received a stale response from the RPC endpoint).

whereas before it was technically possible it was set to an older block (if, somehow, we received a stale response from the RPC endpoint).

Okay, I was not aware we had run into that edge case or that we were attempting to solve that in this PR. Based on the original bug report and other reports in the past, I thought that we were only handling the case in which the latest block number stops advancing, not that it goes backward. But I suppose these changes are more technically correct, so okay.

As far as I know, we did not run into that edge case, nor was fixing it an intended goal here. I believe it was fixed incidentally while refactoring

yeah, a good example of doing too much in one PR

should I undo this or move it into a separate PR?

I think it's okay to include here. You mention in the PR that we want to "correctly fetch and return the most recent block number", and this is part of that, so I think it makes sense.

src/PollingBlockTracker.ts

…unning

src/PollingBlockTracker.ts

mcmire · 2025-10-07T21:28:38Z

These changes are needed to enable a way for the blockRef middleware
to correctly fetch and return the most recent block number when the BlockTracker isn't polling by avoiding the cache, but also while ensuring that we don't refetch the block number if it is not stale yet.

@jiexi Interesting. Can you give an example of how you expect the middleware to use the new options you've added?

jiexi · 2025-10-07T21:42:21Z

@mcmire This line in the BlockRef middleware would just become const latestBlockNumber = await blockTracker.getLatestBlock({useCache: false});

src/PollingBlockTracker.ts

Co-authored-by: Mark Stacey <markjstacey@gmail.com>

…l/fetch-latest-if-stale

mcmire · 2025-10-07T22:05:24Z

@mcmire This line in the BlockRef middleware would just become const latestBlockNumber = await blockTracker.getLatestBlock({useCache: false});

Hmm. I'm curious to know how this will work in practice. Requests to eth_blockNumber are cached via the block cache middleware. So I believe that if the block tracker is not running, even if you disable the block tracker's cache, in the context of our conventional middleware stack, getLatestBlock will still return the same block number until the block tracker is resumed... right?

mcmire · 2025-10-07T22:42:17Z

Requests to eth_blockNumber are cached via the block cache middleware.

Wait, this can't be right, or else there'd be infinite recursion between the middleware and the block tracker 🤔

Putting that aside, then... Wouldn't bypassing the block tracker cache mean that we'd make a request for the latest block on each request through the provider, if the block tracker is not running?

src/PollingBlockTracker.test.ts

Gudahtt · 2025-10-08T13:15:19Z

Putting that aside, then... Wouldn't bypassing the block tracker cache mean that we'd make a request for the latest block on each request through the provider, if the block tracker is not running?

Not exactly. If the tracker is active, it will just wait for the next polling loop. If it's not active, it will only make a request if one hasn't been made within X seconds (the same as the polling interval). We're still capped at making at most one request per polling interval most of the time.

There are edge cases where the polling is stopped then started again, where more frequent calls are technically possible. Though this is a pre-existing issue, and not likely to manifest as a major volume issue (for an individual or overall)

Gudahtt · 2025-10-08T14:06:28Z

Requests to eth_blockNumber are cached via the block cache middleware.

Only if they're made via a network client, or with a provider/middleware pipeline with the network client in it. That's where the caching middleware is.

The block tracker itself uses a provider with just a single middleware function, the fetch middleware. No caching middleware.

src/PollingBlockTracker.ts

mcmire · 2025-10-08T14:47:45Z

src/PollingBlockTracker.ts

+        // We want to rate limit calls to this method if we made a direct fetch
+        // for the block number because the BlockTracker was not running. We
+        // achieve this by delaying the unsetting of the #pendingLatestBlock promise.
+        setTimeout(() => {


Ah, this is how we are ensuring we aren't making a new request when calling getLatestBlock({ useCache: false }). Nice.

mcmire · 2025-10-08T15:06:16Z

@jiexi @Gudahtt Okay, I re-reviewed this PR and I guess I had missed the addition of setTimeout to rate limit requests when the block tracker is not running. This addresses my concern.

I had one thought. Even with these changes, when useCache is true, if we've previously retrieved the latest block number, we will always reuse it, until the next time the block tracker runs. getLatestBlock, then, assumes that at some point the block tracker will run. If that assumption is not true and at some point the block tracker won't run, then getLatestBlock is effectively useless, unless the developer always uses useCache: false.

In other words, in adding useCache: false, we do provide a way to ensure that we are using the latest block number even when the block tracker is not running. But the pitfall that we are addressing is present nonetheless.

My question is, do we need useCache? Would it be more useful to always capture the last fetched time and if getLatestBlock is called within the cache timeframe, it returns the last fetched block number, otherwise it either waits for the next block or fetches it immediately? I realize that would fundamentally change how getLatestBlock would work and I know we're looking for a fast solution but wanted to throw that out there.

Gudahtt · 2025-10-08T15:31:14Z

Great question! That definitely might be a good idea. I feel similarly, the default value (i.e. the behaviour more closely matching how the block tracker acts today) doesn't seem useful even as an option.

The reason for making it an optional parameter for now would be to avoid a breaking change, while we're addressing this critical bug at least. It also minimizes risks that this has some unintended impact.

Gudahtt

Could you update the changelog as well?

CHANGELOG.md

Gudahtt · 2025-10-08T16:57:03Z

src/PollingBlockTracker.test.ts

+              });
+              await timeoutCallbacks[1]();
+              const block2 = await blockPromise2;
+              expect(block2).toBe('0x3');


I'm having trouble understanding how this test asserts the description. i.e. if the block tracker didn't wait for the next block, what is stopping this test from passing?

Because of the numAutomaticCalls: 2 would only allow 2 setTimeouts to pass. This allows 3 update loops to occur:

first update happens immediately (not via setTimeout), and queues up setTimeout for second update

second update happens after setTimeout is executed, and queues up setTimeout for third update

third update happens after setTimeout is executed

but if the getLatestBlock() call wasn't waiting for the next block, we'd have 2 more setTimeouts we'd need to await for, which would cause the test to fail since it would need to allow 3 setTimeouts to pass.

first update happens immediately (not via setTimeout), and queues up setTimeout for second update

first getLatestBlock() is called, waits for second update

second update happens after setTimeout is executed, and queues up setTimeout for third update

first getLatestBlock() gets event, queues up setTimeout to release the pendingBlock promise

second getLatestBlock() is called, waits for third update

third update happens after setTimeout is executed

second getLatestBlock() gets event

actually, I shouldn't need to call timeoutCallbacks though given the automatic calls. Let me play around with this again

cleaned up here 17ae0e0

added explicit _waitingForNextIteration checks here f233852

but if the getLatestBlock() call wasn't waiting for the next block, we'd have 2 more setTimeouts we'd need to await for

I was thinking of the opposite case. i.e. what if it incorrectly fetches immediately instead of waiting for the next loop. This test would still pass despite that behavior contradicting the description

Actually no, the await pollingLoopPromise1 step should timeout in that case. Nevermind, I think that's covered now as well

Co-authored-by: Mark Stacey <markjstacey@gmail.com>

…l/fetch-latest-if-stale

mcmire · 2025-10-08T17:53:49Z

@jiexi Would you mind updating the changelog in this PR? This is a practice that we have slowly been rolling out to all library repos; it is easier to do while you have the context in your head and it saves time later when making a release. (EDIT: Oh, you did, I guess I hadn't refreshed the page. Maybe we can capture fixing getLatestBlock so that it no longer returns a stale block number as a separate bullet point?)

jiexi · 2025-10-08T18:05:39Z

Maybe we can capture fixing getLatestBlock so that it no longer returns a stale block number as a separate bullet point?)

Mark actually pointed out that this bug didn't actually exist. I was wrong to say it was a bug.

#340 (comment)

cursor · 2025-10-08T18:06:28Z

src/PollingBlockTracker.ts

-        const latestBlock = await this._fetchLatestBlock();
-        this._newPotentialLatest(latestBlock);
+      try {
+        const latestBlock = await this._updateLatestBlock();


Bug: Stale Block Data in Latest Block Retrieval

The _updateLatestBlock method returns this._currentBlock which can be stale or null if _newPotentialLatest rejects the freshly fetched block. This causes getLatestBlock({ useCache: false }) to return outdated data or throw a runtime error. Also, when the tracker is running, getLatestBlock({ useCache: false }) waits for the next polling event instead of fetching immediately.

Additional Locations (1)

src/PollingBlockTracker.ts#L324-L332

mcmire · 2025-10-08T18:06:09Z

CHANGELOG.md

+### Changed
+
+- `PollingBlockTracker.getLatestBlock()` now accepts an optional param option `useCache` which ignores the cached block number value in state and instead updates and returns a new block number retrieved within the last `pollingInterval` period when false. Defaults: true ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))


I wonder if "state" could create confusion since this isn't a controller. Maybe we can clean up the wording a bit. We can also document the edge cased we fixed:

Suggested change

### Changed

- `PollingBlockTracker.getLatestBlock()` now accepts an optional param option `useCache` which ignores the cached block number value in state and instead updates and returns a new block number retrieved within the last `pollingInterval` period when false. Defaults: true ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

### Changed

- `PollingBlockTracker.getLatestBlock()` now accepts an optional parameter `useCache` ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

- This option defaults to `true`, but when `false`, it ignores the cached block number and instead updates and returns a new block number, ensuring that the frequency of requests is limited to the `pollingInterval` period

### Fixed

- Fix `PollingBlockTracker.getLatestBlock()` so it always returns monotonically increasing block numbers ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

- If the RPC endpoint returns a stale block number that is less than a previous request it will effectively be ignored

(EDIT: If we didn't really fix a bug, then I guess we just have)

Suggested change

### Changed

- `PollingBlockTracker.getLatestBlock()` now accepts an optional param option `useCache` which ignores the cached block number value in state and instead updates and returns a new block number retrieved within the last `pollingInterval` period when false. Defaults: true ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

### Changed

- `PollingBlockTracker.getLatestBlock()` now accepts an optional parameter `useCache` ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

- This option defaults to `true`, but when `false`, it ignores the cached block number and instead updates and returns a new block number, ensuring that the frequency of requests is limited to the `pollingInterval` period

(Or something like that. Probably could be refined further.)

took the first half your suggestion here aa0f910

Gudahtt

LGTM!

…)" This reverts commit 1d1406b.

add options to getLatestBlock

3da8732

jiexi requested a review from a team as a code owner October 7, 2025 17:49

jiexi added 2 commits October 7, 2025 10:51

lint

f3ef6e6

cleanup wasRunning

22006e4

jiexi commented Oct 7, 2025

View reviewed changes

src/PollingBlockTracker.ts Outdated Show resolved Hide resolved

jiexi commented Oct 7, 2025

View reviewed changes

src/PollingBlockTracker.ts Outdated Show resolved Hide resolved

jiexi changed the title ~~feat: Add cache and wait optional params to getLatestBlock()~~ feat: Add useCache and waitForPending optional params to getLatestBlock() Oct 7, 2025

only delay unsetting pendingLatestBlock if the block tracker is not r…

194e855

…unning

This comment was marked as outdated.

Sign in to view

jiexi added 3 commits October 7, 2025 12:14

lint

6453182

remove extra space

51b24f8

fix polling isRunning check in getLatestBlock

c1842b9

This comment was marked as outdated.

Sign in to view

Gudahtt reviewed Oct 7, 2025

View reviewed changes

src/PollingBlockTracker.ts Outdated Show resolved Hide resolved

jiexi added 2 commits October 7, 2025 14:19

remove waitForPending

f59c095

restore checkForLatestBlock

20b6c10

reorganize getLatestBlock fetch and poll try catch blocks

83e8a15

jiexi changed the title ~~feat: Add useCache and waitForPending optional params to getLatestBlock()~~ feat: Add useCache optional params to getLatestBlock() Oct 7, 2025

jiexi changed the title ~~feat: Add useCache optional params to getLatestBlock()~~ feat: Add useCache optional param to getLatestBlock() Oct 7, 2025

Gudahtt reviewed Oct 7, 2025

View reviewed changes

src/PollingBlockTracker.ts Outdated Show resolved Hide resolved

jiexi and others added 5 commits October 7, 2025 14:45

mark checkForLatestBlock deprecated

9a516e8

Update src/PollingBlockTracker.ts

ce63eb1

Co-authored-by: Mark Stacey <markjstacey@gmail.com>

jsdoc

e23bc9c

Merge remote-tracking branch 'origin/jl/fetch-latest-if-stale' into j…

30a2cfd

…l/fetch-latest-if-stale

lint

3d63b9d

jiexi added 2 commits October 7, 2025 17:29

Add specs

8e41b21

add specs

a71ca3d

jiexi commented Oct 8, 2025

View reviewed changes

src/PollingBlockTracker.test.ts Show resolved Hide resolved

cryptodev-2s reviewed Oct 8, 2025

View reviewed changes

src/PollingBlockTracker.ts Show resolved Hide resolved

mcmire reviewed Oct 8, 2025

View reviewed changes

Gudahtt reviewed Oct 8, 2025

View reviewed changes

jiexi added 2 commits October 8, 2025 08:51

cleanup numAutomaticCalls

32a138e

changelog

2407ab3

Gudahtt reviewed Oct 8, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Gudahtt reviewed Oct 8, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Gudahtt reviewed Oct 8, 2025

View reviewed changes

jiexi and others added 4 commits October 8, 2025 10:15

Apply suggestion from @Gudahtt

e49d5bc

Co-authored-by: Mark Stacey <markjstacey@gmail.com>

update changelog

70c87f5

Merge remote-tracking branch 'origin/jl/fetch-latest-if-stale' into j…

e3d13f1

…l/fetch-latest-if-stale

cleanup when the block tracker is already started spec

17ae0e0

add explicit _waitingForNextIteration event checks

f233852

cursor bot reviewed Oct 8, 2025

View reviewed changes

mcmire reviewed Oct 8, 2025

View reviewed changes

update changelog using Elliot's comment

aa0f910

Gudahtt approved these changes Oct 8, 2025

View reviewed changes

jiexi merged commit 1d1406b into main Oct 8, 2025
15 checks passed

jiexi deleted the jl/fetch-latest-if-stale branch October 8, 2025 18:52

jiexi mentioned this pull request Oct 9, 2025

[Bug]: Critical - Provider data stale/bad when connected network differs from activity filter network MetaMask/metamask-extension#36532

Closed

jiexi added a commit that referenced this pull request Oct 15, 2025

Revert "feat: Add useCache optional param to getLatestBlock() (#340…

4db4a51

…)" This reverts commit 1d1406b.

		### Changed

		- `PollingBlockTracker.getLatestBlock()` now accepts an optional param option `useCache` which ignores the cached block number value in state and instead updates and returns a new block number retrieved within the last `pollingInterval` period when false. Defaults: true ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))

-### Changed
-- `PollingBlockTracker.getLatestBlock()` now accepts an optional param option `useCache` which ignores the cached block number value in state and instead updates and returns a new block number retrieved within the last `pollingInterval` period when false. Defaults: true ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))
+### Changed
+- `PollingBlockTracker.getLatestBlock()` now accepts an optional parameter `useCache` ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))
+  - This option defaults to `true`, but when `false`, it ignores the cached block number and instead updates and returns a new block number, ensuring that the frequency of requests is limited to the `pollingInterval` period
+### Fixed
+- Fix `PollingBlockTracker.getLatestBlock()` so it always returns monotonically increasing block numbers ([#340](https://github.com/MetaMask/eth-block-tracker/pull/340))
+  - If the RPC endpoint returns a stale block number that is less than a previous request it will effectively be ignored

Uh oh!

feat: Add useCache optional param to getLatestBlock() #340

feat: Add useCache optional param to getLatestBlock() #340

Uh oh!

Conversation

jiexi commented Oct 7, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jiexi Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

mcmire commented Oct 7, 2025

Uh oh!

jiexi commented Oct 7, 2025

Uh oh!

Uh oh!

mcmire commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcmire commented Oct 7, 2025

Uh oh!

Uh oh!

Gudahtt commented Oct 8, 2025

Uh oh!

Gudahtt commented Oct 8, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Gudahtt commented Oct 8, 2025

Uh oh!

Gudahtt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jiexi Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

feat: Add `useCache` optional param to `getLatestBlock()` #340

feat: Add `useCache` optional param to `getLatestBlock()` #340

jiexi commented Oct 7, 2025 •

edited by cursor bot

Loading

jiexi Oct 7, 2025 •

edited

Loading

mcmire Oct 8, 2025 •

edited

Loading

mcmire commented Oct 7, 2025 •

edited

Loading

mcmire commented Oct 8, 2025 •

edited

Loading

jiexi Oct 8, 2025 •

edited

Loading

mcmire commented Oct 8, 2025 •

edited

Loading

mcmire Oct 8, 2025 •

edited

Loading