web3.js vs ethers.js

How Ethereum transactions work

April 5, 2023

tags

Libraries

Ethereum

JavaScript

Blog posts

When building dapps that interact with Ethereum-based chains, Node.js developers typically reach for one of two JavaScript libraries: [web3.js][web3-docs] or [ethers.js][ethers-docs]. Both of these libraries wrap the [Ethereum JSON-RPC API][eth-jrpc-docs], providing useful functionality like [local signing](#separatingkeysfromtheAPIendpoint), [nonce tracking](#noncemanagement), and [Solidity ABI support](#ABI-management). In fact, most functionality is _the same_ in both libraries, which makes it difficult to choose between them. In this blog post, we explain why we ultimately prefer [ethers.js][ethers-docs]---after outlining the anatomy of Ethereum transactions, the JSON-RPC API, and why JavaScript libraries are helpful to begin with. In case you're familiar with most of these topics and want to skip forward, here's a table of contents: - [**The anatomy of an Ethereum transaction**](#theanatomyofanethereumtransaction) and how the Ethereum JSONRPC API works. - [**Why use a library**](#whyusealibraryatall?) instead of the raw Ethereum API? - [**Why we prefer ethers.js**](#whywepreferethers.jsoverweb3.js) over web3.js - [**An FAQ**](#ethereumtransactionfaq) outlining some common questions about transactions, the Ethereum API, and ethers.js and web3.js. ## The anatomy of an Ethereum transaction The Ethereum [JSON-RPC API][eth-jrpc-docs] lets developers interact with the blockchain by querying---or even sending transactions to---an [Ethereum node][ethnode] over HTTP or WebSockets. The JSON-RPC API has two different methods for submitting Ethereum transactions: [`eth_sendTransaction()`][send] and [`eth_sendRawTransaction()`][sendraw]. The most important difference between these methods is the way they handle transaction signing: `eth_sendTransaction()` expects an unsigned transaction, whereas `eth_sendRawTransaction()` expects a signed transaction. We explain the distinction next, and then finish by showing an example Ethereum transaction using the raw JSON-RPC API. ### Why is signing important, how signing works, and the difference between `eth_sendTransaction()` and `eth_sendRawTransaction()` Each Ethereum transaction must be signed by the private key associated with the account sending the transaction. This ensures transaction _authenticity_---that the transaction truly originates from the sender account. Without signing, anyone could submit transactions "from" your account---maybe draining your account!---without detection. If you use `eth_sendTransaction()` to submit your Ethereum transaction, the RPC endpoint (e.g., an Ethereum node) you connect to must (1) sign your transaction with your private key and then (2) broadcast a request to the Ethereum network to [actually execute that transaction](https://ethereum.org/en/developers/docs/transactions/#transaction-lifecycle). If you use `eth_sendRawTransaction()`, you're responsible for supplying the method with an _already signed_ transaction; you can sign transactions before sending them with the `signTransaction()` method, though it's more complex in practice (which we discuss [later](#separatingkeysfromtheapiendpoint)). ### An example transaction using the raw Ethereum JSON-RPC API The following example from the documentation of the [`eth_sendTransaction()`][send] method shows an Ethereum transaction sent using `curl` through the Ethereum JSON-RPC API: ```bash # Request curl -X POST --data '{     "jsonrpc": "2.0",     "id": 1,     "method": "eth_sendTransaction",     "params":[         {             // address of sender             "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155",             // address of receiver (none if creating contract)             "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",             // the maximum amount of gas the sender is willing to provide to             // execute the transaction (30400)             "gas": "0x76c0",             // maximum gas price the sender is willing to pay (10000000000000)             "gasPrice": "0x9184e72a000",             // the amount of wei to send as an integer (2441406250)             "value": "0x9184e72a",             // for contract creation, the compiled code of the contract             // for contract method calls, the encoding of the method and its arguments             "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"         },     ] }' # Result {     "id":1,     "jsonrpc": "2.0",     "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" } ``` The `to`, `gas`, `gasPrice`, `value` and `data` fields in `eth_sendTransaction()` are optional: - The `to` field is not set when a transaction creates a new smart contract. - The `gas` and `gasPrice` fields, which are used to pay for the execution of a transaction, have default values. - The `value` field is only set if a transaction transfers ETH (the value is denominated in wei; 1 ETH is 1018 wei). - The `data` field isn't set for simple transfers (i.e., transactions that are not contract creations or contract calls). The result of sending a transaction is a transaction hash, which can be used to get a transaction receipt using [`eth_getTransactionReceipt()`][getreceipt]. The transaction receipt contains information about the status of a transaction---success or failure---as well as other metadata (e.g., the number of the block the transaction ended up in). ## Why use a library at all? It may not be immediately evident why developers use complex wrapper libraries like web3.js and ethers.js instead of using the Ethereum JSON-RPC API directly. But wrapper libraries are important because they provide support for: 1. [Separating keys from API endpoints](#separatingkeysfromtheapiendpoint). 2. [Nonce management](#noncemanagement). 3. [Gas price estimation](#gaspriceestimation). 4. [ABI management](#abimanagement). In the next sections, we describe what all of these tasks _are_, and then outline what makes them tricky. ### Separating keys from the API endpoint If you use `eth_sendTransaction()`, the transaction is signed by the Ethereum node, which means that node needs access to your private key. If you're running your own Ethereum node, it's possible---but risky!---to configure that node with access to your key (see the subsection on [private key management](#moreonprivatekeymanagement) directly below). If you're using a popular service like [Alchemy][alchemy] or [Infura](https://www.infura.io) to host your endpoint, though, things become untenable: these services don't support transaction signing because giving them access to your keys is a massive security risk. Since `eth_sendRawTransaction()` lets you separate the signing and submitting steps, it _can_ be used with services like Alchemy. This flow lets you restrict access to secret keys at the cost of implementing your own local signing logic. That's where web3.js and ethers.js come in: **both libraries implement local signing for you**, so you can keep your keys safe while using third-party node providers. The libraries' local signing essentially replicates the functionality of [`eth_signTransaction()`][sign] using a local private key; if you opt against a library, you must implement this logic manually, which requires detailed knowledge of how the signature is computed. #### A few words on private key management It is _extremely_ important to minimize the risk of exposing your private key: anyone who knows it can create valid transactions---meaning that an attacker who learns your private key can completely drain your wallet. Configuring your local Ethereum node with private key access dramatically increases the likelihood that something goes wrong, including: 1. Direct compromise. This might happen if the local machine isn't well secured, or if there is a bug in the node software. 2. Accidents. As one example, it's possible to accidentally send a test transaction to mainnet instead of a testnet. This might happen if the node is incorrectly configured. As a result of these (and _many other_) risks, it's considered good practice to separate keys from nodes. ### Nonce management All Ethereum transactions have a `nonce` field that must contain the number of transactions that the sender account has created (and the Ethereum network has executed, either successfully or not) prior to this transaction. The nonce ensures that a transaction can be processed at most once, which prevents "replay attacks". If the transaction's nonce is correct, the transaction can be executed. If it's too small---meaning less than or equal to the nonce value in the sender's most recently executed transaction---the Ethereum API will reject the transaction. Otherwise, if the nonce value is too large, it cannot be executed until all nonces less than this value have been used; in this case, the Ethereum node may queue this transaction and wait for others to execute. When you use `eth_sendTransaction()`, the Ethereum node can set the transaction's nonce field for you: it calculates the next nonce value (based on the sender's transaction history and any pending transactions), incorporates that value into the transaction, and then signs and submits the transaction to the network. If, instead, you sign transactions locally and submit them with `eth_sendRawTransaction()`, the Ethereum node cannot choose the nonce: the transaction is already signed when the node receives it, and any change to the transaction---including to the nonce field---would invalidate the signature, causing the transaction to be rejected. To do local signing, then, you must also do local nonce calculation. Local nonce calculation is more complex than it sounds: concurrent applications, for example, introduce race conditions into the calculation logic. **Both web3.js and ethers.js handle this (surprisingly complicated) nonce management for you**. ### Gas price estimation Recall that the execution cost of Ethereum transactions is measured in an abstract unit called "gas". A given Ethereum transaction always takes the same amount of gas, but the value of that gas (measured in ETH) fluctuates based on how busy the chain is. When you submit a transaction, you must declare how much ETH you're willing to spend to execute it. If the value is too low, validators won't execute your transaction; if the value is too high, you waste money. Just like nonces, gas price constraints must be encoded into a transaction _before_ signing---so if you're signing locally, you're responsible for gas price estimation. **Both web3.js and ethers.js implement gas estimation for you.** ### ABI management On Ethereum, smart contract functions can be invoked by initiating a transaction with the contract's address. The [`eth_call()`][call] method from the JSON-RPC API, for example, takes the address of the smart contract you'd like to call in the `to` field. What about specifying the function _within_ that smart contract that you'd like to call, or providing arguments to that function? The transaction has a `data` field that holds arbitrary binary data, and that is where you shove the function and argument information. "Arbitrary binary data" doesn't square with how we're used to thinking of pieces of a Solidity smart contract. For example, consider this smart contract with two methods accepting typed arguments: ```solidity contract Example {     function addOne(uint256 num) public pure returns (uint256) {         return num + 1;     }     function neg(bool p) public pure returns (bool) {         return !p;     } } ``` `addOne()` takes a `uint256` argument, while `neg()` takes a `bool` argument. To actually _call_ these methods using `eth_call()`, you [encode][abispec] both the signature of the method you intend to call (e.g., `addOne(uint256)`) and its argument (e.g., `num`) into the `data` field of the transaction. (Concretely, the first four bytes of the `data` field contain the first four bytes of the Keccak-256 hash of the function signature, and the remainder contains the actual values.) Similarly, when you invoke a Solidity contract's method through `eth_call()`, the return value is encoded and stored in the `result` field of the response object. The encoding and decoding of data for a smart contract is called its ABI (Application Binary Interface). Handling the encoding and decoding required by the ABI gets even more complicated when you consider that JavaScript applications often need to talk to Solidity smart contracts---and JavaScript and Solidity are very different languages. For example, Solidity's `uint256` can hold a value that doesn't fit into a JavaScript `number`; what's the JavaScript application supposed to do when it receives a `uint256`?! If you want to safely convert the return value of `addOne` into a JavaScript value that a frontend application can use, you need to load it into a JavaScript [`BigInt`][bigint]. This means there's _a lot_ of conversion going on to invoke even simple smart contract methods like `addOne`: !!! WARNING     *Invoking a method*: JS Value → Solidity Value → Binary Data     and _even more_ conversions on the way out:     *Reading method result*: Binary Data → Solidity Value → JS Value Mistakes in these conversions can result in expensive vulnerabilities. Thankfully, **web3.js and ethers.js handle encoding and decoding for you** by using the ABI description generated by the Solidity compiler to generate JavaScript classes. The JavaScript classes, in turn, handle value conversion across the Solidity-JavaScript boundary. In both examples below, you'll notice a distinct lack of conversions; instead, the libraries let you refer to our `Example` smart contract (line one) and then call `addOne` on that contract (line two) using normal JavaScript values. **web3.js** ```js let contract = new web3.eth.Contract(abiJson, "0xd..."); let result = await contract.addOne(3).call(); ``` **ethers.js** ```js let contract = new Contract("0xd...", abiJson, provider); let result = await contract.addOne(2); ``` ## Why we prefer ethers.js over web3.js Although both web3.js and ethers.js implement the features above, ethers.js has some distinct advantages. ### Flexible `Provider`/`Signer` ecosystem When implementing out-of-band transaction signing, web3.js has a pretty direct translation of the process [we described earlier](#separatingkeysfromtheapiendpoint): ```js // web3.js example let web3 = new Web3('https://...'); // specify your account let account = web3.eth.accounts.privateKeyToAccount(privateKey); // sign the transaction locally let trx = await account.signTransaction({/*...*/}); // send the signed transaction to the node await web3.eth.sendSignedTransaction(trx); ``` While this code is perfectly reasonable, it requires you to explicitly pass around both the `account` and `web3` object. Furthermore, web3.js doesn't provide standard API support for other methods of transaction signing, for example, using a Key Management Service. In ethers.js, the responsibilities of signing are captured in the abstract `Signer` class, which can be implemented with in-memory wallets, [hardware wallets][ethers-hardware-wallets], or even remote key-signing services. Signers wrap `Provider`s that represent a connection to an Ethereum API endpoint. Altogether, signing transactions with ethers.js looks like this: ```js import {LedgerSigner} from "@ethersproject/hardware-wallets"; // connection to an Ethereum endpoint let provider = new ethers.providers.JsonRpcProvider('https://...'); // the signer object let signer; if (local_signing) {     // sign with the local private key     signer = new ethers.Wallet(privateKey, provider); } else {     // sign with a hardware wallet     signer = new LedgerSigner(provider); } await signer.sendTransaction({/*...*/}); ``` In addition to the basic `JsonRpcProvider` (line 1), ethers.js has [`Provider` implementations](https://docs.ethers.io/v5/api/providers/api-providers/) for many popular third-party endpoints such as [Etherscan][etherscan], [Alchemy][alchemy], [Cloudflare][cloudflare], and others. These implementations handle the particular authentication schemes and other quirks unique to these endpoints, which makes your life easier. ### More permissive license web3.js is licensed under the [LGPL][lgpl], meaning you can freely use it as a dependency, but any modified version of web3.js that you distribute must also be open source and licensed under the LGPL. ethers.js uses the [MIT license][mit-license] which allows any and all modifications with very few strings attached. Choosing an MIT-licensed library will keep your lawyers happy and give you more options as your project evolves. (Disclaimer: we are not lawyers, and we are certainly not your lawyers! Please consult your counsel for advice on the best license for you.) ### Smaller codesize If you're deploying your dapp in the browser---or in any context that requires it to be regularly downloaded---the size of your library is crucial to your application's responsiveness. ethers.js manages to support more functionality than web3.js in a much smaller package: **web3.js**: `1.1 MB` minified, `310 kb` gzipped **ethers.js**: `322 kb` minified, `104 kb` gzipped ## Ethereum transaction FAQ Here are answers to some of the transaction-related questions we've seen around the web. ### Q: What's the difference between `eth_sendTransaction()` and `eth_sendRawTransaction()`? See the section on [the difference between these two methods](#whyissigningimportanthowsigningworksandthedifferencebetweeneth_sendTransactionandeth_sendRawTransaction). ### Q: What is a nonce and why is it important? See our explanation of [nonce management](#noncemangagement). ### Q: Does the nonce increase if the transaction fails? What about if the transaction never reaches the node (e.g., because of a network issue)? If the transaction is received by an Ethereum node and executed by the network, the sender's nonce value increases. This is true even if the transaction fails during execution (e.g., because it doesn't include enough gas). If the transaction never reaches a node, or if it is rejected before execution (say, because of a bad signature), the sender's next nonce value _does not_ increase. Here's another way to think about it: every executed transaction, successful or not, is recorded in an Ethereum block. The sender's current nonce value is equal to the number of transactions from that sender recorded in all Ethereum blocks. This means that the sender's nonce value increases every time a new transaction from that sender is incorporated into an Ethereum block, and does not change otherwise. ### Q: What are `nonce too high` and `nonce too low` errors? How do you fix them? See our explanation of [nonce management](#noncemangagement). A `nonce too low` error for transaction `T` means that the node and network have already seen some other transaction `T'`, sent _by you_, with `T`'s nonce. A `nonce too high` error for transaction `T` means that the node and network haven't yet seen a transaction with a nonce of one less than `T`'s. Not all software will error if a nonce is too high; some implementations may hold the transaction and wait to release it once it's the transaction's "turn". ### Q: What is an out of gas error and how do I fix it? This error means that the amount of gas you sent with your transaction wasn't sufficient to execute that transaction. You'll need to increase your transaction's gas limit and re-submit. See our discussion of [gas price estimation](#gaspriceestimation) for more information. ### Q: Why shouldn't I give my local Ethereum node access to my private key? See our section on [separating keys from the API endpoint](#separatingkeysfromtheapiendpoint). Giving a local node access increases the risk of exposure of the key and theft of your funds. It can also lead to mistakes like accidentally sending valid transactions to the wrong network. [call]: (https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call) [send]: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction [sendraw]: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction [sign]: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_signtransaction [getreceipt]: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactionreceipt [ethnode]: https://www.alchemy.com/overviews/what-is-an-ethereum-node [lgpl]: https://choosealicense.com/licenses/lgpl-3.0/ [alchemy]: https://www.alchemy.com/ [cloudflare]: https://developers.cloudflare.com/web3/ethereum-gateway/ [etherscan]: https://etherscan.io/ [ens]: https://ens.domains/ [mit-license]: https://choosealicense.com/licenses/mit/ [eth-jrpc-docs]: https://ethereum.org/en/developers/docs/apis/json-rpc/ [web3-docs]: https://web3js.readthedocs.io/en/v1.8.1/ [ethers-docs]: https://docs.ethers.io/v5/ [eth-call]: https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call [bigint]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt [ethers-hardware-wallets]: https://www.npmjs.com/package/@ethersproject/hardware-wallets [abi-bug]: # [abispec]: https://docs.soliditylang.org/en/latest/abi-spec.html

Cubist teams up with Babylon and Lombard to bring Bitcoin to Sui

We look forward to Cap-3 in December, when BTC holders will be able to deposit their BTC to Lombard for staking on Babylon and receive LBTC natively minted on Sui.

November 25, 2024

A step towards smart contracts on Bitcoin

Hardware-enshrined smart contracts, which we developed using our CubeSigner key management platform, allow Bitcoin protocols to encode complex operational logic and maintain decentralized governance much like a traditional smart contract on Ethereum.

November 18, 2024

Introducing the Bascule Drawbridge for Bitcoin bridge security

Bascule is a new Bitcoin bridge security system built on top of the CubeSigner key management platform to prevent cross-chain hacks in real-time.

October 23, 2024

web3.js vs ethers.js

How Ethereum transactions work

Read more

Cubist teams up with Babylon and Lombard to bring Bitcoin to Sui

A step towards smart contracts on Bitcoin

Introducing the Bascule Drawbridge for Bitcoin bridge security

Tell us what keeps you up at night.