Simple Ethereum Client
======================
This repository is a python client to access ethereum network.
Requirements
------------
- `Web3.py <https://web3py.readthedocs.io/en/stable/index.html>`__
- `py-solc-x <https://solcx.readthedocs.io/en/latest/>`__
Usage
-----
- `Instantiate client <#instantiate-client>`__
- `Check connection <#check-connection>`__
- `Connect to new node <#connect-to-new-node>`__
- `Create new ethereum account <#create-new-ethereum-account>`__
- `Get account instance <#get-account-instance>`__
- `Get account properties <#get-account-properties>`__
- `Change account password <#change-account-password>`__
- `Transfer balance to another
account <#transfer-balance-to-another-account>`__
- `Compile smart contract <#compile-smart-contract>`__
- `Deploy smart contract <#deploy-smart-contract>`__
- `Get contract <#get-contract>`__
- `Modify contract's storage <#modify-contracts-storage>`__
- `Parse contract event log <#parse-contract-event-log>`__
- `Call contract <#call-contract>`__
- `Cancel transaction <#cancel-transaction>`__
- `Get blockchain data <#get-blockchain-data>`__
Instantiate client
~~~~~~~~~~~~~~~~~~
Initialize the client
.. code:: python
from ezeth import ETHClient
node_host = 'localhost'
node_port = 8545
node_connection_type = 'http'
node_consensus = 'PoW'
client = ETHClient(
node_host=node_host,
node_port=node_port,
node_connection_type=node_connection_type,
node_consensus=node_consensus
)
Check connection
~~~~~~~~~~~~~~~~
.. code:: python
print(client.isConnected)
# True
Connect to new node
~~~~~~~~~~~~~~~~~~~
.. code:: python
node_host = 'localhost'
node_port = 8546
node_connection_type = 'http'
node_consensus = 'PoW'
client.connect(
node_host=node_host,
node_port=node_port,
node_connection_type=node_connection_type,
node_consensus=node_consensus
)
Create new ethereum account
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The returned object is dictionary with 2 keys,
- ``"account"``, contains the instance of ``LocalAccount``
- ``"encrypted_key"``, contains the dictionary that contains address
and private key of the account encrypted with password input from the
parameter
.. code:: python
import json
from eth_account.signers.local import LocalAccount
password = 'pass123'
new_account = client.create_account(password)
print(isinstance(new_account, LocalAccount))
# True
with open('account_data.json', 'w') as f:
json.dump(new_account['encrypted_key'], f)
Get account instance
~~~~~~~~~~~~~~~~~~~~
To get account instance from encrypted private key, use this method
.. code:: python
import json
from eth_account.signers.local import LocalAccount
password = 'pass123'
with open('account_data.json') as f:
encrypted_key = json.load(f)
account = client.get_account(
password,
encrypted_key
)
print(isinstance(account, LocalAccount))
# True
To get account instance from private key, use this method
.. code:: python
# don't use this private key in development
private_key = '0xd69ff3bd9e6a4455c13974be6ac741996c94eedf9725ad3c7fbccb833d3fae79'
account = client.get_account_from_key(private_key)
print(isinstance(account, LocalAccount))
# True
Get account properties
~~~~~~~~~~~~~~~~~~~~~~
The returned object is dictionary with 3 keys,
- ``"address"``, the address of the account
- ``"balance"``, the balance of the account at current network
- ``"nonce"``, the current nonce (number of transactions) of the
account at current network
.. code:: python
account_address = account.address
account_properties = client.get_account_properties(account_address)
print(account_properties)
# {'address': '0xf3cCa25419069bcd6B94bE3876Ac3400070E4796', 'balance': 0, 'nonce': 0}
Change account password
~~~~~~~~~~~~~~~~~~~~~~~
To change password of the encrypted private key, use this method
.. code:: python
import json
old_password = 'pass123'
new_password = 'newpasss123'
with open('account_data.json') as f:
encrypted_key = json.load(f)
new_encrypted_key = client.change_account_password(
old_password,
new_password,
encrypted_key
)
with open('new_account_data.json', 'w') as f:
json.dump(new_encrypted_key, f)
Transfer balance to another account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
receiver_address = '0xf3cCa25419069bcd6B94bE3876Ac3400070E4796'
value = 10
message = 'here is the money'
transaction = client.transfer(
receiver_address,
value,
message,
account=account
)
To estimate the cost to transfer, use this
.. code:: python
cost = client.estimate_transfer_price(
value,
message
)
print(cost)
# {'cost': 664680000000000, 'value': 10, 'total': 664680000000010}
Compile smart contract
~~~~~~~~~~~~~~~~~~~~~~
The returned object is dictionary with keys in format
``<filename>:<contractname>`` (ex. ``"Storage.sol:Storage"``) and the
value is dictionary with 2 keys,
- ``"abi"``, contains ABI of the contract
- ``"bin"``, contains bytecode of the contract
.. code:: python
solc_version = '0.8.11'
sol_file = 'Storage.sol'
compiled_contract = client.compile_contract(
sol_file,
solc_version
)
Here is example of contract
.. code:: solidity
// SPDX-License-Identifier: GPL-3.0
// Storage.sol
pragma solidity >=0.4.16 <0.9.0;
contract Storage {
uint storedData;
event ValueModified(
uint oldValue,
uint newValue
);
constructor(uint initValue) {
storedData = initValue;
}
function set(uint newValue) public {
emit ValueModified(storedData, newValue);
storedData = newValue;
}
function get() public view returns (uint) {
return storedData;
}
}
Deploy smart contract
~~~~~~~~~~~~~~~~~~~~~
.. code:: python
storage_contract = compiled_contract['Storage.sol:Storage']
contract_bytecode = storage_contract['bin']
contract_abi = storage_contract['abi']
# for contract constructor
init_value = 10
deployed_contract_data = client.deploy_contract(
contract_bytecode,
contract_abi,
account=account,
initValue=init_value
)
To estimate the cost to deploy smart contract, use this
.. code:: python
cost = client.estimate_deploy_contract_price(
contract_bytecode,
contract_abi,
account_address=account.address,
initValue=init_value
)
print(cost)
# {'cost': 5166480000000000, 'value': 0, 'total': 5166480000000000}
..
The account which deployed the smart contract must have a sufficient
balance to estimate the cost if the constructor is payable method.
Get contract
~~~~~~~~~~~~
To get the deployed smart contract address, use this
.. code:: python
transaction_hash = deployed_contract_data['transaction_hash']
contract_address = client.get_contract_address(transaction_hash)
print(contract_address)
# 0x7c0ce101E6712DD4E447CE2af81AAD5f8fbF34D0
To get the instance of the deployed smart contract, use this
.. code:: python
contract = client.get_contract(
contract_address,
contract_abi
)
Modify contract's storage
~~~~~~~~~~~~~~~~~~~~~~~~~
To modify contract storage by contract method, use this
.. code:: python
contract_method = 'set'
new_value = 13
transaction = client.contract_method(
contract_method,
contract=contract,
account=account,
newValue=new_value
)
To test contract method locally without sending transaction to network, use this
.. code:: python
# will raise exception if something wrong, else return True
client.contract_method_test(
contract_method,
contract=contract,
account_address=account.address,
newValue=new_value
)
To estimate the cost, use this
.. code:: python
cost = client.estimate_contract_method_price(
contract_method,
contract=contract,
account_address=account.address,
newValue=new_value
)
print(cost)
# {'cost': 811560000000000, 'value': 0, 'total': 811560000000000}
..
The account which modify the smart contract's storage must have a
sufficient balance to estimate the cost if the method is payable
method.
Parse contract event log
~~~~~~~~~~~~~~~~~~~~~~~~
To parse event log that is emitted from modified smart contract, use
this
.. code:: python
event_name = 'ValueModified'
transaction_hash = transaction['hash']
event_log = client.parse_contract_event_log(
event_name,
transaction_hash,
contract=contract
)
Call contract
~~~~~~~~~~~~~
To call contract's ``pure`` and ``view`` methods, use this
.. code:: python
contract_method = 'get'
currentValue = client.contract_call(
contract_method,
contract=contract
)
print(currentValue)
# 13
Cancel transaction
~~~~~~~~~~~~~~~~~~
To cancel any transaction from account, use this
.. code:: python
transaction_hash = transaction['hash']
new_transaction = client.cancel_transaction(
transaction_hash,
account=account
)
To estimate the cost, use this
.. code:: python
cost = client.estimate_cancel_transaction_price(
transaction_hash
)
print(cost)
# {'cost': 811590000000000, 'value': 0, 'total': 811590000000000}
..
Transaction that already verified or mined can't be canceled. The way
the transaction canceled is by sending new empty transaction with the
same nonce but higher gas price so the empty transaction will be
mined and the old one will be discarded.
Get blockchain data
~~~~~~~~~~~~~~~~~~~
To get detailed transaction from transaction hash, use this
.. code:: python
transaction = client.get_transaction(transaction_hash)
To get transaction receipt (the prove that transaction is verified or
mined), use this
.. code:: python
receipt = client.get_transaction_receipt(transaction_hash)
To get detailed block, use this
.. code:: python
block = client.get_block('latest')
Raw data
{
"_id": null,
"home_page": "https://github.com/fahadh4ilyas/Simple-Ethereum-Client.git",
"name": "ezeth",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<3.11",
"maintainer_email": "",
"keywords": "ethereum,web3,solidity",
"author": "Ahmad Fahadh Ilyas",
"author_email": "fahadhilyas4@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f1/59/bece0e173f7c96df400a4b6df0e25d61ee6274ed0f5f5f8b6511ea1c820d/ezeth-1.3.1.tar.gz",
"platform": null,
"description": "Simple Ethereum Client\r\n======================\r\n\r\nThis repository is a python client to access ethereum network.\r\n\r\nRequirements\r\n------------\r\n\r\n- `Web3.py <https://web3py.readthedocs.io/en/stable/index.html>`__\r\n- `py-solc-x <https://solcx.readthedocs.io/en/latest/>`__\r\n\r\nUsage\r\n-----\r\n\r\n- `Instantiate client <#instantiate-client>`__\r\n- `Check connection <#check-connection>`__\r\n- `Connect to new node <#connect-to-new-node>`__\r\n- `Create new ethereum account <#create-new-ethereum-account>`__\r\n- `Get account instance <#get-account-instance>`__\r\n- `Get account properties <#get-account-properties>`__\r\n- `Change account password <#change-account-password>`__\r\n- `Transfer balance to another\r\n account <#transfer-balance-to-another-account>`__\r\n- `Compile smart contract <#compile-smart-contract>`__\r\n- `Deploy smart contract <#deploy-smart-contract>`__\r\n- `Get contract <#get-contract>`__\r\n- `Modify contract's storage <#modify-contracts-storage>`__\r\n- `Parse contract event log <#parse-contract-event-log>`__\r\n- `Call contract <#call-contract>`__\r\n- `Cancel transaction <#cancel-transaction>`__\r\n- `Get blockchain data <#get-blockchain-data>`__\r\n\r\nInstantiate client\r\n~~~~~~~~~~~~~~~~~~\r\n\r\nInitialize the client\r\n\r\n.. code:: python\r\n\r\n from ezeth import ETHClient\r\n\r\n node_host = 'localhost'\r\n node_port = 8545\r\n node_connection_type = 'http'\r\n node_consensus = 'PoW'\r\n\r\n client = ETHClient(\r\n node_host=node_host,\r\n node_port=node_port,\r\n node_connection_type=node_connection_type,\r\n node_consensus=node_consensus\r\n )\r\n\r\nCheck connection\r\n~~~~~~~~~~~~~~~~\r\n\r\n.. code:: python\r\n\r\n print(client.isConnected)\r\n # True\r\n\r\nConnect to new node\r\n~~~~~~~~~~~~~~~~~~~\r\n\r\n.. code:: python\r\n\r\n node_host = 'localhost'\r\n node_port = 8546\r\n node_connection_type = 'http'\r\n node_consensus = 'PoW'\r\n\r\n client.connect(\r\n node_host=node_host,\r\n node_port=node_port,\r\n node_connection_type=node_connection_type,\r\n node_consensus=node_consensus\r\n )\r\n\r\nCreate new ethereum account\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nThe returned object is dictionary with 2 keys,\r\n\r\n- ``\"account\"``, contains the instance of ``LocalAccount``\r\n- ``\"encrypted_key\"``, contains the dictionary that contains address\r\n and private key of the account encrypted with password input from the\r\n parameter\r\n\r\n.. code:: python\r\n\r\n import json\r\n from eth_account.signers.local import LocalAccount\r\n\r\n password = 'pass123'\r\n\r\n new_account = client.create_account(password)\r\n\r\n print(isinstance(new_account, LocalAccount))\r\n # True\r\n\r\n with open('account_data.json', 'w') as f:\r\n json.dump(new_account['encrypted_key'], f)\r\n\r\nGet account instance\r\n~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo get account instance from encrypted private key, use this method\r\n\r\n.. code:: python\r\n\r\n import json\r\n from eth_account.signers.local import LocalAccount\r\n\r\n password = 'pass123'\r\n\r\n with open('account_data.json') as f:\r\n encrypted_key = json.load(f)\r\n\r\n account = client.get_account(\r\n password,\r\n encrypted_key\r\n )\r\n\r\n print(isinstance(account, LocalAccount))\r\n # True\r\n\r\nTo get account instance from private key, use this method\r\n\r\n.. code:: python\r\n\r\n # don't use this private key in development\r\n private_key = '0xd69ff3bd9e6a4455c13974be6ac741996c94eedf9725ad3c7fbccb833d3fae79'\r\n\r\n account = client.get_account_from_key(private_key)\r\n\r\n print(isinstance(account, LocalAccount))\r\n # True\r\n\r\nGet account properties\r\n~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nThe returned object is dictionary with 3 keys,\r\n\r\n- ``\"address\"``, the address of the account\r\n- ``\"balance\"``, the balance of the account at current network\r\n- ``\"nonce\"``, the current nonce (number of transactions) of the\r\n account at current network\r\n\r\n.. code:: python\r\n\r\n account_address = account.address\r\n\r\n account_properties = client.get_account_properties(account_address)\r\n\r\n print(account_properties)\r\n # {'address': '0xf3cCa25419069bcd6B94bE3876Ac3400070E4796', 'balance': 0, 'nonce': 0}\r\n\r\nChange account password\r\n~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo change password of the encrypted private key, use this method\r\n\r\n.. code:: python\r\n\r\n import json\r\n\r\n old_password = 'pass123'\r\n new_password = 'newpasss123'\r\n\r\n with open('account_data.json') as f:\r\n encrypted_key = json.load(f)\r\n\r\n new_encrypted_key = client.change_account_password(\r\n old_password,\r\n new_password,\r\n encrypted_key\r\n )\r\n\r\n with open('new_account_data.json', 'w') as f:\r\n json.dump(new_encrypted_key, f)\r\n\r\nTransfer balance to another account\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n.. code:: python\r\n\r\n receiver_address = '0xf3cCa25419069bcd6B94bE3876Ac3400070E4796'\r\n value = 10\r\n message = 'here is the money'\r\n\r\n transaction = client.transfer(\r\n receiver_address,\r\n value,\r\n message,\r\n account=account\r\n )\r\n\r\nTo estimate the cost to transfer, use this\r\n\r\n.. code:: python\r\n\r\n cost = client.estimate_transfer_price(\r\n value,\r\n message\r\n )\r\n\r\n print(cost)\r\n # {'cost': 664680000000000, 'value': 10, 'total': 664680000000010}\r\n\r\nCompile smart contract\r\n~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nThe returned object is dictionary with keys in format\r\n``<filename>:<contractname>`` (ex. ``\"Storage.sol:Storage\"``) and the\r\nvalue is dictionary with 2 keys,\r\n\r\n- ``\"abi\"``, contains ABI of the contract\r\n- ``\"bin\"``, contains bytecode of the contract\r\n\r\n.. code:: python\r\n\r\n solc_version = '0.8.11'\r\n sol_file = 'Storage.sol'\r\n\r\n compiled_contract = client.compile_contract(\r\n sol_file,\r\n solc_version\r\n )\r\n\r\nHere is example of contract\r\n\r\n.. code:: solidity\r\n\r\n // SPDX-License-Identifier: GPL-3.0\r\n\r\n // Storage.sol\r\n\r\n pragma solidity >=0.4.16 <0.9.0;\r\n\r\n contract Storage {\r\n uint storedData;\r\n\r\n event ValueModified(\r\n uint oldValue,\r\n uint newValue\r\n );\r\n\r\n constructor(uint initValue) {\r\n storedData = initValue;\r\n }\r\n\r\n function set(uint newValue) public {\r\n emit ValueModified(storedData, newValue);\r\n storedData = newValue;\r\n }\r\n\r\n function get() public view returns (uint) {\r\n return storedData;\r\n }\r\n }\r\n\r\nDeploy smart contract\r\n~~~~~~~~~~~~~~~~~~~~~\r\n\r\n.. code:: python\r\n\r\n storage_contract = compiled_contract['Storage.sol:Storage']\r\n contract_bytecode = storage_contract['bin']\r\n contract_abi = storage_contract['abi']\r\n\r\n # for contract constructor\r\n init_value = 10\r\n\r\n deployed_contract_data = client.deploy_contract(\r\n contract_bytecode,\r\n contract_abi,\r\n account=account,\r\n initValue=init_value\r\n )\r\n\r\nTo estimate the cost to deploy smart contract, use this\r\n\r\n.. code:: python\r\n\r\n cost = client.estimate_deploy_contract_price(\r\n contract_bytecode,\r\n contract_abi,\r\n account_address=account.address,\r\n initValue=init_value\r\n )\r\n\r\n print(cost)\r\n # {'cost': 5166480000000000, 'value': 0, 'total': 5166480000000000}\r\n\r\n..\r\n\r\n The account which deployed the smart contract must have a sufficient\r\n balance to estimate the cost if the constructor is payable method.\r\n\r\nGet contract\r\n~~~~~~~~~~~~\r\n\r\nTo get the deployed smart contract address, use this\r\n\r\n.. code:: python\r\n\r\n transaction_hash = deployed_contract_data['transaction_hash']\r\n\r\n contract_address = client.get_contract_address(transaction_hash)\r\n\r\n print(contract_address)\r\n # 0x7c0ce101E6712DD4E447CE2af81AAD5f8fbF34D0\r\n\r\nTo get the instance of the deployed smart contract, use this\r\n\r\n.. code:: python\r\n\r\n contract = client.get_contract(\r\n contract_address,\r\n contract_abi\r\n )\r\n\r\nModify contract's storage\r\n~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo modify contract storage by contract method, use this\r\n\r\n.. code:: python\r\n\r\n contract_method = 'set'\r\n new_value = 13\r\n\r\n transaction = client.contract_method(\r\n contract_method,\r\n contract=contract,\r\n account=account,\r\n newValue=new_value\r\n )\r\n\r\nTo test contract method locally without sending transaction to network, use this\r\n\r\n.. code:: python\r\n\r\n # will raise exception if something wrong, else return True\r\n client.contract_method_test(\r\n contract_method,\r\n contract=contract,\r\n account_address=account.address,\r\n newValue=new_value\r\n )\r\n\r\nTo estimate the cost, use this\r\n\r\n.. code:: python\r\n\r\n cost = client.estimate_contract_method_price(\r\n contract_method,\r\n contract=contract,\r\n account_address=account.address,\r\n newValue=new_value\r\n )\r\n\r\n print(cost)\r\n # {'cost': 811560000000000, 'value': 0, 'total': 811560000000000}\r\n\r\n..\r\n\r\n The account which modify the smart contract's storage must have a\r\n sufficient balance to estimate the cost if the method is payable\r\n method.\r\n\r\nParse contract event log\r\n~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo parse event log that is emitted from modified smart contract, use\r\nthis\r\n\r\n.. code:: python\r\n\r\n event_name = 'ValueModified'\r\n transaction_hash = transaction['hash']\r\n\r\n event_log = client.parse_contract_event_log(\r\n event_name,\r\n transaction_hash,\r\n contract=contract\r\n )\r\n\r\nCall contract\r\n~~~~~~~~~~~~~\r\n\r\nTo call contract's ``pure`` and ``view`` methods, use this\r\n\r\n.. code:: python\r\n\r\n contract_method = 'get'\r\n\r\n currentValue = client.contract_call(\r\n contract_method,\r\n contract=contract\r\n )\r\n\r\n print(currentValue)\r\n # 13\r\n\r\nCancel transaction\r\n~~~~~~~~~~~~~~~~~~\r\n\r\nTo cancel any transaction from account, use this\r\n\r\n.. code:: python\r\n\r\n transaction_hash = transaction['hash']\r\n\r\n new_transaction = client.cancel_transaction(\r\n transaction_hash,\r\n account=account\r\n )\r\n\r\nTo estimate the cost, use this\r\n\r\n.. code:: python\r\n\r\n cost = client.estimate_cancel_transaction_price(\r\n transaction_hash\r\n )\r\n\r\n print(cost)\r\n # {'cost': 811590000000000, 'value': 0, 'total': 811590000000000}\r\n\r\n..\r\n\r\n Transaction that already verified or mined can't be canceled. The way\r\n the transaction canceled is by sending new empty transaction with the\r\n same nonce but higher gas price so the empty transaction will be\r\n mined and the old one will be discarded.\r\n\r\nGet blockchain data\r\n~~~~~~~~~~~~~~~~~~~\r\n\r\nTo get detailed transaction from transaction hash, use this\r\n\r\n.. code:: python\r\n\r\n transaction = client.get_transaction(transaction_hash)\r\n\r\nTo get transaction receipt (the prove that transaction is verified or\r\nmined), use this\r\n\r\n.. code:: python\r\n\r\n receipt = client.get_transaction_receipt(transaction_hash)\r\n\r\nTo get detailed block, use this\r\n\r\n.. code:: python\r\n\r\n block = client.get_block('latest')\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "simple python client to access ethereum network",
"version": "1.3.1",
"split_keywords": [
"ethereum",
"web3",
"solidity"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f159bece0e173f7c96df400a4b6df0e25d61ee6274ed0f5f5f8b6511ea1c820d",
"md5": "cda1fab9b696c0b55050237db2147a75",
"sha256": "f1879539d297aa010c5a1f10eb12a23e7cfb022b83d28df88b046d6a90a7ab0e"
},
"downloads": -1,
"filename": "ezeth-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "cda1fab9b696c0b55050237db2147a75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<3.11",
"size": 15114,
"upload_time": "2023-03-13T09:26:34",
"upload_time_iso_8601": "2023-03-13T09:26:34.841401Z",
"url": "https://files.pythonhosted.org/packages/f1/59/bece0e173f7c96df400a4b6df0e25d61ee6274ed0f5f5f8b6511ea1c820d/ezeth-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-13 09:26:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "fahadh4ilyas",
"github_project": "Simple-Ethereum-Client.git",
"lcname": "ezeth"
}
JSON
