5 min read

Overview

The Ethereum network processes over one million transactions a day. These transactions originate from users wanting to transfer Ether or interact with smart contracts. In this guide, we will teach you about the Pending and Queued state of transactions on the Ethereum network. We will also demonstrate how to request data programmatically with Python and Web3.py, using our handy QuickNode endpoints as the infrastructure to communicate with the Ethereum network.

What we will do:

• Define Pending and Queued Transactions
• Set up an Ethereum Node with QuickNode
• Write Python code to retrieve Pending and Queued transaction data

What you will need:

• A basic understanding of transactions
• Python (version 3.6+) and Pip installed on your machine
• A text editor
• Terminal

Difference between Pending and Queued Transactions

A transaction on Ethereum consists of different components such as a cryptographically signed signature (deriving from the sender's private key), a set of instructions, a node to be broadcasted on, and a fee that will go to a miner. Once a transaction is broadcasted to the network, it can go into two different states depending on the value used in the transactions nonce field. The states fall into these categories:

Pending - Transactions available to be processed and included in the next block.
Queued - Transactions out of sequence that cannot be included in the next block.

A transaction must include a nonce. The nonce value in a transaction is set by the sender and allows for the ordering of transactions while also preventing replay attacks. All transactions submitted from an account must follow its nonce sequence to put in a pending transaction state.

For example, say an account sends its first transaction and has its nonce set to 0. The second transaction sent from the account should contain a nonce value of 1. The third transaction sent is expected to have a nonce value of 2 and so on, incrementing by one each transaction. In a scenario where you have submitted multiple transactions, and the first transaction (i.e., nonce=0) is still pending, the remaining transactions from the sending account (with nonce one and greater) would be in a queued state until the first transaction has been processed.

Alternatively, if an account accidentally sends a transaction with an out-of-sequence nonce, the said transaction would stay queued until the transaction is replaced with the correct nonce or until another transaction with the missing nonce(s) is submitted and processed first.

There are two reasons why a transaction can be in a queued state:

1. There can be existing pending transaction(s) that must be processed first.
2. The transaction has been submitted with an out of sequence nonce.

Now that we have a theoretical understanding of transactions and their different states, we will demonstrate how to view them programmatically with Web3.py and Python.

Set Up Your QuickNode Ethereum Endpoint

To demonstrate how to view pending and queued transactions, we can use an Ethereum client such as Geth or OpenEthereum (fka Parity). Since that can be too involved for just viewing transactions, we will use a free endpoint from QuickNode to make this easy. To get a free Ethereum node, navigate to QuickNode and signup! After you have created your free Ethereum endpoint, copy your HTTP Provider endpoint:

Retrieving Pending and Queued Transactions

Now that we have our Ethereum node ready, we can start writing code to retrieve data from the Ethereum blockchain.

First, we will open up the terminal and run the following command to create a new project directory and navigate inside it:

Then create an empty Python file by running the following command:

Next, install dependencies needed to run our Python project:

Now that we have our project setup, open the main.py file and add the code below:

from web3 import Web3, HTTPProvider
 
provider_url = "YOUR_QUICKNODE_NODE_URL"
provider = Web3.HTTPProvider(provider_url)
 
txpool_data = provider.make_request('txpool_content', [])
first_queued_address =  list(txpool_data['result']['queued'].keys())[0]
first_queued_transaction = txpool_data['result']['queued'][first_queued_address]
print("Queued Transaction: ", [i for i in first_queued_transaction.items()])

Note you can replace instances of the word queued with pending to see pending transactions instead.

A quick explanation of the code above:

Line 1: Import dependencies
Line 3: Store our QuickNode endpoint URL in a variable called provider_url.
Line 4: Create a Web3 HTTProvider object using our variable provider_url.
Line 6: We make a call to the txpool_content RPC method using our provider.
Line 8: Declare a variable first_queued_address that will store the first from address from the queued transaction array.
Line 9: Store the first transaction object from the queued transaction array in a variable called first_queued_transaction.
Line 11: Use list comprehension and print statements to view the first transaction object from the queued array.

The Txpool_content RPC endpoint used in the Python script above allows us to retrieve queued and pending transactions from Ethereum main-net. Additional information regarding the endpoint we are requesting data from is found here:

• Txpool_content RPC Method

Save the file and navigate back to your terminal to run the following command:

python3 main.py 

After the code finishes executing, you will see print statements that display queued transactions. Our code restricts the display of queued transactions to one record in each array since showing all can take extra computational effort:

To verify that a transaction is queued, you can copy the transaction hash from the hash field above and search for it on Etherscan:

The transaction data retrieved from our Python script matches the data displayed on Etherscan. We can categorize this transaction as a smart contract transaction because the recipient of the transaction is a smart contract address, and the data field is being used to call the contracts approve function. Note the transaction has a nonce of 9; this information will be useful to keep in mind for the next step.

To find out why the transaction above is queued, we can check the transaction activity of the from address. If the sender has no other pending transactions, the queued state is most likely due to an incorrect nonce. If the sender has pending transactions, it's likely the transaction is queued due to other pending transactions waiting to be processed first.

After further research, we can conclude that the transaction is queued because another transaction from the same account with a lower nonce is still pending. Once the transaction with nonce eight is processed, the next queued transaction (i.e., nonce nine) will transition to a pending state. 

Conclusion

Now you know how to tell the difference between pending and queued transactions on Ethereum. Plus, we also demonstrated how to request pending and queued transactions using Python with Web3.py.

Subscribe to our newsletter for more articles and guides on Ethereum. Feel free to reach out to us via Twitter if you have any feedback. You can always chat with us on our Discord community server, featuring some of the coolest developers you'll ever meet :)