@ethereumjs/tx

What is @ethereumjs/tx?

@ethereumjs/tx is a library for creating, signing, and serializing Ethereum transactions. It is part of the EthereumJS suite of tools and is widely used for handling Ethereum transactions in a programmatic way.

What are @ethereumjs/tx's main functionalities?

Creating a Transaction

This feature allows you to create a new Ethereum transaction by providing the necessary transaction data such as nonce, gas price, gas limit, recipient address, value, and data.

const { Transaction } = require('@ethereumjs/tx');
const txData = {
  nonce: '0x00',
  gasPrice: '0x09184e72a000',
  gasLimit: '0x2710',
  to: '0x0000000000000000000000000000000000000000',
  value: '0x00',
  data: '0x00'
};
const tx = Transaction.fromTxData(txData);

Signing a Transaction

This feature allows you to sign a transaction using a private key. The signed transaction can then be sent to the Ethereum network.

const { Transaction } = require('@ethereumjs/tx');
const { privateToAddress, toBuffer } = require('ethereumjs-util');
const privateKey = Buffer.from('your_private_key', 'hex');
const txData = { /* transaction data */ };
const tx = Transaction.fromTxData(txData);
const signedTx = tx.sign(privateKey);

Serializing a Transaction

This feature allows you to serialize a transaction into a format that can be sent over the network or stored for later use.

const { Transaction } = require('@ethereumjs/tx');
const txData = { /* transaction data */ };
const tx = Transaction.fromTxData(txData);
const serializedTx = tx.serialize();

Other packages similar to @ethereumjs/tx

ethers

The ethers.js library is a complete and compact library for interacting with the Ethereum blockchain and its ecosystem. It provides similar functionalities for creating, signing, and sending transactions, but also includes additional features like interacting with smart contracts, ENS, and more.

web3

Web3.js is a collection of libraries that allow you to interact with a local or remote Ethereum node using HTTP, IPC, or WebSocket. It provides comprehensive functionalities for creating, signing, and sending transactions, as well as interacting with smart contracts and other Ethereum network features.

README

@ethereumjs/tx

Implements schema and functions related to Ethereum's transaction.

Note: this README reflects the state of the library from v3.0.0 onwards. See README from the standalone repository for an introduction on the last preceeding release.

INSTALL

npm install @ethereumjs/tx

USAGE

Introduction

To instantiate a tx it is not recommended to use the constructor directly. Instead each tx type comes with the following set of static constructor methods which helps on instantiation depending on the input data format:

• public static fromTxData(txData: TxData, opts: TxOptions = {}): instantiate from a data dictionary
• public static fromSerializedTx(serialized: Buffer, opts: TxOptions = {}): instantiate from a serialized tx
• public static fromValuesArray(values: Buffer[], opts: TxOptions = {}): instantiate from a values array

See one of the code examples on the tx types below on how to use.

All types of transaction objects are frozen with Object.freeze() which gives you enhanced security and consistency properties when working with the instantiated object. This behavior can be modified using the freeze option in the constructor if needed.

Transaction Types

This library supports the following transaction types (EIP-2718):

• AccessListEIP2930Transaction (EIP-2930, optional access lists)
• Transaction, the Ethereum standard tx up to berlin, now referred to as legacy txs with the introduction of tx types

Please note that for now you have to manually set the hardfork in Common to berlin to allow for typed tx instantiation, since the current Common release series v2 (tx type support introduced with v2.2.0) still defaults to istanbul for backwards-compatibility reasons.

Access List Transactions (EIP-2930)

• Class: AccessListEIP2930Transaction
• Activation: berlin

This is the recommended tx type starting with the activation of the berlin HF, see the following code snipped for an example on how to instantiate:

import Common from '@ethereumjs/common'
import { AccessListEIP2930Transaction } from '@ethereumjs/tx'

const common = new Common({ chain: 'mainnet', hardfork: 'berlin' })

