Skip to content

Latest commit

 

History

History
435 lines (292 loc) · 15 KB

providers.rst

File metadata and controls

435 lines (292 loc) · 15 KB
Raw

Providers

The provider is how web3 talks to the blockchain. Providers take JSON-RPC requests and return the response. This is normally done by submitting the request to an HTTP or IPC socket based server.

Note

Web3.py supports one provider per instance. If you have an advanced use case that requires multiple providers, create and configure a new web3 instance per connection.

If you are already happily connected to your Ethereum node, then you can skip the rest of the Providers section.

Choosing How to Connect to Your Node

Most nodes have a variety of ways to connect to them. If you have not decided what kind of node to use, head on over to choosing_node

The most common ways to connect to your node are:

  1. IPC (uses local filesystem: fastest and most secure)
  2. Websockets (works remotely, faster than HTTP)
  3. HTTP (more nodes support it)

If you're not sure how to decide, choose this way:

  • If you have the option of running Web3.py on the same machine as the node, choose IPC.
  • If you must connect to a node on a different computer, use Websockets.
  • If your node does not support Websockets, use HTTP.

Most nodes have a way of "turning off" connection options. We recommend turning off all connection options that you are not using. This provides a safer setup: it reduces the number of ways that malicious hackers can try to steal your ether.

Once you have decided how to connect, you specify the details using a Provider. Providers are Web3.py classes that are configured for the kind of connection you want.

See:

  • ~web3.providers.ipc.IPCProvider
  • ~web3.providers.websocket.WebsocketProvider
  • ~web3.providers.rpc.HTTPProvider

Once you have configured your provider, for example:

from web3 import Web3
my_provider = Web3.IPCProvider('/my/node/ipc/path')

Then you are ready to initialize your Web3 instance, like so:

w3 = Web3(my_provider)

Finally, you are ready to get started with Web3.py<first_w3_use>.

Automatic vs Manual Providers

The Web3 object will look for the Ethereum node in a few standard locations if no providers are specified. Auto-detection happens when you initialize like so:

from web3.auto import w3

# which is equivalent to:

from web3 import Web3
w3 = Web3()

Sometimes, web3 cannot automatically detect where your node is.

  • If you are not sure which kind of connection method to use, see choosing_provider.
  • If you know the connection method, but not the other information needed to connect (like the path to the IPC file), you will need to look up that information in your node's configuration.
  • If you're not sure which node you are using, see choosing_node

For a deeper dive into how automated detection works, see:

How Automated Detection Works

Web3 attempts to connect to nodes in the following order, using the first successful connection it can make:

  1. The connection specified by an environment variable, see provider_uri
  2. ~web3.providers.ipc.IPCProvider, which looks for several IPC file locations. IPCProvider will not automatically detect a testnet connection, it is suggested that the user instead uses a w3 instance from web3.auto.infura (e.g. from web3.auto.infura.ropsten import w3) if they want to auto-detect a testnet.
  3. ~web3.providers.rpc.HTTPProvider, which attempts to connect to "http://localhost:8545"
  4. None - if no providers are successful, you can still use Web3 APIs that do not require a connection, like:
    • overview_type_conversions
    • overview_currency_conversions
    • overview_addresses
    • eth-account
    • etc.

Examples Using Automated Detection

Some nodes provide APIs beyond the standards. Sometimes the same information is provided in different ways across nodes. If you want to write code that works across multiple nodes, you may want to look up the node type you are connected to.

For example, the following retrieves the client enode endpoint for both geth and parity:

from web3.auto import w3

connected = w3.isConnected()

if connected and w3.clientVersion.startswith('Parity'):
    enode = w3.parity.enode

elif connected and w3.clientVersion.startswith('Geth'):
    enode = w3.geth.admin.nodeInfo['enode']

else:
    enode = None

Provider via Environment Variable

Alternatively, you can set the environment variable WEB3_PROVIDER_URI before starting your script, and web3 will look for that provider first.

