API Reference Python¶
Python bindings and library for in3. Go to our readthedocs page for more on usage.
This library is based on the C version of Incubed, which limits the compatibility for Cython, so please contribute by compiling it to your own platform and sending us a pull-request!
Quickstart¶
Install with pip¶
pip install in3
In3 Client API¶
import in3
in3_client = in3.Client()
# Sends a request to the Incubed Network, that in turn will collect proofs from the Ethereum client,
# attest and sign the response, then send back to the client, that will verify signatures and proofs.
block_number = in3_client.eth.block_number()
print(block_number) # Mainnet's block number
in3_client # incubed network api
in3_client.eth # ethereum api
in3_client.account # ethereum account api
in3_client.contract # ethereum smart-contract api
Tests¶
pytest --pylama
Index¶
Explanation of this source code architecture and how it is organized. For more on design-patterns see here or on Martin Fowler’s Catalog of Patterns of Enterprise Application Architecture.
- in3.init.py: Library entry point, imports organization. Standard for any pipy package.
- in3.client: Incubed Client and API.
- in3.model: MVC Model classes for the Incubed client module domain.
- in3.transport: HTTP Transport function and error handling.
- in3.wallet: WiP - Wallet API.
- in3.exception: Custom exceptions.
- in3.eth: Ethereum module.
- in3.eth.api: Ethereum API.
- in3.eth.account: Ethereum accounts.
- in3.eth.contract: Ethereum smart-contracts API.
- in3.eth.model: MVC Model classes for the Ethereum client module domain. Manages serializaation.
- in3.eth.factory: Ethereum Object Factory. Manages deserialization.
- in3.libin3: Module for the libin3 runtime. Libin3 is written in C and can be found here.
- in3.libin3.shared: Native shared libraries for multiple operating systems and platforms.
- in3.libin3.enum: Enumerations mapping C definitions to python.
- in3.libin3.lib_loader: Bindings using Ctypes.
- in3.libin3.runtime: Runtime object, bridging the remote procedure calls to the libin3 instances.
Examples¶
connect_to_ethereum¶
source : in3-c/python/examples/connect_to_ethereum.py
"""
Connects to Ethereum and fetches attested information from each chain.
"""
import in3
print('\nEthereum Main Network')
client = in3.Client()
latest_block = client.eth.block_number()
gas_price = client.eth.gas_price()
print('Latest BN: {}\nGas Price: {} Wei'.format(latest_block, gas_price))
print('\nEthereum Kovan Test Network')
client = in3.Client('kovan')
latest_block = client.eth.block_number()
gas_price = client.eth.gas_price()
print('Latest BN: {}\nGas Price: {} Wei'.format(latest_block, gas_price))
print('\nEthereum Goerli Test Network')
client = in3.Client('goerli')
latest_block = client.eth.block_number()
gas_price = client.eth.gas_price()
print('Latest BN: {}\nGas Price: {} Wei'.format(latest_block, gas_price))
# Produces
"""
Ethereum Main Network
Latest BN: 9801135
Gas Price: 2000000000 Wei
Ethereum Kovan Test Network
Latest BN: 17713464
Gas Price: 6000000000 Wei
Ethereum Goerli Test Network
Latest BN: 2460853
Gas Price: 4610612736 Wei
"""
incubed_network¶
source : in3-c/python/examples/incubed_network.py
"""
Shows Incubed Network Nodes Stats
"""
import in3
print('\nEthereum Goerli Test Network')
client = in3.Client('goerli')
node_list = client.refresh_node_list()
print('\nIncubed Registry:')
print('\ttotal servers:', node_list.totalServers)
print('\tlast updated in block:', node_list.lastBlockNumber)
print('\tregistry ID:', node_list.registryId)
print('\tcontract address:', node_list.contract)
print('\nNodes Registered:\n')
for node in node_list.nodes:
print('\turl:', node.url)
print('\tdeposit:', node.deposit)
print('\tweight:', node.weight)
print('\tregistered in block:', node.registerTime)
print('\n')
# Produces
"""
Ethereum Goerli Test Network
Incubed Registry:
total servers: 7
last updated in block: 2320627
registry ID: 0x67c02e5e272f9d6b4a33716614061dd298283f86351079ef903bf0d4410a44ea
contract address: 0x5f51e413581dd76759e9eed51e63d14c8d1379c8
Nodes Registered:
url: https://in3-v2.slock.it/goerli/nd-1
deposit: 10000000000000000
weight: 2000
registered in block: 1576227711
url: https://in3-v2.slock.it/goerli/nd-2
deposit: 10000000000000000
weight: 2000
registered in block: 1576227741
url: https://in3-v2.slock.it/goerli/nd-3
deposit: 10000000000000000
weight: 2000
registered in block: 1576227801
url: https://in3-v2.slock.it/goerli/nd-4
deposit: 10000000000000000
weight: 2000
registered in block: 1576227831
url: https://in3-v2.slock.it/goerli/nd-5
deposit: 10000000000000000
weight: 2000
registered in block: 1576227876
url: https://tincubeth.komputing.org/
deposit: 10000000000000000
weight: 1
registered in block: 1578947320
url: https://h5l45fkzz7oc3gmb.onion/
deposit: 10000000000000000
weight: 1
registered in block: 1578954071
"""
resolve_eth_names¶
source : in3-c/python/examples/resolve_eth_names.py
"""
Resolves ENS domains to Ethereum addresses
ENS is a smart-contract system that registers and resolves `.eth` domains.
"""
import in3
def _print():
print('\nAddress for {} @ {}: {}'.format(domain, chain, address))
print('Owner for {} @ {}: {}'.format(domain, chain, owner))
# Find ENS for the desired chain or the address of your own ENS resolver. https://docs.ens.domains/ens-deployments
domain = 'depraz.eth'
print('\nEthereum Name Service')
# Instantiate In3 Client for Goerli
chain = 'goerli'
client = in3.Client(chain)
address = client.ens_address(domain)
# Instantiate In3 Client for Mainnet
chain = 'mainnet'
client = in3.Client(chain)
address = client.ens_address(domain)
owner = client.ens_owner(domain)
_print()
# Instantiate In3 Client for Kovan
chain = 'kovan'
client = in3.Client(chain)
try:
address = client.ens_address(domain)
owner = client.ens_owner(domain)
_print()
except in3.ClientException:
print('\nENS is not available on Kovan.')
# Produces
"""
Ethereum Name Service
Address for depraz.eth @ mainnet: 0x0b56ae81586d2728ceaf7c00a6020c5d63f02308
Owner for depraz.eth @ mainnet: 0x6fa33809667a99a805b610c49ee2042863b1bb83
ENS is not available on Kovan.
"""
send_transaction¶
source : in3-c/python/examples/send_transaction.py
"""
Sends Ethereum transactions using Incubed.
Incubed send Transaction does all necessary automation to make sending a transaction a breeze.
Works with included `data` field for smart-contract calls.
"""
import json
import in3
import time
# On Metamask, be sure to be connected to the correct chain, click on the `...` icon on the right corner of
# your Account name, select `Account Details`. There, click `Export Private Key`, copy the value to use as secret.
sender_secret = hex(0x9852782D2AD26C64161665586D23391ECED2D2ED7432A1D26FD326D28EA0171F)
receiver = hex(0x6FA33809667A99A805b610C49EE2042863b1bb83)
# 1000000000000000000 == 1 ETH
value_in_wei = 1463926659
chain = 'goerli'
client = in3.Client(chain)
# A transaction is only final if a certain number of blocks are mined on top of it.
# This number varies with the chain's consensus algorithm. Time can be calculated over using:
# wait_time = blocks_for_consensus * avg_block_time_in_secs
confirmation_wait_time_in_seconds = 25
etherscan_link_mask = 'https://{}{}etherscan.io/tx/{}'
print('Ethereum Transaction using Incubed\n')
try:
sender = client.eth.account.recover(sender_secret)
tx = in3.eth.NewTransaction(to=receiver, value=value_in_wei)
print('Sending {} Wei from {} to {}.\n'.format(tx.value, sender.address, tx.to))
tx_hash = client.eth.account.send_transaction(sender, tx)
print('Transaction accepted with hash {}.'.format(tx_hash))
add_dot_if_chain = '.' if chain else ''
print(etherscan_link_mask.format(chain, add_dot_if_chain, tx_hash))
print('\nWaiting {} seconds for confirmation.\n'.format(confirmation_wait_time_in_seconds))
time.sleep(confirmation_wait_time_in_seconds)
receipt: in3.eth.TransactionReceipt = client.eth.transaction_receipt(tx_hash)
print('Transaction was sent successfully!')
print(json.dumps(receipt.to_dict(), indent=4, sort_keys=True))
print('\nMined on block {} used {} GWei.'.format(receipt.blockNumber, receipt.gasUsed))
except in3.PrivateKeyNotFoundException as e:
print(str(e))
except in3.ClientException as e:
print('Client returned error: ', str(e))
print('Please try again.')
# Response
"""
Ethereum Transaction using Incubed
Sending 1463926659 Wei from 0x0b56Ae81586D2728Ceaf7C00A6020C5D63f02308 to 0x6fa33809667a99a805b610c49ee2042863b1bb83.
Transaction accepted with hash 0xbeebda39e31e42d2a26476830fdcdc2d21e9df090af203e7601d76a43074d8d3.
https://goerli.etherscan.io/tx/0xbeebda39e31e42d2a26476830fdcdc2d21e9df090af203e7601d76a43074d8d3
Waiting 25 seconds for confirmation.
Transaction was sent successfully!
{
"From": "0x0b56Ae81586D2728Ceaf7C00A6020C5D63f02308",
"blockHash": "0x9693714c9d7dbd31f36c04fbd262532e68301701b1da1a4ee8fc04e0386d868b",
"blockNumber": 2615346,
"cumulativeGasUsed": 21000,
"gasUsed": 21000,
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"status": 1,
"to": "0x6FA33809667A99A805b610C49EE2042863b1bb83",
"transactionHash": "0xbeebda39e31e42d2a26476830fdcdc2d21e9df090af203e7601d76a43074d8d3",
"transactionIndex": 0
}
Mined on block 2615346 used 21000 GWei.
"""
smart_contract¶
source : in3-c/python/examples/smart_contract.py
"""
Manually calling ENS smart-contract
![UML Sequence Diagram of how Ethereum Name Service ENS resolves a name.](https://lh5.googleusercontent.com/_OPPzaxTxKggx9HuxloeWtK8ggEfIIBKRCEA6BKMwZdzAfUpIY6cz7NK5CFmiuw7TwknbhFNVRCJsswHLqkxUEJ5KdRzpeNbyg8_H9d2RZdG28kgipT64JyPZUP--bAizozaDcxCq34)
"""
import in3
client = in3.Client('goerli')
domain_name = client.ens_namehash('depraz.eth')
ens_registry_addr = '0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e'
ens_resolver_abi = 'resolver(bytes32):address'
# Find resolver contract for ens name
resolver_tx = {
"to": ens_registry_addr,
"data": client.eth.contract.encode(ens_resolver_abi, domain_name)
}
tx = in3.eth.NewTransaction(**resolver_tx)
encoded_resolver_addr = client.eth.contract.call(tx)
resolver_address = client.eth.contract.decode(ens_resolver_abi, encoded_resolver_addr)
# Resolve name
ens_addr_abi = 'addr(bytes32):address'
name_tx = {
"to": resolver_address,
"data": client.eth.contract.encode(ens_addr_abi, domain_name)
}
encoded_domain_address = client.eth.contract.call(in3.eth.NewTransaction(**name_tx))
domain_address = client.eth.contract.decode(ens_addr_abi, encoded_domain_address)
print('END domain:\n{}\nResolved by:\n{}\nTo address:\n{}'.format(domain_name, resolver_address, domain_address))
# Produces
"""
END domain:
0x4a17491df266270a8801cee362535e520a5d95896a719e4a7d869fb22a93162e
Resolved by:
0x4b1488b7a6b320d2d721406204abc3eeaa9ad329
To address:
0x0b56ae81586d2728ceaf7c00a6020c5d63f02308
"""
Running the examples¶
To run an example, you need to install in3 first:
pip install in3
This will install the library system-wide. Please consider using virtualenv
or pipenv
for a project-wide install.
Then copy one of the examples and paste into a file, i.e. example.py
:
MacOS
pbpaste > example.py
Execute the example with python:
python example.py
Incubed Modules¶
Client¶
Client(self,
chain: str = 'mainnet',
in3_config: ClientConfig = None,
transport=<CFunctionType object at 0x11093b120>)
Incubed network client. Connect to the blockchain via a list of bootnodes, then gets the latest list of nodes in the network and ask a certain number of the to sign the block header of given list, putting their deposit at stake. Once with the latest list at hand, the client can request any other on-chain information using the same scheme.
Arguments:
in3_config
ClientConfig or str - (optional) Configuration for the client. If not provided, default is loaded.
get_node_list¶
Client.get_node_list()
Gets the list of Incubed nodes registered in the selected chain registry contract.
Returns:
node_list
NodeList - List of registered in3 nodes and metadata.
raw_configure¶
Client.raw_configure(cfg_dict: dict)
Send RPC to change client configuration. Don’t use outside the constructor, might cause instability.
ens_resolve¶
Client.ens_resolve(domain_name: str,
domain_type: str,
registry: str = None)
Resolves ENS domain name to Ethereum address.
Arguments:
domain_name
- ENS supported domain. mydomain.ens, mydomain.xyz, etcdomain_type
- ‘hash’|’addr’|’owner’|’resolver’registry
- ENS registry contract address. i.e. 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e
Returns:
address
str - Ethereum address corresponding to domain name.
ClientConfig¶
ClientConfig(self,
chain_finality_threshold: int = None,
account_secret: str = None,
latest_block_stall: int = None,
node_signatures: int = None,
node_signature_consensus: int = None,
node_min_deposit: int = None,
node_list_auto_update: bool = None,
node_limit: int = None,
request_timeout: int = None,
request_retries: int = None,
response_proof_level: str = None,
response_includes_code: bool = None,
response_keep_proof: bool = None,
cached_blocks: int = None,
cached_code_bytes: int = None,
in3_registry: dict = None)
Determines the behavior of the in3 client, which chain to connect to and how to manage information security policies.
Considering integrity is guaranteed and confidentiality is not available on public blockchains, these settings will provide a balance between availability, and financial stake in case of repudiation.
The newer the block is, higher are the chances it gets repudiated by a fork in the chain. In3 nodes will decide individually to sign on repudiable information, reducing the availability. If the application needs the very latest block, consider using a calculated value in node_signature_consensus
and set node_signatures
to zero. This setting is as secure as a light-client.
The older the block gets, the highest is its availability because of the close-to-zero repudiation risk, but blocks older than circa one year are stored in Archive Nodes, expensive computers, so, despite of the low risk, there are not many nodes available with such information, and they must search for the requested block in its database, lowering the availability as well. If the application needs access to old blocks, consider setting request_timeout
and request_retries
to accomodate the time the archive nodes take to fetch the inforamtion.
The verification policy enforces an extra step of security, adding a financial stake in case of repudiation or false/broken proof. For high security application, consider setting a calculated value in node_min_deposit
and request as much signatures as necessary in node_signatures
. Setting chain_finality_threshold
high will guarantee non-repudiability.
All args are Optional. Defaults connect to Ethereum main network with regular security levels.
Arguments:
chain_finality_threshold
int - Behavior depends on the chain consensus algorithm: POA - percent of signers needed in order reach finality (% of the validators) i.e.: 60 %. POW - mined blocks on top of the requested, i.e. 8 blocks. Defaults are defined in enum.Chain.latest_block_stall
int - Distance considered safe, consensus wise, from the very latest block. Higher values exponentially increases state finality, and therefore data security, as well guaranteeded responses from in3 nodes. example: 10 - will ask for the state from (latestBlock-10).account_secret
str - Account SK to sign all in3 requests. (Experimental useset_account_sk
) example: 0x387a8233c96e1fc0ad5e284353276177af2186e7afa85296f106336e376669f7node_signatures
int - Node signatures attesting the response to your request. Will send a separate request for each. example: 3 nodes will have to sign the response.node_signature_consensus
int - Useful when signatureCount <= 1. The client will check for consensus in responses. example: 10 - will ask for 10 different nodes and compare results looking for a consensus in the responses.node_min_deposit
int - Only nodes owning at least this amount will be chosen to sign responses to your requests. i.e. 1000000000000000000 Weinode_list_auto_update
bool - If true the nodelist will be automatically updated. False may compromise data security.node_limit
int - Limit nodes stored in the client. example: 150 nodesrequest_timeout
int - Milliseconds before a request times out. example: 100000 msrequest_retries
int - Maximum times the client will retry to contact a certain node. example: 10 retriesresponse_proof_level
str - ‘none’|’standard’|’full’ Full gets the whole block Patricia-Merkle-Tree, Standard only verifies the specific tree branch concerning the request, None only verifies the root hashes, like a light-client does.response_includes_code
bool - If true, every request with the address field will include the data, if existent, that is stored in that wallet/smart-contract. If false, only the code digest is included.response_keep_proof
bool - If true, proof data will be kept in every rpc response. False will remove this data after using it to verify the responses. Useful for debugging and manually verifying the proofs.cached_blocks
int - Maximum blocks kept in memory. example: 100 last requested blockscached_code_bytes
int - Maximum number of bytes used to cache EVM code in memory. example: 100000 bytesin3_registry
dict - In3 Registry Smart Contract configuration data
In3Node¶
In3Node(self, url: str, address: Account, index: int, deposit: int,
props: int, timeout: int, registerTime: int, weight: int)
Registered remote verifier that attest, by signing the block hash, that the requested block and transaction were indeed mined are in the correct chain fork.
Arguments:
url
str - Endpoint to post to example: https://in3.slock.itindex
int - Index within the contract example: 13address
in3.Account - Address of the node, which is the public address it iis signing with. example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679deposit
int - Deposit of the node in wei example: 12350000props
int - Properties of the node. example: 3timeout
int - Time (in seconds) until an owner is able to receive his deposit back after he unregisters himself example: 3600registerTime
int - When the node was registered in (unixtime?)weight
int - Score based on qualitative metadata to base which nodes to ask signatures from.
NodeList¶
NodeList(self, nodes: [<class 'in3.model.In3Node'>], contract: Account,
registryId: str, lastBlockNumber: int, totalServers: int)
List of incubed nodes and its metadata, in3 registry contract from which the list was taken, network/registry id, and last block number in the selected chain.
Arguments:
nodes
[In3Node] - list of incubed nodescontract
Account - incubed registry contract from which the list was takenregistryId
str - uuid of this incubed network. one chain could contain more than one incubed networks.lastBlockNumber
int - last block signed by the networktotalServers
int - Total servers number (for integrity?)
EthAccountApi¶
EthAccountApi(self, runtime: In3Runtime, factory: EthObjectFactory)
Manages accounts and smart-contracts
new_account¶
EthAccountApi.new_account(qrng=False)
Creates a new Ethereum account and saves it in the wallet.
Arguments:
qrng
bool - True uses a Quantum Random Number Generator api for generating the private key.
Returns:
account
Account - Newly created Ethereum account.
recover_account¶
EthAccountApi.recover_account(secret: str)
Recovers an account from a secret.
Arguments:
secret
str - Account private key in hexadecimal string
Returns:
account
Account - Recovered Ethereum account.
parse_mnemonics¶
EthAccountApi.parse_mnemonics(mnemonics: str)
Recovers an account secret from mnemonics phrase
Arguments:
mnemonics
str - BIP39 mnemonics phrase.
Returns:
secret
str - Account secret. Userecover_account
to create a new account with this secret.
sign¶
EthAccountApi.sign(private_key: str, message: str)
Use ECDSA to sign a message.
Arguments:
private_key
str - Must be either an address(20 byte) or an raw private key (32 byte)”}}’message
str - Data to be hashed and signed. Dont input hashed data unless you know what you are doing.
Returns:
signed_message
str - ECDSA calculated r, s, and parity v, concatenated. v = 27 + (r % 2)
get_balance¶
EthAccountApi.get_balance(address: str, at_block: int = 'latest')
Returns the balance of the account of given address.
Arguments:
address
str - address to check for balanceat_block
int or str - block number IN3BlockNumber or EnumBlockStatus
Returns:
balance
int - integer of the current balance in wei.
send_transaction¶
EthAccountApi.send_transaction(sender: Account,
transaction: NewTransaction)
Signs and sends the assigned transaction. Requires account.secret
value set.
Transactions change the state of an account, just the balance, or additionally, the storage and the code.
Every transaction has a cost, gas, paid in Wei. The transaction gas is calculated over estimated gas times the
gas cost, plus an additional miner fee, if the sender wants to be sure that the transaction will be mined in the
latest block.
Arguments:
sender
Account - Sender Ethereum account. Senders generally pay the gas costs, so they must have enough balance to pay gas + amount sent, if any.transaction
NewTransaction - All information needed to perform a transaction. Minimum is to and value. Client will add the other required fields, gas and chaindId.
Returns:
tx_hash
hex - Transaction hash, used to get the receipt and check if the transaction was mined.
send_raw_transaction¶
EthAccountApi.send_raw_transaction(signed_transaction: str)
Sends a signed and encoded transaction.
Arguments:
signed_transaction
- Signed keccak hash of the serialized transaction Client will add the other required fields, gas and chaindId.
Returns:
tx_hash
hex - Transaction hash, used to get the receipt and check if the transaction was mined.
get_transaction_receipt¶
EthAccountApi.get_transaction_receipt(tx_hash: str)
After a transaction is received the by the client, it returns the transaction hash. With it, it is possible to gather the receipt, once a miner has mined and it is part of an acknowledged block. Because how it is possible, in distributed systems, that data is asymmetric in different parts of the system, the transaction is only “final” once a certain number of blocks was mined after it, and still it can be possible that the transaction is discarded after some time. But, in general terms, it is accepted that after 6 to 8 blocks from latest, that it is very likely that the transaction will stay in the chain.
Arguments:
tx_hash
- Transaction hash.
Returns:
tx_receipt
- The mined Transaction data including event logs.
estimate_gas¶
EthAccountApi.estimate_gas(transaction: NewTransaction)
Gas estimation for transaction. Used to fill transaction.gas field. Check RawTransaction docs for more on gas.
Arguments:
transaction
- Unsent transaction to be estimated. Important that the fields data or/and value are filled in.
Returns:
gas
int - Calculated gas in Wei.
get_transaction_count¶
EthAccountApi.get_transaction_count(address: str,
at_block: int = 'latest')
Number of transactions mined from this address. Used to set transaction nonce. Nonce is a value that will make a transaction fail in case it is different from (transaction count + 1). It exists to mitigate replay attacks.
Arguments:
address
str - Ethereum account addressat_block
int - Block number
Returns:
tx_count
int - Number of transactions mined from this address.
checksum_address¶
EthAccountApi.checksum_address(address: str, add_chain_id: bool = True)
Will convert an upper or lowercase Ethereum address to a checksum address, that uses case to encode values. See EIP55.
Arguments:
address
- Ethereum address string or object.add_chain_id
bool - Will append the chain id of the address, for multi-chain support, canonical for Eth.
Returns:
checksum_address
- EIP-55 compliant, mixed-case address object.
EthContractApi¶
EthContractApi(self, runtime: In3Runtime, factory: EthObjectFactory)
Manages smart-contract data and transactions
eth_call¶
EthContractApi.eth_call(transaction: NewTransaction,
block_number: int = 'latest')
Calls a smart-contract method. Will be executed locally by Incubed’s EVM or signed and sent over to save the state changes. Check https://ethereum.stackexchange.com/questions/3514/how-to-call-a-contract-method-using-the-eth-call-json-rpc-api for more.
Arguments:
transaction (NewTransaction):
block_number
int or str - Desired block number integer or ‘latest’, ‘earliest’, ‘pending’.
Returns:
method_returned_value
- A hexadecimal. For decoding use in3.abi_decode.
get_storage_at¶
EthContractApi.get_storage_at(address: str,
position: int = 0,
at_block: int = 'latest')
Stored value in designed position at a given address. Storage can be used to store a smart contract state, constructor or just any data. Each contract consists of a EVM bytecode handling the execution and a storage to save the state of the contract. The storage is essentially a key/value store. Use get_code to get the smart-contract code.
Arguments:
address
str - Ethereum account addressposition
int - Position index, 0x0 up to 0x64at_block
int or str - Block number
Returns:
storage_at
str - Stored value in designed position. Use decode(‘hex’) to see ascii format of the hex data.
get_code¶
EthContractApi.get_code(address: str, at_block: int = 'latest')
Smart-Contract bytecode in hexadecimal. If the account is a simple wallet the function will return ‘0x’.
Arguments:
address
str - Ethereum account addressat_block
int or str - Block number
Returns:
bytecode
str - Smart-Contract bytecode in hexadecimal.
abi_encode¶
EthContractApi.abi_encode(fn_signature: str, *fn_args)
Smart-contract ABI encoder. Used to serialize a rpc to the EVM. Based on the Solidity specification. Note: Parameters refers to the list of variables in a method declaration. Arguments are the actual values that are passed in when the method is invoked. When you invoke a method, the arguments used must match the declaration’s parameters in type and order.
Arguments:
fn_signature
str - Function name, with parameters. i.e.getBalance(uint256):uint256
, can contain the return types but will be ignored.fn_args
tuple - Function parameters, in the same order as in passed on to method_name.
Returns:
encoded_fn_call
str - i.e. “0xf8b2cb4f0000000000000000000000001234567890123456789012345678901234567890”
abi_decode¶
EthContractApi.abi_decode(fn_signature: str, encoded_value: str)
Smart-contract ABI decoder. Used to parse rpc responses from the EVM. Based on the Solidity specification.
Arguments:
fn_signature
- Function signature. e.g.(address,string,uint256)
orgetBalance(address):uint256
. In case of the latter, the function signature will be ignored and only the return types will be parsed.encoded_value
- Abi encoded values. Usually the string returned from a rpc to the EVM.
Returns:
decoded_return_values
tuple - “0x1234567890123456789012345678901234567890”, “0x05”
EthereumApi¶
EthereumApi(self, runtime: In3Runtime)
Module based on Ethereum’s api and web3.js
keccak256¶
EthereumApi.keccak256(message: str)
Keccak-256 digest of the given data. Compatible with Ethereum but not with SHA3-256.
Arguments:
message
str - Message to be hashed.
Returns:
digest
str - The message digest.
gas_price¶
EthereumApi.gas_price()
The current gas price in Wei (1 ETH equals 1000000000000000000 Wei ).
Returns:
price
int - minimum gas value for the transaction to be mined
block_number¶
EthereumApi.block_number()
Returns the number of the most recent block the in3 network can collect signatures to verify. Can be changed by Client.Config.replaceLatestBlock. If you need the very latest block, change Client.Config.signatureCount to zero.
Returns:
block_number (int) : Number of the most recent block
get_block_by_hash¶
EthereumApi.get_block_by_hash(block_hash: str,
get_full_block: bool = False)
Blocks can be identified by root hash of the block merkle tree (this), or sequential number in which it was mined (get_block_by_number).
Arguments:
block_hash
str - Desired block hashget_full_block
bool - If true, returns the full transaction objects, otherwise only its hashes.
Returns:
block
Block - Desired block, if exists.
get_block_by_number¶
EthereumApi.get_block_by_number(block_number: [<class 'int'>],
get_full_block: bool = False)
Blocks can be identified by sequential number in which it was mined, or root hash of the block merkle tree (this) (get_block_by_hash).
Arguments:
block_number
int or str - Desired block number integer or ‘latest’, ‘earliest’, ‘pending’.get_full_block
bool - If true, returns the full transaction objects, otherwise only its hashes.
Returns:
block
Block - Desired block, if exists.
get_transaction_by_hash¶
EthereumApi.get_transaction_by_hash(tx_hash: str)
Transactions can be identified by root hash of the transaction merkle tree (this) or by its position in the block transactions merkle tree. Every transaction hash is unique for the whole chain. Collision could in theory happen, chances are 67148E-63%.
Arguments:
tx_hash
- Transaction hash.
Returns:
transaction
- Desired transaction, if exists.
Ethereum Objects¶
DataTransferObject¶
DataTransferObject()
Maps marshalling objects transferred to, and from a remote facade, in this case, libin3 rpc api. For more on design-patterns see Martin Fowler’s Catalog of Patterns of Enterprise Application Architecture.
Transaction¶
Transaction(self, From: str, to: str, gas: int, gasPrice: int, hash: str,
nonce: int, transactionIndex: int, blockHash: str,
value: int, input: str, publicKey: str, standardV: int,
raw: str, creates: str, chainId: int, r: int, s: int,
v: int)
Arguments:
From
hex str - Address of the sender account.to
hex str - Address of the receiver account. Left undefined for a contract creation transaction.gas
int - Gas for the transaction miners and execution in wei. Will get multiplied bygasPrice
. Use in3.eth.account.estimate_gas to get a calculated value. Set too low and the transaction will run out of gas.value
int - Value transferred in wei. The endowment for a contract creation transaction.data
hex str - Either a ABI byte string containing the data of the function call on a contract, or in the case of a contract-creation transaction the initialisation code.gasPrice
int - Price of gas in wei, defaults to in3.eth.gasPrice. Also know astx fee price
. Set your gas price too low and your transaction may get stuck. Set too high on your own loss. gasLimit (int); Maximum gas paid for this transaction. Set by the client using this rationale if left empty: gasLimit = G(transaction) + G(txdatanonzero) × dataByteLength. Minimum is 21000.nonce
int - Number of transactions mined from this address. Nonce is a value that will make a transaction fail in case it is different from (transaction count + 1). It exists to mitigate replay attacks. This allows to overwrite your own pending transactions by sending a new one with the same nonce. Use in3.eth.account.get_transaction_count to get the latest value.hash
hex str - Keccak of the transaction bytes, not part of the transaction. Also known as receipt, because this field is filled after the transaction is sent, by eth_sendTransactionblockHash
hex str - Block hash that this transaction was mined in. null when its pending.blockHash
int - Block number that this transaction was mined in. null when its pending.transactionIndex
int - Integer of the transactions index position in the block. null when its pending.signature
hex str - ECDSA of transaction.data, calculated r, s and v concatenated. V is parity set by v = 27 + (r % 2).
NewTransaction¶
NewTransaction(self,
From: str = None,
to: str = None,
nonce: int = None,
value: int = None,
data: str = None,
gasPrice: int = None,
gasLimit: int = None,
hash: str = None,
signature: str = None)
Unsent transaction. Use to send a new transaction.
Arguments:
From
hex str - Address of the sender account.to
hex str - Address of the receiver account. Left undefined for a contract creation transaction.value
int - (optional) Value transferred in wei. The endowment for a contract creation transaction.data
hex str - (optional) Either a ABI byte string containing the data of the function call on a contract, or in the case of a contract-creation transaction the initialisation code.gasPrice
int - (optional) Price of gas in wei, defaults to in3.eth.gasPrice. Also know astx fee price
. Set your gas price too low and your transaction may get stuck. Set too high on your own loss. gasLimit (int); (optional) Maximum gas paid for this transaction. Set by the client using this rationale if left empty: gasLimit = G(transaction) + G(txdatanonzero) × dataByteLength. Minimum is 21000.nonce
int - (optional) Number of transactions mined from this address. Nonce is a value that will make a transaction fail in case it is different from (transaction count + 1). It exists to mitigate replay attacks. This allows to overwrite your own pending transactions by sending a new one with the same nonce. Use in3.eth.account.get_transaction_count to get the latest value.hash
hex str - (optional) Keccak of the transaction bytes, not part of the transaction. Also known as receipt, because this field is filled after the transaction is sent.signature
hex str - (optional) ECDSA of transaction, r, s and v concatenated. V is parity set by v = 27 + (r % 2).
Filter¶
Filter(self, fromBlock: int, toBlock: int, address: str, topics: list,
blockhash: str)
Filters are event catchers running on the Ethereum Client. Incubed has a client-side implementation. An event will be stored in case it is within to and from blocks, or in the block of blockhash, contains a transaction to the designed address, and has a word listed on topics.
Log¶
Log(self, address: <built-in function hex>,
blockHash: <built-in function hex>, blockNumber: int,
data: <built-in function hex>, logIndex: int, removed: bool,
topics: [<built-in function hex>],
transactionHash: <built-in function hex>, transactionIndex: int,
transactionLogIndex: int, Type: str)
Transaction Log for events and data returned from smart-contract method calls.
TransactionReceipt¶
TransactionReceipt(self,
blockHash: <built-in function hex>,
blockNumber: int,
cumulativeGasUsed: int,
From: str,
gasUsed: int,
logsBloom: <built-in function hex>,
status: int,
transactionHash: <built-in function hex>,
transactionIndex: int,
logs: [<class 'in3.eth.model.Log'>] = None,
to: str = None,
contractAddress: str = None)
Receipt from a mined transaction.
Arguments:
blockHash: blockNumber:
cumulativeGasUsed
- total amount of gas used by block From:gasUsed
- amount of gas used by this specific transaction logs: logsBloom:status
- 1 if transaction succeeded, 0 otherwise. transactionHash: transactionIndex:to
- Account to which this transaction was sent. If the transaction was a contract creation this value is set to None.contractAddress
- Contract Account address created, f the transaction was a contract creation, or None otherwise.
Account¶
Account(self,
address: str,
chain_id: int,
secret: int = None,
domain: str = None)
An Ethereum account.
Arguments:
address
- Account address. Derived from public key.chain_id
- ID of the chain the account is used in.secret
- Account private key. A 256 bit number.domain
- ENS Domain name. ie. niceguy.eth
Library Runtime¶
Shared Library Runtime module
Loads libin3
according to host hardware architecture and OS.
Maps symbols, methods and types from the library.
Encapsulates low-level rpc calls into a comprehensive runtime.
In3Runtime¶
In3Runtime(self, chain_id: int,
transport: <function CFUNCTYPE at 0x11028e7a0>)
Instantiate libin3 and frees it when garbage collected.
Arguments:
chain_id
int - Chain-id based on EIP-155. If None provided, will connect to the Ethereum network. i.e: 0x1 for mainNet
Library Loader¶
Load libin3 shared library for the current system, map function ABI, sets in3 network transport functions.
Example of RPC to In3-Core library, In3 Network and back.
+----------------+ +----------+ +------------+ +------------------+
| | in3.client.eth.block_number() | | in3_client_rpc | | In3 Network Request | |e
| python +------------------------------>+ python +-----------------------> libin3 +------------------------> python |
| application | | in3 | | in3-core | | http_transport |
| <-------------------------------+ <-----------------------+ <------------------------+ |
+----------------+ primitive or Object +----------+ ctype object +------------+ in3_req_add_response +------------------+
libin3_new¶
libin3_new(chain_id: int,
transport: <function CFUNCTYPE at 0x11028e7a0>,
debug=False)
Instantiate new In3 Client instance.
Arguments:
chain_id
int - Chain id as integertransport
- Transport function for the in3 network requestsdebug
- Turn on debugger logging
Returns:
instance
int - Memory address of the client instance, return value from libin3_new
libin3_free¶
libin3_free(instance: int)
Free In3 Client objects from memory.
Arguments:
instance
int - Memory address of the client instance, return value from libin3_new
libin3_exec¶
libin3_exec(instance: int, rpc: bytes)
Make Remote Procedure Call mapped methods in the client.
Arguments:
instance
int - Memory address of the client instance, return value from libin3_newrpc
bytes - Serialized function call, a json string.
Returns:
returned_value
object - The returned function value(s)
libin3_call¶
libin3_call(instance: int, fn_name: bytes, fn_args: bytes)
Make Remote Procedure Call to an arbitrary method of a libin3 instance
Arguments:
instance
int - Memory address of the client instance, return value from libin3_newfn_name
bytes - Name of function that will be called in the client rpc.fn_args
- (bytes) Serialized list of arguments, matching the parameters order of this function. i.e. [‘0x123’]
Returns:
result
int - Function execution status.
libin3_set_pk¶
libin3_set_pk(instance: int, private_key: bytes)
Register the signer module in the In3 Client instance, with selected private key loaded in memory.
Arguments:
instance
int - Memory address of the client instance, return value from libin3_newprivate_key
- 256 bit number.