Documentation

Documentation »API »Transactions

Transactions

Each state-changing operation on Ethereum requires a transaction.

TYPES

<src>AccessList⇒ Array< AccessListEntry >

An ordered collection of AccessList entries.

<src>AccessListEntry⇒ { address: string , storageKeys: Array< string > }

A single AccessList entry of storage keys (slots) for an address.

<src>AccessListish⇒ AccessList | Array< tuple< string, Array< string > > > | Record< string, Array< string > >

Any ethers-supported access list structure.

<src>AuthorizationLike⇒ { address: string , chainId: BigNumberish , nonce: BigNumberish , signature: SignatureLike }

<src>BlobLike⇒ BytesLike | { commitment: BytesLike , data: BytesLike , proof: BytesLike }

A BLOb object that can be passed for EIP-4844 transactions.

It may have had its commitment and proof already provided or rely on an attached KzgLibrary to compute them.

<src>KzgLibraryLike⇒ KzgLibrary | { blobToKZGCommitment: (blob: string) => string , computeBlobKZGProof: (blob: string, commitment: string) => string } | { blobToKzgCommitment: (blob: string) => string | Uint8Array , computeBlobProof: (blob: string, commitment: string) => string | Uint8Array }

A KZG Library with any of the various API configurations. As the library is still experimental and the API is not stable, depending on the version used the method names and signatures are still in flux.

This allows any of the versions to be passed into Transaction while providing a stable external API.

FUNCTIONS

<src>accessListify(value: AccessListish)⇒ AccessList

Returns a AccessList from any ethers-supported access-list structure.

<src>authorizationify(auth: AuthorizationLike)⇒ Authorization

<src>computeAddress(key: string | SigningKey)⇒ string

Returns the address for the key.

The key may be any standard form of public key or a private key.

<src>recoverAddress(digest: BytesLike, signature: SignatureLike)⇒ string

Returns the recovered address for the private key that was used to sign digest that resulted in signature.

interface Authorization

PROPERTIES

<src>authorization.address⇒ string

<src>authorization.chainId⇒ bigint

<src>authorization.nonce⇒ bigint

<src>authorization.signature⇒ Signature

interface Blob

A full-valid BLOb object for EIP-4844 transactions.

The commitment and proof should have been computed using a KZG library.

PROPERTIES

<src>blob.commitment⇒ string

<src>blob.data⇒ string

<src>blob.proof⇒ string

interface KzgLibrary

A KZG Library with the necessary functions to compute BLOb commitments and proofs.

PROPERTIES

<src>kzgLibrary.blobToKzgCommitment⇒ (blob: Uint8Array) => Uint8Array

<src>kzgLibrary.computeBlobKzgProof⇒ (blob: Uint8Array, commitment: Uint8Array) => Uint8Array

class Transaction

A Transaction describes an operation to be executed on Ethereum by an Externally Owned Account (EOA). It includes who (the to address), what (the data) and how much (the value in ether) the operation should entail.

tx = new Transaction()
// Transaction {}

tx.data = "0x1234";
// '0x1234'

PROPERTIES

<src>transaction.accessList⇒ null | AccessList

The access list.

An access list permits discounted (but pre-paid) access to bytecode and state variable access within contract execution.

<src>transaction.authorizationList⇒ null | Array< Authorization >

<src>transaction.blobs⇒ null | Array< Blob >

The BLObs for the Transaction, if any.

If blobs is non-null, then the seriailized will return the network formatted sidecar, otherwise it will return the standard EIP-2718 payload. The unsignedSerialized is unaffected regardless.

When setting blobs, either fully valid Blob objects may be specified (i.e. correctly padded, with correct committments and proofs) or a raw BytesLike may be provided.

If raw BytesLike are provided, the kzg property must be already set. The blob will be correctly padded and the KzgLibrary will be used to compute the committment and proof for the blob.

A BLOb is a sequence of field elements, each of which must be within the BLS field modulo, so some additional processing may be required to encode arbitrary data to ensure each 32 byte field is within the valid range.

Setting this automatically populates blobVersionedHashes, overwriting any existing values. Setting this to null does not remove the blobVersionedHashes, leaving them present.

<src>transaction.blobVersionedHashes⇒ null | Array< string >

The BLOb versioned hashes for Cancun transactions.

<src>transaction.chainId⇒ bigint

The chain ID this transaction is valid on.

<src>transaction.data⇒ string

The transaction data. For init transactions this is the deployment code.

<src>transaction.from⇒ null | stringread-only

The sending address, if signed. Otherwise, null.

<src>transaction.fromPublicKey⇒ null | stringread-only

The public key of the sender, if signed. Otherwise, null.

<src>transaction.gasLimit⇒ bigint

The gas limit.

<src>transaction.gasPrice⇒ null | bigint

The gas price.

On legacy networks this defines the fee that will be paid. On EIP-1559 networks, this should be null.

<src>transaction.hash⇒ null | stringread-only

The transaction hash, if signed. Otherwise, null.

