Web3 Python API - cogeorg/teaching GitHub Wiki

Web3.py is a Python implementation of web3.js, the Ethereum compatible JavaScript API. To use this library, you need to have a local node already running. The library communicates with the node through RPC calls and will work with any Ethereum node that exposes an RPC layer.

web3 contains the eth object - web3.eth (for specifically Ethereum blockchain interactions) and the shh object - web3.shh (for Whisper interaction - Whisper is a low level communication protocol used by decentralized applications to communicate with each other).

Read more in the documentation on ReadTheDocs

Installation

Web3.py can be installed using pip as follows

pip install web3

Using Web3

To use the web3 library you will need to instantiate an instance of the Web3 object. Web3 uses providers to connects to the blockchain. The Web3 library comes with a the following built-in providers that should be suitable for most normal use cases.

web3.HTTPProvider for connecting to http and https based JSON-RPC servers.
web3.IPCProvider for connecting to ipc socket based JSON-RPC servers.

The HTTPProvider takes the full URI where the server can be found and the IPCProvider takes the filesystem path where the IPC socket can be found. If no path is provided for the IPC socket, it will use the default path for your operating system. To connect to the blockchain, execute the following in your python console

>>> from web3 import Web3, HTTPProvider, IPCProvider

# The default server URL for the geth client is http://localhost:8545. # Use this port to communicate with your node.

>>> web3 = Web3(HTTPProvider('http://localhost:8545'))

# or for an IPC based connection

>>> web3 = Web3(IPCProvider())

Apart from eth and ssh, here are some of the objects contained in web3

Type Conversions

web3.toHex(value)

Takes ah string as input and returns it in its hexadecimal representation.

Example
```
 >>> web3.toHex("crypto")
 0x63727970746f
```
web3.toText(value)

Takes a hexstr as input and returns its string equivalent. Text gets decoded as UTF-8

Example
```
 >>> web3.toText('0x626c6f636b636861696e')
 blockchain
```
web3.toInt(value)

Takes a hexstr as input and returns its integer equivalent

Example
```
 >>> web3.toInt(hexstr='0x8000')
 32768
```

Currency conversions

web3.toWei(value, currency)

Returns the value in the denomination specified by the currency argument converted to wei

Example
```
 >>> web3.toWei(1,'ether')
 1000000000000000000
```

Addresses

web3.isAddress(value)

Returns True if the value is of the recognized address formats

Example
```
 >>> web3.isAddress('0x58372902c462066cadb2c7eab18fa4060ed0cf02')
True
```

Cryptographic hashing

web3.soliditySha3(abi_types, value)

Returns the sha3 as it would be computed by the solidity sha3 function on the provided value and abi_types. The abi_types value should be a list of solidity type strings which correspond to each of the provided values

Example
```
 >>> web3.soliditySha3(['uint8', 'address'], (1, "0x49eddd3769c0712032808d86597b84ac5c2f5614"))
0x12ae32ae001ccf850d42fdb4fe2067c92e69568b8bfbe2f2e3666b598b533067
```

RPC Methods

Eth

The web3.eth object exposes the following properties and methods to interact with the RPC APIs under the eth_ namespace:

Properties

web3.eth.defaultAccount
Returns the ethereum address that will be used as the default from address for all transactions
web3.eth.defaultBlock
Returns the default block number that will be used for any RPC methods that accept a block identifier. Defaults to 'latest'
web3.eth.coinbase
Returns the current coinbase address
web3.eth.mining
Returns boolean as to whether the node is currently mining
web3.eth.accounts
Returns the list of known accounts
web3.eth.hashrate
Returns the current number of hashes per second the node is mining with
web3.eth.gasPrice
Returns the current gas price in Wei

Methods

web3.eth.getBalance(address [, block_identifier])
Returns the balance of the given address at the block specified by block_identifier. The block_identifier is an optional parameter which defaults to web3.eth.defaultBlock if unspecified.

web3.eth.getBlock(block_identifier [, returnTransactionObjects])
Returns the block specified by block_identifier. Delegates to the eth_getBlockByNumber RPC method if block_identifier is an integer or one of the predefined block parameters 'latest', 'earliest', 'pending'. If a block hash is entered, it delegates to the eth_getBlockByHash method. returnTransactionObjects is an optional boolean parameter, set to false by default. If true, the returned block will contain all transactions as objects, otherwise it will only contain the transaction hashes.

Example

