Skip to content

Latest commit

 

History

History
302 lines (234 loc) · 9.31 KB

README.md

File metadata and controls

302 lines (234 loc) · 9.31 KB
Raw

ether

Python versions PyPi Version

The web3.py operation wrapper, offering interaction through Wallet instances.

Web3.py suggests to interact with instance of Web3 as primary entity. We offer way to use Wallet entity, that is more familiar, since we try to provide the similar to digital wallet apps' logic. We introduce:

  • possibility to set and change current wallet's network by network's name
  • swift and robust performing transactions
  • quick performing useful functions of Web3.py

The project is made by the Croco Factory team

ether's source code is made available under the MIT License

Quick start

You can quickly use supported networks as RPC:

Network Native Token Testnet
Arbitrum Goerli ETH ✅
Arbitrum Sepolia ETH ✅
Arbitrum ETH ❌
Avalanche AVAX ❌
Base ETH ❌
Base Sepolia ETH ✅
Base Goerli ETH ✅
BSC BNB ❌
BSC Testnet BNB ✅
Ethereum ETH ❌
Fantom FTM ❌
Fantom Testnet FTM ✅
Fuji AVAX ✅
Goerli ETH ✅
Linea ETH ❌
Linea Goerli ETH ✅
Linea Sepolia ETH ✅
Mumbai MATIC ✅
opBNB BNB ❌
opBNB Testnet BNB ✅
Optimism ETH ❌
Optimism Sepolia ETH ✅
Optimism Goerli ETH ✅
Polygon MATIC ❌
Sepolia ETH ❌
Scroll ETH ❌
zkSync ETH ❌

For specifying network you only need to pass network's name.

from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')

If you use unsupported network, you can specify it using Network instance

from ether import Wallet, Network

network_info = Network(
    name='Custom',
    rpc='wss://custom.publicnode.com',
    token='CUSTOM'
)
custom_wallet = Wallet('your_private_key', network_info)

Library supports asynchronous approach

from ether import AsyncWallet

async def validate_balance():
    async_wallet = AsyncWallet('your_private_key', 'Arbitrum')
    balance = await async_wallet.get_balance()
    assert balance > 0.1

Quick overview

You can perform the following actions, using ether:

approve

When you want to spend non-native tokens, for instance USDT, you need to perform approving operation.

from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

stargate_router = '0x8731d54E9D02c286767d56ac03e8037C07e01e98'
usdt = my_wallet.get_token('0xdAC17F958D2ee523a2206206994597C13D831ec7')
usdt_amount = provider.to_wei(0.001, 'ether')

my_wallet.approve(usdt, stargate_router, usdt_amount)

build_and_transact

If you don't need to check estimated gas or directly use transact, you can call build_and_transact. It's based on getting closure as argument. Closure is transaction's function, called with arguments. Notice that it has to be not built or awaited 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

stargate_abi = [...]
stargate_router = '0x8731d54E9D02c286767d56ac03e8037C07e01e98'
stargate = my_wallet.provider.eth.contract(stargate_router, abi=stargate_abi)

eth_amount = provider.to_wei(0.001, 'ether')
closure = stargate.functions.swapETH(...) 
my_wallet.build_and_transact(closure, eth_amount)

build_tx_params

You can use build_tx_params to quickly get dictionary of params for building transaction. Public key, chain id and nonce are generated automatically. You also can also choose not to set a gas and the gas price 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'BSC')

my_wallet.build_tx_params(0)
{
  "from": "0xe977Fa8D8AE7D3D6e28c17A868EF04bD301c583f", 
  "chainId": 56, 
  "nonce": 168, 
  "value": 0, 
  "gas": 250000, 
  "gasPrice": 1000000000
}

create

You can use that, when you want to create all-new wallet 
from ether import Wallet
wallet = Wallet.create('Arbitrum')

estimate_gas

When you want to estimate an amount of gas to send a transaction, you can use estimate_gas 
from ether import Wallet

my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

stargate_router = '0x8731d54E9D02c286767d56ac03e8037C07e01e98'
stargate_abi = [...]
eth_amount = provider.to_wei(0.001, 'ether')

stargate = my_wallet.provider.eth.contract(stargate_router, abi=stargate_abi)
params = my_wallet.build_tx_params(eth_amount)
tx_params = stargate.functions.swapETH(...).buildTransaction(params)
gas = my_wallet.estimate_gas(tx_params)
tx_params['gas'] = gas

my_wallet.transact(tx_params)

get_balance

You can get the balance of the native token of your wallet. 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
balance = my_wallet.get_balance()

get_balance_of

You can get the balance of specified token of your wallet 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')

usdt = my_wallet.get_token('0xdAC17F958D2ee523a2206206994597C13D831ec7')
balance = my_wallet.get_balance_of(usdt, convert=True)
print(balance)

get_token

You can get the `Token` instance, containing information about symbol and decimals. Also this function used for another instance-methods of Wallet. 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
usdt = my_wallet.get_token('0xdAC17F958D2ee523a2206206994597C13D831ec7')
print(usdt.decimals)

get_explorer_url

You can get entire wallet's list of transactions 
from ether import Wallet
from web3.contract import Contract
my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

stargate_router = '0x8731d54E9D02c286767d56ac03e8037C07e01e98'
stargate_abi = [...]
stargate = Contract(stargate_router, stargate_abi)

eth_amount = provider.to_wei(0.001, 'ether')
closure = stargate.functions.swapETH(...) 
tx_hash = my_wallet.build_and_transact(closure, eth_amount)
print(my_wallet.get_explorer_url(tx_hash))

is_native_token

If you want to check, if the specific token is native token of network, you can use is_native_token.

You can use any case in a token's ticker.

from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
assert my_wallet.is_native_token('eTh')

transact

After building transaction you can perform it, passing transaction data to transact 
from ether import Wallet

my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

stargate_router = '0x8731d54E9D02c286767d56ac03e8037C07e01e98'
stargate_abi = [...]
eth_amount = provider.to_wei(0.001, 'ether')

stargate = my_wallet.provider.eth.contract(stargate_router, abi=stargate_abi)
params = my_wallet.build_tx_params(eth_amount)
tx_data = stargate.functions.swapETH(...).buildTransaction(params)
gas = my_wallet.estimate_gas(tx_data)
tx_data['gas'] = gas

my_wallet.transact(tx_data)

transfer

You can transfer tokens to another wallet 
from ether import Wallet
my_wallet = Wallet('your_private_key', 'Arbitrum')
provider = my_wallet.provider

recipient = '0xe977Fa8D8AE7D3D6e28c17A868EF04bD301c583f'
usdt = my_wallet.get_token('0xdAC17F958D2ee523a2206206994597C13D831ec7')
usdt_amount = provider.to_wei(0.001, 'ether')

my_wallet.transfer(usdt, recipient, usdt_amount)

Installing ether

To install the package from PyPi you can use:

pip install pyether

To install the package from GitHub you can use:

pip install git+https://github.com/CrocoFactory/ether.git