Local network: L2 finality trails ~32 blocks behind head, so one account stalls on the PXE tagging window after 27 private transfers

[1ll-main]

Aztec version: 5.2.0 (aztec start --local-network, CLI wallet), Linux x86_64. Not run on nightly, but v6.0.0-nightly.20260910 has the same anvil launch line and the same window (84).

What happens

One account uses the bundled Token and calls transfer(self, 1) in a loop. The 28th transfer fails with:

Highest used index 84 is at or past the window end 84 (no index finalized yet). Tagging window length 84 is configured too low. Contact the Aztec team to increase it!

Retrying fails the same way. At that point the chain tips were proposed=34 proven=34 finalized=2, and the account's first tx on this tagging secret was in block 7.

Why

• The local network starts anvil with default settings: anvil --silent --port "$ANVIL_PORT" in yarn-project/aztec/scripts/aztec.sh (now in aztec-labs-eng/aztec-node). L1 finalized is therefore latest - 64.
• Anvil mines only when an L1 tx arrives (automine, as the Local Network RFC Local Network requirements #23258 describes), which came to about 2 L1 blocks per L2 block here. The L2 finalized tip ends up about 32 blocks behind the head.
• Each self-transfer uses 3 tag indexes (the mint uses 1), so the account fills the 84-index window before any of its txs finalize.
• On an idle local network nothing else advances L1, so it never recovers on its own.

Evidence

• Mining 70 L1 blocks (JSON-RPC anvil_mine) moved L2 finalized from 2 to 34, and the same wallet DB then sent 5 more transfers.
• With anvil pre-started on 8545 as anvil --silent --port 8545 --slots-in-an-epoch 1 (the wrapper's own anvil then fails to bind), 60 transfers in a row succeeded, with finalized one block behind the head.

Possibly missed in #21156

#21156 replaced the finalized-block heuristic (provenBlock - 2 * epochDuration) with L1 finality. It also gave the test helper startAnvil a --slots-in-an-epoch 1 default, "so the finalized block advances immediately, making tests that check L1-finality-based logic work without needing hundreds of mined blocks". aztec.sh already had the local-network anvil line then, and that PR didn't change it. The Local Network RFC (#23258) expects blocks to become proven near-immediately but doesn't mention finality.

If this is unintended, passing --slots-in-an-epoch 1 to the local-network anvil would avoid it. We haven't checked for side effects: some e2e tests raise slotsInAnEpoch (#21452 to 32, #21869 to 4) because near-immediate finality broke reorg and sentinel tests.

Repro

Token.json is the bundled token_contract-Token.json, copied to a path without @. The CLI treats paths containing @ as nargo package refs.

aztec start --local-network
aztec-wallet import-test-accounts
aztec-wallet deploy ./Token.json -f accounts:test0 -a token --args <test0> Token TKN 18
aztec-wallet send set_minter -ca contracts:token -c ./Token.json --args <test0> true -f accounts:test0
aztec-wallet send mint_to_private -ca contracts:token -c ./Token.json --args <test0> 1000000 -f accounts:test0
for i in $(seq 1 28); do
  aztec-wallet send transfer -ca contracts:token -c ./Token.json --args <test0> 1 -f accounts:test0 || break
done

Related

• [BUG] PXE: "Conflicting range" corruption at the UNFINALIZED tagging window boundary — variant not covered by the v4.3.0 fix (CLI wallet, v4.4.0) #24485 (closed): the earlier Conflicting range report.
• fix(pxe): UNFINALIZED_TAGGING_INDEXES_WINDOW_LEN should be MAX_PRIVATE_LOGS_PER_TX + headroom, not exactly MAX_PRIVATE_LOGS_PER_TX #24437: sets the window to MAX_PRIVATE_LOGS_PER_TX + 20.
• PXE: a publicly reverted tx keeps its pending sender tagging index until L1 finality, blocking the account's further constrained note deliveries #25418: sender tagging also waits on L1 finality after a public revert, on testnet.

[1ll-main]

Related context: in #24486 a maintainer explained that on the local network the anchor block only advances when a tx is sent, which is expected. This issue is different in two ways. The stall happens while the account is sending txs continuously: at the failure the tips were proposed=34 finalized=2, so constant activity doesn't keep finality close. And once it hits, the account can't send the tx that would move things forward, so it needs outside action such as anvil_mine.

[1ll-main]

I verified that matching the existing startAnvil helper's finality setting resolves the reproduced stall. The proposed change in yarn-project/aztec/scripts/aztec.sh is:

-      anvil --silent --port "$ANVIL_PORT" &
+      anvil --silent --port "$ANVIL_PORT" --slots-in-an-epoch 1 &

Validation:

• On v5.2.0, the original launcher stalled on private self-transfer 28. Adding only this flag allowed 60 consecutive private self-transfers to complete.
• I added a regression test that runs the actual shell launcher with real Anvil, replacing only the L2 entrypoint. After mining 100 blocks, the original launcher reports finalized block 36; the patched launcher reports block 98, as expected.
• For the proposed change in aztec-labs-eng/aztec-node, full bootstrap, TypeScript build, repository-wide formatting and lint checks, and all 92 CLI tests passed.

The complete fix and regression test are available in the accompanying local-network-finality.patch.txt, based on aztec-labs-eng/aztec-node main at f6971440a4306410f3a43566aa89693b3eacde94. It can be applied with git am local-network-finality.patch.txt.

Sharing the patch here because PR creation is restricted to collaborators.