>>> web3.eth.getBlock('latest')
AttributeDict({'difficulty': 161449,
 'extraData': '0xd683010702846765746885676f312e398664617277696e',
 'gasLimit': 4712388,
  'gasUsed': 0,
  'hash': '0xdd3e5c97c9fcc3768277dc03b025db61e9ca53a7aaf56a6e3c73c8a1c0a48938',
  'logsBloom': '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
  'miner': '0x32ae509ac06bddf5b29c86bac5d247b1002596b2',
  'mixHash': '0x0f1d9c0e943e1af74fd8e7bbb3dda903bc41d4d5ee9bc7176f4b671cbc30f372',
  'nonce': '0x7ace69910e67c735',
  'number': 432,
  'parentHash': '0x669fd45ef3493642403ebfbb02ba181e0aec5c246bd60d1a26cf0f36fe1a2c88',
  'receiptsRoot': '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
  'sha3Uncles': '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347',
  'size': 536,
  'stateRoot': '0x460fd7ede43e1a61fa075361246460551dc5f3adcf65f16fa64d0748522fb086',
  'timestamp': 1516114053,
  'totalDifficulty': 63103010,
  'transactions': [],
  'transactionsRoot': '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
  'uncles': []})

web3.eth.getTransaction(transaction_hash)
Returns the transaction specified by transaction_hash
web3.eth.getTransactionFromBlock(block_identifier, transaction_index)
Returns the transaction at the index specified by transaction_index from the block specified by block_identifier. Delegates to the eth_getTransactionByBlockNumberAndIndex RPC method if block_identifier is an integer or one of the predefined block parameters 'latest', 'earliest', 'pending', otherwise delegates to the eth_getTransactionByBlockHashAndIndex RPC method
web3.eth.sendTransaction(transaction_object)
Signs and sends the given transaction and returns the 32 Bytes transaction hash as HEX string. The transaction_object should be a dictionary with the following keys:
- from: string - (optional, default: web3.eth.defaultAccount) The address the transaction is send from
- to: string - (optional when creating new contract) The address the transaction is directed to
- gas: integer - (optional) The amount of gas to use for the transaction (unused gas is refunded)
- gasPrice: integer - (optional) The price of gas for this transaction in wei, defaults to the mean network gas price
- value: integer - (optional) Integer of the value send with this transaction
- data: string - (optional) Either a byte string containing the associated data of the message, or in the case of a contract-creation transaction, the initialization code
- nonce: integer - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce
web3.eth.sign(address, dataToSign)
Signs the given data with the private key of the given address. The address must be unlocked

Filters

The following methods are available on the web3.eth object for interacting with the filtering API

web3.eth.filter(filter_params)
Can be used to set up filters for pending transactions, new blocks and event logs. If filter_params is the string 'pending' then a new filter is registered using the eth_newPendingTransactionFilter RPC method. This creates a filter in the node to notify the user when new pending transactions arrive. If filter_params is the string 'latest' then a new filter is registered using the eth_newBlockFilter RPC method. This will create a new filter that will be called each time the node receives a new block. Lastly, if filter_params is a dictionary then a new filter is registered using the eth_newFilter RPC method. This will create a filter object, based on filter_params, to notify when the state changes (logs).

filter_params should be a dictionary with the following keys:
- fromBlock: integer|string - (optional, default: 'latest') Integer block number, or 'latest' for the last mined block or 'pending', 'earliest' for not yet mined transactions
- toBlock: integer|string - (optional, default: 'latest') Integer block number, or 'latest' for the last mined block or 'pending', 'earliest' for not yet mined transactions
- address: string or list of strings - (optional) Contract address or a list of addresses from which logs should originate
- topics: Array of strings or null - (optional) Array of topics that should be used for filtering
A filter object with the following methods will be returned
- filter.get(callback): Returns all of the log entries that fit the filter
- filter.watch(callback): Watches for state changes that fit the filter and calls the callback
- filter.stopWatching(): Stops the watch and uninstalls the filter in the node. Should always be called once it is done
web3.eth.getFilterLogs(filter_id)
Returns all entries for the given filter_id

Contracts

web3.eth.contract(inputArgs)
Creates a contract object for a solidity contract defined by inputArgs. The following arguments are accepted for contract class creation
- abi
- asm
- ast
- bytecode
- bytecode_runtime
- clone_bin
- dev_doc
- interface
- metadata
- opcodes
- src_map
- src_map_runtime
- user_doc

Each contract object is exposed to the following properties and methods

Contract.address
The hexadecimal encoded 20-byte address of the contract. This will remain empty until the contract transaction has been mined
Contract.abi
The contract ABI array
Contract.bytecode
The contract bytecode string
Contract.deploy(transaction, args)
Construct and send a transaction to deploy the contract and returns the transaction hash for the deploy transaction. If provided, transaction should be a dictionary conforming to the web3.eth.sendTransaction(transaction) method. If a gas parameter is not provided in the deployment transaction, then the gas value will be calculated using the web3.eth.estimateGas() method. If the contract takes constructor arguments they should be provided as a list via the args parameter
Contract.transact(transaction).function(args)
Executes the specified function by sending a new public transaction and returns the transaction hash.

