Formatters

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

tsx

import { 
  defineBlock,
  defineChain,
  defineTransaction, 
  defineTransactionReceipt, 
  defineTransactionRequest 
} from 'viem' 

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

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, ... }

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, ... }

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, ... }

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, ... }

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, ... }

Formatters ​

Usage ​

API ​

formatters.block ​

formatters.transaction ​

formatters.transactionReceipt ​

formatters.transactionRequest ​