<src>transaction.kzg⇒ null | KzgLibrary

<src>transaction.maxFeePerBlobGas⇒ null | bigint

The max fee per blob gas for Cancun transactions.

<src>transaction.maxFeePerGas⇒ null | bigint

The maximum total fee per unit of gas to pay. On legacy networks this should be null.

<src>transaction.maxPriorityFeePerGas⇒ null | bigint

The maximum priority fee per unit of gas to pay. On legacy networks this should be null.

<src>transaction.nonce⇒ number

The transaction nonce.

<src>transaction.serialized⇒ stringread-only

The serialized transaction.

This throws if the transaction is unsigned. For the pre-image, use unsignedSerialized.

<src>transaction.signature⇒ null | Signature

If signed, the signature for this transaction.

<src>transaction.to⇒ null | string

The to address for the transaction or null if the transaction is an init transaction.

<src>transaction.type⇒ null | number

The transaction type.

If null, the type will be automatically inferred based on explicit properties.

<src>transaction.typeName⇒ null | stringread-only

The name of the transaction type.

<src>transaction.unsignedHash⇒ stringread-only

The pre-image hash of this transaction.

This is the digest that a Signer must sign to authorize this transaction.

<src>transaction.unsignedSerialized⇒ stringread-only

The transaction pre-image.

The hash of this is the digest which needs to be signed to authorize this transaction.

<src>transaction.value⇒ bigint

The amount of ether (in wei) to send in this transactions.

CREATING INSTANCES

<src>new Transaction()

Creates a new Transaction with default values.

<src>Transaction.from(tx?: string | TransactionLike < string >)⇒ Transaction

Create a Transaction from a serialized transaction or a Transaction-like object.

METHODS

<src>transaction.clone()⇒ Transaction

Create a copy of this transaciton.

<src>transaction.inferType()⇒ number

Return the most "likely" type; currently the highest supported transaction type.

<src>transaction.inferTypes()⇒ Array< number >

Validates the explicit properties and returns a list of compatible transaction types.

<src>transaction.isBerlin()⇒ boolean

Returns true if this transaction is berlin hardform transaction (i.e. type === 1).

This provides a Type Guard that the related properties are non-null.

<src>transaction.isCancun()⇒ boolean

Returns true if this transaction is an EIP-4844 BLOB transaction.

This provides a Type Guard that the related properties are non-null.

<src>transaction.isLegacy()⇒ boolean

Returns true if this transaction is a legacy transaction (i.e. type === 0).

This provides a Type Guard that the related properties are non-null.

<src>transaction.isLondon()⇒ boolean

Returns true if this transaction is london hardform transaction (i.e. type === 2).

This provides a Type Guard that the related properties are non-null.

<src>transaction.isSigned()⇒ boolean

Returns true if signed.

This provides a Type Guard that properties requiring a signed transaction are non-null.

<src>transaction.toJSON()⇒ any

Return a JSON-friendly object.

interface TransactionLike

A TransactionLike is an object which is appropriate as a loose input for many operations which will populate missing properties of a transaction.

PROPERTIES

<src>transactionLike.accessList⇒ null | AccessListish

The access list for berlin and london transactions.

<src>transactionLike.authorizationList⇒ null | Array< Authorization >

The EIP-7702 authorizations (if any).

<src>transactionLike.blobs⇒ null | Array< BlobLike >

The blobs (if any) attached to this transaction (see EIP-4844).

<src>transactionLike.blobVersionedHashes⇒ null | Array< string >

The versioned hashes (see EIP-4844).

<src>transactionLike.chainId⇒ null | BigNumberish

The chain ID the transaction is valid on.

<src>transactionLike.data⇒ null | string

The data.

<src>transactionLike.from⇒ null | A

The sender.

<src>transactionLike.gasLimit⇒ null | BigNumberish

The maximum amount of gas that can be used.

<src>transactionLike.gasPrice⇒ null | BigNumberish

The gas price for legacy and berlin transactions.

<src>transactionLike.hash⇒ null | string

The transaction hash.

<src>transactionLike.kzg⇒ null | KzgLibraryLike

An external library for computing the KZG commitments and proofs necessary for EIP-4844 transactions (see EIP-4844).

This is generally null, unless you are creating BLOb transactions.

<src>transactionLike.maxFeePerBlobGas⇒ null | BigNumberish

The maximum fee per blob gas (see EIP-4844).

<src>transactionLike.maxFeePerGas⇒ null | BigNumberish

The maximum total fee per gas for london transactions.

<src>transactionLike.maxPriorityFeePerGas⇒ null | BigNumberish

The maximum priority fee per gas for london transactions.

<src>transactionLike.nonce⇒ null | number

The nonce.

<src>transactionLike.signature⇒ null | SignatureLike

The signature provided by the sender.

<src>transactionLike.to⇒ null | A

The recipient address or null for an init transaction.

<src>transactionLike.type⇒ null | number

The type.

<src>transactionLike.value⇒ null | BigNumberish

The value (in wei) to send.