The first part of this function call transact(transaction) takes a single parameter which should be a python dictionary conforming to the same format as the web3.eth.sendTransaction(transaction) method. The second part of the function call function(args) selects the appropriate contract function based on the name and provided arguments.
Contract.call(transaction).function(args)
Calls a contract function, executing the transaction locally using the eth_call API. This will not create a new public transaction. This method behaves the same as the Contract.transact method, with transaction details being passed into the first portion of the function call, and function arguments being passed into the second portion.
Contract.estimateGas(transaction).function(args)
Calls a contract function, executing the transaction locally using the eth_call API. This will not create a new public transaction. Returns the amount of gas consumed which can be used as a gas estimate for executing this transaction publicly.

Management APIs

Admin

The admin API gives you access to several non-standard RPC methods, which will allow you to have a fine grained control over your Geth instance, including but not limited to network peer and RPC endpoint management.

Properties

web3.admin.datadir
Returns the absolute path the running Geth node currently uses to store all its databases
web3.admin.nodeInfo
Returns information about the currently running node
web3.admin.peers
Returns the current peers the node is connected to

Methods

web3.admin.addPeer(nodeUrl)
Requests adding a new remote node to the list of tracked static nodes and returns boolean as to whether the server was successfully started
web3.admin.startRPC(host, port, cors, apis)
Starts an HTTP based JSON RPC API webserver to handle client requests. All the parameters are optional:
- host: network interface to open the listener socket on (defaults to "localhost")
- port: network port to open the listener socket on (defaults to 8545)
- cors: cross-origin resource sharing header to use (defaults to "")
- apis: API modules to offer over this interface (defaults to "eth,net,web3")
web3.admin.stopRPC()
Stops the HTTP based JSON RPC server
web3.admin.startWS(host, port, cors, apis)
Starts the Websocket based JSON RPC API webserver. All the parameters are optional:
- host: network interface to open the listener socket on (defaults to "localhost")
- port: network port to open the listener socket on (defaults to 8546)
- cors: cross-origin resource sharing header to use (defaults to "")
- apis: API modules to offer over this interface (defaults to "eth,net,web3")
web3.admin.stopWS()
Stops the Websocket based JSON RPC server

Miner

The miner API allows you to remote control the node's mining operation and set various mining specific settings

Methods

web3.miner.setExtra(value)
Set the 32 byte value as the extra data that will be included when this node mines a block
web3.miner.setGasPrice(value)
Sets the minimal accepted gas price when mining transactions. Any transactions that are below this limit are excluded from the mining process
web3.miner.start(num_threads)
Start the CPU mining process with the given number of threads and generate a new DAG if need be
web3.miner.stop()
Stop the CPU mining operation
web3.miner.setEtherBase
Sets the etherbase, where mining rewards will go

Personal

The personal API manages private keys in the key store

Properties

web3.personal.listAccounts
Returns all the Ethereum account addresses of all keys in the key store

Methods

web3.personal.importRawKey(keydata, passphrase)
Imports the given unencrypted private key (hex string) into the key store, encrypting it with the passphrase. Returns the address of the new account
web3.personal.newAccount(passphrase)
Generates a new private key and stores it in the key store directory. The key file is encrypted with the given passphrase. Returns the address of the new account. In the geth console, newAccount will prompt for a passphrase when it is not supplied as the argument
personal.sendTransaction(transaction_object, passphrase)
Validates the given passphrase and submits a transaction. The transaction_object is the same argument as for eth_sendTransaction and contains the from address. If the passphrase can be used to decrypt the private key belonging to transaction_object.from the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls
web3.personal.lockAccount(address)
Locks the given address
web3.personal.unlockAccount(address, passphrase, duration)
Unlocks the given address for duration seconds. Both passphrase and duration are optional when using the JavaScript console. If the passphrase is not supplied as an argument, the console will prompt for the passphrase interactively. duration defaults to 300 seconds and the unencrypted key will be held in memory until this expires. An explicit duration of zero seconds unlocks the address until geth exits
web3.personal.sign(message, account, [password])
Calculates an Ethereum specific signature
web3.personal.ecRecover(message, signature)
Returns the address associated with the private key that was used to calculate the signature in personal.sign

Tx Pool

The txpool API gives you access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing

Properties

web3.txpool.content
Returns a list of transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. Returns an object with two fields pending and queued
web3.txpool.inspect
Returns a textual summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. Returns an object with two fields pending and queued
web3.txpool.status
Returns an object with two fields pending and queued, each of which is a counter representing the number of transactions in that particular state

Web3 Python API - cogeorg/teaching GitHub Wiki

Installation

Using Web3

Type Conversions

web3.toHex(value)

web3.toText(value)

web3.toInt(value)

Currency conversions

web3.toWei(value, currency)

Addresses

web3.isAddress(value)

Cryptographic hashing

web3.soliditySha3(abi_types, value)

RPC Methods

Eth

Properties

Methods

Example

Filters

Contracts

Management APIs

Admin

Properties

Methods

Miner

Methods

Personal

Properties

Methods

Tx Pool

Properties