Negligent Pachinko Machine

    @gxchain2-ethereumjs/tx
    TypeScript icon, indicating that this package has built-in type declarations

    3.3.1 • Public • Published

    @ethereumjs/tx

    NPM Package GitHub Issues Actions Status Code Coverage Discord

    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

    Setup

    Static Constructor Methods

    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.

    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. If there is no Common provided the chain ID provided as a paramter on typed tx or the chain ID derived from the v value on signed EIP-155 conforming legacy txs will be taken (introduced in v3.2.1). In other cases the chain defaults to mainnet.

    Base default HF (determined by Common): istanbul

    Starting with v3.2.1 the tx library now deviates from the default HF for typed tx using the following rule: "The default HF is the default HF from Common if the tx type is active on that HF. Otherwise it is set to the first greater HF where the tx is active."

    Supported Hardforks:

    Hardfork Introduced Description
    london v3.2.0 EIP-1559 Transactions
    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)

    Transaction Types

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

    • FeeMarketEIP1559Transaction (EIP-1559, gas fee market)
    • 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 up to v3.2.0 you mandatorily had to use a Common instance for typed tx instantiation and set the hardfork in Common to minimally berlin (EIP-2930) respectively london (EIP-1559) 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 (also see tx default HF section below).

    Gas Fee Market Transactions (EIP-1559)

    • Class: FeeMarketEIP1559Transaction
    • Activation: london
    • Type: 2

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

    import Common, { Chain, Hardfork } from '@ethereumjs/common'
    import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx'
    
    const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London })
    
    const txData = {
      "data": "0x1a8451e600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "gasLimit": "0x02625a00",
      "maxPriorityFeePerGas": "0x01",
      "maxFeePerGas": "0xff",
      "nonce": "0x00",
      "to": "0xcccccccccccccccccccccccccccccccccccccccc",
      "value": "0x0186a0",
      "v": "0x01",
      "r": "0xafb6e247b1c490e284053c87ab5f6b59e219d51f743f7a4d83e400782bc7e4b9",
      "s": "0x479a268e0e0acd4de3f1e28e4fac2a6b32a4195e8dfa9d19147abe8807aa6f64",
      "chainId": "0x01",
      "accessList": [],
      "type": "0x02"
    }
    
    const tx = FeeMarketEIP1559Transaction.fromTxData(txData, { common })

    Access List Transactions (EIP-2930)

    • Class: AccessListEIP2930Transaction
    • Activation: berlin
    • Type: 1

    This transaction type has been introduced along the berlin HF. See the following code snipped for an example on how to instantiate:

    import Common, { Chain, Hardfork } from '@ethereumjs/common'
    import { AccessListEIP2930Transaction } from '@ethereumjs/tx'
    
    const common = new Common({ chain: Chain.Mainnet, hardfork: 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 })

    For generating access lists from tx data based on a certain network state there is a reportAccessList option on the Vm.runTx() method of the @ethereumjs/vm TypeScript VM implementation.

    Legacy Transactions

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

    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 Common, { Chain } from '@ethereumjs/common'
    import { Transaction } from '@ethereumjs/tx'
    
    const txParams = {
      nonce: '0x00',
      gasPrice: '0x09184e72a000',
      gasLimit: '0x2710',
      to: '0x0000000000000000000000000000000000000000',
      value: '0x00',
      data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057',
    }
    
    const common = new Common({ chain: 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, { Chain, Hardfork } from '@ethereumjs/common'
    import { TransactionFactory } from '@ethereumjs/tx'
    
    const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Berlin })
    
    const txData = {} // Use data from the different tx type examples
    const tx = TransactionFactory.fromTxData(txData, { common })
    
    if (tx.supports(Capability.EIP2930AccessLists)) {
      // Do something which only makes sense for txs with support for access lists
    }

    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 = {})

    Sending a Transaction

    L2 Support

    This library has been tested to work with various L2 networks (v3.3.0+). All predefined supported custom chains introduced with Common v2.4.0 or higher are supported, the following is a simple example to send a tx to the xDai chain:

    import { Transaction } from '@ethereumjs/tx'
    import Common from '@ethereumjs/common'
    
    const from = 'PUBLIC_KEY'
    const PRIV_KEY = process.argv[2]
    const to = 'DESTINATION_ETHEREUM_ADDRESS'
    
    const common = Common.custom(CustomChain.xDaiChain)
    
    const txData = {
      from,
      nonce: 0,
      gasPrice: 1000000000,
      gasLimit: 21000,
      to,
      value: 1,
    }
    
    const tx = Transaction.fromTxData(txData, { common })
    const signedTx = tx.sign(Buffer.from(PRIV_KEY, 'hex'))

    The following L2 networks have been tested to work with @ethereumjs/tx, see usage examples as well as some notes on pecularities in the issues linked below:

     L2 Network  Common name  Issue
    Arbitrum Rinkeby Testnet  CustomChain.ArbitrumRinkebyTestnet  #1290
    Polygon Mainnet  CustomChain.PolygonMainnet  #1289
    Polygon Mumbai Testnet  CustomChain.PolygonMumbai  #1289
    xDai Chain  Common.xDaiChain  #1323

    For a non-predefined custom chain it is also possible to just provide a chain ID as well as other parameters to Common:

    const common = Common.custom({ chainId: 1234 })

    Special Topics

    Signing with a hardware or external wallet

    To sign a tx with a hardware or external wallet use tx.getMessageToSign(false) to return an EIP-155 compliant unsigned tx.

    A legacy transaction will return a Buffer list of the values, and a Typed Transaction (EIP-2718) will return the serialized output.

    Here is an example of signing txs with @ledgerhq/hw-app-eth as of v6.5.0:

    import { Transaction, FeeMarketEIP1559Transaction } from '@ethereumjs/tx'
    import Common, { Chain } from '@ethereumjs/common'
    import { rlp } from 'ethereumjs-util'
    import Eth from '@ledgerhq/hw-app-eth'
    
    const eth = new Eth(transport)
    const common = new Common({ chain: Chain.Rinkeby })
    
    let txData: any = { value: 1 }
    let tx: Transaction | FeeMarketEIP1559Transaction
    let unsignedTx: Buffer[] | Buffer
    let signedTx: typeof tx
    const bip32Path = "44'/60'/0'/0/0"
    
    const run = async () => {
      // Signing a legacy tx
      tx = Transaction.fromTxData(txData, { common })
      unsignedTx = tx.getMessageToSign(false)
      unsignedTx = rlp.encode(unsignedTx) // ledger signTransaction API expects it to be serialized
      let { v, r, s } = await eth.signTransaction(bip32Path, unsignedTx)
      txData = { ...txData, v, r, s }
      signedTx = Transaction.fromTxData(txData, { common })
      let from = signedTx.getSenderAddress().toString()
      console.log(`signedTx: 0x${signedTx.serialize().toString('hex')}\nfrom: ${from}`)
    
      // Signing a 1559 tx
      txData = { value: 1 }
      tx = FeeMarketEIP1559Transaction.fromTxData(txData, { common })
      unsignedTx = tx.getMessageToSign(false)
      ;({ v, r, s } = await eth.signTransaction(bip32Path, unsignedTx)) // this syntax is: object destructuring - assignment without declaration
      txData = { ...txData, v, r, s }
      signedTx = FeeMarketEIP1559Transaction.fromTxData(txData, { common })
      from = signedTx.getSenderAddress().toString()
      console.log(`signedTx: ${signedTx.serialize().toString('hex')}\nfrom: ${from}`)
    }
    
    run()

    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, freeze: false }
      const tx = Transaction.fromTxData(txParams, opts)
    
      // override getSenderAddress
      tx.getSenderAddress = () => { return from }
    
      return tx
    }

    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

    Install

    npm i @gxchain2-ethereumjs/tx

    DownloadsWeekly Downloads

    12

    Version

    3.3.1

    License

    MPL-2.0

    Unpacked Size

    374 kB

    Total Files

    59

    Last publish

    Collaborators

    • samlior