Skip to content

Formatters

Configure chain-based formatters in Viem

You can modify how Blocks & Transactions are formatted by using the formatters property on the Chain.

This is useful for chains that have a different Block or Transaction structure than Mainnet (e.g. Celo & OP Stack chains).

Usage

import { 
  defineBlock,
  defineChain,
  defineTransaction, 
  defineTransactionReceipt, 
  defineTransactionRequest 
} from 'viem' 
 
export const example = defineChain({
  /* ... */
  formatters: { 
    block: defineBlock(/* ... */),
    transaction: defineTransaction(/* ... */),
    transactionReceipt: defineTransactionReceipt(/* ... */),
    transactionRequest: defineTransactionRequest(/* ... */),
  } 
})

API

formatters.block

You can modify how Blocks are formatted by using the formatters.block property on the Chain.

You can either pass in the Block overrides, or the whole Block itself to the format function of defineBlock. You can also exclude certain properties with exclude.

import { defineBlock, defineChain, hexToBigInt } from 'viem'
 
type RpcBlockOverrides = { 
  secondaryFee: `0x${string}`
}
type BlockOverrides = {
  secondaryFee: bigint
}
 
const example = defineChain({
  /* ... */
  formatters: { 
    block: defineBlock({
      exclude: ['difficulty'],
      format(args: RpcBlockOverrides): BlockOverrides {
        return {
          secondaryFee: hexToBigInt(args.secondaryFee)
        }
      },
    }),
  },
})
 
const block = await client.getBlock() 
//    ^? { ..., difficulty: never, secondaryFee: bigint, ... }

formatters.transaction

You can modify how Transactions are formatted by using the formatters.transaction property on the Chain.

You can either pass in the Transaction overrides, or the whole Transaction itself to the format function of defineTransaction. You can also exclude certain properties with exclude.

import { defineTransaction, defineChain, hexToBigInt } from 'viem'
 
type RpcTransactionOverrides = { 
  mint: `0x${string}`
}
type TransactionOverrides = {
  mint: bigint
}
 
const example = defineChain({
  /* ... */
  formatters: { 
    transaction: defineTransaction({
      exclude: ['gasPrice'],
      format(args: RpcTransactionOverrides): TransactionOverrides {
        return {
          mint: hexToBigInt(args.mint)
        }
      },
    }),
  },
})
 
const transaction = await client.getTransaction({ hash: '0x...' }) 
//    ^? { ..., gasPrice: never, mint: bigint, ... }

formatters.transactionReceipt

You can modify how Transaction Receipts are formatted by using the formatters.transactionReceipt property on the Chain.

You can either pass in the Transaction Receipt overrides, or the whole Transaction Receipt itself to the format function of defineTransactionReceipt. You can also exclude certain properties with exclude.

import { defineTransactionReceipt, defineChain, hexToBigInt } from 'viem'
 
type RpcTransactionReceiptOverrides = { 
  l1Fee: `0x${string}`
}
type TransactionReceiptOverrides = {
  l1Fee: bigint
}
 
const example = defineChain({
  /* ... */
  formatters: { 
    transactionReceipt: defineTransactionReceipt({
      exclude: ['effectiveGasPrice'],
      format(args: RpcTransactionReceiptOverrides): 
        TransactionReceiptOverrides {
        return {
          l1Fee: hexToBigInt(args.l1Fee)
        }
      },
    }),
  },
})
 
const receipt = await client.getTransactionReceipt({ hash: '0x...' }) 
//    ^? { ..., effectiveGasPrice: never, l1Fee: bigint, ... }

formatters.transactionRequest

You can modify how Transaction Requests are formatted by using the formatters.transactionRequest property on the Chain.

You can either pass in the Transaction Request overrides, or the whole Transaction Request itself to the format function of defineTransactionRequest. You can also exclude certain properties with exclude.

import { defineTransactionRequest, defineChain, hexToBigInt } from 'viem'
 
type RpcTransactionRequestOverrides = { 
  secondaryFee: `0x${string}`
}
type TransactionRequestOverrides = {
  secondaryFee: bigint
}
 
const example = defineChain({
  /* ... */
  formatters: { 
    transactionRequest: defineTransactionRequest({
      exclude: ['effectiveGasPrice'],
      format(args: TransactionRequestOverrides): 
        RpcTransactionRequestOverrides {
        return {
          secondaryFee: numberToHex(args.secondaryFee)
        }
      },
    }),
  },
})
 
const receipt = await client.getTransactionReceipt({ hash: '0x...' }) 
//    ^? { ..., effectiveGasPrice: never, l1Fee: bigint, ... }