Send Parallel Transactions

Submit multiple transactions in parallel using Tempo's 2D nonces. The nonceKey property allow you to send concurrent transactions without waiting for each one to confirm sequentially.

Understanding nonce keys

Tempo uses a 2D nonce system that enables parallel transaction execution:

• Protocol nonce (key 0): The default sequential nonce. Transactions must be processed in order.
• User nonces (keys 1+): Independent nonce sequences that allow concurrent transaction submission.

When you send a transaction without specifying a nonceKey, it uses the protocol nonce and behaves like a standard sequential transaction. By specifying different nonce keys, you can submit multiple transactions simultaneously without waiting for confirmations.

Key management strategies

There are two ways to specify a nonceKey for a transaction:

Explicit keys

Explicit keys (1n, 2n, etc.) are best when you want to reuse keys. For high-throughput applications, these keys can be used to load-balance transaction submission to the network in a gas-efficient way. You can track the most recent call on each key in your application, and, once that transaction confirms, the same key can be used for new transactions. This approach is more gas efficient, as provisioning a new nonceKey costs gas.

'random' keys

For simple cases where you don't need to track keys. This approach is recommended when handling bursts of high activity, in which you need to submit transfers to the network and don't care about the added gas costs for provisioning multiple keys.

Demo

By the end of this guide you will understand how to send parallel payments using nonce keys.

Steps

import { Actions } from 'tempo.ts/wagmi'
import { parseUnits } from 'viem'
import { config } from './wagmi.config'
 
 
// Fetch nonces for each key in parallel
const [nonce1, nonce2] = await Promise.all([
  Actions.nonce.getNonce(config, { account, nonceKey: 1n }), 
  Actions.nonce.getNonce(config, { account, nonceKey: 2n }), 
])
 
console.log('Current nonce for nonceKey 1:', nonce1)
console.log('Current nonce for nonceKey 2:', nonce2)

import { Actions } from 'tempo.ts/wagmi'
import { parseUnits } from 'viem'
import { config } from './wagmi.config'
 
const account = '0x...' // your sender account
const alphaUsd = '0x20c0000000000000000000000000000000000001'
 
const [nonce1, nonce2] = await Promise.all([
  Actions.nonce.getNonce(config, { account, nonceKey: 1n }),
  Actions.nonce.getNonce(config, { account, nonceKey: 2n }),
])
 
// Send both transfers in parallel using different nonce keys
const [hash1, hash2] = await Promise.all([
  Actions.token.transfer(config, {
    amount: parseUnits('100', 6),
    to: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
    token: alphaUsd,
    nonceKey: 1n, 
    nonce: Number(nonce1), 
  }),
  Actions.token.transfer(config, {
    amount: parseUnits('50', 6),
    to: '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
    token: alphaUsd,
    nonceKey: 2n, 
    nonce: Number(nonce2), 
  }),
])
 
console.log('Transaction 1:', hash1)
console.log('Transaction 2:', hash2)

Recipes

Use random nonce keys

For simple cases where you don't need to manage specific keys, use 'random' to automatically generate a unique nonce key:

import { Actions } from 'tempo.ts/wagmi'
import { parseUnits } from 'viem'
import { config } from './wagmi.config'
 
// Using 'random' automatically generates a unique nonce key
const hash = await Actions.token.transfer(config, {
  amount: parseUnits('100', 6),
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb',
  token: '0x20c0000000000000000000000000000000000001',
  nonceKey: 'random', 
})
 
console.log('Transaction hash:', hash)

Query active nonce keys

Track how many nonce keys your account is using:

import { client } from './viem.config'
 
// Get the count of active nonce keys for an account
const count = await client.nonce.getNonceKeyCount({
  account: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb',
})
 
console.log('Active nonce keys:', count)

Best Practices

When to use nonce keys

Use nonce keys when you need to:

• Send multiple independent transactions simultaneously
• Build high-throughput applications that can't wait for sequential confirmations
• Process payments to multiple recipients concurrently

When to use batch transactions instead

Use batch transactions instead of nonce keys when:

• Operations need to be atomic
• Calls have sequential dependencies
• You want a single transaction fee for multiple operations

Batch transactions are not as appropriate for the payments to multiple recipients use case, because if a single payment fails, all the calls in the batch transaction roll back.

Learning Resources