Valid formats for this environment variable are:

  • file:///path/to/node/rpc-json/file.ipc
  • http://192.168.1.2:8545
  • https://node.ontheweb.com
  • ws://127.0.0.1:8546

Auto-initialization Provider Shortcuts

There are a couple auto-initialization shortcuts for common providers.

Infura Mainnet

To easily connect to the Infura Mainnet remote node, first register for a free project ID if you don't have one at https://infura.io/register .

Then set the environment variable WEB3_INFURA_PROJECT_ID with your Project ID:

$ export WEB3_INFURA_PROJECT_ID=YourProjectID

If you have checked the box in the Infura UI indicating that requests need an optional secret key, set the environment variable WEB3_INFURA_API_SECRET:

$ export WEB3_INFURA_API_SECRET=YourProjectSecret
>>> from web3.auto.infura import w3

# confirm that the connection succeeded
>>> w3.isConnected()
True

Geth dev Proof of Authority

To connect to a geth --dev Proof of Authority instance with defaults:

>>> from web3.auto.gethdev import w3

# confirm that the connection succeeded
>>> w3.isConnected()
True

Built In Providers

Web3 ships with the following providers which are appropriate for connecting to local and remote JSON-RPC servers.

HTTPProvider

IPCProvider

WebsocketProvider

EthereumTesterProvider

Warning

Experimental: This provider is experimental. There are still significant gaps in functionality. However it is being actively developed and supported.

Note

To install the needed dependencies to use EthereumTesterProvider, you can install the pip extras package that has the correct interoperable versions of the eth-tester and py-evm dependencies needed to do testing: e.g. pip install web3[tester]

AutoProvider

~web3.providers.auto.AutoProvider is the default used when initializing web3.Web3 without any providers. There's rarely a reason to use it explicitly.

AsyncHTTPProvider

Warning

This provider is unstable and there are still gaps in functionality. However, it is being actively developed.

Supported Methods

Eth
  • web3.eth.accounts <web3.eth.Eth.accounts>
  • web3.eth.block_number <web3.eth.Eth.block_number>
  • web3.eth.chain_id <web3.eth.Eth.chain_id>
  • web3.eth.coinbase <web3.eth.Eth.coinbase>
  • web3.eth.gas_price <web3.eth.Eth.gas_price>
  • web3.eth.hashrate <web3.eth.Eth.hashrate>
  • web3.eth.max_priority_fee <web3.eth.Eth.max_priority_fee>
  • web3.eth.mining <web3.eth.Eth.mining>
  • web3.eth.call() <web3.eth.Eth.call>
  • web3.eth.estimate_gas() <web3.eth.Eth.estimate_gas>
  • web3.eth.generate_gas_price() <web3.eth.Eth.generate_gas_price>
  • web3.eth.get_balance() <web3.eth.Eth.get_balance>
  • web3.eth.get_block() <web3.eth.Eth.get_block>
  • web3.eth.get_code() <web3.eth.Eth.get_code>
  • web3.eth.get_raw_transaction() <web3.eth.Eth.get_raw_transaction>
  • web3.eth.get_raw_transaction_by_block() <web3.eth.Eth.get_raw_transaction_by_block>
  • web3.eth.get_transaction() <web3.eth.Eth.get_transaction>
  • web3.eth.get_transaction_count() <web3.eth.Eth.get_transaction_count>
  • web3.eth.get_transaction_receipt() <web3.eth.Eth.get_transaction_receipt>
  • web3.eth.send_transaction() <web3.eth.Eth.send_transaction>
  • web3.eth.send_raw_transaction() <web3.eth.Eth.send_raw_transaction>
  • web3.eth.wait_for_transaction_receipt() <web3.eth.Eth.wait_for_transaction_receipt>
Net
  • web3.net.listening() <web3.net.listening>
  • web3.net.peer_count() <web3.net.peer_count>
  • web3.net.version() <web3.net.version>

Supported Middleware

  • Gas Price Strategy <web3.middleware.gas_price_strategy_middleware>
  • Buffered Gas Estimate Middleware <web3.middleware.buffered_gas_estimate_middleware>