feat(tempo): expiring nonces (wevm#4304)

* feat(tempo): expiring nonces (TIP-1009)

- Rename nonceKey: 'random' to nonceKey: 'expiring' to align with TIP-1009 terminology
- Add automatic concurrent transaction detection using event loop tick tracking
- Extract validBefore from test snapshots and add direct assertions
- Refactor concurrent detection into separate module (internal/concurrent.ts)
- Update documentation with explanation and link to TIP-1009
- Fix validator.test.ts to use random addresses to avoid ValidatorAlreadyExists errors

BREAKING CHANGE: nonceKey: 'random' renamed to nonceKey: 'expiring'

Amp-Thread-ID: https://ampcode.com/threads/T-019c0606-05cd-7147-8ed8-c9c6c50e208c
Co-authored-by: Amp <amp@ampcode.com>

* Update shiny-nonces-expire.md

* chore: fmt

* chore: tweaks

* u

* chore: u

* chore: up

* chore: up

* chore: up

---------

Co-authored-by: Amp <amp@ampcode.com>

Author: jxom

.changeset/shiny-nonces-expire.md

@@ -0,0 +1,16 @@
+---
+"viem": minor
+---
+
+**Breaking (`viem/tempo`):** Renamed `nonceKey: 'random'` to `nonceKey: 'expiring'` to align with [TIP-1009](https://docs.tempo.xyz/protocol/tips/tip-1009) terminology.
+
+TIP-1009 defines "expiring nonces" as time-based replay protection using `validBefore` timestamps. The name `'expiring'` better describes the mechanism than `'random'`.
+
+```diff
+await sendTransaction(client, {
+  account,
+- nonceKey: 'random',
++ nonceKey: 'expiring',
+  to: '0x...',
+})
+```

pnpm-lock.yaml

@@ -46,9 +46,9 @@ Nonce for the transaction.
 
 ### nonceKey (optional)
 
-- **Type:** `'random' | bigint`
+- **Type:** `'expiring' | bigint`
 
-Nonce key for the transaction. Use `'random'` to generate a random nonce key.
+Nonce key for the transaction. Use `'expiring'` to use [expiring nonces (TIP-1009)](https://docs.tempo.xyz/protocol/tips/tip-1009), which enables concurrent transaction submission without nonce ordering.
 
 ### validBefore (optional)
 

site/snippets/tempo/write-parameters.mdx

@@ -29,7 +29,6 @@ describe('decorator', () => {
         "amm",
         "dex",
         "faucet",
-        "nonce",
         "fee",
         "policy",
         "reward",

src/tempo/Decorator.test.ts

@@ -121,7 +121,7 @@ export type TransactionRequestTempo<
     calls?: readonly TxTempo.Call<quantity>[] | undefined
     feePayer?: Account | true | undefined
     feeToken?: Address | bigint | undefined
-    nonceKey?: 'random' | quantity | undefined
+    nonceKey?: 'expiring' | quantity | undefined
     validBefore?: index | undefined
     validAfter?: index | undefined
   }

src/tempo/Transaction.ts

@@ -107,7 +107,7 @@ describe('withFeePayer', () => {
       const receipt = await sendTransactionSync(client, {
         account,
         feePayer: true,
-        to: '0x0000000000000000000000000000000000000000',
+        to: '0x0000000000000000000000000000000000000001',
       })
 
       expect(receipt.status).toBe('success')
@@ -118,7 +118,7 @@ describe('withFeePayer', () => {
     test('behavior: non-sponsored transaction uses default transport', async () => {
       const receipt = await sendTransactionSync(client, {
         account: accounts[0],
-        to: '0x0000000000000000000000000000000000000000',
+        to: '0x0000000000000000000000000000000000000002',
       })
 
       expect(receipt.status).toBe('success')

src/tempo/Transport.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect, test } from 'vitest'
 import { accounts, getClient, nodeEnv } from '~test/tempo/config.js'
+import {
+  generatePrivateKey,
+  privateKeyToAddress,
+} from '../../accounts/index.js'
 import { isAddress } from '../../utils/address/isAddress.js'
 import * as actions from './index.js'
 
 const account = accounts[0]
 const account2 = accounts[1]
 const validator = accounts[19]
+const randomValidatorAddress = privateKeyToAddress(generatePrivateKey())
 
 const client = getClient({
   account,
@@ -16,7 +21,7 @@ describe.runIf(nodeEnv === 'localnet')('add', () => {
     const initialCount = await actions.validator.getCount(client)
 
     const { receipt } = await actions.validator.addSync(client, {
-      newValidatorAddress: account2.address,
+      newValidatorAddress: randomValidatorAddress,
       publicKey:
         '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
       active: true,
@@ -31,9 +36,9 @@ describe.runIf(nodeEnv === 'localnet')('add', () => {
 
     // Verify the validator was added
     const validator = await actions.validator.get(client, {
-      validator: account2.address,
+      validator: randomValidatorAddress,
     })
-    expect(validator.validatorAddress).toBe(account2.address)
+    expect(validator.validatorAddress).toBe(randomValidatorAddress)
     expect(validator.active).toBe(true)
   })
 

src/tempo/actions/validator.test.ts

@@ -18,42 +18,33 @@ const client = getClient({
   account: accounts.at(0)!,
 })
 
+const maxUint256 = 2n ** 256n - 1n
+
 describe('prepareTransactionRequest', () => {
-  test('behavior: sequential nonce keys for feePayer transactions', async () => {
+  test('behavior: expiring nonces for feePayer transactions', async () => {
+    const now = Math.floor(Date.now() / 1000)
     const requests = await Promise.all([
       prepareTransactionRequest(client, { feePayer: true }),
       prepareTransactionRequest(client, { feePayer: true }),
       prepareTransactionRequest(client, { feePayer: true }),
     ])
 
-    expect(requests[0]?.nonceKey).toBe(0n)
-    expect(requests[1]?.nonceKey).toBeGreaterThan(0n)
-    expect(requests[2]?.nonceKey).toBeGreaterThan(0n)
-  })
-
-  test('behavior: nonce key counter resets after event loop tick', async () => {
-    const requests1 = await Promise.all([
-      prepareTransactionRequest(client, { feePayer: true }),
-      prepareTransactionRequest(client, { feePayer: true }),
-    ])
-
-    expect(requests1[0]?.nonceKey).toBe(0n)
-    expect(requests1[1]?.nonceKey).toBeGreaterThan(0n)
+    // All feePayer transactions use expiring nonces (nonceKey = uint256.max)
+    expect(requests[0]?.nonceKey).toBe(maxUint256)
+    expect(requests[1]?.nonceKey).toBe(maxUint256)
+    expect(requests[2]?.nonceKey).toBe(maxUint256)
 
-    // Wait for microtask queue to flush
-    await new Promise((resolve) => queueMicrotask(() => resolve(undefined)))
-
-    const requests2 = await Promise.all([
-      prepareTransactionRequest(client, { feePayer: true }),
-      prepareTransactionRequest(client, { feePayer: true }),
-    ])
+    // All should have nonce = 0 for expiring nonces
+    expect(requests[0]?.nonce).toBe(0)
+    expect(requests[1]?.nonce).toBe(0)
+    expect(requests[2]?.nonce).toBe(0)
 
-    // Counter should have reset
-    expect(requests2[0]?.nonceKey).toBe(0n)
-    expect(requests2[1]?.nonceKey).toBeGreaterThan(0n)
+    // All should have validBefore set within 30 seconds
+    expect(requests[0]?.validBefore).toBeGreaterThanOrEqual(now)
+    expect(requests[0]?.validBefore).toBeLessThanOrEqual(now + 31)
   })
 
-  test('behavior: explicit nonceKey overrides counter', async () => {
+  test('behavior: explicit nonceKey overrides expiring nonce', async () => {
     const requests = await Promise.all([
       prepareTransactionRequest(client, {
         feePayer: true,
@@ -66,50 +57,46 @@ describe('prepareTransactionRequest', () => {
       }),
     ])
 
+    // Explicit nonceKey uses 2D nonce mode
     expect(requests[0]?.nonceKey).toBe(42n)
-    expect(requests[1]?.nonceKey).toBe(0n)
+    expect(requests[0]?.validBefore).toBeUndefined()
+
+    // Default feePayer uses expiring nonces
+    expect(requests[1]?.nonceKey).toBe(maxUint256)
+    expect(requests[1]?.validBefore).toBeDefined()
+
     expect(requests[2]?.nonceKey).toBe(100n)
+    expect(requests[2]?.validBefore).toBeUndefined()
   })
 
-  test('behavior: default nonceKey when feePayer is not true', async () => {
+  test('behavior: default nonceKey when feePayer is not set', async () => {
     const request = await prepareTransactionRequest(client, {})
     expect(request?.nonceKey).toBe(undefined)
+    expect(request?.validBefore).toBeUndefined()
   })
 
-  test('behavior: nonce with sequential nonceKey', async () => {
-    const requests = await Promise.all([
-      prepareTransactionRequest(client, { feePayer: true }), // nonceKey: 0n
-      prepareTransactionRequest(client, { feePayer: true }), // nonceKey: 1n
-      prepareTransactionRequest(client, { feePayer: true }), // nonceKey: 2n
-    ])
-
-    expect(requests[0]?.nonce).toBeDefined()
-    expect(requests[0]?.nonceKey).toBe(0n)
-
-    // nonceKey >= 1n is truthy, so nonce is 0
-    expect(requests[1]?.nonce).toBe(0)
-    expect(requests[1]?.nonceKey).toBeGreaterThan(0n)
-
-    expect(requests[2]?.nonce).toBe(0)
-    expect(requests[2]?.nonceKey).toBeGreaterThan(0n)
+  test('behavior: nonceKey expiring uses expiring nonces', async () => {
+    const now = Math.floor(Date.now() / 1000)
+    const request = await prepareTransactionRequest(client, {
+      nonceKey: 'expiring',
+    })
+    expect(request?.nonceKey).toBe(maxUint256)
+    expect(request?.nonce).toBe(0)
+    expect(request?.validBefore).toBeGreaterThanOrEqual(now)
+    expect(request?.validBefore).toBeLessThanOrEqual(now + 31)
   })
 
-  test('behavior: explicit nonce is preserved', async () => {
+  test('behavior: explicit validBefore is preserved', async () => {
+    const customValidBefore = Math.floor(Date.now() / 1000) + 15
     const request = await prepareTransactionRequest(client, {
       feePayer: true,
-      nonce: 123,
+      validBefore: customValidBefore,
     })
-    expect(request?.nonce).toBe(123)
-    expect(request?.nonceKey).toBe(0n)
-  })
-
-  test('behavior: default nonceKey is 0n (falsy)', async () => {
-    const request = await prepareTransactionRequest(client, {})
-    expect(request?.nonceKey).toBe(undefined)
-    expect(request?.nonce).toBeDefined()
+    expect(request?.nonceKey).toBe(maxUint256)
+    expect(request?.validBefore).toBe(customValidBefore)
   })
 
-  test('behavior: sendTransaction', async () => {
+  test('behavior: sendTransaction with expiring nonces', async () => {
     const receipts = await Promise.all([
       sendTransactionSync(client, {
         to: '0x0000000000000000000000000000000000000000',
@@ -134,9 +121,10 @@ describe('prepareTransactionRequest', () => {
         hash: receipts[2].transactionHash,
       }),
     ])
-    expect(transactions[0].nonceKey).toBe(undefined)
-    expect(transactions[1].nonceKey).toBeGreaterThan(0n)
-    expect(transactions[2].nonceKey).toBeGreaterThan(0n)
+    // Concurrent transactions automatically use expiring nonces
+    expect(transactions[0].nonceKey).toBe(maxUint256)
+    expect(transactions[1].nonceKey).toBe(maxUint256)
+    expect(transactions[2].nonceKey).toBe(maxUint256)
   })
 
   test('behavior: feeToken from chain config', async () => {