const txData = {
  "data": "0x1a8451e600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "gasLimit": "0x02625a00",
  "gasPrice": "0x01",
  "nonce": "0x00",
  "to": "0xcccccccccccccccccccccccccccccccccccccccc",
  "value": "0x0186a0",
  "v": "0x01",
  "r": "0xafb6e247b1c490e284053c87ab5f6b59e219d51f743f7a4d83e400782bc7e4b9",
  "s": "0x479a268e0e0acd4de3f1e28e4fac2a6b32a4195e8dfa9d19147abe8807aa6f64",
  "chainId": "0x01",
  "accessList": [
    {
      "address": "0x0000000000000000000000000000000000000101",
      "storageKeys": [
        "0x0000000000000000000000000000000000000000000000000000000000000000",
        "0x00000000000000000000000000000000000000000000000000000000000060a7"
      ]
    }
  ],
  "type": "0x01"
}

const tx = AccessListEIP2930Transaction.fromTxData(txData, { common })

A mechanism to generate access lists from tx data based on a certain network state is not part of this library.

Legacy Transactions

• Class: Transaction
• Activation: chainstart (with modifications along the road, see HF section below)

Legacy transaction are still valid transaction within Ethereum mainnet but will likely be deprecated at some point. See this example script or the following code example on how to use.

import { Transaction } from '@ethereumjs/tx'

const txParams = {
  nonce: '0x00',
  gasPrice: '0x09184e72a000',
  gasLimit: '0x2710',
  to: '0x0000000000000000000000000000000000000000',
  value: '0x00',
  data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057',
}

const common = new Common({ chain: 'mainnet' })
const tx = Transaction.fromTxData(txParams, { common })

const privateKey = Buffer.from(
  'e331b6d69882b4cb4ea581d88e0b604039a3de5967688d3dcffdd2270c0fd109',
  'hex',
)

const signedTx = tx.sign(privateKey)

const serializedTx = signedTx.serialize()

Transaction Factory

If you only know on runtime which tx type will be used within your code or if you want to keep your code transparent to tx types, this library comes with a TransactionFactory for your convenience which can be used as follows:

import Common from '@ethereumjs/common'
import { TransactionFactory } from '@ethereumjs/tx'

const common = new Common({ chain: 'mainnet', hardfork: 'berlin' })

const txData = {} // Use data from the different tx type examples
const tx = TransactionFactory.fromTxData(txData, { common })

The correct tx type class for instantiation will then be chosen on runtime based on the data provided as an input.

TransactionFactory supports the following static constructor methods:

• public static fromTxData(txData: TxData | AccessListEIP2930TxData, txOptions: TxOptions = {}): TypedTransaction
• public static fromSerializedData(data: Buffer, txOptions: TxOptions = {}): TypedTransaction
• public static fromBlockBodyData(data: Buffer | Buffer[], txOptions: TxOptions = {})

Fake Transaction

Creating a fake transaction for use in e.g. VM.runTx() is simple, just overwrite getSenderAddress() with a custom Address like so:

import { Address } from 'ethereumjs-util'
import { Transaction } from '@ethereumjs/tx'

_getFakeTransaction(txParams: TxParams): Transaction {
  const from = Address.fromString(txParams.from)
  delete txParams.from

  const opts = { common: this._common }
  const tx = Transaction.fromTxData(txParams, opts)

  const fakeTx = Object.create(tx)
  // override getSenderAddress
  fakeTx.getSenderAddress = () => { return from }
  return fakeTx
}

SETUP

Chain and Hardfork Support

The Transaction constructor receives a parameter of an @ethereumjs/common object that lets you specify the chain and hardfork to be used. The chain defaults to mainnet.

Current default HF (determined by Common): istanbul

Supported Hardforks

Hardfork	Introduced	Description
berlin	v3.1.0	EIP-2718 Typed Transactions, Optional Access Lists Tx Type EIP-2930
muirGlacier	v2.1.2	-
istanbul	v2.1.1	Support for reduced non-zero call data gas prices (EIP-2028)
spuriousDragon	v2.0.0	EIP-155 replay protection (disable by setting HF pre-spuriousDragon)

API

Documentation

EthereumJS

See our organizational documentation for an introduction to EthereumJS as well as information on current standards and best practices.

If you want to join for work or do improvements on the libraries have a look at our contribution guidelines.

LICENSE

MPL-2.0