Welcome to Incubed’s documentation!¶

t

returns: btc_transaction_t *

btc_d_to_blockheader¶

btc_blockheader_t* btc_d_to_blockheader(d_token_t *t);

Deserializes a btc_transaction_t type.

You must free the result with free() after use!

arguments:

t

returns: btc_blockheader_t *

btc_d_to_block_txids¶

btc_block_txids_t* btc_d_to_block_txids(d_token_t *t);

Deserializes a btc_blockheader_t type.

You must free the result with free() after use!

arguments:

t

returns: btc_block_txids_t *

btc_d_to_block_txdata¶

btc_block_txdata_t* btc_d_to_block_txdata(d_token_t *t);

Deserializes a btc_block_txids_t type.

You must free the result with free() after use!

arguments:

t

returns: btc_block_txdata_t *

eth_api.h¶

Ethereum API.

This header-file defines easy to use function, which are preparing the JSON-RPC-Request, which is then executed and verified by the incubed-client.

File: c/src/api/eth1/eth_api.h

BLKNUM (blk)¶

Initializer macros for eth_blknum_t.

#define BLKNUM (blk) ((eth_blknum_t){.u64 = blk, .is_u64 = true})

BLKNUM_LATEST ()¶

#define BLKNUM_LATEST () ((eth_blknum_t){.def = BLK_LATEST, .is_u64 = false})

BLKNUM_EARLIEST ()¶

#define BLKNUM_EARLIEST () ((eth_blknum_t){.def = BLK_EARLIEST, .is_u64 = false})

BLKNUM_PENDING ()¶

The current error or null if all is ok.

#define BLKNUM_PENDING () ((eth_blknum_t){.def = BLK_PENDING, .is_u64 = false})

eth_last_error ()¶

#define eth_last_error () api_last_error()

eth_blknum_def_t¶

Abstract type for holding a block number.

The enum type contains the following values:

BLK_LATEST	0
BLK_EARLIEST	1
BLK_PENDING	2

eth_tx_t¶

A transaction.

The stuct contains following fields:

bytes32_t	hash	the blockhash
bytes32_t	block_hash	hash of ther containnig block
`uint64_t`	block_number	number of the containing block
address_t	from	sender of the tx
`uint64_t`	gas	gas send along
`uint64_t`	gas_price	gas price used
bytes_t	data	data send along with the transaction
`uint64_t`	nonce	nonce of the transaction
address_t	to	receiver of the address 0x0000. . -Address is used for contract creation.
uint256_t	value	the value in wei send
`int`	transaction_index	the transaction index
`uint8_t`	signature	signature of the transaction

eth_block_t¶

An Ethereum Block.

The stuct contains following fields:

`uint64_t`	number	the blockNumber
bytes32_t	hash	the blockhash
`uint64_t`	gasUsed	gas used by all the transactions
`uint64_t`	gasLimit	gasLimit
address_t	author	the author of the block.
uint256_t	difficulty	the difficulty of the block.
bytes_t	extra_data	the extra_data of the block.
`uint8_t`	logsBloom	the logsBloom-data
bytes32_t	parent_hash	the hash of the parent-block
bytes32_t	sha3_uncles	root hash of the uncle-trie
bytes32_t	state_root	root hash of the state-trie
bytes32_t	receipts_root	root of the receipts trie
bytes32_t	transaction_root	root of the transaction trie
`int`	tx_count	number of transactions in the block
eth_tx_t *	tx_data	array of transaction data or NULL if not requested
bytes32_t *	tx_hashes	array of transaction hashes or NULL if not requested
`uint64_t`	timestamp	the unix timestamp of the block
bytes_t *	seal_fields	sealed fields
`int`	seal_fields_count	number of seal fields

eth_log_t¶

A linked list of Ethereum Logs

The stuct contains following fields:

`bool`	removed	true when the log was removed, due to a chain reorganization. false if its a valid log
`size_t`	log_index	log index position in the block
`size_t`	transaction_index	transactions index position log was created from
bytes32_t	transaction_hash	hash of the transactions this log was created from
bytes32_t	block_hash	hash of the block where this log was in
`uint64_t`	block_number	the block number where this log was in
address_t	address	address from which this log originated
bytes_t	data	non-indexed arguments of the log
bytes32_t *	topics	array of 0 to 4 32 Bytes DATA of indexed log arguments
`size_t`	topic_count	counter for topics
eth_logstruct , *	next	pointer to next log in list or NULL

eth_tx_receipt_t¶

A transaction receipt.

The stuct contains following fields:

bytes32_t	transaction_hash	the transaction hash
`int`	transaction_index	the transaction index
bytes32_t	block_hash	hash of ther containnig block
`uint64_t`	block_number	number of the containing block
`uint64_t`	cumulative_gas_used	total amount of gas used by block
`uint64_t`	gas_used	amount of gas used by this specific transaction
bytes_t *	contract_address	contract address created (if the transaction was a contract creation) or NULL
`bool`	status	1 if transaction succeeded, 0 otherwise.
eth_log_t *	logs	array of log objects, which this transaction generated

DEFINE_OPTIONAL_T¶

DEFINE_OPTIONAL_T(uint64_t);

uint256_t eth_getStorageAt(in3_t *in3, address_t account, bytes32_t key, eth_blknum_t block);

Returns the storage value of a given address.

arguments:

in3_t *	in3
address_t	account
bytes32_t	key
eth_blknum_t	block

returns: uint256_t

eth_getCode¶

bytes_t eth_getCode(in3_t *in3, address_t account, eth_blknum_t block);

Returns the code of the account of given address.

(Make sure you free the data-point of the result after use.)

arguments:

in3_t *	in3
address_t	account
eth_blknum_t	block

returns: bytes_t

eth_getBalance¶

uint256_t eth_getBalance(in3_t *in3, address_t account, eth_blknum_t block);

Returns the balance of the account of given address.

arguments:

in3_t *	in3
address_t	account
eth_blknum_t	block

returns: uint256_t

eth_blockNumber¶

uint64_t eth_blockNumber(in3_t *in3);

Returns the current price per gas in wei.

arguments:

in3

returns: uint64_t

eth_gasPrice¶

uint64_t eth_gasPrice(in3_t *in3);

Returns the current blockNumber, if bn==0 an error occured and you should check eth_last_error()

arguments:

in3

returns: uint64_t

eth_getBlockByNumber¶

eth_block_t* eth_getBlockByNumber(in3_t *in3, eth_blknum_t number, bool include_tx);

Returns the block for the given number (if number==0, the latest will be returned).

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
eth_blknum_t	number
`bool`	include_tx

returns: eth_block_t *

eth_getBlockByHash¶

eth_block_t* eth_getBlockByHash(in3_t *in3, bytes32_t hash, bool include_tx);

Returns the block for the given hash.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
bytes32_t	hash
`bool`	include_tx

returns: eth_block_t *

eth_getLogs¶

eth_log_t* eth_getLogs(in3_t *in3, char *fopt);

Returns a linked list of logs.

If result is null, check eth_last_error()! otherwise make sure to free the log, its topics and data after using it!

arguments:

in3_t *	in3
`char *`	fopt

returns: eth_log_t *

eth_newFilter¶

in3_ret_t eth_newFilter(in3_t *in3, json_ctx_t *options);

Creates a new event filter with specified options and returns its id (>0) on success or 0 on failure.

arguments:

in3_t *	in3
json_ctx_t *	options

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_newBlockFilter¶

in3_ret_t eth_newBlockFilter(in3_t *in3);

Creates a new block filter with specified options and returns its id (>0) on success or 0 on failure.

arguments:

in3

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_newPendingTransactionFilter¶

in3_ret_t eth_newPendingTransactionFilter(in3_t *in3);

Creates a new pending txn filter with specified options and returns its id on success or 0 on failure.

arguments:

in3

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_uninstallFilter¶

bool eth_uninstallFilter(in3_t *in3, size_t id);

Uninstalls a filter and returns true on success or false on failure.

arguments:

in3_t *	in3
`size_t`	id

returns: bool

eth_getFilterChanges¶

in3_ret_t eth_getFilterChanges(in3_t *in3, size_t id, bytes32_t **block_hashes, eth_log_t **logs);

Sets the logs (for event filter) or blockhashes (for block filter) that match a filter; returns <0 on error, otherwise no.

of block hashes matched (for block filter) or 0 (for log filter)

arguments:

in3_t *	in3
`size_t`	id
bytes32_t **	block_hashes
eth_log_t **	logs

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_getFilterLogs¶

in3_ret_t eth_getFilterLogs(in3_t *in3, size_t id, eth_log_t **logs);

Sets the logs (for event filter) or blockhashes (for block filter) that match a filter; returns <0 on error, otherwise no.

of block hashes matched (for block filter) or 0 (for log filter)

arguments:

in3_t *	in3
`size_t`	id
eth_log_t **	logs

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_chainId¶

uint64_t eth_chainId(in3_t *in3);

Returns the currently configured chain id.

arguments:

in3

returns: uint64_t

eth_getBlockTransactionCountByHash¶

uint64_t eth_getBlockTransactionCountByHash(in3_t *in3, bytes32_t hash);

Returns the number of transactions in a block from a block matching the given block hash.

arguments:

in3_t *	in3
bytes32_t	hash

returns: uint64_t

eth_getBlockTransactionCountByNumber¶

uint64_t eth_getBlockTransactionCountByNumber(in3_t *in3, eth_blknum_t block);

Returns the number of transactions in a block from a block matching the given block number.

arguments:

in3_t *	in3
eth_blknum_t	block

returns: uint64_t

eth_call_fn¶

json_ctx_t* eth_call_fn(in3_t *in3, address_t contract, eth_blknum_t block, char *fn_sig,...);

Returns the result of a function_call.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it with json_free()!

arguments:

in3_t *	in3
address_t	contract
eth_blknum_t	block
`char *`	fn_sig
`...`

returns: json_ctx_t *

eth_estimate_fn¶

uint64_t eth_estimate_fn(in3_t *in3, address_t contract, eth_blknum_t block, char *fn_sig,...);

Returns the result of a function_call.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it with json_free()!

arguments:

in3_t *	in3
address_t	contract
eth_blknum_t	block
`char *`	fn_sig
`...`

returns: uint64_t

eth_getTransactionByHash¶

eth_tx_t* eth_getTransactionByHash(in3_t *in3, bytes32_t tx_hash);

Returns the information about a transaction requested by transaction hash.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
bytes32_t	tx_hash

returns: eth_tx_t *

eth_getTransactionByBlockHashAndIndex¶

eth_tx_t* eth_getTransactionByBlockHashAndIndex(in3_t *in3, bytes32_t block_hash, size_t index);

Returns the information about a transaction by block hash and transaction index position.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
bytes32_t	block_hash
`size_t`	index

returns: eth_tx_t *

eth_getTransactionByBlockNumberAndIndex¶

eth_tx_t* eth_getTransactionByBlockNumberAndIndex(in3_t *in3, eth_blknum_t block, size_t index);

Returns the information about a transaction by block number and transaction index position.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
eth_blknum_t	block
`size_t`	index

returns: eth_tx_t *

eth_getTransactionCount¶

uint64_t eth_getTransactionCount(in3_t *in3, address_t address, eth_blknum_t block);

Returns the number of transactions sent from an address.

arguments:

in3_t *	in3
address_t	address
eth_blknum_t	block

returns: uint64_t

eth_getUncleByBlockNumberAndIndex¶

eth_block_t* eth_getUncleByBlockNumberAndIndex(in3_t *in3, eth_blknum_t block, size_t index);

Returns information about a uncle of a block by number and uncle index position.

If result is null, check eth_last_error()! otherwise make sure to free the result after using it!

arguments:

in3_t *	in3
eth_blknum_t	block
`size_t`	index

returns: eth_block_t *

eth_getUncleCountByBlockHash¶

uint64_t eth_getUncleCountByBlockHash(in3_t *in3, bytes32_t hash);

Returns the number of uncles in a block from a block matching the given block hash.

arguments:

in3_t *	in3
bytes32_t	hash

returns: uint64_t

eth_getUncleCountByBlockNumber¶

uint64_t eth_getUncleCountByBlockNumber(in3_t *in3, eth_blknum_t block);

Returns the number of uncles in a block from a block matching the given block number.

arguments:

in3_t *	in3
eth_blknum_t	block

returns: uint64_t

eth_sendTransaction¶

bytes_t* eth_sendTransaction(in3_t *in3, address_t from, address_t to, OPTIONAL_T(uint64_t) gas, OPTIONAL_T(uint64_t) gas_price, OPTIONAL_T(uint256_t) value, OPTIONAL_T(bytes_t) data, OPTIONAL_T(uint64_t) nonce);

Creates new message call transaction or a contract creation.

Returns (32 Bytes) - the transaction hash, or the zero hash if the transaction is not yet available. Free result after use with b_free().

arguments:

in3_t *	in3
address_t	from
address_t	to
OPTIONAL_T(uint64_t)	gas
OPTIONAL_T(uint64_t)	gas_price
`(,)`	value
`(,)`	data
OPTIONAL_T(uint64_t)	nonce

returns: bytes_t *

eth_sendRawTransaction¶

bytes_t* eth_sendRawTransaction(in3_t *in3, bytes_t data);

Creates new message call transaction or a contract creation for signed transactions.

Returns (32 Bytes) - the transaction hash, or the zero hash if the transaction is not yet available. Free after use with b_free().

arguments:

in3_t *	in3
bytes_t	data

returns: bytes_t *

eth_getTransactionReceipt¶

eth_tx_receipt_t* eth_getTransactionReceipt(in3_t *in3, bytes32_t tx_hash);

Returns the receipt of a transaction by transaction hash.

Free result after use with eth_tx_receipt_free()

arguments:

in3_t *	in3
bytes32_t	tx_hash

returns: eth_tx_receipt_t *

eth_wait_for_receipt¶

char* eth_wait_for_receipt(in3_t *in3, bytes32_t tx_hash);

Waits for receipt of a transaction requested by transaction hash.

arguments:

in3_t *	in3
bytes32_t	tx_hash

returns: char *

eth_log_free¶

void eth_log_free(eth_log_t *log);

Frees a eth_log_t object.

arguments:

eth_log_t *

log

eth_tx_receipt_free¶

void eth_tx_receipt_free(eth_tx_receipt_t *txr);

Frees a eth_tx_receipt_t object.

arguments:

eth_tx_receipt_t *

txr

in3_register_eth_api¶

in3_ret_t in3_register_eth_api(in3_t *c);

this function should only be called once and will register the eth-API verifier.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ipfs_api.h¶

IPFS API.

This header-file defines easy to use function, which are preparing the JSON-RPC-Request, which is then executed and verified by the incubed-client.

File: c/src/api/ipfs/ipfs_api.h

ipfs_put¶

char* ipfs_put(in3_t *in3, const bytes_t *content);

Returns the IPFS multihash of stored content on success OR NULL on error (check api_last_error()).

Result must be freed by caller.

arguments:

in3_t *	in3
bytes_tconst , *	content

returns: char *

ipfs_get¶

bytes_t* ipfs_get(in3_t *in3, const char *multihash);

Returns the content associated with specified multihash on success OR NULL on error (check api_last_error()).

Result must be freed by caller.

arguments:

in3_t *	in3
`const char *`	multihash

returns: bytes_t *

usn_api.h¶

USN API.

This header-file defines easy to use function, which are verifying USN-Messages.

File: c/src/api/usn/usn_api.h

usn_msg_type_t¶

The enum type contains the following values:

USN_ACTION	0
USN_REQUEST	1
USN_RESPONSE	2

usn_event_type_t¶

The enum type contains the following values:

BOOKING_NONE	0
BOOKING_START	1
BOOKING_STOP	2

usn_booking_handler¶

typedef int(* usn_booking_handler) (usn_event_t *)

returns: int(*

usn_verify_message¶

usn_msg_result_t usn_verify_message(usn_device_conf_t *conf, char *message);

arguments:

usn_device_conf_t *	conf
`char *`	message

returns: usn_msg_result_t

usn_register_device¶

in3_ret_t usn_register_device(usn_device_conf_t *conf, char *url);

arguments:

usn_device_conf_t *	conf
`char *`	url

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

usn_parse_url¶

usn_url_t usn_parse_url(char *url);

arguments:

char * url

returns: usn_url_t

usn_update_state¶

unsigned int usn_update_state(usn_device_conf_t *conf, unsigned int wait_time);

arguments:

usn_device_conf_t *	conf
`unsigned int`	wait_time

returns: unsigned int

usn_update_bookings¶

in3_ret_t usn_update_bookings(usn_device_conf_t *conf);

arguments:

usn_device_conf_t *

conf

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

usn_remove_old_bookings¶

void usn_remove_old_bookings(usn_device_conf_t *conf);

arguments:

usn_device_conf_t *

conf

usn_get_next_event¶

usn_event_t usn_get_next_event(usn_device_conf_t *conf);

arguments:

usn_device_conf_t *

conf

returns: usn_event_t

usn_rent¶

in3_ret_t usn_rent(in3_t *c, address_t contract, address_t token, char *url, uint32_t seconds, bytes32_t tx_hash);

arguments:

in3_t *	c
address_t	contract
address_t	token
`char *`	url
`uint32_t`	seconds
bytes32_t	tx_hash

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

usn_return¶

in3_ret_t usn_return(in3_t *c, address_t contract, char *url, bytes32_t tx_hash);

arguments:

in3_t *	c
address_t	contract
`char *`	url
bytes32_t	tx_hash

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

usn_price¶

in3_ret_t usn_price(in3_t *c, address_t contract, address_t token, char *url, uint32_t seconds, address_t controller, bytes32_t price);

arguments:

in3_t *	c
address_t	contract
address_t	token
`char *`	url
`uint32_t`	seconds
address_t	controller
bytes32_t	price

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

api_utils.h¶

Ethereum API utils.

This header-file helper utils for use with API modules.

File: c/src/api/utils/api_utils.h

set_error_fn¶

function to set error.

Will only be called internally. default implementation is NOT MT safe!

typedef void(* set_error_fn) (int err, const char *msg)

get_error_fn¶

function to get last error message.

default implementation is NOT MT safe!

typedef char*(* get_error_fn) (void)

returns: char *(*

as_double¶

long double as_double(uint256_t d);

Converts a uint256_t in a long double.

Important: since a long double stores max 16 byte, there is no guarantee to have the full precision.

Converts a uint256_t in a long double.

arguments:

uint256_t

d

returns: long double

as_long¶

uint64_t as_long(uint256_t d);

Converts a uint256_t in a long .

Important: since a long double stores 8 byte, this will only use the last 8 byte of the value.

Converts a uint256_t in a long .

arguments:

uint256_t

d

returns: uint64_t

to_uint256¶

uint256_t to_uint256(uint64_t value);

Converts a uint64_t into its uint256_t representation.

arguments:

uint64_t value

returns: uint256_t

decrypt_key¶

in3_ret_t decrypt_key(d_token_t *key_data, char *password, bytes32_t dst);

Decrypts the private key from a json keystore file using PBKDF2 or SCRYPT (if enabled)

arguments:

d_token_t *	key_data
`char *`	password
bytes32_t	dst

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

to_checksum¶

in3_ret_t to_checksum(address_t adr, chain_id_t chain_id, char out[43]);

converts the given address to a checksum address.

If chain_id is passed, it will use the EIP1191 to include it as well.

arguments:

address_t	adr
chain_id_t	chain_id
`char`	out

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

api_set_error_fn¶

void api_set_error_fn(set_error_fn fn);

arguments:

set_error_fn

fn

api_get_error_fn¶

void api_get_error_fn(get_error_fn fn);

arguments:

get_error_fn

fn

api_last_error¶

char* api_last_error();

returns current error or null if all is ok

returns: char *

Module core¶

client.h¶

this file defines the incubed configuration struct and it registration.

File: c/src/core/client/client.h

IN3_PROTO_VER¶

the protocol version used when sending requests from the this client

#define IN3_PROTO_VER "2.1.0"

CHAIN_ID_MULTICHAIN¶

chain_id working with all known chains

#define CHAIN_ID_MULTICHAIN 0x0

CHAIN_ID_MAINNET¶

chain_id for mainnet

#define CHAIN_ID_MAINNET 0x01

CHAIN_ID_KOVAN¶

chain_id for kovan

#define CHAIN_ID_KOVAN 0x2a

CHAIN_ID_TOBALABA¶

chain_id for tobalaba

#define CHAIN_ID_TOBALABA 0x44d

CHAIN_ID_GOERLI¶

chain_id for goerlii

#define CHAIN_ID_GOERLI 0x5

CHAIN_ID_EVAN¶

chain_id for evan

#define CHAIN_ID_EVAN 0x4b1

CHAIN_ID_EWC¶

chain_id for ewc

#define CHAIN_ID_EWC 0xf6

CHAIN_ID_IPFS¶

chain_id for ipfs

#define CHAIN_ID_IPFS 0x7d0

CHAIN_ID_BTC¶

chain_id for btc

#define CHAIN_ID_BTC 0x99

CHAIN_ID_LOCAL¶

chain_id for local chain

#define CHAIN_ID_LOCAL 0xFFFF

DEF_REPL_LATEST_BLK¶

default replace_latest_block

#define DEF_REPL_LATEST_BLK 6

in3_node_props_init (np)¶

Initializer for in3_node_props_t.

#define in3_node_props_init (np) *(np) = 0

PLGN_ACT_TRANSPORT¶

#define PLGN_ACT_TRANSPORT (PLGN_ACT_TRANSPORT_SEND | PLGN_ACT_TRANSPORT_RECEIVE | PLGN_ACT_TRANSPORT_CLEAN)

PLGN_ACT_CACHE¶

#define PLGN_ACT_CACHE (PLGN_ACT_CACHE_SET | PLGN_ACT_CACHE_GET | PLGN_ACT_CACHE_CLEAR)

in3_for_chain (chain_id)¶

creates a new Incubes configuration for a specified chain and returns the pointer.

when creating the client only the one chain will be configured. (saves memory). but if you pass CHAIN_ID_MULTICHAIN as argument all known chains will be configured allowing you to switch between chains within the same client or configuring your own chain.

you need to free this instance with in3_free after use!

Before using the client you still need to set the tramsport and optional the storage handlers:

example of initialization: , ** This Method is depricated. you should use in3_for_chain instead.**

// register verifiers
in3_register_eth_full();

// create new client
in3_t* client = in3_for_chain(CHAIN_ID_MAINNET);

// configure transport
client->transport    = send_curl;

// configure storage
in3_set_storage_handler(c, storage_get_item, storage_set_item, storage_clear, NULL);

// ready to use ...

#define in3_for_chain (chain_id) in3_for_chain_default(chain_id)

assert_in3 (c)¶

#define assert_in3 (c) assert(c);                                       \
  assert(c->chain_id);                             \
  assert(c->plugins);                              \
  assert(c->chains);                               \
  assert(c->request_count > 0);                    \
  assert(c->chains_length > 0);                    \
  assert(c->chains_length < 10);                   \
  assert(c->max_attempts > 0);                     \
  assert(c->proof >= 0 && c->proof <= PROOF_FULL); \
  assert(c->proof >= 0 && c->proof <= PROOF_FULL);

in3_chain_type_t¶

the type of the chain.

for incubed a chain can be any distributed network or database with incubed support. Depending on this chain-type the previously registered verifyer will be choosen and used.

The enum type contains the following values:

CHAIN_ETH	0	Ethereum chain.
CHAIN_SUBSTRATE	1	substrate chain
CHAIN_IPFS	2	ipfs verifiaction
CHAIN_BTC	3	Bitcoin chain.
CHAIN_EOS	4	EOS chain.
CHAIN_IOTA	5	IOTA chain.
CHAIN_GENERIC	6	other chains

in3_proof_t¶

the type of proof.

Depending on the proof-type different levels of proof will be requested from the node.

The enum type contains the following values:

PROOF_NONE	0	No Verification.
PROOF_STANDARD	1	Standard Verification of the important properties.
PROOF_FULL	2	All field will be validated including uncles.

in3_node_props_type_t¶

The enum type contains the following values:

NODE_PROP_PROOF	0x1	filter out nodes which are providing no proof
NODE_PROP_MULTICHAIN	0x2	filter out nodes other then which have capability of the same RPC endpoint may also accept requests for different chains
NODE_PROP_ARCHIVE	0x4	filter out non-archive supporting nodes
NODE_PROP_HTTP	0x8	filter out non-http nodes
NODE_PROP_BINARY	0x10	filter out nodes that don’t support binary encoding
NODE_PROP_ONION	0x20	filter out non-onion nodes
NODE_PROP_SIGNER	0x40	filter out non-signer nodes
NODE_PROP_DATA	0x80	filter out non-data provider nodes
NODE_PROP_STATS	0x100	filter out nodes that do not provide stats
NODE_PROP_MIN_BLOCK_HEIGHT	0x400	filter out nodes that will sign blocks with lower min block height than specified

in3_flags_type_t¶

a list of flags definiing the behavior of the incubed client.

They should be used as bitmask for the flags-property.

The enum type contains the following values:

FLAGS_KEEP_IN3	0x1	the in3-section with the proof will also returned
FLAGS_AUTO_UPDATE_LIST	0x2	the nodelist will be automaticly updated if the last_block is newer
FLAGS_INCLUDE_CODE	0x4	the code is included when sending eth_call-requests
FLAGS_BINARY	0x8	the client will use binary format
FLAGS_HTTP	0x10	the client will try to use http instead of https
FLAGS_STATS	0x20	nodes will keep track of the stats (default=true)
FLAGS_NODE_LIST_NO_SIG	0x40	nodelist update request will not automatically ask for signatures and proof
FLAGS_BOOT_WEIGHTS	0x80	if true the client will initialize the first weights from the nodelist given by the nodelist.

in3_node_attr_type_t¶

a list of node attributes (mostly used internally)

The enum type contains the following values:

ATTR_WHITELISTED	1	indicates if node exists in whiteList
ATTR_BOOT_NODE	2	used to avoid filtering manually added nodes before first nodeList update

in3_filter_type_t¶

Filter type used internally when managing filters.

The enum type contains the following values:

FILTER_EVENT	0	Event filter.
FILTER_BLOCK	1	Block filter.
FILTER_PENDING	2	Pending filter (Unsupported)

in3_plugin_act_t¶

plugin action list

The enum type contains the following values:

PLGN_ACT_INIT	0x1	initialize plugin - use for allocating/setting-up internal resources
PLGN_ACT_TERM	0x2	terminate plugin - use for releasing internal resources and cleanup.
PLGN_ACT_TRANSPORT_SEND	0x4	sends out a request - the transport plugin will receive a request_t as plgn_ctx, it may set a cptr which will be passed back when fetching more resonses.
PLGN_ACT_TRANSPORT_RECEIVE	0x8	fetch next response - the transport plugin will receive a request_t as plgn_ctx, which contains a cptr if set previously
PLGN_ACT_TRANSPORT_CLEAN	0x10	freeup transport resources - the transport plugin will receive a request_t as plgn_ctx if the cptr was set.
PLGN_ACT_SIGN_ACCOUNT	0x20	returns the default account of the signer
PLGN_ACT_SIGN_PREPARE	0x40	allowes a wallet to manipulate the payload before signing - the plgn_ctx will be in3_sign_ctx_t. This way a tx can be send through a multisig
PLGN_ACT_SIGN	0x80	signs the payload - the plgn_ctx will be in3_sign_ctx_t.
PLGN_ACT_RPC_HANDLE	0x100	a plugin may respond to a rpc-request directly (without sending it to the node).
PLGN_ACT_RPC_VERIFY	0x200	verifies the response. the plgn_ctx will be a in3_vctx_t holding all data
PLGN_ACT_CACHE_SET	0x400	stores data to be reused later - the plgn_ctx will be a in3_cache_ctx_t containing the data
PLGN_ACT_CACHE_GET	0x800	reads data to be previously stored - the plgn_ctx will be a in3_cache_ctx_t containing the key. if the data was found the data-property needs to be set.
PLGN_ACT_CACHE_CLEAR	0x1000	clears alls stored data - plgn_ctx will be NULL
PLGN_ACT_CONFIG_SET	0x2000	gets a config-token and reads data from it
PLGN_ACT_CONFIG_GET	0x4000	gets a stringbuilder and adds all config to it.
PLGN_ACT_PAY_PREPARE	0x8000	prerpares a payment
PLGN_ACT_PAY_FOLLOWUP	0x10000	called after a requeest to update stats.
PLGN_ACT_PAY_HANDLE	0x20000	handles the payment
PLGN_ACT_PAY_SIGN_REQ	0x40000	signs a request
PLGN_ACT_NL_PICK_DATA	0x80000	picks the data nodes
PLGN_ACT_NL_PICK_SIGNER	0x100000	picks the signer nodes
PLGN_ACT_NL_PICK_FOLLOWUP	0x200000	called after receiving a response in order to decide whether a update is needed.

chain_id_t¶

type for a chain_id.

typedef uint32_t chain_id_t

in3_node_props_t¶

Node capabilities.

typedef uint64_t in3_node_props_t

in3_node_attr_t¶

typedef uint8_t in3_node_attr_t

in3_node_t¶

incubed node-configuration.

These information are read from the Registry contract and stored in this struct representing a server or node.

The stuct contains following fields:

address_t	address	address of the server
`uint64_t`	deposit	the deposit stored in the registry contract, which this would lose if it sends a wrong blockhash
`uint_fast16_t`	index	index within the nodelist, also used in the contract as key
`uint_fast16_t`	capacity	the maximal capacity able to handle
in3_node_props_t	props	used to identify the capabilities of the node. See in3_node_props_type_t in nodelist.h
`char *`	url	the url of the node
`uint_fast8_t`	attrs	bitmask of internal attributes

in3_node_weight_t¶

Weight or reputation of a node.

Based on the past performance of the node a weight is calculated given faster nodes a higher weight and chance when selecting the next node from the nodelist. These weights will also be stored in the cache (if available)

The stuct contains following fields:

uint32_t response_count counter for responses

uint32_t total_response_time total of all response times

uint64_t

blacklisted_until

if >0 this node is blacklisted until k.

k is a unix timestamp

in3_whitelist_t¶

defines a whitelist structure used for the nodelist.

The stuct contains following fields:

`bool`	needs_update	if true the nodelist should be updated and will trigger a in3_nodeList-request before the next request is send.
`uint64_t`	last_block	last blocknumber the whiteList was updated, which is used to detect changed in the whitelist
address_t	contract	address of whiteList contract. If specified, whiteList is always auto-updated and manual whiteList is overridden
bytes_t	addresses	serialized list of node addresses that constitute the whiteList

in3_verified_hash_t¶

represents a blockhash which was previously verified

The stuct contains following fields:

`uint64_t`	block_number	the number of the block
bytes32_t	hash	the blockhash

in3_chain_t¶

Chain definition inside incubed.

for incubed a chain can be any distributed network or database with incubed support.

The stuct contains following fields:

`bool`	dirty	indicates whether the nodelist has been modified after last read from cache
`uint8_t`	version	version of the chain
`unsigned int`	nodelist_length	number of nodes in the nodeList
`uint16_t`	avg_block_time	average block time (seconds) for this chain (calculated internally)
chain_id_t	chain_id	chain_id, which could be a free or based on the public ethereum networkId
in3_chain_type_t	type	chaintype
`uint64_t`	last_block	last blocknumber the nodeList was updated, which is used to detect changed in the nodelist
in3_node_t *	nodelist	array of nodes
in3_node_weight_t *	weights	stats and weights recorded for each node
bytes_t **	init_addresses	array of addresses of nodes that should always part of the nodeList
bytes_t *	contract	the address of the registry contract
bytes32_t	registry_id	the identifier of the registry
in3_verified_hash_t *	verified_hashes	contains the list of already verified blockhashes
in3_whitelist_t *	whitelist	if set the whitelist of the addresses.
`uint64_t`	exp_last_block	the last_block when the nodelist last changed reported by this node
`uint64_t`	timestamp	approx. time when nodelist must be updated (i.e. when reported last_block will be considered final)
address_t	node	node that reported the last_block which necessitated a nodeList update
`struct in3_chain::@2 *`	nodelist_upd8_params

in3_pay_prepare¶

payment prepearation function.

allows the payment to handle things before the request will be send.

typedef in3_ret_t(* in3_pay_prepare) (struct in3_ctx *ctx, void *cptr)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_pay_follow_up¶

called after receiving a parseable response with a in3-section.

typedef in3_ret_t(* in3_pay_follow_up) (struct in3_ctx *ctx, void *node, d_token_t *in3, d_token_t *error, void *cptr)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_pay_free¶

free function for the custom pointer.

typedef void(* in3_pay_free) (void *cptr)

in3_pay_handle_request¶

handles the request.

this function is called when the in3-section of payload of the request is built and allows the handler to add properties.

typedef in3_ret_t(* in3_pay_handle_request) (struct in3_ctx *ctx, sb_t *sb, void *cptr)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_pay_t¶

the payment handler.

if a payment handler is set it will be used when generating the request.

The stuct contains following fields:

in3_pay_prepare	prepare	payment prepearation function.
in3_pay_follow_up	follow_up	payment function to be called after the request.
in3_pay_handle_request	handle_request	this function is called when the in3-section of payload of the request is built and allows the handler to add properties.
in3_pay_free	free	frees the custom pointer (cptr).
`void *`	cptr	custom object whill will be passed to functions

in3_t¶

Incubed Configuration.

This struct holds the configuration and also point to internal resources such as filters or chain configs.

The stuct contains following fields:

`uint8_t`	request_count	the number of request send when getting a first answer
`uint8_t`	signature_count	the number of signatures used to proof the blockhash.
`uint8_t`	replace_latest_block	if specified, the blocknumber latest will be replaced by blockNumber- specified value
`uint_fast8_t`	flags	a bit mask with flags defining the behavior of the incubed client. See the FLAG…-defines
`uint16_t`	node_limit	the limit of nodes to store in the client.
`uint16_t`	finality	the number of signatures in percent required for the request
`uint16_t`	chains_length	number of configured chains
`uint_fast16_t`	max_attempts	the max number of attempts before giving up
`uint_fast16_t`	max_verified_hashes	max number of verified hashes to cache (actual number may temporarily exceed this value due to pending requests)
`uint_fast16_t`	alloc_verified_hashes	number of currently allocated verified hashes
`uint_fast16_t`	pending	number of pending requests created with this instance
`uint32_t`	cache_timeout	number of seconds requests can be cached.
`uint32_t`	timeout	specifies the number of milliseconds before the request times out. increasing may be helpful if the device uses a slow connection.
chain_id_t	chain_id	servers to filter for the given chain. The chain-id based on EIP-155.
`in3_plugin_supp_acts_t`	plugin_acts	bitmask of supported actions of all plugins registered with this client
in3_proof_t	proof	the type of proof used
`uint64_t`	min_deposit	min stake of the server. Only nodes owning at least this amount will be chosen.
in3_node_props_t	node_props	used to identify the capabilities of the node.
in3_chain_t *	chains	chain spec and nodeList definitions
in3_filter_handler_t *	filters	filter handler
in3_plugin_t *	plugins	list of registered plugins
`void *`	internal	pointer to internal data

in3_filter_t¶

The stuct contains following fields:

`bool`	is_first_usage	if true the filter was not used previously
in3_filter_type_t	type	filter type: (event, block or pending)
`uint64_t`	last_block	block no. when filter was created OR eth_getFilterChanges was called
`char *`	options	associated filter options
`void(*`	release	method to release owned resources

in3_plugin_t¶

plugin interface definition

The stuct contains following fields:

`in3_plugin_supp_acts_t`	acts	bitmask of supported actions this plugin can handle
`void *`	data	opaque pointer to plugin data
in3_plugin_act_fn	action_fn	plugin action handler
in3_plugin_t *	next	pointer to next plugin in list

in3_plugin_act_fn¶

plugin action handler

Implementations of this function must strictly follow the below pattern for return values -

IN3_OK - successfully handled specified action
IN3_WAITING - handling specified action, but waiting for more information
IN3_EIGNORE - could handle specified action, but chose to ignore it so maybe another handler could handle it
Other errors - handled but failed

typedef in3_ret_t(* in3_plugin_act_fn) (void *plugin_data, in3_plugin_act_t action, void *plugin_ctx)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_plugin_supp_acts_t¶

typedef uint32_t in3_plugin_supp_acts_t

in3_filter_handler_t¶

Handler which is added to client config in order to handle filter.

The stuct contains following fields:

in3_filter_t **	array
`size_t`	count	array of filters

plgn_register¶

a register-function for a plugion.

typedef in3_ret_t(* plgn_register) (in3_t *c)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_node_props_set¶

NONULL void in3_node_props_set(in3_node_props_t *node_props, in3_node_props_type_t type, uint8_t value);

setter method for interacting with in3_node_props_t.

arguments:

in3_node_props_t *	node_props	pointer to the properties to change
in3_node_props_type_t	type	key or type of the property
`uint8_t`	value	value to set

returns: NONULL void

in3_node_props_get¶

static uint32_t in3_node_props_get(in3_node_props_t np, in3_node_props_type_t t);

returns the value of the specified propertytype.

< the value to extract

arguments:

in3_node_props_t	np	property to read from
in3_node_props_type_t	t

returns: uint32_t : value as a number

in3_node_props_matches¶

static bool in3_node_props_matches(in3_node_props_t np, in3_node_props_type_t t);

checkes if the given type is set in the properties

< the value to extract

arguments:

in3_node_props_t	np	property to read from
in3_node_props_type_t	t

returns: bool : true if set

in3_new¶

in3_t* in3_new() __attribute__((deprecated("use in3_for_chain(CHAIN_ID_MULTICHAIN)")));

creates a new Incubes configuration and returns the pointer.

This Method is depricated. you should use in3_for_chain(CHAIN_ID_MULTICHAIN) instead.

you need to free this instance with in3_free after use!

Before using the client you still need to set the tramsport and optional the storage handlers:

example of initialization:

// register verifiers
in3_register_eth_full();

// create new client
in3_t* client = in3_new();

// configure transport
client->transport    = send_curl;

// configure storage
in3_set_storage_handler(c, storage_get_item, storage_set_item, storage_clear, NULL);

// ready to use ...

returns: in3_t * : the incubed instance.

in3_for_chain_default¶

in3_t* in3_for_chain_default(chain_id_t chain_id);

arguments:

chain_id_t

chain_id

the chain_id (see CHAIN_ID_… constants).

returns: in3_t *

in3_client_rpc¶

NONULL in3_ret_t in3_client_rpc(in3_t *c, const char *method, const char *params, char **result, char **error);

sends a request and stores the result in the provided buffer

arguments:

in3_t *	c	the pointer to the incubed client config.
`const char *`	method	the name of the rpc-funcgtion to call.
`const char *`	params	docs for input parameter v.
`char **`	result	pointer to string which will be set if the request was successfull. This will hold the result as json-rpc-string. (make sure you free this after use!)
`char **`	error	pointer to a string containg the error-message. (make sure you free it after use!)

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_rpc_raw¶

NONULL in3_ret_t in3_client_rpc_raw(in3_t *c, const char *request, char **result, char **error);

sends a request and stores the result in the provided buffer, this method will always return the first, so bulk-requests are not saupported.

arguments:

in3_t *	c	the pointer to the incubed client config.
`const char *`	request	the rpc request including method and params.
`char **`	result	pointer to string which will be set if the request was successfull. This will hold the result as json-rpc-string. (make sure you free this after use!)
`char **`	error	pointer to a string containg the error-message. (make sure you free it after use!)

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_exec_req¶

NONULL char* in3_client_exec_req(in3_t *c, char *req);

executes a request and returns result as string.

in case of an error, the error-property of the result will be set. This fuinction also supports sending bulk-requests, but you can not mix internal and external calls, since bulk means all requests will be send to picked nodes. The resulting string must be free by the the caller of this function!

arguments:

in3_t *	c	the pointer to the incubed client config.
`char *`	req	the request as rpc.

returns: NONULL char *

in3_client_register_chain¶

in3_ret_t in3_client_register_chain(in3_t *client, chain_id_t chain_id, in3_chain_type_t type, address_t contract, bytes32_t registry_id, uint8_t version, address_t wl_contract);

registers a new chain or replaces a existing (but keeps the nodelist)

arguments:

in3_t *	client	the pointer to the incubed client config.
chain_id_t	chain_id	the chain id.
in3_chain_type_t	type	the verification type of the chain.
address_t	contract	contract of the registry.
bytes32_t	registry_id	the identifier of the registry.
`uint8_t`	version	the chain version.
address_t	wl_contract	contract of whiteList.

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_add_node¶

NONULL in3_ret_t in3_client_add_node(in3_t *client, chain_id_t chain_id, char *url, in3_node_props_t props, address_t address);

adds a node to a chain ore updates a existing node

[in] public address of the signer.

arguments:

in3_t *	client	the pointer to the incubed client config.
chain_id_t	chain_id	the chain id.
`char *`	url	url of the nodes.
in3_node_props_t	props	properties of the node.
address_t	address

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_remove_node¶

NONULL in3_ret_t in3_client_remove_node(in3_t *client, chain_id_t chain_id, address_t address);

removes a node from a nodelist

[in] public address of the signer.

arguments:

in3_t *	client	the pointer to the incubed client config.
chain_id_t	chain_id	the chain id.
address_t	address

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_clear_nodes¶

NONULL in3_ret_t in3_client_clear_nodes(in3_t *client, chain_id_t chain_id);

removes all nodes from the nodelist

[in] the chain id.

arguments:

in3_t *	client	the pointer to the incubed client config.
chain_id_t	chain_id

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_free¶

NONULL void in3_free(in3_t *a);

frees the references of the client

arguments:

a

the pointer to the incubed client config to free.

returns: NONULL void

in3_cache_init¶

NONULL in3_ret_t in3_cache_init(in3_t *c);

inits the cache.

this will try to read the nodelist from cache.

inits the cache.

arguments:

c

the incubed client

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_get_chain¶

NONULL in3_chain_t* in3_get_chain(const in3_t *c);

returns the chain-config for the current chain_id.

arguments:

in3_tconst , *

c

the incubed client

returns: in3_chain_tNONULL , *

in3_find_chain¶

NONULL in3_chain_t* in3_find_chain(const in3_t *c, chain_id_t chain_id);

finds the chain-config for the given chain_id.

My return NULL if not found.

arguments:

in3_tconst , *	c	the incubed client
chain_id_t	chain_id	chain_id

returns: in3_chain_tNONULL , *

in3_configure¶

NONULL char* in3_configure(in3_t *c, const char *config);

configures the clent based on a json-config.

For details about the structure of ther config see https://in3.readthedocs.io/en/develop/api-ts.html#type-in3config Returns NULL on success, and error string on failure (to be freed by caller) - in which case the client state is undefined

arguments:

in3_t *	c	the incubed client
`const char *`	config	JSON-string with the configuration to set.

returns: NONULL char *

in3_get_config¶

NONULL char* in3_get_config(in3_t *c);

gets the current config as json.

For details about the structure of ther config see https://in3.readthedocs.io/en/develop/api-ts.html#type-in3config

arguments:

c

the incubed client

returns: NONULL char *

context.h¶

Request Context. This is used for each request holding request and response-pointers but also controls the execution process.

File: c/src/core/client/context.h

ctx_type¶

type of the request context,

The enum type contains the following values:

CT_RPC	0	a json-rpc request, which needs to be send to a incubed node
CT_SIGN	1	a sign request

state¶

The current state of the context.

you can check this state after each execute-call.

The enum type contains the following values:

CTX_SUCCESS	0	The ctx has a verified result.
CTX_WAITING_TO_SEND	1	the request has not been sent yet
CTX_WAITING_FOR_RESPONSE	2	the request is sent but not all of the response are set ()
CTX_ERROR	-1	the request has a error

ctx_type_t¶

type of the request context,

The enum type contains the following values:

CT_RPC	0	a json-rpc request, which needs to be send to a incubed node
CT_SIGN	1	a sign request

node_match_t¶

the weight of a certain node as linked list.

This will be used when picking the nodes to send the request to. A linked list of these structs desribe the result.

The stuct contains following fields:

`unsigned int`	index	index of the node in the nodelist
`bool`	blocked	if true this node has been blocked for sending wrong responses
`uint32_t`	s	The starting value.
`uint32_t`	w	weight value
weightstruct , *	next	next in the linkedlist or NULL if this is the last element

in3_response_t¶

response-object.

if the error has a length>0 the response will be rejected

The stuct contains following fields:

`uint32_t`	time	measured time (in ms) which will be used for ajusting the weights
in3_ret_t	state	the state of the response
sb_t	data	a stringbuilder to add the result

in3_ctx_t¶

The Request config.

This is generated for each request and represents the current state. it holds the state until the request is finished and must be freed afterwards.

The stuct contains following fields:

`uint_fast8_t`	signers_length	number or addresses
`uint_fast16_t`	len	the number of requests
`uint_fast16_t`	attempt	the number of attempts
ctx_type_t	type	the type of the request
in3_ret_t	verification_state	state of the verification
`char *`	error	in case of an error this will hold the message, if not it points to NULL
json_ctx_t *	request_context	the result of the json-parser for the request.
json_ctx_t *	response_context	the result of the json-parser for the response.
d_token_t **	requests	references to the tokens representring the requests
d_token_t **	responses	references to the tokens representring the parsed responses
in3_response_t *	raw_response	the raw response-data, which should be verified.
`uint8_t *`	signers	the addresses of servers requested to sign the blockhash
node_match_t *	nodes	selected nodes to process the request, which are stored as linked list.
cache_entry_t *	cache	optional cache-entries. These entries will be freed when cleaning up the context.
in3_ctxstruct , *	required	pointer to the next required context. if not NULL the data from this context need get finished first, before being able to resume this context.
in3_t *	client	reference to the client

in3_ctx_state_t¶

The current state of the context.

you can check this state after each execute-call.

The enum type contains the following values:

CTX_SUCCESS	0	The ctx has a verified result.
CTX_WAITING_TO_SEND	1	the request has not been sent yet
CTX_WAITING_FOR_RESPONSE	2	the request is sent but not all of the response are set ()
CTX_ERROR	-1	the request has a error

ctx_new¶

NONULL in3_ctx_t* ctx_new(in3_t *client, const char *req_data);

creates a new context.

the request data will be parsed and represented in the context. calling this function will only parse the request data, but not send anything yet.

Important: the req_data will not be cloned but used during the execution. The caller of the this function is also responsible for freeing this string afterwards.

arguments:

in3_t *	client	the client-config.
`const char *`	req_data	the rpc-request as json string.

in3_send_ctx¶

NONULL in3_ret_t in3_send_ctx(in3_ctx_t *ctx);

sends a previously created context to nodes and verifies it.

The execution happens within the same thread, thich mean it will be blocked until the response ha beedn received and verified. In order to handle calls asynchronously, you need to call the in3_ctx_execute function and provide the data as needed.

arguments:

ctx

the request context.

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_ctx_last_waiting¶

NONULL in3_ctx_t* in3_ctx_last_waiting(in3_ctx_t *ctx);

finds the last waiting request-context.

arguments:

ctx

the request context.

in3_ctx_exec_state¶

NONULL in3_ctx_state_t in3_ctx_exec_state(in3_ctx_t *ctx);

executes the context and returns its state.

arguments:

ctx

the request context.

returns: in3_ctx_state_tNONULL

in3_ctx_execute¶

NONULL in3_ret_t in3_ctx_execute(in3_ctx_t *ctx);

execute the context, but stops whenever data are required.

This function should be used in order to call data in a asyncronous way, since this function will not use the transport-function to actually send it.

The caller is responsible for delivering the required responses. After calling you need to check the return-value:

IN3_WAITING : provide the required data and then call in3_ctx_execute again.
IN3_OK : success, we have a result.
any other status = error

$digraph G { node[fontname="Helvetica", shape=Box, color=lightblue, style=filled ] edge[fontname="Helvetica", style=solid, fontsize=8 , color=grey] rankdir = LR; RPC[label="RPC-Request"] CTX[label="in3_ctx_t"] sign[label="sign data",color=lightgrey, style=""] request[label="fetch data",color=lightgrey, style=""] exec[ label="in3_ctx_execute()",color=lightgrey, style="", shape=circle ] free[label="ctx_free()",color=lightgrey, style=""] RPC -> CTX [label="ctx_new()"] CTX -> exec exec -> error [label="IN3_..."] exec -> response[label="IN3_OK"] exec -> waiting[label="IN3_WAITING"] waiting -> sign[label=CT_SIGN] waiting -> request[label=CT_RPC] sign -> exec [label="in3_ctx_add_response()"] request -> exec[label="in3_ctx_add_response()"] response -> free error->free { rank = same; exec, sign, request } }$

Here is a example how to use this function:

 in3_ret_t in3_send_ctx(in3_ctx_t* ctx) {
  in3_ret_t ret;
  // execute the context and store the return value.
  // if the return value is 0 == IN3_OK, it was successful and we return,
  // if not, we keep on executing
  while ((ret = in3_ctx_execute(ctx))) {
    // error we stop here, because this means we got an error
    if (ret != IN3_WAITING) return ret;

    // handle subcontexts first, if they have not been finished
    while (ctx->required && in3_ctx_state(ctx->required) != CTX_SUCCESS) {
      // exxecute them, and return the status if still waiting or error
      if ((ret = in3_send_ctx(ctx->required))) return ret;

      // recheck in order to prepare the request.
      // if it is not waiting, then it we cannot do much, becaus it will an error or successfull.
      if ((ret = in3_ctx_execute(ctx)) != IN3_WAITING) return ret;
    }

    // only if there is no response yet...
    if (!ctx->raw_response) {

      // what kind of request do we need to provide?
      switch (ctx->type) {

        // RPC-request to send to the nodes
        case CT_RPC: {

            // build the request
            in3_request_t* request = in3_create_request(ctx);

            // here we use the transport, but you can also try to fetch the data in any other way.
            ctx->client->transport(request);

            // clean up
            request_free(request);
            break;
        }

        // this is a request to sign a transaction
        case CT_SIGN: {
            // read the data to sign from the request
            d_token_t* params = d_get(ctx->requests[0], K_PARAMS);
            // the data to sign
            bytes_t    data   = d_to_bytes(d_get_at(params, 0));
            // the account to sign with
            bytes_t    from   = d_to_bytes(d_get_at(params, 1));

            // prepare the response
            ctx->raw_response = _malloc(sizeof(in3_response_t));
            sb_init(&ctx->raw_response[0].error);
            sb_init(&ctx->raw_response[0].result);

            // data for the signature 
            uint8_t sig[65];
            // use the signer to create the signature
            ret = ctx->client->signer->sign(ctx, SIGN_EC_HASH, data, from, sig);
            // if it fails we report this as error
            if (ret < 0) return ctx_set_error(ctx, ctx->raw_response->error.data, ret);
            // otherwise we simply add the raw 65 bytes to the response.
            sb_add_range(&ctx->raw_response->result, (char*) sig, 0, 65);
        }
      }
    }
  }
  // done...
  return ret;
}

arguments:

ctx

the request context.

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_ctx_state¶

NONULL in3_ctx_state_t in3_ctx_state(in3_ctx_t *ctx);

returns the current state of the context.

arguments:

ctx

the request context.

returns: in3_ctx_state_tNONULL

ctx_get_error_data¶

char* ctx_get_error_data(in3_ctx_t *ctx);

returns the error of the context.

arguments:

ctx

the request context.

returns: char *

ctx_get_response_data¶

char* ctx_get_response_data(in3_ctx_t *ctx);

returns json response for that context

arguments:

ctx

the request context.

returns: char *

ctx_get_type¶

NONULL ctx_type_t ctx_get_type(in3_ctx_t *ctx);

returns the type of the request

arguments:

ctx

the request context.

returns: ctx_type_tNONULL

ctx_free¶

NONULL void ctx_free(in3_ctx_t *ctx);

frees all resources allocated during the request.

But this will not free the request string passed when creating the context!

arguments:

ctx

the request context.

returns: NONULL void

ctx_add_required¶

NONULL in3_ret_t ctx_add_required(in3_ctx_t *parent, in3_ctx_t *ctx);

adds a new context as a requirment.

Whenever a verifier needs more data and wants to send a request, we should create the request and add it as dependency and stop.

If the function is called again, we need to search and see if the required status is now useable.

Here is an example of how to use it:

in3_ret_t get_from_nodes(in3_ctx_t* parent, char* method, char* params, bytes_t* dst) {
  // check if the method is already existing
  in3_ctx_t* ctx = ctx_find_required(parent, method);
  if (ctx) {
    // found one - so we check if it is useable.
    switch (in3_ctx_state(ctx)) {
      // in case of an error, we report it back to the parent context
      case CTX_ERROR:
        return ctx_set_error(parent, ctx->error, IN3_EUNKNOWN);
      // if we are still waiting, we stop here and report it.
      case CTX_WAITING_FOR_REQUIRED_CTX:
      case CTX_WAITING_FOR_RESPONSE:
        return IN3_WAITING;

      // if it is useable, we can now handle the result.
      case CTX_SUCCESS: {
        d_token_t* r = d_get(ctx->responses[0], K_RESULT);
        if (r) {
          // we have a result, so write it back to the dst
          *dst = d_to_bytes(r);
          return IN3_OK;
        } else
          // or check the error and report it
          return ctx_check_response_error(parent, 0);
      }
    }
  }

  // no required context found yet, so we create one:

  // since this is a subrequest it will be freed when the parent is freed.
  // allocate memory for the request-string
  char* req = _malloc(strlen(method) + strlen(params) + 200);
  // create it
  sprintf(req, "{\"method\":\"%s\",\"jsonrpc\":\"2.0\",\"id\":1,\"params\":%s}", method, params);
  // and add the request context to the parent.
  return ctx_add_required(parent, ctx_new(parent->client, req));
}

arguments:

in3_ctx_t *	parent	the current request context.
in3_ctx_t *	ctx	the new request context to add.

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ctx_find_required¶

NONULL in3_ctx_t* ctx_find_required(const in3_ctx_t *parent, const char *method);

searches within the required request contextes for one with the given method.

This method is used internaly to find a previously added context.

arguments:

in3_ctx_tconst , *	parent	the current request context.
`const char *`	method	the method of the rpc-request.

ctx_remove_required¶

NONULL in3_ret_t ctx_remove_required(in3_ctx_t *parent, in3_ctx_t *ctx, bool rec);

removes a required context after usage.

removing will also call free_ctx to free resources.

arguments:

in3_ctx_t *	parent	the current request context.
in3_ctx_t *	ctx	the request context to remove.
`bool`	rec	if true all sub contexts will aösp be removed

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ctx_check_response_error¶

NONULL in3_ret_t ctx_check_response_error(in3_ctx_t *c, int i);

check if the response contains a error-property and reports this as error in the context.

arguments:

in3_ctx_t *	c	the current request context.
`int`	i	the index of the request to check (if this is a batch-request, otherwise 0).

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ctx_get_error¶

NONULL in3_ret_t ctx_get_error(in3_ctx_t *ctx, int id);

determins the errorcode for the given request.

arguments:

in3_ctx_t *	ctx	the current request context.
`int`	id	the index of the request to check (if this is a batch-request, otherwise 0).

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_client_rpc_ctx_raw¶

NONULL in3_ctx_t* in3_client_rpc_ctx_raw(in3_t *c, const char *request);

sends a request and returns a context used to access the result or errors.

This context MUST be freed with ctx_free(ctx) after usage to release the resources.

arguments:

in3_t *	c	the client config.
`const char *`	request	rpc request.

in3_client_rpc_ctx¶

NONULL in3_ctx_t* in3_client_rpc_ctx(in3_t *c, const char *method, const char *params);

sends a request and returns a context used to access the result or errors.

This context MUST be freed with ctx_free(ctx) after usage to release the resources.

arguments:

in3_t *	c	the clientt config.
`const char *`	method	rpc method.
`const char *`	params	params as string.

in3_ctx_get_proof¶

NONULL in3_proof_t in3_ctx_get_proof(in3_ctx_t *ctx, int i);

determines the proof as set in the request.

arguments:

in3_ctx_t *	ctx	the current request.
`int`	i	the index within the request.

returns: in3_proof_tNONULL

ctx_get_node¶

static NONULL in3_node_t* ctx_get_node(const in3_chain_t *chain, const node_match_t *node);

arguments:

in3_chain_tconst , *	chain
node_match_tconst , *	node

returns: in3_node_tNONULL , *

ctx_get_node_weight¶

static NONULL in3_node_weight_t* ctx_get_node_weight(const in3_chain_t *chain, const node_match_t *node);

arguments:

in3_chain_tconst , *	chain
node_match_tconst , *	node

returns: in3_node_weight_tNONULL , *

ctx_send_sub_request¶

in3_ret_t ctx_send_sub_request(in3_ctx_t *parent, char *method, char *params, char *in3, d_token_t **result);

arguments:

in3_ctx_t *	parent
`char *`	method
`char *`	params
`char *`	in3
d_token_t **	result

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

plugin.h¶

this file defines the plugin-contexts

File: c/src/core/client/plugin.h

in3_plugin_is_registered (client,action)¶

checks if a plugin for specified action is registered with the client

#define in3_plugin_is_registered (client,action) ((client)->plugin_acts & (action))

plugin_register (c,acts,action_fn,data,replace_ex)¶

registers a plugin and uses the function name as plugin name

#define plugin_register (c,acts,action_fn,data,replace_ex) in3_plugin_register(#action_fn, c, acts, action_fn, data, replace_ex)

vc_err (vc,msg)¶

#define vc_err (vc,msg) vc_set_error(vc, NULL)

d_signature_type_t¶

type of the requested signature

The enum type contains the following values:

SIGN_EC_RAW	0	sign the data directly
SIGN_EC_HASH	1	hash and sign the data

in3_request_t¶

request-object.

represents a RPC-request

The stuct contains following fields:

`char *`	payload	the payload to send
`char **`	urls	array of urls
`uint_fast16_t`	urls_len	number of urls
in3_ctxstruct , *	ctx	the current context
`void *`	cptr	a custom ptr to hold information during
`uint32_t`	wait	time in ms to wait before sending out the request

in3_transport_legacy¶

typedef in3_ret_t(* in3_transport_legacy) (in3_request_t *request)

returns: in3_ret_t(* the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_sign_account_ctx_t¶

action context when retrieving the account of a signer.

The stuct contains following fields:

in3_ctxstruct , *	ctx	the context of the request in order report errors
address_t	account	the account to use for the signature

in3_sign_prepare_ctx_t¶

action context when retrieving the account of a signer.

The stuct contains following fields:

in3_ctxstruct , *	ctx	the context of the request in order report errors
address_t	account	the account to use for the signature
bytes_t	old_tx
bytes_t	new_tx

in3_sign_ctx_t¶

signing context.

This Context is passed to the signer-function.

The stuct contains following fields:

`uint8_t`	signature	the resulting signature needs to be writte into these bytes
d_signature_type_t	type	the type of signature
in3_ctxstruct , *	ctx	the context of the request in order report errors
bytes_t	message	the message to sign
bytes_t	account	the account to use for the signature

in3_configure_ctx_t¶

context used during configure

The stuct contains following fields:

in3_t *	client	the client to configure
d_token_t *	token	the token not handled yet
`char *`	error_msg	message in case of an incorrect config

in3_get_config_ctx_t¶

context used during get config

The stuct contains following fields:

in3_t *	client	the client to configure
sb_t *	sb	stringbuilder to add json-config

in3_storage_get_item¶

storage handler function for reading from cache.

typedef bytes_t*(* in3_storage_get_item) (void *cptr, const char *key)

returns: bytes_t *(* : the found result. if the key is found this function should return the values as bytes otherwise NULL.

in3_storage_set_item¶

storage handler function for writing to the cache.

typedef void(* in3_storage_set_item) (void *cptr, const char *key, bytes_t *value)

in3_storage_clear¶

storage handler function for clearing the cache.

typedef void(* in3_storage_clear) (void *cptr)

in3_cache_ctx_t¶

context used during get config

The stuct contains following fields:

in3_ctx_t *	ctx	the request context
`char *`	key	the key to fetch
bytes_t *	content	the content to set

in3_plugin_register¶

in3_ret_t in3_plugin_register(const char *name, in3_t *c, in3_plugin_supp_acts_t acts, in3_plugin_act_fn action_fn, void *data, bool replace_ex);

registers a plugin with the client

arguments:

`const char *`	name	the name of the plugin (optional), which is ignored if LOGGIN is not defined
in3_t *	c	the client
`in3_plugin_supp_acts_t`	acts	the actions to register for combined with OR
in3_plugin_act_fn	action_fn	the plugin action function
`void *`	data	an optional data or config struct which will be passed to the action function when executed
`bool`	replace_ex	if this is true and an plugin with the same action is already registered, it will replace it

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_default¶

void in3_register_default(plgn_register reg_fn);

adds a plugin rregister function to the default.

All defaults functions will automaticly called and registered for every new in3_t instance.

arguments:

plgn_register

reg_fn

in3_plugin_execute_all¶

in3_ret_t in3_plugin_execute_all(in3_t *c, in3_plugin_act_t action, void *plugin_ctx);

executes all plugins irrespective of their return values, returns first error (if any)

arguments:

in3_t *	c
in3_plugin_act_t	action
`void *`	plugin_ctx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_plugin_execute_first¶

in3_ret_t in3_plugin_execute_first(in3_ctx_t *ctx, in3_plugin_act_t action, void *plugin_ctx);

executes all plugin actions one-by-one, stops when a plugin returns anything other than IN3_EIGNORE.

returns IN3_EPLGN_NONE if no plugin was able to handle specified action, otherwise returns IN3_OK plugin errors are reported via the in3_ctx_t

arguments:

in3_ctx_t *	ctx
in3_plugin_act_t	action
`void *`	plugin_ctx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_plugin_execute_first_or_none¶

in3_ret_t in3_plugin_execute_first_or_none(in3_ctx_t *ctx, in3_plugin_act_t action, void *plugin_ctx);

same as in3_plugin_execute_first(), but returns IN3_OK even if no plugin could handle specified action

arguments:

in3_ctx_t *	ctx
in3_plugin_act_t	action
`void *`	plugin_ctx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_rpc_handle_start¶

NONULL sb_t* in3_rpc_handle_start(in3_rpc_handle_ctx_t *hctx);

creates a response and returns a stringbuilder to add the result-data.

arguments:

in3_rpc_handle_ctx_t *

hctx

returns: sb_tNONULL , *

in3_rpc_handle_finish¶

NONULL in3_ret_t in3_rpc_handle_finish(in3_rpc_handle_ctx_t *hctx);

finish the response.

arguments:

in3_rpc_handle_ctx_t *

hctx

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_rpc_handle_with_bytes¶

NONULL in3_ret_t in3_rpc_handle_with_bytes(in3_rpc_handle_ctx_t *hctx, bytes_t data);

creates a response with bytes.

arguments:

in3_rpc_handle_ctx_t *	hctx
bytes_t	data

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_rpc_handle_with_string¶

NONULL in3_ret_t in3_rpc_handle_with_string(in3_rpc_handle_ctx_t *hctx, char *data);

creates a response with string.

arguments:

in3_rpc_handle_ctx_t *	hctx
`char *`	data

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_rpc_handle_with_int¶

NONULL in3_ret_t in3_rpc_handle_with_int(in3_rpc_handle_ctx_t *hctx, uint64_t value);

creates a response with a value which is added as hex-string.

arguments:

in3_rpc_handle_ctx_t *	hctx
`uint64_t`	value

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_get_request_payload¶

char* in3_get_request_payload(in3_request_t *request);

getter to retrieve the payload from a in3_request_t struct

arguments:

request

request struct

returns: char *

in3_get_request_urls¶

char** in3_get_request_urls(in3_request_t *request);

getter to retrieve the urls list from a in3_request_t struct

arguments:

request

request struct

returns: char **

in3_get_request_urls_len¶

int in3_get_request_urls_len(in3_request_t *request);

getter to retrieve the urls list length from a in3_request_t struct

arguments:

request

request struct

returns: int

in3_get_request_timeout¶

uint32_t in3_get_request_timeout(in3_request_t *request);

getter to retrieve the urls list length from a in3_request_t struct

arguments:

request

request struct

returns: uint32_t

in3_req_add_response¶

NONULL void in3_req_add_response(in3_request_t *req, int index, bool is_error, const char *data, int data_len, uint32_t time);

adds a response for a request-object.

This function should be used in the transport-function to set the response.

arguments:

in3_request_t *	req	the the request
`int`	index	the index of the url, since this request could go out to many urls
`bool`	is_error	if true this will be reported as error. the message should then be the error-message
`const char *`	data	the data or the the string
`int`	data_len	the length of the data or the the string (use -1 if data is a null terminated string)
`uint32_t`	time	the time this request took in ms or 0 if not possible (it will be used to calculate the weights)

returns: NONULL void

in3_ctx_add_response¶

NONULL void in3_ctx_add_response(in3_ctx_t *ctx, int index, bool is_error, const char *data, int data_len, uint32_t time);

adds a response to a context.

This function should be used in the transport-function to set the response.

arguments:

in3_ctx_t *	ctx	the current context
`int`	index	the index of the url, since this request could go out to many urls
`bool`	is_error	if true this will be reported as error. the message should then be the error-message
`const char *`	data	the data or the the string
`int`	data_len	the length of the data or the the string (use -1 if data is a null terminated string)
`uint32_t`	time	the time this request took in ms or 0 if not possible (it will be used to calculate the weights)

returns: NONULL void

in3_set_default_legacy_transport¶

void in3_set_default_legacy_transport(in3_transport_legacy transport);

defines a default transport which is used when creating a new client.

arguments:

in3_transport_legacy transport the default transport-function.

in3_sign_ctx_get_message¶

bytes_t in3_sign_ctx_get_message(in3_sign_ctx_t *ctx);

helper function to retrieve and message from a in3_sign_ctx_t

arguments:

in3_sign_ctx_t *

ctx

the signer context

returns: bytes_t

in3_sign_ctx_get_account¶

bytes_t in3_sign_ctx_get_account(in3_sign_ctx_t *ctx);

helper function to retrieve and account from a in3_sign_ctx_t

arguments:

in3_sign_ctx_t *

ctx

the signer context

returns: bytes_t

in3_sign_ctx_get_signature¶

uint8_t* in3_sign_ctx_get_signature(in3_sign_ctx_t *ctx);

helper function to retrieve the signature from a in3_sign_ctx_t

arguments:

in3_sign_ctx_t *

ctx

the signer context

returns: uint8_t *

create_sign_ctx¶

NONULL in3_sign_ctx_t* create_sign_ctx(in3_ctx_t *ctx);

creates a signer ctx to be used for async signing.

arguments:

ctx

the rpc context

returns: in3_sign_ctx_tNONULL , *

in3_set_storage_handler¶

void in3_set_storage_handler(in3_t *c, in3_storage_get_item get_item, in3_storage_set_item set_item, in3_storage_clear clear, void *cptr);

create a new storage handler-object to be set on the client.

the caller will need to free this pointer after usage.

arguments:

in3_t *	c	the incubed client
in3_storage_get_item	get_item	function pointer returning a stored value for the given key.
in3_storage_set_item	set_item	function pointer setting a stored value for the given key.
in3_storage_clear	clear	function pointer clearing all contents of cache.
`void *`	cptr	custom pointer which will will be passed to functions

vc_set_error¶

in3_ret_t vc_set_error(in3_vctx_t *vc, char *msg);

arguments:

in3_vctx_t *	vc	the verification context.
`char *`	msg	the error message.

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

bytes.h¶

util helper on byte arrays.

File: c/src/core/util/bytes.h

bb_new ()¶

creates a new bytes_builder with a initial size of 32 bytes

#define bb_new () bb_newl(32)

bb_read (bb,i,vptr)¶

#define bb_read (_bb_,_i_,_vptr_) bb_readl((_bb_), (_i_), (_vptr_), sizeof(*_vptr_))

bb_read_next (bb,iptr,vptr)¶

#define bb_read_next (_bb_,_iptr_,_vptr_) do {                                          \
    size_t _l_ = sizeof(*_vptr_);               \
    bb_readl((_bb_), *(_iptr_), (_vptr_), _l_); \
    *(_iptr_) += _l_;                           \
  } while (0)

bb_readl (bb,i,vptr,l)¶

#define bb_readl (_bb_,_i_,_vptr_,_l_) memcpy((_vptr_), (_bb_)->b.data + (_i_), _l_)

b_read (b,i,vptr)¶

#define b_read (_b_,_i_,_vptr_) b_readl((_b_), (_i_), _vptr_, sizeof(*_vptr_))

b_readl (b,i,vptr,l)¶

#define b_readl (_b_,_i_,_vptr_,_l_) memcpy(_vptr_, (_b_)->data + (_i_), (_l_))

address_t¶

pointer to a 20byte address

typedef uint8_t address_t[20]

bytes32_t¶

pointer to a 32byte word

typedef uint8_t bytes32_t[32]

wlen_t¶

number of bytes within a word (min 1byte but usually a uint)

typedef uint_fast8_t wlen_t

bytes_t¶

a byte array

The stuct contains following fields:

`uint8_t *`	data	the byte-data
`uint32_t`	len	the length of the array ion bytes

b_new¶

RETURNS_NONULL bytes_t* b_new(const uint8_t *data, uint32_t len);

allocates a new byte array with 0 filled

arguments:

`const uint8_t *`	data
`uint32_t`	len

returns: bytes_tRETURNS_NONULL , *

b_print¶

NONULL void b_print(const bytes_t *a);

prints a the bytes as hex to stdout

arguments:

a

returns: NONULL void

ba_print¶

NONULL void ba_print(const uint8_t *a, size_t l);

prints a the bytes as hex to stdout

arguments:

`const uint8_t *`	a
`size_t`	l

returns: NONULL void

b_cmp¶

NONULL int b_cmp(const bytes_t *a, const bytes_t *b);

compares 2 byte arrays and returns 1 for equal and 0 for not equal

arguments:

bytes_tconst , *	a
bytes_tconst , *	b

returns: NONULL int

bytes_cmp¶

int bytes_cmp(const bytes_t a, const bytes_t b);

compares 2 byte arrays and returns 1 for equal and 0 for not equal

arguments:

bytes_tconst	a
bytes_tconst	b

returns: int

b_free¶

void b_free(bytes_t *a);

frees the data

arguments:

bytes_t *

a

b_dup¶

NONULL bytes_t* b_dup(const bytes_t *a);

clones a byte array

arguments:

a

returns: bytes_tNONULL , *

b_read_byte¶

NONULL uint8_t b_read_byte(bytes_t *b, size_t *pos);

reads a byte on the current position and updates the pos afterwards.

arguments:

bytes_t *	b
`size_t *`	pos

returns: NONULL uint8_t

b_read_int¶

NONULL uint32_t b_read_int(bytes_t *b, size_t *pos);

reads a integer on the current position and updates the pos afterwards.

arguments:

bytes_t *	b
`size_t *`	pos

returns: NONULL uint32_t

b_read_long¶

NONULL uint64_t b_read_long(bytes_t *b, size_t *pos);

reads a long on the current position and updates the pos afterwards.

arguments:

bytes_t *	b
`size_t *`	pos

returns: NONULL uint64_t

b_new_chars¶

NONULL char* b_new_chars(bytes_t *b, size_t *pos);

creates a new string (needs to be freed) on the current position and updates the pos afterwards.

arguments:

bytes_t *	b
`size_t *`	pos

returns: NONULL char *

b_new_fixed_bytes¶

NONULL bytes_t* b_new_fixed_bytes(bytes_t *b, size_t *pos, int len);

reads bytes with a fixed length on the current position and updates the pos afterwards.

arguments:

bytes_t *	b
`size_t *`	pos
`int`	len

returns: bytes_tNONULL , *

bb_newl¶

bytes_builder_t* bb_newl(size_t l);

creates a new bytes_builder

arguments:

size_t l

returns: bytes_builder_t *

bb_free¶

NONULL void bb_free(bytes_builder_t *bb);

frees a bytebuilder and its content.

arguments:

bb

returns: NONULL void

bb_check_size¶

NONULL int bb_check_size(bytes_builder_t *bb, size_t len);

internal helper to increase the buffer if needed

arguments:

bytes_builder_t *	bb
`size_t`	len

returns: NONULL int

bb_write_chars¶

NONULL void bb_write_chars(bytes_builder_t *bb, char *c, int len);

writes a string to the builder.

arguments:

bytes_builder_t *	bb
`char *`	c
`int`	len

returns: NONULL void

bb_write_dyn_bytes¶

NONULL void bb_write_dyn_bytes(bytes_builder_t *bb, const bytes_t *src);

writes bytes to the builder with a prefixed length.

arguments:

bytes_builder_t *	bb
bytes_tconst , *	src

returns: NONULL void

bb_write_fixed_bytes¶

NONULL void bb_write_fixed_bytes(bytes_builder_t *bb, const bytes_t *src);

writes fixed bytes to the builder.

arguments:

bytes_builder_t *	bb
bytes_tconst , *	src

returns: NONULL void

bb_write_int¶

NONULL void bb_write_int(bytes_builder_t *bb, uint32_t val);

writes a ineteger to the builder.

arguments:

bytes_builder_t *	bb
`uint32_t`	val

returns: NONULL void

bb_write_long¶

NONULL void bb_write_long(bytes_builder_t *bb, uint64_t val);

writes s long to the builder.

arguments:

bytes_builder_t *	bb
`uint64_t`	val

returns: NONULL void

bb_write_long_be¶

NONULL void bb_write_long_be(bytes_builder_t *bb, uint64_t val, int len);

writes any integer value with the given length of bytes

arguments:

bytes_builder_t *	bb
`uint64_t`	val
`int`	len

returns: NONULL void

bb_write_byte¶

NONULL void bb_write_byte(bytes_builder_t *bb, uint8_t val);

writes a single byte to the builder.

arguments:

bytes_builder_t *	bb
`uint8_t`	val

returns: NONULL void

bb_write_raw_bytes¶

NONULL void bb_write_raw_bytes(bytes_builder_t *bb, void *ptr, size_t len);

writes the bytes to the builder.

arguments:

bytes_builder_t *	bb
`void *`	ptr
`size_t`	len

returns: NONULL void

bb_clear¶

NONULL void bb_clear(bytes_builder_t *bb);

resets the content of the builder.

arguments:

bb

returns: NONULL void

bb_replace¶

NONULL void bb_replace(bytes_builder_t *bb, int offset, int delete_len, uint8_t *data, int data_len);

replaces or deletes a part of the content.

arguments:

bytes_builder_t *	bb
`int`	offset
`int`	delete_len
`uint8_t *`	data
`int`	data_len

returns: NONULL void

bb_move_to_bytes¶

RETURNS_NONULL NONULL bytes_t* bb_move_to_bytes(bytes_builder_t *bb);

frees the builder and moves the content in a newly created bytes struct (which needs to be freed later).

arguments:

bb

returns: bytes_tRETURNS_NONULL NONULL , *

bb_read_long¶

NONULL uint64_t bb_read_long(bytes_builder_t *bb, size_t *i);

reads a long from the builder

arguments:

bytes_builder_t *	bb
`size_t *`	i

returns: NONULL uint64_t

bb_read_int¶

NONULL uint32_t bb_read_int(bytes_builder_t *bb, size_t *i);

reads a int from the builder

arguments:

bytes_builder_t *	bb
`size_t *`	i

returns: NONULL uint32_t

bytes¶

static bytes_t bytes(uint8_t *a, uint32_t len);

converts the given bytes to a bytes struct

arguments:

`uint8_t *`	a
`uint32_t`	len

returns: bytes_t

cloned_bytes¶

bytes_t cloned_bytes(bytes_t data);

cloned the passed data

arguments:

bytes_t

data

returns: bytes_t

b_optimize_len¶

static NONULL void b_optimize_len(bytes_t *b);

< changed the data and len to remove leading 0-bytes

arguments:

bytes_t *

b

returns: NONULL void

data.h¶

json-parser.

The parser can read from :

json
bin

When reading from json all ‘0x’… values will be stored as bytes_t. If the value is lower than 0xFFFFFFF, it is converted as integer.

File: c/src/core/util/data.h

DATA_DEPTH_MAX¶

the max DEPTH of the JSON-data allowed.

It will throw an error if reached.

#define DATA_DEPTH_MAX 11

printX¶

#define printX printf

fprintX¶

#define fprintX fprintf

snprintX¶

#define snprintX snprintf

vprintX¶

#define vprintX vprintf

d_type_t¶

type of a token.

The enum type contains the following values:

T_BYTES	0	content is stored as data ptr.
T_STRING	1	content is stored a c-str
T_ARRAY	2	the node is an array with the length stored in length
T_OBJECT	3	the node is an object with properties
T_BOOLEAN	4	boolean with the value stored in len
T_INTEGER	5	a integer with the value stored
T_NULL	6	a NULL-value

d_key_t¶

typedef uint16_t d_key_t

d_token_t¶

a token holding any kind of value.

use d_type, d_len or the cast-function to get the value.

The stuct contains following fields:

`uint8_t *`	data	the byte or string-data
`uint32_t`	len	the length of the content (or number of properties) depending + type.
`d_key_t`	key	the key of the property.

str_range_t¶

internal type used to represent the a range within a string.

The stuct contains following fields:

`char *`	data	pointer to the start of the string
`size_t`	len	len of the characters

json_ctx_t¶

parser for json or binary-data.

it needs to freed after usage.

The stuct contains following fields:

d_token_t *	result	the list of all tokens. the first token is the main-token as returned by the parser.
`char *`	c	pointer to the src-data
`size_t`	allocated	amount of tokens allocated result
`size_t`	len	number of tokens in result
`size_t`	depth	max depth of tokens in result

d_iterator_t¶

iterator over elements of a array opf object.

usage:

for (d_iterator_t iter = d_iter( parent ); iter.left ; d_iter_next(&iter)) {
  uint32_t val = d_int(iter.token);
}

The stuct contains following fields:

d_token_t *	token	current token
`int`	left	number of result left

d_to_bytes¶

bytes_t d_to_bytes(d_token_t *item);

returns the byte-representation of token.

In case of a number it is returned as bigendian. booleans as 0x01 or 0x00 and NULL as 0x. Objects or arrays will return 0x.

arguments:

item

returns: bytes_t

d_bytes_to¶

int d_bytes_to(d_token_t *item, uint8_t *dst, const int max);

writes the byte-representation to the dst.

details see d_to_bytes.

arguments:

d_token_t *	item
`uint8_t *`	dst
`const int`	max

returns: int

d_bytes¶

bytes_t* d_bytes(const d_token_t *item);

returns the value as bytes (Carefully, make sure that the token is a bytes-type!)

arguments:

item

returns: bytes_t *

d_bytesl¶

bytes_t* d_bytesl(d_token_t *item, size_t l);

returns the value as bytes with length l (may reallocates)

arguments:

d_token_t *	item
`size_t`	l

returns: bytes_t *

d_string¶

char* d_string(const d_token_t *item);

converts the value as string.

Make sure the type is string!

arguments:

item

returns: char *

d_int¶

int32_t d_int(const d_token_t *item);

returns the value as integer.

only if type is integer

arguments:

item

returns: int32_t

d_intd¶

int32_t d_intd(const d_token_t *item, const uint32_t def_val);

returns the value as integer or if NULL the default.

only if type is integer

arguments:

d_token_tconst , *	item
`const uint32_t`	def_val

returns: int32_t

d_long¶

uint64_t d_long(const d_token_t *item);

returns the value as long.

only if type is integer or bytes, but short enough

arguments:

item

returns: uint64_t

d_longd¶

uint64_t d_longd(const d_token_t *item, const uint64_t def_val);

returns the value as long or if NULL the default.

only if type is integer or bytes, but short enough

arguments:

d_token_tconst , *	item
`const uint64_t`	def_val

returns: uint64_t

d_create_bytes_vec¶

bytes_t** d_create_bytes_vec(const d_token_t *arr);

arguments:

arr

returns: bytes_t **

d_type¶

static d_type_t d_type(const d_token_t *item);

creates a array of bytes from JOSN-array

type of the token

arguments:

item

returns: d_type_t

d_len¶

static int d_len(const d_token_t *item);

< number of elements in the token (only for object or array, other will return 0)

arguments:

item

returns: int

d_eq¶

bool d_eq(const d_token_t *a, const d_token_t *b);

compares 2 token and if the value is equal

arguments:

d_token_tconst , *	a
d_token_tconst , *	b

returns: bool

keyn¶

NONULL d_key_t keyn(const char *c, const size_t len);

generates the keyhash for the given stringrange as defined by len

arguments:

`const char *`	c
`const size_t`	len

returns: NONULL d_key_t

d_get¶

d_token_t* d_get(d_token_t *item, const uint16_t key);

returns the token with the given propertyname (only if item is a object)

arguments:

d_token_t *	item
`const uint16_t`	key

returns: d_token_t *

d_get_or¶

d_token_t* d_get_or(d_token_t *item, const uint16_t key1, const uint16_t key2);

returns the token with the given propertyname or if not found, tries the other.

(only if item is a object)

arguments:

d_token_t *	item
`const uint16_t`	key1
`const uint16_t`	key2

returns: d_token_t *

d_get_at¶

d_token_t* d_get_at(d_token_t *item, const uint32_t index);

returns the token of an array with the given index

arguments:

d_token_t *	item
`const uint32_t`	index

returns: d_token_t *

d_next¶

d_token_t* d_next(d_token_t *item);

returns the next sibling of an array or object

arguments:

item

returns: d_token_t *

d_serialize_binary¶

NONULL void d_serialize_binary(bytes_builder_t *bb, d_token_t *t);

write the token as binary data into the builder

arguments:

bytes_builder_t *	bb
d_token_t *	t

returns: NONULL void

parse_binary¶

NONULL json_ctx_t* parse_binary(const bytes_t *data);

parses the data and returns the context with the token, which needs to be freed after usage!

arguments:

data

returns: json_ctx_tNONULL , *

parse_binary_str¶

NONULL json_ctx_t* parse_binary_str(const char *data, int len);

parses the data and returns the context with the token, which needs to be freed after usage!

arguments:

`const char *`	data
`int`	len

returns: json_ctx_tNONULL , *

parse_json¶

NONULL json_ctx_t* parse_json(const char *js);

parses json-data, which needs to be freed after usage!

arguments:

const char * js

returns: json_ctx_tNONULL , *

json_free¶

NONULL void json_free(json_ctx_t *parser_ctx);

frees the parse-context after usage

arguments:

parser_ctx

returns: NONULL void

d_to_json¶

NONULL str_range_t d_to_json(const d_token_t *item);

returns the string for a object or array.

This only works for json as string. For binary it will not work!

arguments:

item

returns: str_range_tNONULL

d_create_json¶

NONULL char* d_create_json(d_token_t *item);

creates a json-string.

It does not work for objects if the parsed data were binary!

arguments:

item

returns: NONULL char *

json_create¶

json_ctx_t* json_create();

returns: json_ctx_t *

json_create_null¶

NONULL d_token_t* json_create_null(json_ctx_t *jp);

arguments:

jp

json_create_bool¶

NONULL d_token_t* json_create_bool(json_ctx_t *jp, bool value);

arguments:

json_ctx_t *	jp
`bool`	value

json_create_int¶

NONULL d_token_t* json_create_int(json_ctx_t *jp, uint64_t value);

arguments:

json_ctx_t *	jp
`uint64_t`	value

json_create_string¶

NONULL d_token_t* json_create_string(json_ctx_t *jp, char *value);

arguments:

json_ctx_t *	jp
`char *`	value

json_create_bytes¶

NONULL d_token_t* json_create_bytes(json_ctx_t *jp, bytes_t value);

arguments:

json_ctx_t *	jp
bytes_t	value

json_create_object¶

NONULL d_token_t* json_create_object(json_ctx_t *jp);

arguments:

jp

json_create_array¶

NONULL d_token_t* json_create_array(json_ctx_t *jp);

arguments:

jp

json_object_add_prop¶

NONULL d_token_t* json_object_add_prop(d_token_t *object, d_key_t key, d_token_t *value);

arguments:

d_token_t *	object
`d_key_t`	key
d_token_t *	value

json_array_add_value¶

NONULL d_token_t* json_array_add_value(d_token_t *object, d_token_t *value);

arguments:

d_token_t *	object
d_token_t *	value

d_get_keystr¶

char* d_get_keystr(d_key_t k);

returns the string for a key.

This only works track_keynames was activated before!

arguments:

d_key_t k

returns: char *

d_track_keynames¶

void d_track_keynames(uint8_t v);

activates the keyname-cache, which stores the string for the keys when parsing.

arguments:

uint8_t v

d_clear_keynames¶

void d_clear_keynames();

delete the cached keynames

key¶

static NONULL d_key_t key(const char *c);

arguments:

const char * c

returns: NONULL d_key_t

d_get_stringk¶

static char* d_get_stringk(d_token_t *r, d_key_t k);

reads token of a property as string.

arguments:

d_token_t *	r
`d_key_t`	k

returns: char *

d_get_string¶

static char* d_get_string(d_token_t *r, char *k);

reads token of a property as string.

arguments:

d_token_t *	r
`char *`	k

returns: char *

d_get_string_at¶

static char* d_get_string_at(d_token_t *r, uint32_t pos);

reads string at given pos of an array.

arguments:

d_token_t *	r
`uint32_t`	pos

returns: char *

d_get_intk¶

static int32_t d_get_intk(d_token_t *r, d_key_t k);

reads token of a property as int.

arguments:

d_token_t *	r
`d_key_t`	k

returns: int32_t

d_get_intkd¶

static int32_t d_get_intkd(d_token_t *r, d_key_t k, uint32_t d);

reads token of a property as int.

arguments:

d_token_t *	r
`d_key_t`	k
`uint32_t`	d

returns: int32_t

d_get_int¶

static int32_t d_get_int(d_token_t *r, char *k);

reads token of a property as int.

arguments:

d_token_t *	r
`char *`	k

returns: int32_t

d_get_int_at¶

static int32_t d_get_int_at(d_token_t *r, uint32_t pos);

reads a int at given pos of an array.

arguments:

d_token_t *	r
`uint32_t`	pos

returns: int32_t

d_get_longk¶

static uint64_t d_get_longk(d_token_t *r, d_key_t k);

reads token of a property as long.

arguments:

d_token_t *	r
`d_key_t`	k

returns: uint64_t

d_get_longkd¶

static uint64_t d_get_longkd(d_token_t *r, d_key_t k, uint64_t d);

reads token of a property as long.

arguments:

d_token_t *	r
`d_key_t`	k
`uint64_t`	d

returns: uint64_t

d_get_long¶

static uint64_t d_get_long(d_token_t *r, char *k);

reads token of a property as long.

arguments:

d_token_t *	r
`char *`	k

returns: uint64_t

d_get_long_at¶

static uint64_t d_get_long_at(d_token_t *r, uint32_t pos);

reads long at given pos of an array.

arguments:

d_token_t *	r
`uint32_t`	pos

returns: uint64_t

d_get_bytesk¶

static bytes_t* d_get_bytesk(d_token_t *r, d_key_t k);

reads token of a property as bytes.

arguments:

d_token_t *	r
`d_key_t`	k

returns: bytes_t *

d_get_bytes¶

static bytes_t* d_get_bytes(d_token_t *r, char *k);

reads token of a property as bytes.

arguments:

d_token_t *	r
`char *`	k

returns: bytes_t *

d_get_bytes_at¶

static bytes_t* d_get_bytes_at(d_token_t *r, uint32_t pos);

reads bytes at given pos of an array.

arguments:

d_token_t *	r
`uint32_t`	pos

returns: bytes_t *

d_is_binary_ctx¶

static bool d_is_binary_ctx(json_ctx_t *ctx);

check if the parser context was created from binary data.

arguments:

ctx

returns: bool

d_get_byteskl¶

bytes_t* d_get_byteskl(d_token_t *r, d_key_t k, uint32_t minl);

arguments:

d_token_t *	r
`d_key_t`	k
`uint32_t`	minl

returns: bytes_t *

d_getl¶

d_token_t* d_getl(d_token_t *item, uint16_t k, uint32_t minl);

arguments:

d_token_t *	item
`uint16_t`	k
`uint32_t`	minl

returns: d_token_t *

d_iter¶

d_iterator_t d_iter(d_token_t *parent);

creates a iterator for a object or array

arguments:

parent

returns: d_iterator_t

d_iter_next¶

static bool d_iter_next(d_iterator_t *const iter);

fetched the next token an returns a boolean indicating whther there is a next or not.

arguments:

d_iterator_t *const

iter

returns: bool

debug.h¶

logs debug data only if the DEBUG-flag is set.

File: c/src/core/util/debug.h

dbg_log (msg,…)¶

logs a debug-message including file and linenumber

dbg_log_raw (msg,…)¶

logs a debug-message without the filename

msg_dump¶

void msg_dump(const char *s, const unsigned char *data, unsigned len);

dumps the given data as hex coded bytes to stdout

arguments:

`const char *`	s
`const unsigned char *`	data
`unsigned`	len

error.h¶

defines the return-values of a function call.

File: c/src/core/util/error.h

DEPRECATED¶

depreacted-attribute

#define DEPRECATED __attribute__((deprecated))

OPTIONAL_T (t)¶

Optional type similar to C++ std::optional Optional types must be defined prior to usage (e.g.

DEFINE_OPTIONAL_T(int)) Use OPTIONAL_T_UNDEFINED(t) & OPTIONAL_T_VALUE(t, v) for easy initialization (rvalues) Note: Defining optional types for pointers is ill-formed by definition. This is because redundant

#define OPTIONAL_T (t) opt_##t

DEFINE_OPTIONAL_T (t)¶

Optional types must be defined prior to usage (e.g.

DEFINE_OPTIONAL_T(int)) Use OPTIONAL_T_UNDEFINED(t) & OPTIONAL_T_VALUE(t, v) for easy initialization (rvalues)

#define DEFINE_OPTIONAL_T (t) typedef struct {           \
    t    value;              \
    bool defined;            \
  } OPTIONAL_T(t)

OPTIONAL_T_UNDEFINED (t)¶

marks a used value as undefined.

#define OPTIONAL_T_UNDEFINED (t) ((OPTIONAL_T(t)){.defined = false})

OPTIONAL_T_VALUE (t,v)¶

sets the value of an optional type.

#define OPTIONAL_T_VALUE (t,v) ((OPTIONAL_T(t)){.value = v, .defined = true})

in3_ret_t¶

ERROR types used as return values.

All values (except IN3_OK) indicate an error. IN3_WAITING may be treated like an error, since we have stop executing until the response has arrived, but it is a valid return value.

The enum type contains the following values:

IN3_OK	0	Success.
IN3_EUNKNOWN	-1	Unknown error - usually accompanied with specific error msg.
IN3_ENOMEM	-2	No memory.
IN3_ENOTSUP	-3	Not supported.
IN3_EINVAL	-4	Invalid value.
IN3_EFIND	-5	Not found.
IN3_ECONFIG	-6	Invalid config.
IN3_ELIMIT	-7	Limit reached.
IN3_EVERS	-8	Version mismatch.
IN3_EINVALDT	-9	Data invalid, eg. invalid/incomplete JSON
IN3_EPASS	-10	Wrong password.
IN3_ERPC	-11	RPC error (i.e. in3_ctx_t::error set)
IN3_ERPCNRES	-12	RPC no response.
IN3_EUSNURL	-13	USN URL parse error.
IN3_ETRANS	-14	Transport error.
IN3_ERANGE	-15	Not in range.
IN3_WAITING	-16	the process can not be finished since we are waiting for responses
IN3_EIGNORE	-17	Ignorable error.
IN3_EPAYMENT_REQUIRED	-18	payment required
IN3_ENODEVICE	-19	harware wallet device not connected
IN3_EAPDU	-20	error in hardware wallet communication
IN3_EPLGN_NONE	-21	no plugin could handle specified action

in3_errmsg¶

char* in3_errmsg(in3_ret_t err);

converts a error code into a string.

These strings are constants and do not need to be freed.

arguments:

in3_ret_t

err

the error code

returns: char *

scache.h¶

util helper on byte arrays.

File: c/src/core/util/scache.h

cache_props¶

The enum type contains the following values:

CACHE_PROP_MUST_FREE	0x1	indicates the content must be freed
CACHE_PROP_SRC_REQ	0x2	the value holds the src-request
CACHE_PROP_ONLY_EXTERNAL	0x4	should only be freed if the context is external

cache_props_t¶

The enum type contains the following values:

CACHE_PROP_MUST_FREE	0x1	indicates the content must be freed
CACHE_PROP_SRC_REQ	0x2	the value holds the src-request
CACHE_PROP_ONLY_EXTERNAL	0x4	should only be freed if the context is external

cache_entry_t¶

represents a single cache entry in a linked list.

These are used within a request context to cache values and automaticly free them.

The stuct contains following fields:

bytes_t	key	an optional key of the entry
bytes_t	value	the value
`uint8_t`	buffer	the buffer is used to store extra data, which will be cleaned when freed.
`cache_props_t`	props	if true, the cache-entry will be freed when the request context is cleaned up.
cache_entrystruct , *	next	pointer to the next entry.

in3_cache_get_entry¶

bytes_t* in3_cache_get_entry(cache_entry_t *cache, bytes_t *key);

get the entry for a given key.

arguments:

cache_entry_t *	cache	the root entry of the linked list.
bytes_t *	key	the key to compare with

returns: bytes_t *

in3_cache_add_entry¶

cache_entry_t* in3_cache_add_entry(cache_entry_t **cache, bytes_t key, bytes_t value);

adds an entry to the linked list.

arguments:

cache_entry_t **	cache	the root entry of the linked list.
bytes_t	key	an optional key
bytes_t	value	the value of the entry

returns: cache_entry_t *

in3_cache_free¶

void in3_cache_free(cache_entry_t *cache, bool is_external);

clears all entries in the linked list.

arguments:

cache_entry_t *	cache	the root entry of the linked list.
`bool`	is_external	true if this is the root context or an external.

in3_cache_add_ptr¶

static NONULL cache_entry_t* in3_cache_add_ptr(cache_entry_t **cache, void *ptr);

adds a pointer, which should be freed when the context is freed.

arguments:

cache_entry_t **	cache	the root entry of the linked list.
`void *`	ptr	pointer to memory which shold be freed.

returns: cache_entry_tNONULL , *

stringbuilder.h¶

simple string buffer used to dynamicly add content.

File: c/src/core/util/stringbuilder.h

sb_add_hexuint (sb,i)¶

shortcut macro for adding a uint to the stringbuilder using sizeof(i) to automaticly determine the size

#define sb_add_hexuint (sb,i) sb_add_hexuint_l(sb, i, sizeof(i))

sb_t¶

string build struct, which is able to hold and modify a growing string.

The stuct contains following fields:

`char *`	data	the current string (null terminated)
`size_t`	allocted	number of bytes currently allocated
`size_t`	len	the current length of the string

sb_new¶

sb_t* sb_new(const char *chars);

creates a new stringbuilder and copies the inital characters into it.

arguments:

const char * chars

returns: sb_t *

sb_init¶

NONULL sb_t* sb_init(sb_t *sb);

initializes a stringbuilder by allocating memory.

arguments:

sb_t *

sb

returns: sb_tNONULL , *

sb_free¶

NONULL void sb_free(sb_t *sb);

frees all resources of the stringbuilder

arguments:

sb_t *

sb

returns: NONULL void

sb_add_char¶

NONULL sb_t* sb_add_char(sb_t *sb, char c);

add a single character

arguments:

sb_t *	sb
`char`	c

returns: sb_tNONULL , *

sb_add_chars¶

NONULL sb_t* sb_add_chars(sb_t *sb, const char *chars);

adds a string

arguments:

sb_t *	sb
`const char *`	chars

returns: sb_tNONULL , *

sb_add_range¶

NONULL sb_t* sb_add_range(sb_t *sb, const char *chars, int start, int len);

add a string range

arguments:

sb_t *	sb
`const char *`	chars
`int`	start
`int`	len

returns: sb_tNONULL , *

sb_add_key_value¶

NONULL sb_t* sb_add_key_value(sb_t *sb, const char *key, const char *value, int value_len, bool as_string);

adds a value with an optional key.

if as_string is true the value will be quoted.

arguments:

sb_t *	sb
`const char *`	key
`const char *`	value
`int`	value_len
`bool`	as_string

returns: sb_tNONULL , *

sb_add_bytes¶

sb_t* sb_add_bytes(sb_t *sb, const char *prefix, const bytes_t *bytes, int len, bool as_array);

add bytes as 0x-prefixed hexcoded string (including an optional prefix), if len>1 is passed bytes maybe an array ( if as_array==true)

arguments:

sb_t *	sb
`const char *`	prefix
bytes_tconst , *	bytes
`int`	len
`bool`	as_array

returns: sb_t *

sb_add_hexuint_l¶

NONULL sb_t* sb_add_hexuint_l(sb_t *sb, uintmax_t uint, size_t l);

add a integer value as hexcoded, 0x-prefixed string

Other types not supported

arguments:

sb_t *	sb
`uintmax_t`	uint
`size_t`	l

returns: sb_tNONULL , *

sb_add_escaped_chars¶

NONULL sb_t* sb_add_escaped_chars(sb_t *sb, const char *chars);

add chars but escapes all quotes

arguments:

sb_t *	sb
`const char *`	chars

returns: sb_tNONULL , *

sb_add_int¶

NONULL sb_t* sb_add_int(sb_t *sb, uint64_t val);

adds a numeric value to the stringbuilder

arguments:

sb_t *	sb
`uint64_t`	val

returns: sb_tNONULL , *

format_json¶

NONULL char* format_json(const char *json);

format a json string and returns a new string, which needs to be freed

arguments:

const char * json

returns: NONULL char *

sb_add_rawbytes¶

sb_t* sb_add_rawbytes(sb_t *sb, char *prefix, bytes_t b, unsigned int fix_size);

arguments:

sb_t *	sb
`char *`	prefix
bytes_t	b
`unsigned int`	fix_size

returns: sb_t *

utils.h¶

utility functions.

File: c/src/core/util/utils.h

_strtoull (str,endptr,base)¶

#define _strtoull (str,endptr,base) strtoull(str, endptr, base)

SWAP (a,b)¶

simple swap macro for integral types

#define SWAP (a,b) {                \
    void* p = a;   \
    a       = b;   \
    b       = p;   \
  }

min (a,b)¶

simple min macro for interagl types

#define min (a,b) ((a) < (b) ? (a) : (b))

max (a,b)¶

simple max macro for interagl types

#define max (a,b) ((a) > (b) ? (a) : (b))

IS_APPROX (n1,n2,err)¶

Check if n1 & n2 are at max err apart Expects n1 & n2 to be integral types.

#define IS_APPROX (n1,n2,err) ((n1 > n2) ? ((n1 - n2) <= err) : ((n2 - n1) <= err))

STR_IMPL_ (x)¶

simple macro to stringify other macro defs eg.

usage - to concatenate a const with a string at compile time -> define SOME_CONST_UINT 10U printf(“Using default value of “ STR(SOME_CONST_UINT));

#define STR_IMPL_ (x) #x

STR (x)¶

#define STR (x) STR_IMPL_(x)

optimize_len (a,l)¶

changes to pointer (a) and it length (l) to remove leading 0 bytes.

#define optimize_len (a,l) while (l > 1 && *a == 0) { \
    l--;                     \
    a++;                     \
  }

TRY (exp)¶

executes the expression and expects the return value to be a int indicating the error.

if the return value is negative it will stop and return this value otherwise continue.

#define TRY (exp) {                        \
    int _r = (exp);        \
    if (_r < 0) return _r; \
  }

TRY_FINAL (exp,final)¶

executes the expression and expects the return value to be a int indicating the error.

if the return value is negative it will stop and return this value otherwise continue.

#define TRY_FINAL (exp,final) {                           \
    int _r = (exp);           \
    final;                    \
    if (_r < 0) return _r;    \
  }

EXPECT_EQ (exp,val)¶

executes the expression and expects value to equal val.

if not it will return IN3_EINVAL

#define EXPECT_EQ (exp,val) if ((exp) != val) return IN3_EINVAL;

TRY_SET (var,exp)¶

executes the expression and expects the return value to be a int indicating the error.

the return value will be set to a existing variable (var). if the return value is negative it will stop and return this value otherwise continue.

#define TRY_SET (var,exp) {                          \
    var = (exp);             \
    if (var < 0) return var; \
  }

TRY_GOTO (exp)¶

executes the expression and expects the return value to be a int indicating the error.

if the return value is negative it will stop and jump (goto) to a marked position “clean”. it also expects a previously declared variable “in3_ret_t res”.

#define TRY_GOTO (exp) {                          \
    res = (exp);             \
    if (res < 0) goto clean; \
  }

time_func¶

Pluggable functions: Mechanism to replace library functions with custom alternatives.

This is particularly useful for embedded systems which have their own time or rand functions.

eg. // define function with specified signature uint64_t my_time(void* t) { // … }

// then call in3_set_func_*() int main() { in3_set_func_time(my_time); // Henceforth, all library calls will use my_time() instead of the platform default time function } time function defaults to k_uptime_get() for zeohyr and time(NULL) for other platforms expected to return a u64 value representative of time (from epoch/start)

typedef uint64_t(* time_func) (void *t)

returns: uint64_t(*

rand_func¶

rand function defaults to k_uptime_get() for zeohyr and rand() for other platforms expected to return a random number

typedef int(* rand_func) (void *s)

returns: int(*

srand_func¶

srand function defaults to NOOP for zephyr and srand() for other platforms expected to set the seed for a new sequence of random numbers to be returned by in3_rand()

typedef void(* srand_func) (unsigned int s)

bytes_to_long¶

uint64_t bytes_to_long(const uint8_t *data, int len);

converts the bytes to a unsigned long (at least the last max len bytes)

arguments:

`const uint8_t *`	data
`int`	len

returns: uint64_t

bytes_to_int¶

static uint32_t bytes_to_int(const uint8_t *data, int len);

converts the bytes to a unsigned int (at least the last max len bytes)

arguments:

`const uint8_t *`	data
`int`	len

returns: uint32_t

char_to_long¶

uint64_t char_to_long(const char *a, int l);

converts a character into a uint64_t

arguments:

`const char *`	a
`int`	l

returns: uint64_t

hexchar_to_int¶

uint8_t hexchar_to_int(char c);

converts a hexchar to byte (4bit)

arguments:

char c

returns: uint8_t

u64_to_str¶

const char* u64_to_str(uint64_t value, char *pBuf, int szBuf);

converts a uint64_t to string (char*); buffer-size min.

21 bytes

arguments:

`uint64_t`	value
`char *`	pBuf
`int`	szBuf

returns: const char *

hex_to_bytes¶

int hex_to_bytes(const char *hexdata, int hexlen, uint8_t *out, int outlen);

convert a c hex string to a byte array storing it into an existing buffer.

arguments:

`const char *`	hexdata
`int`	hexlen
`uint8_t *`	out
`int`	outlen

returns: int

hex_to_new_bytes¶

bytes_t* hex_to_new_bytes(const char *buf, int len);

convert a c string to a byte array creating a new buffer

arguments:

`const char *`	buf
`int`	len

returns: bytes_t *

bytes_to_hex¶

int bytes_to_hex(const uint8_t *buffer, int len, char *out);

convefrts a bytes into hex

arguments:

`const uint8_t *`	buffer
`int`	len
`char *`	out

returns: int

sha3¶

bytes_t* sha3(const bytes_t *data);

hashes the bytes and creates a new bytes_t

arguments:

data

returns: bytes_t *

keccak¶

int keccak(bytes_t data, void *dst);

writes 32 bytes to the pointer.

arguments:

bytes_t	data
`void *`	dst

returns: int

long_to_bytes¶

void long_to_bytes(uint64_t val, uint8_t *dst);

converts a long to 8 bytes

arguments:

`uint64_t`	val
`uint8_t *`	dst

int_to_bytes¶

void int_to_bytes(uint32_t val, uint8_t *dst);

converts a int to 4 bytes

arguments:

`uint32_t`	val
`uint8_t *`	dst

_strdupn¶

char* _strdupn(const char *src, int len);

duplicate the string

arguments:

`const char *`	src
`int`	len

returns: char *

min_bytes_len¶

int min_bytes_len(uint64_t val);

calculate the min number of byte to represents the len

arguments:

uint64_t val

returns: int

uint256_set¶

void uint256_set(const uint8_t *src, wlen_t src_len, bytes32_t dst);

sets a variable value to 32byte word.

arguments:

`const uint8_t *`	src
wlen_t	src_len
bytes32_t	dst

str_replace¶

char* str_replace(char *orig, const char *rep, const char *with);

replaces a string and returns a copy.

arguments:

`char *`	orig
`const char *`	rep
`const char *`	with

returns: char *

str_replace_pos¶

char* str_replace_pos(char *orig, size_t pos, size_t len, const char *rep);

replaces a string at the given position.

arguments:

`char *`	orig
`size_t`	pos
`size_t`	len
`const char *`	rep

returns: char *

str_find¶

char* str_find(char *haystack, const char *needle);

lightweight strstr() replacements

arguments:

`char *`	haystack
`const char *`	needle

returns: char *

str_remove_html¶

char* str_remove_html(char *data);

remove all html-tags in the text.

arguments:

char * data

returns: char *

current_ms¶

uint64_t current_ms();

current timestamp in ms.

returns: uint64_t

memiszero¶

static bool memiszero(uint8_t *ptr, size_t l);

arguments:

`uint8_t *`	ptr
`size_t`	l

returns: bool

in3_set_func_time¶

void in3_set_func_time(time_func fn);

arguments:

time_func

fn

in3_time¶

uint64_t in3_time(void *t);

arguments:

void * t

returns: uint64_t

in3_set_func_rand¶

void in3_set_func_rand(rand_func fn);

arguments:

rand_func

fn

in3_rand¶

int in3_rand(void *s);

arguments:

void * s

returns: int

in3_set_func_srand¶

void in3_set_func_srand(srand_func fn);

arguments:

srand_func

fn

in3_srand¶

void in3_srand(unsigned int s);

arguments:

unsigned int s

in3_sleep¶

void in3_sleep(uint32_t ms);

arguments:

uint32_t ms

parse_float_val¶

int64_t parse_float_val(const char *data, int32_t expo);

parses a float-string and returns the value as int

arguments:

`const char *`	data	the data string
`int32_t`	expo	the exponent

returns: int64_t

Module pay¶

pay_eth.h¶

USN API.

This header-file defines easy to use function, which are verifying USN-Messages.

File: c/src/pay/eth/pay_eth.h

in3_pay_eth_config_t¶

The stuct contains following fields:

`uint64_t`	bulk_size
`uint64_t`	max_price
`uint64_t`	nonce
`uint64_t`	gas_price

in3_register_pay_eth¶

void in3_register_pay_eth();

pay_eth_configure¶

char* pay_eth_configure(in3_t *c, d_token_t *cconfig);

arguments:

in3_t *	c
d_token_t *	cconfig

returns: char *

zksync.h¶

ZKSync API.

This header-file registers zksync api functions.

File: c/src/pay/zksync/zksync.h

in3_register_zksync¶

in3_ret_t in3_register_zksync(in3_t *c);

arguments:

File: c/src/signer/ledger-nano/signer/ethereum_apdu_client.h

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

Module signer¶

ethereum_apdu_client.h¶

this file defines the incubed configuration struct and it registration.

eth_ledger_set_signer_txn¶

in3_ret_t eth_ledger_set_signer_txn(in3_t *in3, uint8_t *bip_path);

attaches ledger nano hardware wallet signer with incubed .

bip32 path to be given to point the specific public/private key in HD tree for Ethereum!

arguments:

in3_t *	in3
`uint8_t *`	bip_path

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_ledger_get_public_addr¶

in3_ret_t eth_ledger_get_public_addr(uint8_t *i_bip_path, uint8_t *o_public_key);

returns public key at the bip_path .

returns IN3_ENODEVICE error if ledger nano device is not connected

arguments:

`uint8_t *`	i_bip_path
`uint8_t *`	o_public_key

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ledger_signer.h¶

this file defines the incubed configuration struct and it registration.

File: c/src/signer/ledger-nano/signer/ledger_signer.h

eth_ledger_set_signer¶

in3_ret_t eth_ledger_set_signer(in3_t *in3, uint8_t *bip_path);

attaches ledger nano hardware wallet signer with incubed .

bip32 path to be given to point the specific public/private key in HD tree for Ethereum!

arguments:

in3_t *	in3
`uint8_t *`	bip_path

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_ledger_get_public_key¶

in3_ret_t eth_ledger_get_public_key(uint8_t *bip_path, uint8_t *public_key);

returns public key at the bip_path .

returns IN3_ENODEVICE error if ledger nano device is not connected

arguments:

`uint8_t *`	bip_path
`uint8_t *`	public_key

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

signer.h¶

Ethereum Nano verification.

File: c/src/signer/pk-signer/signer.h

hasher_t¶

The enum type contains the following values:

hasher_sha2	0
hasher_sha2d	1
hasher_sha2_ripemd	2
hasher_sha3	3
hasher_sha3k	4
hasher_blake	5
hasher_blaked	6
hasher_blake_ripemd	7
hasher_groestld_trunc	8
hasher_overwinter_prevouts	9
hasher_overwinter_sequence	10
hasher_overwinter_outputs	11
hasher_overwinter_preimage	12
hasher_sapling_preimage	13

eth_set_pk_signer¶

in3_ret_t eth_set_pk_signer(in3_t *in3, bytes32_t pk);

simply signer with one private key.

since the pk pointting to the 32 byte private key is not cloned, please make sure, you manage memory allocation correctly!

simply signer with one private key.

arguments:

in3_t *	in3
bytes32_t	pk

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_set_request_signer¶

in3_ret_t eth_set_request_signer(in3_t *in3, bytes32_t pk);

sets the signer and a pk to the client

arguments:

in3_t *	in3
bytes32_t	pk

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_register_request_signer¶

in3_ret_t eth_register_request_signer(in3_t *in3);

arguments:

in3

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_set_pk_signer_hex¶

uint8_t* eth_set_pk_signer_hex(in3_t *in3, char *key);

simply signer with one private key as hex.

arguments:

in3_t *	in3
`char *`	key

returns: uint8_t *

ec_sign_pk_hash¶

in3_ret_t ec_sign_pk_hash(uint8_t *message, size_t len, uint8_t *pk, hasher_t hasher, uint8_t *dst);

Signs message after hashing it with hasher function given in ‘hasher_t’, with the given private key.

arguments:

`uint8_t *`	message
`size_t`	len
`uint8_t *`	pk
`hasher_t`	hasher
`uint8_t *`	dst

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

ec_sign_pk_raw¶

in3_ret_t ec_sign_pk_raw(uint8_t *message, uint8_t *pk, uint8_t *dst);

Signs message raw with the given private key.

arguments:

`uint8_t *`	message
`uint8_t *`	pk
`uint8_t *`	dst

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

Module transport¶

in3_curl.h¶

transport-handler using libcurl.

File: c/src/transport/curl/in3_curl.h

send_curl¶

in3_ret_t send_curl(void *plugin_data, in3_plugin_act_t action, void *plugin_ctx);

a transport function using curl.

arguments:

`void *`	plugin_data
in3_plugin_act_t	action
`void *`	plugin_ctx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_curl¶

in3_ret_t in3_register_curl(in3_t *c);

registers curl as a default transport.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_http.h¶

transport-handler using simple http.

File: c/src/transport/http/in3_http.h

send_http¶

in3_ret_t send_http(void *plugin_data, in3_plugin_act_t action, void *plugin_ctx);

a very simple transport function, which allows to send http-requests without a dependency to curl.

Here each request will be transformed to http instead of https.

You can use it by setting the transport-function-pointer in the in3_t->transport to this function:

#include <in3/in3_http.h>
...
c->transport = send_http;

arguments:

`void *`	plugin_data
in3_plugin_act_t	action
`void *`	plugin_ctx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_http¶

in3_ret_t in3_register_http(in3_t *c);

registers http as a default transport.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

Module verifier¶

btc.h¶

Bitcoin verification.

File: c/src/verifier/btc/btc.h

in3_register_btc¶

in3_ret_t in3_register_btc(in3_t *c);

this function should only be called once and will register the bitcoin verifier.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_basic.h¶

Ethereum Nanon verification.

File: c/src/verifier/eth1/basic/eth_basic.h

eth_verify_tx_values¶

in3_ret_t eth_verify_tx_values(in3_vctx_t *vc, d_token_t *tx, bytes_t *raw);

verifies internal tx-values.

arguments:

in3_vctx_t *	vc
d_token_t *	tx
bytes_t *	raw

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_eth_getTransaction¶

in3_ret_t eth_verify_eth_getTransaction(in3_vctx_t *vc, bytes_t *tx_hash);

verifies a transaction.

arguments:

in3_vctx_t *	vc
bytes_t *	tx_hash

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_eth_getTransactionByBlock¶

in3_ret_t eth_verify_eth_getTransactionByBlock(in3_vctx_t *vc, d_token_t *blk, uint32_t tx_idx);

verifies a transaction by block hash/number and id.

arguments:

in3_vctx_t *	vc
d_token_t *	blk
`uint32_t`	tx_idx

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_account_proof¶

in3_ret_t eth_verify_account_proof(in3_vctx_t *vc);

verify account-proofs

arguments:

in3_vctx_t *

vc

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_eth_getBlock¶

in3_ret_t eth_verify_eth_getBlock(in3_vctx_t *vc, bytes_t *block_hash, uint64_t blockNumber);

verifies a block

arguments:

in3_vctx_t *	vc
bytes_t *	block_hash
`uint64_t`	blockNumber

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_eth_getBlockTransactionCount¶

in3_ret_t eth_verify_eth_getBlockTransactionCount(in3_vctx_t *vc, bytes_t *block_hash, uint64_t blockNumber);

verifies block transaction count by number or hash

arguments:

in3_vctx_t *	vc
bytes_t *	block_hash
`uint64_t`	blockNumber

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_eth_basic¶

in3_ret_t in3_register_eth_basic(in3_t *c);

this function should only be called once and will register the eth-nano verifier.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_eth_getLog¶

in3_ret_t eth_verify_eth_getLog(in3_vctx_t *vc, int l_logs);

verify logs

arguments:

in3_vctx_t *	vc
`int`	l_logs

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_prepare_unsigned_tx¶

in3_ret_t eth_prepare_unsigned_tx(d_token_t *tx, in3_ctx_t *ctx, bytes_t *dst);

prepares a transaction and writes the data to the dst-bytes.

In case of success, you MUST free only the data-pointer of the dst.

arguments:

d_token_t *	tx	a json-token desribing the transaction
in3_ctx_t *	ctx	the current context
bytes_t *	dst	the bytes to write the result to.

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_sign_raw_tx¶

in3_ret_t eth_sign_raw_tx(bytes_t raw_tx, in3_ctx_t *ctx, address_t from, bytes_t *dst);

signs a unsigned raw transaction and writes the raw data to the dst-bytes.

In case of success, you MUST free only the data-pointer of the dst.

arguments:

bytes_t	raw_tx	the unsigned raw transaction to sign
in3_ctx_t *	ctx	the current context
address_t	from	the address of the account to sign with
bytes_t *	dst	the bytes to write the result to.

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

handle_eth_sendTransaction¶

in3_ret_t handle_eth_sendTransaction(in3_ctx_t *ctx, d_token_t *req);

expects a req-object for a transaction and converts it into a sendRawTransaction after signing.

arguments:

in3_ctx_t *	ctx	the current context
d_token_t *	req	the request

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_wallet_sign¶

RETURNS_NONULL NONULL char* eth_wallet_sign(const char *key, const char *data);

minimum signer for the wallet, returns the signed message which needs to be freed

arguments:

`const char *`	key
`const char *`	data

returns: RETURNS_NONULL NONULL char *

trie.h¶

Patricia Merkle Tree Imnpl

File: c/src/verifier/eth1/basic/trie.h

trie_node_type_t¶

Node types.

The enum type contains the following values:

NODE_EMPTY	0	empty node
NODE_BRANCH	1	a Branch
NODE_LEAF	2	a leaf containing the value.
NODE_EXT	3	a extension

in3_hasher_t¶

hash-function

typedef void(* in3_hasher_t) (bytes_t *src, uint8_t *dst)

in3_codec_add_t¶

codec to organize the encoding of the nodes

typedef void(* in3_codec_add_t) (bytes_builder_t *bb, bytes_t *val)

in3_codec_finish_t¶

typedef void(* in3_codec_finish_t) (bytes_builder_t *bb, bytes_t *dst)

in3_codec_decode_size_t¶

typedef int(* in3_codec_decode_size_t) (bytes_t *src)

returns: int(*

in3_codec_decode_index_t¶

typedef int(* in3_codec_decode_index_t) (bytes_t *src, int index, bytes_t *dst)

returns: int(*

trie_node_t¶

single node in the merkle trie.

The stuct contains following fields:

`uint8_t`	hash	the hash of the node
bytes_t	data	the raw data
bytes_t	items	the data as list
`uint8_t`	own_memory	if true this is a embedded node with own memory
trie_node_type_t	type	type of the node
trie_nodestruct , *	next	used as linked list

trie_codec_t¶

the codec used to encode nodes.

The stuct contains following fields:

in3_codec_add_t	encode_add
`in3_codec_finish_t`	encode_finish
`in3_codec_decode_size_t`	decode_size
`in3_codec_decode_index_t`	decode_item

trie_t¶

a merkle trie implementation.

This is a Patricia Merkle Tree.

The stuct contains following fields:

in3_hasher_t	hasher	hash-function.
trie_codec_t *	codec	encoding of the nocds.
bytes32_t	root	The root-hash.
trie_node_t *	nodes	linked list of containes nodes

trie_new¶

trie_t* trie_new();

creates a new Merkle Trie.

returns: trie_t *

trie_free¶

void trie_free(trie_t *val);

frees all resources of the trie.

arguments:

trie_t *

val

trie_set_value¶

void trie_set_value(trie_t *t, bytes_t *key, bytes_t *value);

sets a value in the trie.

The root-hash will be updated automaticly.

arguments:

trie_t *	t
bytes_t *	key
bytes_t *	value

big.h¶

Ethereum Nanon verification.

File: c/src/verifier/eth1/evm/big.h

big_is_zero¶

uint8_t big_is_zero(uint8_t *data, wlen_t l);

arguments:

`uint8_t *`	data
wlen_t	l

returns: uint8_t

big_shift_left¶

void big_shift_left(uint8_t *a, wlen_t len, int bits);

arguments:

`uint8_t *`	a
wlen_t	len
`int`	bits

big_shift_right¶

void big_shift_right(uint8_t *a, wlen_t len, int bits);

arguments:

`uint8_t *`	a
wlen_t	len
`int`	bits

big_cmp¶

int big_cmp(const uint8_t *a, const wlen_t len_a, const uint8_t *b, const wlen_t len_b);

arguments:

`const uint8_t *`	a
wlen_tconst	len_a
`const uint8_t *`	b
wlen_tconst	len_b

returns: int

big_signed¶

int big_signed(uint8_t *val, wlen_t len, uint8_t *dst);

returns 0 if the value is positive or 1 if negavtive.

in this case the absolute value is copied to dst.

arguments:

`uint8_t *`	val
wlen_t	len
`uint8_t *`	dst

returns: int

big_int¶

int32_t big_int(uint8_t *val, wlen_t len);

arguments:

`uint8_t *`	val
wlen_t	len

returns: int32_t

big_add¶

int big_add(uint8_t *a, wlen_t len_a, uint8_t *b, wlen_t len_b, uint8_t *out, wlen_t max);

arguments:

`uint8_t *`	a
wlen_t	len_a
`uint8_t *`	b
wlen_t	len_b
`uint8_t *`	out
wlen_t	max

returns: int

big_sub¶

int big_sub(uint8_t *a, wlen_t len_a, uint8_t *b, wlen_t len_b, uint8_t *out);

arguments:

`uint8_t *`	a
wlen_t	len_a
`uint8_t *`	b
wlen_t	len_b
`uint8_t *`	out

returns: int

big_mul¶

int big_mul(uint8_t *a, wlen_t la, uint8_t *b, wlen_t lb, uint8_t *res, wlen_t max);

arguments:

`uint8_t *`	a
wlen_t	la
`uint8_t *`	b
wlen_t	lb
`uint8_t *`	res
wlen_t	max

returns: int

big_div¶

int big_div(uint8_t *a, wlen_t la, uint8_t *b, wlen_t lb, wlen_t sig, uint8_t *res);

arguments:

`uint8_t *`	a
wlen_t	la
`uint8_t *`	b
wlen_t	lb
wlen_t	sig
`uint8_t *`	res

returns: int

big_mod¶

int big_mod(uint8_t *a, wlen_t la, uint8_t *b, wlen_t lb, wlen_t sig, uint8_t *res);

arguments:

`uint8_t *`	a
wlen_t	la
`uint8_t *`	b
wlen_t	lb
wlen_t	sig
`uint8_t *`	res

returns: int

big_exp¶

int big_exp(uint8_t *a, wlen_t la, uint8_t *b, wlen_t lb, uint8_t *res);

arguments:

`uint8_t *`	a
wlen_t	la
`uint8_t *`	b
wlen_t	lb
`uint8_t *`	res

returns: int

big_log256¶

int big_log256(uint8_t *a, wlen_t len);

arguments:

`uint8_t *`	a
wlen_t	len

returns: int

code.h¶

code cache.

File: c/src/verifier/eth1/evm/code.h

in3_get_code¶

in3_ret_t in3_get_code(in3_vctx_t *vc, address_t address, cache_entry_t **target);

fetches the code and adds it to the context-cache as cache_entry.

So calling this function a second time will take the result from cache.

arguments:

in3_vctx_t *	vc
address_t	address
cache_entry_t **	target

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

evm.h¶

main evm-file.

File: c/src/verifier/eth1/evm/evm.h

gas_options¶

EVM_ERROR_EMPTY_STACK¶

the no more elements on the stack

#define EVM_ERROR_EMPTY_STACK -20

EVM_ERROR_INVALID_OPCODE¶

the opcode is not supported

#define EVM_ERROR_INVALID_OPCODE -21

EVM_ERROR_BUFFER_TOO_SMALL¶

reading data from a position, which is not initialized

#define EVM_ERROR_BUFFER_TOO_SMALL -22

EVM_ERROR_ILLEGAL_MEMORY_ACCESS¶

the memory-offset does not exist

#define EVM_ERROR_ILLEGAL_MEMORY_ACCESS -23

EVM_ERROR_INVALID_JUMPDEST¶

the jump destination is not marked as valid destination

#define EVM_ERROR_INVALID_JUMPDEST -24

EVM_ERROR_INVALID_PUSH¶

the push data is empy

#define EVM_ERROR_INVALID_PUSH -25

EVM_ERROR_UNSUPPORTED_CALL_OPCODE¶

error handling the call, usually because static-calls are not allowed to change state

#define EVM_ERROR_UNSUPPORTED_CALL_OPCODE -26

EVM_ERROR_TIMEOUT¶

the evm ran into a loop

#define EVM_ERROR_TIMEOUT -27

EVM_ERROR_INVALID_ENV¶

the enviroment could not deliver the data

#define EVM_ERROR_INVALID_ENV -28

EVM_ERROR_OUT_OF_GAS¶

not enough gas to exewcute the opcode

#define EVM_ERROR_OUT_OF_GAS -29

EVM_ERROR_BALANCE_TOO_LOW¶

not enough funds to transfer the requested value.

#define EVM_ERROR_BALANCE_TOO_LOW -30

EVM_ERROR_STACK_LIMIT¶

stack limit reached

#define EVM_ERROR_STACK_LIMIT -31

EVM_ERROR_SUCCESS_CONSUME_GAS¶

write success but consume all gas

#define EVM_ERROR_SUCCESS_CONSUME_GAS -32

EVM_PROP_FRONTIER¶

#define EVM_PROP_FRONTIER 1

EVM_PROP_EIP150¶

#define EVM_PROP_EIP150 2

EVM_PROP_EIP158¶

#define EVM_PROP_EIP158 4

EVM_PROP_CONSTANTINOPL¶

#define EVM_PROP_CONSTANTINOPL 16

EVM_PROP_ISTANBUL¶

#define EVM_PROP_ISTANBUL 32

EVM_PROP_NO_FINALIZE¶

#define EVM_PROP_NO_FINALIZE 32768

EVM_PROP_STATIC¶

#define EVM_PROP_STATIC 256

EVM_ENV_BALANCE¶

#define EVM_ENV_BALANCE 1

EVM_ENV_CODE_SIZE¶

#define EVM_ENV_CODE_SIZE 2

EVM_ENV_CODE_COPY¶

#define EVM_ENV_CODE_COPY 3

EVM_ENV_BLOCKHASH¶

#define EVM_ENV_BLOCKHASH 4

EVM_ENV_STORAGE¶

#define EVM_ENV_STORAGE 5

EVM_ENV_BLOCKHEADER¶

#define EVM_ENV_BLOCKHEADER 6

EVM_ENV_CODE_HASH¶

#define EVM_ENV_CODE_HASH 7

EVM_ENV_NONCE¶

#define EVM_ENV_NONCE 8

MATH_ADD¶

#define MATH_ADD 1

MATH_SUB¶

#define MATH_SUB 2

MATH_MUL¶

#define MATH_MUL 3

MATH_DIV¶

#define MATH_DIV 4

MATH_SDIV¶

#define MATH_SDIV 5

MATH_MOD¶

#define MATH_MOD 6

MATH_SMOD¶

#define MATH_SMOD 7

MATH_EXP¶

#define MATH_EXP 8

MATH_SIGNEXP¶

#define MATH_SIGNEXP 9

CALL_CALL¶

#define CALL_CALL 0

CALL_CODE¶

#define CALL_CODE 1

CALL_DELEGATE¶

#define CALL_DELEGATE 2

CALL_STATIC¶

#define CALL_STATIC 3

OP_AND¶

#define OP_AND 0

OP_OR¶

#define OP_OR 1

OP_XOR¶

#define OP_XOR 2

EVM_DEBUG_BLOCK (…)¶

OP_LOG (…)¶

#define OP_LOG (...) EVM_ERROR_UNSUPPORTED_CALL_OPCODE

OP_SLOAD_GAS (…)¶

OP_CREATE (…)¶

#define OP_CREATE (...) EVM_ERROR_UNSUPPORTED_CALL_OPCODE

OP_ACCOUNT_GAS (…)¶

#define OP_ACCOUNT_GAS (...) exit_zero()

OP_SELFDESTRUCT (…)¶

#define OP_SELFDESTRUCT (...) EVM_ERROR_UNSUPPORTED_CALL_OPCODE

OP_EXTCODECOPY_GAS (evm)¶

OP_SSTORE (…)¶

#define OP_SSTORE (...) EVM_ERROR_UNSUPPORTED_CALL_OPCODE

EVM_CALL_MODE_STATIC¶

#define EVM_CALL_MODE_STATIC 1

EVM_CALL_MODE_DELEGATE¶

#define EVM_CALL_MODE_DELEGATE 2

EVM_CALL_MODE_CALLCODE¶

#define EVM_CALL_MODE_CALLCODE 3

EVM_CALL_MODE_CALL¶

#define EVM_CALL_MODE_CALL 4

evm_state¶

the current state of the evm

The enum type contains the following values:

EVM_STATE_INIT	0	just initialised, but not yet started
EVM_STATE_RUNNING	1	started and still running
EVM_STATE_STOPPED	2	successfully stopped
EVM_STATE_REVERTED	3	stopped, but results must be reverted

evm_state_t¶

the current state of the evm

The enum type contains the following values:

EVM_STATE_INIT	0	just initialised, but not yet started
EVM_STATE_RUNNING	1	started and still running
EVM_STATE_STOPPED	2	successfully stopped
EVM_STATE_REVERTED	3	stopped, but results must be reverted

evm_get_env¶

This function provides data from the enviroment.

depending on the key the function will set the out_data-pointer to the result. This means the enviroment is responsible for memory management and also to clean up resources afterwards.

typedef int(* evm_get_env) (void *evm, uint16_t evm_key, uint8_t *in_data, int in_len, uint8_t **out_data, int offset, int len)

returns: int(*

storage_t¶

The stuct contains following fields:

bytes32_t	key
bytes32_t	value
account_storagestruct , *	next

logs_t¶

The stuct contains following fields:

bytes_t	topics
bytes_t	data
logsstruct , *	next

account_t¶

The stuct contains following fields:

address_t	address
bytes32_t	balance
bytes32_t	nonce
bytes_t	code
storage_t *	storage
accountstruct , *	next

evm_t¶

The stuct contains following fields:

bytes_builder_t	stack
bytes_builder_t	memory
`int`	stack_size
bytes_t	code
`uint32_t`	pos
evm_state_t	state
bytes_t	last_returned
bytes_t	return_data
`uint32_t *`	invalid_jumpdest
`uint32_t`	properties
evm_get_env	env
`void *`	env_ptr
`uint64_t`	chain_id	the chain_id as returned by the opcode
`uint8_t *`	address	the address of the current storage
`uint8_t *`	account	the address of the code
`uint8_t *`	origin	the address of original sender of the root-transaction
`uint8_t *`	caller	the address of the parent sender
bytes_t	call_value	value send
bytes_t	call_data	data send in the tx
bytes_t	gas_price	current gasprice
`uint64_t`	gas
	gas_options

exit_zero¶

int exit_zero(void);

arguments:

`void`¶

returns: int

evm_stack_push¶

int evm_stack_push(evm_t *evm, uint8_t *data, uint8_t len);

arguments:

evm_t *	evm
`uint8_t *`	data
`uint8_t`	len

returns: int

evm_stack_push_ref¶

int evm_stack_push_ref(evm_t *evm, uint8_t **dst, uint8_t len);

arguments:

evm_t *	evm
`uint8_t **`	dst
`uint8_t`	len

returns: int

evm_stack_push_int¶

int evm_stack_push_int(evm_t *evm, uint32_t val);

arguments:

evm_t *	evm
`uint32_t`	val

returns: int

evm_stack_push_long¶

int evm_stack_push_long(evm_t *evm, uint64_t val);

arguments:

evm_t *	evm
`uint64_t`	val

returns: int

evm_stack_get_ref¶

int evm_stack_get_ref(evm_t *evm, uint8_t pos, uint8_t **dst);

arguments:

evm_t *	evm
`uint8_t`	pos
`uint8_t **`	dst

returns: int

evm_stack_pop¶

int evm_stack_pop(evm_t *evm, uint8_t *dst, uint8_t len);

arguments:

evm_t *	evm
`uint8_t *`	dst
`uint8_t`	len

returns: int

evm_stack_pop_ref¶

int evm_stack_pop_ref(evm_t *evm, uint8_t **dst);

arguments:

evm_t *	evm
`uint8_t **`	dst

returns: int

evm_stack_pop_byte¶

int evm_stack_pop_byte(evm_t *evm, uint8_t *dst);

arguments:

evm_t *	evm
`uint8_t *`	dst

returns: int

evm_stack_pop_int¶

int32_t evm_stack_pop_int(evm_t *evm);

arguments:

evm_t *

evm

returns: int32_t

evm_run¶

int evm_run(evm_t *evm, address_t code_address);

arguments:

evm_t *	evm
address_t	code_address

returns: int

evm_sub_call¶

int evm_sub_call(evm_t *parent, uint8_t address[20], uint8_t account[20], uint8_t *value, wlen_t l_value, uint8_t *data, uint32_t l_data, uint8_t caller[20], uint8_t origin[20], uint64_t gas, wlen_t mode, uint32_t out_offset, uint32_t out_len);

handle internal calls.

arguments:

evm_t *	parent
`uint8_t`	address
`uint8_t`	account
`uint8_t *`	value
wlen_t	l_value
`uint8_t *`	data
`uint32_t`	l_data
`uint8_t`	caller
`uint8_t`	origin
`uint64_t`	gas
wlen_t	mode
`uint32_t`	out_offset
`uint32_t`	out_len

returns: int

evm_ensure_memory¶

int evm_ensure_memory(evm_t *evm, uint32_t max_pos);

arguments:

evm_t *	evm
`uint32_t`	max_pos

returns: int

in3_get_env¶

int in3_get_env(void *evm_ptr, uint16_t evm_key, uint8_t *in_data, int in_len, uint8_t **out_data, int offset, int len);

arguments:

`void *`	evm_ptr
`uint16_t`	evm_key
`uint8_t *`	in_data
`int`	in_len
`uint8_t **`	out_data
`int`	offset
`int`	len

returns: int

evm_call¶

int evm_call(void *vc, uint8_t address[20], uint8_t *value, wlen_t l_value, uint8_t *data, uint32_t l_data, uint8_t caller[20], uint64_t gas, uint64_t chain_id, bytes_t **result);

run a evm-call

arguments:

`void *`	vc
`uint8_t`	address
`uint8_t *`	value
wlen_t	l_value
`uint8_t *`	data
`uint32_t`	l_data
`uint8_t`	caller
`uint64_t`	gas
`uint64_t`	chain_id
bytes_t **	result

returns: int

evm_print_stack¶

void evm_print_stack(evm_t *evm, uint64_t last_gas, uint32_t pos);

arguments:

evm_t *	evm
`uint64_t`	last_gas
`uint32_t`	pos

evm_free¶

void evm_free(evm_t *evm);

arguments:

evm_t *

evm

evm_execute¶

int evm_execute(evm_t *evm);

arguments:

evm_t *

evm

returns: int

gas.h¶

evm gas defines.

File: c/src/verifier/eth1/evm/gas.h

op_exec (m,gas)¶

#define op_exec (m,gas) return m;

subgas (g)¶

GAS_CC_NET_SSTORE_NOOP_GAS¶

Once per SSTORE operation if the value doesn’t change.

#define GAS_CC_NET_SSTORE_NOOP_GAS 200

GAS_CC_NET_SSTORE_INIT_GAS¶

Once per SSTORE operation from clean zero.

#define GAS_CC_NET_SSTORE_INIT_GAS 20000

GAS_CC_NET_SSTORE_CLEAN_GAS¶

Once per SSTORE operation from clean non-zero.

#define GAS_CC_NET_SSTORE_CLEAN_GAS 5000

GAS_CC_NET_SSTORE_DIRTY_GAS¶

Once per SSTORE operation from dirty.

#define GAS_CC_NET_SSTORE_DIRTY_GAS 200

GAS_CC_NET_SSTORE_CLEAR_REFUND¶

Once per SSTORE operation for clearing an originally existing storage slot.

#define GAS_CC_NET_SSTORE_CLEAR_REFUND 15000

GAS_CC_NET_SSTORE_RESET_REFUND¶

Once per SSTORE operation for resetting to the original non-zero value.

#define GAS_CC_NET_SSTORE_RESET_REFUND 4800

GAS_CC_NET_SSTORE_RESET_CLEAR_REFUND¶

Once per SSTORE operation for resetting to the original zero valuev.

#define GAS_CC_NET_SSTORE_RESET_CLEAR_REFUND 19800

G_ZERO¶

Nothing is paid for operations of the set Wzero.

#define G_ZERO 0

G_JUMPDEST¶

JUMP DEST.

#define G_JUMPDEST 1

G_BASE¶

This is the amount of gas to pay for operations of the set Wbase.

#define G_BASE 2

G_VERY_LOW¶

This is the amount of gas to pay for operations of the set Wverylow.

#define G_VERY_LOW 3

G_LOW¶

This is the amount of gas to pay for operations of the set Wlow.

#define G_LOW 5

G_MID¶

This is the amount of gas to pay for operations of the set Wmid.

#define G_MID 8

G_HIGH¶

This is the amount of gas to pay for operations of the set Whigh.

#define G_HIGH 10

G_EXTCODE¶

This is the amount of gas to pay for operations of the set Wextcode.

#define G_EXTCODE 700

G_BALANCE¶

This is the amount of gas to pay for a BALANCE operation.

#define G_BALANCE 400

G_SLOAD¶

This is paid for an SLOAD operation.

#define G_SLOAD 200

G_SSET¶

This is paid for an SSTORE operation when the storage value is set to non-zero from zero.

#define G_SSET 20000

G_SRESET¶

This is the amount for an SSTORE operation when the storage value’s zeroness remains unchanged or is set to zero.

#define G_SRESET 5000

R_SCLEAR¶

This is the refund given (added into the refund counter) when the storage value is set to zero from non-zero.

#define R_SCLEAR 15000

R_SELFDESTRUCT¶

This is the refund given (added into the refund counter) for self-destructing an account.

#define R_SELFDESTRUCT 24000

G_SELFDESTRUCT¶

This is the amount of gas to pay for a SELFDESTRUCT operation.

#define G_SELFDESTRUCT 5000

G_CREATE¶

This is paid for a CREATE operation.

#define G_CREATE 32000

G_CODEDEPOSIT¶

This is paid per byte for a CREATE operation to succeed in placing code into the state.

#define G_CODEDEPOSIT 200

G_CALL¶

This is paid for a CALL operation.

#define G_CALL 700

G_CALLVALUE¶

This is paid for a non-zero value transfer as part of the CALL operation.

#define G_CALLVALUE 9000

G_CALLSTIPEND¶

This is a stipend for the called contract subtracted from Gcallvalue for a non-zero value transfer.

#define G_CALLSTIPEND 2300

G_NEWACCOUNT¶

This is paid for a CALL or for a SELFDESTRUCT operation which creates an account.

#define G_NEWACCOUNT 25000

G_EXP¶

This is a partial payment for an EXP operation.

#define G_EXP 10

G_EXPBYTE¶

This is a partial payment when multiplied by dlog256(exponent)e for the EXP operation.

#define G_EXPBYTE 50

G_MEMORY¶

This is paid for every additional word when expanding memory.

#define G_MEMORY 3

G_TXCREATE¶

This is paid by all contract-creating transactions after the Homestead transition.

#define G_TXCREATE 32000

G_TXDATA_ZERO¶

This is paid for every zero byte of data or code for a transaction.

#define G_TXDATA_ZERO 4

G_TXDATA_NONZERO¶

This is paid for every non-zero byte of data or code for a transaction.

#define G_TXDATA_NONZERO 68

G_TRANSACTION¶

This is paid for every transaction.

#define G_TRANSACTION 21000

G_LOG¶

This is a partial payment for a LOG operation.

#define G_LOG 375

G_LOGDATA¶

This is paid for each byte in a LOG operation’s data.

#define G_LOGDATA 8

G_LOGTOPIC¶

This is paid for each topic of a LOG operation.

#define G_LOGTOPIC 375

G_SHA3¶

This is paid for each SHA3 operation.

#define G_SHA3 30

G_SHA3WORD¶

This is paid for each word (rounded up) for input data to a SHA3 operation.

#define G_SHA3WORD 6

G_COPY¶

This is a partial payment for *COPY operations, multiplied by the number of words copied, rounded up.

#define G_COPY 3

G_BLOCKHASH¶

This is a payment for a BLOCKHASH operation.

#define G_BLOCKHASH 20

G_PRE_EC_RECOVER¶

Precompile EC RECOVER.

#define G_PRE_EC_RECOVER 3000

G_PRE_SHA256¶

Precompile SHA256.

#define G_PRE_SHA256 60

G_PRE_SHA256_WORD¶

Precompile SHA256 per word.

#define G_PRE_SHA256_WORD 12

G_PRE_RIPEMD160¶

Precompile RIPEMD160.

#define G_PRE_RIPEMD160 600

G_PRE_RIPEMD160_WORD¶

Precompile RIPEMD160 per word.

#define G_PRE_RIPEMD160_WORD 120

G_PRE_IDENTITY¶

Precompile IDENTIY (copyies data)

#define G_PRE_IDENTITY 15

G_PRE_IDENTITY_WORD¶

Precompile IDENTIY per word.

#define G_PRE_IDENTITY_WORD 3

G_PRE_MODEXP_GQUAD_DIVISOR¶

Gquaddivisor from modexp precompile for gas calculation.

#define G_PRE_MODEXP_GQUAD_DIVISOR 20

G_PRE_ECADD¶

Gas costs for curve addition precompile.

#define G_PRE_ECADD 500

G_PRE_ECMUL¶

Gas costs for curve multiplication precompile.

#define G_PRE_ECMUL 40000

G_PRE_ECPAIRING¶

Base gas costs for curve pairing precompile.

#define G_PRE_ECPAIRING 100000

G_PRE_ECPAIRING_WORD¶

Gas costs regarding curve pairing precompile input length.

#define G_PRE_ECPAIRING_WORD 80000

EVM_STACK_LIMIT¶

max elements of the stack

#define EVM_STACK_LIMIT 1024

EVM_MAX_CODE_SIZE¶

max size of the code

#define EVM_MAX_CODE_SIZE 24576

FRONTIER_G_EXPBYTE¶

fork values

This is a partial payment when multiplied by dlog256(exponent)e for the EXP operation.

#define FRONTIER_G_EXPBYTE 10

FRONTIER_G_SLOAD¶

This is a partial payment when multiplied by dlog256(exponent)e for the EXP operation.

#define FRONTIER_G_SLOAD 50

FREE_EVM (…)¶

INIT_EVM (…)¶

INIT_GAS (…)¶

SUBGAS (…)¶

FINALIZE_SUBCALL_GAS (…)¶

UPDATE_SUBCALL_GAS (…)¶

FINALIZE_AND_REFUND_GAS (…)¶

KEEP_TRACK_GAS (evm)¶

#define KEEP_TRACK_GAS (evm) 0

UPDATE_ACCOUNT_CODE (…)¶

eth_full.h¶

Ethereum Nanon verification.

File: c/src/verifier/eth1/full/eth_full.h

in3_register_eth_full¶

in3_ret_t in3_register_eth_full(in3_t *c);

this function should only be called once and will register the eth-full verifier.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

chainspec.h¶

Ethereum chain specification

File: c/src/verifier/eth1/nano/chainspec.h

BLOCK_LATEST¶

#define BLOCK_LATEST 0xFFFFFFFFFFFFFFFF

eth_consensus_type_t¶

the consensus type.

The enum type contains the following values:

ETH_POW	0	Pro of Work (Ethash)
ETH_POA_AURA	1	Proof of Authority using Aura.
ETH_POA_CLIQUE	2	Proof of Authority using clique.

eip_transition_t¶

The stuct contains following fields:

`uint64_t`	transition_block
`eip_t`	eips

consensus_transition_t¶

The stuct contains following fields:

`uint64_t`	transition_block
eth_consensus_type_t	type
bytes_t	validators
`uint8_t *`	contract

chainspec_t¶

The stuct contains following fields:

`uint64_t`	network_id
`uint64_t`	account_start_nonce
`uint32_t`	eip_transitions_len
eip_transition_t *	eip_transitions
`uint32_t`	consensus_transitions_len
consensus_transition_t *	consensus_transitions

attribute¶

struct __attribute__((__packed__)) eip_;

defines the flags for the current activated EIPs.

Since it does not make sense to support a evm defined before Homestead, homestead EIP is always turned on!

< REVERT instruction

< Bitwise shifting instructions in EVM

< Gas cost changes for IO-heavy operations

< Simple replay attack protection

< EXP cost increase

< Contract code size limit

< Precompiled contracts for addition and scalar multiplication on the elliptic curve alt_bn128

< Precompiled contracts for optimal ate pairing check on the elliptic curve alt_bn128

< Big integer modular exponentiation

< New opcodes: RETURNDATASIZE and RETURNDATACOPY

< New opcode STATICCALL

< Embedding transaction status code in receipts

< Skinny CREATE2

< EXTCODEHASH opcode

< Net gas metering for SSTORE without dirty maps

arguments:

`(packed)`¶

returns: struct

chainspec_create_from_json¶

chainspec_t* chainspec_create_from_json(d_token_t *data);

arguments:

data

returns: chainspec_t *

chainspec_get_eip¶

eip_t chainspec_get_eip(chainspec_t *spec, uint64_t block_number);

arguments:

chainspec_t *	spec
`uint64_t`	block_number

returns: eip_t

chainspec_get_consensus¶

consensus_transition_t* chainspec_get_consensus(chainspec_t *spec, uint64_t block_number);

arguments:

chainspec_t *	spec
`uint64_t`	block_number

returns: consensus_transition_t *

chainspec_to_bin¶

in3_ret_t chainspec_to_bin(chainspec_t *spec, bytes_builder_t *bb);

arguments:

chainspec_t *	spec
bytes_builder_t *	bb

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

chainspec_from_bin¶

chainspec_t* chainspec_from_bin(void *raw);

arguments:

void * raw

returns: chainspec_t *

chainspec_get¶

chainspec_t* chainspec_get(chain_id_t chain_id);

arguments:

chain_id_t

chain_id

returns: chainspec_t *

chainspec_put¶

void chainspec_put(chain_id_t chain_id, chainspec_t *spec);

arguments:

chain_id_t	chain_id
chainspec_t *	spec

eth_nano.h¶

Ethereum Nanon verification.

File: c/src/verifier/eth1/nano/eth_nano.h

in3_verify_eth_nano¶

NONULL in3_ret_t in3_verify_eth_nano(void *p_data, in3_plugin_act_t action, void *pctx);

entry-function to execute the verification context.

arguments:

`void *`	p_data
in3_plugin_act_t	action
`void *`	pctx

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_blockheader¶

in3_ret_t eth_verify_blockheader(in3_vctx_t *vc, bytes_t *header, bytes_t *expected_blockhash);

verifies a blockheader.

arguments:

in3_vctx_t *	vc
bytes_t *	header
bytes_t *	expected_blockhash

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_signature¶

NONULL int eth_verify_signature(in3_vctx_t *vc, bytes_t *msg_hash, d_token_t *sig);

verifies a single signature blockheader.

This function will return a positive integer with a bitmask holding the bit set according to the address that signed it. This is based on the signatiures in the request-config.

arguments:

in3_vctx_t *	vc
bytes_t *	msg_hash
d_token_t *	sig

returns: NONULL int

ecrecover_signature¶

NONULL bytes_t* ecrecover_signature(bytes_t *msg_hash, d_token_t *sig);

returns the address of the signature if the msg_hash is correct

arguments:

bytes_t *	msg_hash
d_token_t *	sig

returns: bytes_tNONULL , *

eth_verify_eth_getTransactionReceipt¶

NONULL in3_ret_t eth_verify_eth_getTransactionReceipt(in3_vctx_t *vc, bytes_t *tx_hash);

verifies a transaction receipt.

arguments:

in3_vctx_t *	vc
bytes_t *	tx_hash

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_in3_nodelist¶

in3_ret_t eth_verify_in3_nodelist(in3_vctx_t *vc, uint32_t node_limit, bytes_t *seed, d_token_t *required_addresses);

verifies the nodelist.

arguments:

in3_vctx_t *	vc
`uint32_t`	node_limit
bytes_t *	seed
d_token_t *	required_addresses

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

eth_verify_in3_whitelist¶

NONULL in3_ret_t eth_verify_in3_whitelist(in3_vctx_t *vc);

verifies the nodelist.

arguments:

in3_vctx_t *

vc

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_eth_nano¶

NONULL in3_ret_t in3_register_eth_nano(in3_t *c);

this function should only be called once and will register the eth-nano verifier.

arguments:

c

returns: in3_ret_tNONULL the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

create_tx_path¶

bytes_t* create_tx_path(uint32_t index);

helper function to rlp-encode the transaction_index.

The result must be freed after use!

arguments:

uint32_t index

returns: bytes_t *

merkle.h¶

Merkle Proof Verification.

File: c/src/verifier/eth1/nano/merkle.h

MERKLE_DEPTH_MAX¶

#define MERKLE_DEPTH_MAX 64

trie_verify_proof¶

int trie_verify_proof(bytes_t *rootHash, bytes_t *path, bytes_t **proof, bytes_t *expectedValue);

verifies a merkle proof.

expectedValue == NULL : value must not exist expectedValue.data ==NULL : please copy the data I want to evaluate it afterwards. expectedValue.data !=NULL : the value must match the data.

arguments:

bytes_t *	rootHash
bytes_t *	path
bytes_t **	proof
bytes_t *	expectedValue

returns: int

trie_path_to_nibbles¶

NONULL uint8_t* trie_path_to_nibbles(bytes_t path, int use_prefix);

helper function split a path into 4-bit nibbles.

The result must be freed after use!

arguments:

bytes_t	path
`int`	use_prefix

returns: NONULL uint8_t * : the resulting bytes represent a 4bit-number each and are terminated with a 0xFF.

trie_matching_nibbles¶

NONULL int trie_matching_nibbles(uint8_t *a, uint8_t *b);

helper function to find the number of nibbles matching both paths.

arguments:

`uint8_t *`	a
`uint8_t *`	b

returns: NONULL int

rlp.h¶

RLP-En/Decoding as described in the Ethereum RLP-Spec.

This decoding works without allocating new memory.

File: c/src/verifier/eth1/nano/rlp.h

rlp_decode¶

int rlp_decode(bytes_t *b, int index, bytes_t *dst);

this function decodes the given bytes and returns the element with the given index by updating the reference of dst.

the bytes will only hold references and do not need to be freed!

bytes_t* tx_raw = serialize_tx(tx);

bytes_t item;

// decodes the tx_raw by letting the item point to range of the first element, which should be the body of a list.
if (rlp_decode(tx_raw, 0, &item) !=2) return -1 ;

// now decode the 4th element (which is the value) and let item point to that range.
if (rlp_decode(&item, 4, &item) !=1) return -1 ;

arguments:

bytes_t *	b
`int`	index
bytes_t *	dst

returns: int : - 0 : means item out of range

1 : item found
2 : list found ( you can then decode the same bytes again)

rlp_decode_in_list¶

int rlp_decode_in_list(bytes_t *b, int index, bytes_t *dst);

this function expects a list item (like the blockheader as first item and will then find the item within this list).

It is a shortcut for

// decode the list
if (rlp_decode(b,0,dst)!=2) return 0;
// and the decode the item
return rlp_decode(dst,index,dst);

arguments:

bytes_t *	b
`int`	index
bytes_t *	dst

returns: int : - 0 : means item out of range

1 : item found
2 : list found ( you can then decode the same bytes again)

rlp_decode_len¶

int rlp_decode_len(bytes_t *b);

returns the number of elements found in the data.

arguments:

bytes_t *

b

returns: int

rlp_encode_item¶

void rlp_encode_item(bytes_builder_t *bb, bytes_t *val);

encode a item as single string and add it to the bytes_builder.

arguments:

bytes_builder_t *	bb
bytes_t *	val

rlp_encode_list¶

void rlp_encode_list(bytes_builder_t *bb, bytes_t *val);

encode a the value as list of already encoded items.

arguments:

bytes_builder_t *	bb
bytes_t *	val

rlp_encode_to_list¶

bytes_builder_t* rlp_encode_to_list(bytes_builder_t *bb);

converts the data in the builder to a list.

This function is optimized to not increase the memory more than needed and is fastet than creating a second builder to encode the data.

arguments:

bb

returns: bytes_builder_t * : the same builder.

rlp_encode_to_item¶

bytes_builder_t* rlp_encode_to_item(bytes_builder_t *bb);

converts the data in the builder to a rlp-encoded item.

This function is optimized to not increase the memory more than needed and is fastet than creating a second builder to encode the data.

arguments:

bb

returns: bytes_builder_t * : the same builder.

rlp_add_length¶

void rlp_add_length(bytes_builder_t *bb, uint32_t len, uint8_t offset);

helper to encode the prefix for a value

arguments:

bytes_builder_t *	bb
`uint32_t`	len
`uint8_t`	offset

serialize.h¶

serialization of ETH-Objects.

This incoming tokens will represent their values as properties based on JSON-RPC.

File: c/src/verifier/eth1/nano/serialize.h

BLOCKHEADER_PARENT_HASH¶

#define BLOCKHEADER_PARENT_HASH 0

BLOCKHEADER_SHA3_UNCLES¶

#define BLOCKHEADER_SHA3_UNCLES 1

BLOCKHEADER_MINER¶

#define BLOCKHEADER_MINER 2

BLOCKHEADER_STATE_ROOT¶

#define BLOCKHEADER_STATE_ROOT 3

BLOCKHEADER_TRANSACTIONS_ROOT¶

#define BLOCKHEADER_TRANSACTIONS_ROOT 4

BLOCKHEADER_RECEIPT_ROOT¶

#define BLOCKHEADER_RECEIPT_ROOT 5

BLOCKHEADER_LOGS_BLOOM¶

#define BLOCKHEADER_LOGS_BLOOM 6

BLOCKHEADER_DIFFICULTY¶

#define BLOCKHEADER_DIFFICULTY 7

BLOCKHEADER_NUMBER¶

#define BLOCKHEADER_NUMBER 8

BLOCKHEADER_GAS_LIMIT¶

#define BLOCKHEADER_GAS_LIMIT 9

BLOCKHEADER_GAS_USED¶

#define BLOCKHEADER_GAS_USED 10

BLOCKHEADER_TIMESTAMP¶

#define BLOCKHEADER_TIMESTAMP 11

BLOCKHEADER_EXTRA_DATA¶

#define BLOCKHEADER_EXTRA_DATA 12

BLOCKHEADER_SEALED_FIELD1¶

#define BLOCKHEADER_SEALED_FIELD1 13

BLOCKHEADER_SEALED_FIELD2¶

#define BLOCKHEADER_SEALED_FIELD2 14

BLOCKHEADER_SEALED_FIELD3¶

#define BLOCKHEADER_SEALED_FIELD3 15

serialize_tx_receipt¶

bytes_t* serialize_tx_receipt(d_token_t *receipt);

creates rlp-encoded raw bytes for a receipt.

The bytes must be freed with b_free after use!

arguments:

receipt

returns: bytes_t *

serialize_tx¶

bytes_t* serialize_tx(d_token_t *tx);

creates rlp-encoded raw bytes for a transaction.

The bytes must be freed with b_free after use!

arguments:

tx

returns: bytes_t *

serialize_tx_raw¶

bytes_t* serialize_tx_raw(bytes_t nonce, bytes_t gas_price, bytes_t gas_limit, bytes_t to, bytes_t value, bytes_t data, uint64_t v, bytes_t r, bytes_t s);

creates rlp-encoded raw bytes for a transaction from direct values.

The bytes must be freed with b_free after use!

arguments:

bytes_t	nonce
bytes_t	gas_price
bytes_t	gas_limit
bytes_t	to
bytes_t	value
bytes_t	data
`uint64_t`	v
bytes_t	r
bytes_t	s

returns: bytes_t *

serialize_account¶

bytes_t* serialize_account(d_token_t *a);

creates rlp-encoded raw bytes for a account.

The bytes must be freed with b_free after use!

arguments:

a

returns: bytes_t *

serialize_block_header¶

bytes_t* serialize_block_header(d_token_t *block);

creates rlp-encoded raw bytes for a blockheader.

The bytes must be freed with b_free after use!

arguments:

block

returns: bytes_t *

rlp_add¶

int rlp_add(bytes_builder_t *rlp, d_token_t *t, int ml);

adds the value represented by the token rlp-encoded to the byte_builder.

arguments:

bytes_builder_t *	rlp
d_token_t *	t
`int`	ml

returns: int : 0 if added -1 if the value could not be handled.

in3_init.h¶

IN3 init module for auto initializing verifiers and transport based on build config.

File: c/src/verifier/in3_init.h

in3_for_chain (chain_id)¶

#define in3_for_chain (chain_id) in3_for_chain_auto_init(chain_id)

in3_init¶

void in3_init();

Global initialization for the in3 lib.

Note: This function is not MT-safe and is expected to be called early during during program startup (i.e. in main()) before other threads are spawned.

in3_for_chain_auto_init¶

in3_t* in3_for_chain_auto_init(chain_id_t chain_id);

Auto-init fallback for easy client initialization meant for single-threaded apps.

This function automatically calls in3_init() before calling in3_for_chain_default(). To enable this feature, make sure you include this header file (i.e. in3_init.h) before client.h. Doing so will replace the call to in3_for_chain() with this function.

arguments:

chain_id_t

chain_id

returns: in3_t *

ipfs.h¶

IPFS verification.

File: c/src/verifier/ipfs/ipfs.h

ipfs_verify_hash¶

in3_ret_t ipfs_verify_hash(const char *content, const char *encoding, const char *requsted_hash);

verifies an IPFS hash.

Supported encoding schemes - hex, utf8 and base64

arguments:

`const char *`	content
`const char *`	encoding
`const char *`	requsted_hash

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

in3_register_ipfs¶

in3_ret_t in3_register_ipfs(in3_t *c);

this function should only be called once and will register the IPFS verifier.

arguments:

c

returns: in3_ret_t the result-status of the function.

Please make sure you check if it was successfull (==IN3_OK)

API Reference TS¶

This page contains a list of all Datastructures and Classes used within the TypeScript IN3 Client.

Examples¶

This is a collection of different incubed-examples.

using Web3¶

Since incubed works with on a JSON-RPC-Level it can easily be used as Provider for Web3:

// import in3-Module
import In3Client from 'in3'
import * as web3 from 'web3'

// use the In3Client as Http-Provider
const web3 = new Web3(new In3Client({
    proof         : 'standard',
    signatureCount: 1,
    requestCount  : 2,
    chainId       : 'mainnet'
}).createWeb3Provider())

// use the web3
const block = await web.eth.getBlockByNumber('latest')
...

using Incubed API¶

Incubed includes a light API, allowinng not only to use all RPC-Methods in a typesafe way, but also to sign transactions and call funnctions of a contract without the web3-library.

For more details see the API-Doc

// import in3-Module
import In3Client from 'in3'

// use the In3Client
const in3 = new In3Client({
    proof         : 'standard',
    signatureCount: 1,
    requestCount  : 2,
    chainId       : 'mainnet'
})

// use the api to call a funnction..
const myBalance = await in3.eth.callFn(myTokenContract, 'balanceOf(address):uint', myAccount)

// ot to send a transaction..
const receipt = await in3.eth.sendTransaction({ 
  to           : myTokenContract, 
  method       : 'transfer(address,uint256)',
  args         : [target,amount],
  confirmations: 2,
  pk           : myKey
})

...

Reading event with incubed¶

// import in3-Module
import In3Client from 'in3'

// use the In3Client
const in3 = new In3Client({
    proof         : 'standard',
    signatureCount: 1,
    requestCount  : 2,
    chainId       : 'mainnet'
})

// use the ABI-String of the smart contract
abi = [{"anonymous":false,"inputs":[{"indexed":false,"name":"name","type":"string"},{"indexed":true,"name":"label","type":"bytes32"},{"indexed":true,"name":"owner","type":"address"},{"indexed":false,"name":"cost","type":"uint256"},{"indexed":false,"name":"expires","type":"uint256"}],"name":"NameRegistered","type":"event"}]

// create a contract-object for a given address
const contract = in3.eth.contractAt(abi, '0xF0AD5cAd05e10572EfcEB849f6Ff0c68f9700455') // ENS contract.

// read all events starting from a specified block until the latest
const logs = await c.events.NameRegistered.getLogs({fromBlock:8022948})) 

// print out the properties of the event.
for (const ev of logs) 
  console.log(`${ev.owner} registered ${ev.name} for ${ev.cost} wei until ${new Date(ev.expires.toNumber()*1000).toString()}`)

...

Main Module¶

Importing incubed is as easy as

import Client,{util} from "in3"

While the In3Client-class is the default import, the following imports can be used:

Type

ABI

the ABI

Interface

AccountProof

the AccountProof

Interface

AuraValidatoryProof

the AuraValidatoryProof

Type

BlockData

the BlockData

Type

BlockType

the BlockType

Interface

ChainSpec

the ChainSpec

Class

IN3Client

the IN3Client

Interface

IN3Config

the IN3Config

Interface

IN3NodeConfig

the IN3NodeConfig

Interface

IN3NodeWeight

the IN3NodeWeight

Interface

IN3RPCConfig

the IN3RPCConfig

Interface

IN3RPCHandlerConfig

the IN3RPCHandlerConfig

Interface

IN3RPCRequestConfig

the IN3RPCRequestConfig

Interface

IN3ResponseConfig

the IN3ResponseConfig

Type

Log

the Log

Type

LogData

the LogData

Interface

LogProof

the LogProof

Interface

Proof

the Proof

Interface

RPCRequest

the RPCRequest

Interface

RPCResponse

the RPCResponse

Type

ReceiptData

the ReceiptData

Interface

ServerList

the ServerList

Interface

Signature

the Signature

Type

Transaction

the Transaction

Type

TransactionData

the TransactionData

Type

TransactionReceipt

the TransactionReceipt

Type

Transport

the Transport

any

AxiosTransport

the AxiosTransport

value= transport.AxiosTransport

EthAPI

EthAPI

the EthAPI

value= _ethapi.default

any

cbor

the cbor

value= _cbor

chainAliases

the chainAliases

value= aliases

chainData

chainData

the chainData

value= _chainData

number []

createRandomIndexes (

len:number,

limit:number,

seed:Buffer ,

result:number [])

helper function creating deterministic random indexes used for limited nodelists

header

header

the header

value= _header

serialize

serialize

the serialize

value= _serialize

any

storage

the storage

value= _storage

any

transport

the transport

value= _transport

typeDefs

the typeDefs

value= types.validationDef

any

util

the util

value= _util

any

validate

the validate

value= validateOb.validate

Package client¶

Type Client¶

Source: client/Client.ts

Client for N3.

number

defaultMaxListeners

the defaultMaxListeners

number

listenerCount (

emitter:EventEmitter ,

event:string

| symbol)

listener count

Client

constructor (

config:Partial<IN3Config> ,

transport:Transport )

creates a new Client.

IN3Config

defConfig

the defConfig

EthAPI

eth

the eth

IpfsAPI

ipfs

the ipfs

IN3Config

config

config

this

addListener (

event:string

| symbol,

listener:)

add listener

Promise<any>

call (

method:string,

params:any,

chain:string,

config:Partial<IN3Config> )

sends a simply RPC-Request

void

clearStats ()

clears all stats and weights, like blocklisted nodes

any

createWeb3Provider ()

create web3 provider

boolean

emit (

event:string

| symbol,

args:any [])

emit

Array<>

eventNames ()

event names

ChainContext

getChainContext (

chainId:string)

Context for a specific chain including cache and chainSpecs.

number

getMaxListeners ()

get max listeners

number

listenerCount (

type:string

| symbol)

listener count

Function []

listeners (

event:string

| symbol)

listeners

this

off (

event:string

| symbol,

listener:)

off

this

on (

event:string

| symbol,

listener:)

on

this

once (

event:string

| symbol,

listener:)

once

this

prependListener (

event:string

| symbol,

listener:)

prepend listener

this

prependOnceListener (

event:string

| symbol,

listener:)

prepend once listener

Function []

rawListeners (

event:string

| symbol)

raw listeners

this

removeAllListeners (

event:string

| symbol)

remove all listeners

this

removeListener (

event:string

| symbol,

listener:)

remove listener

Promise<>

send (

request:RPCRequest []

| RPCRequest ,

callback:,

config:Partial<IN3Config> )

sends one or a multiple requests.

if the request is a array the response will be a array as well.

If the callback is given it will be called with the response, if not a Promise will be returned.

This function supports callback so it can be used as a Provider for the web3.

Promise<RPCResponse>

sendRPC (

method:string,

params:any [],

chain:string,

config:Partial<IN3Config> )

sends a simply RPC-Request

this

setMaxListeners (

n:number)

set max listeners

Promise<void>

updateNodeList (

chainId:string,

conf:Partial<IN3Config> ,

retryCount:number)

fetches the nodeList from the servers.

Promise<void>

updateWhiteListNodes (

config:IN3Config )

update white list nodes

Promise<boolean>

verifyResponse (

request:RPCRequest ,

response:RPCResponse ,

chain:string,

config:Partial<IN3Config> )

Verify the response of a request without any effect on the state of the client.

Note: The node-list will not be updated.

The method will either return true if its inputs could be verified.

Or else, it will throw an exception with a helpful message.

Type ChainContext¶

Source: client/ChainContext.ts

Context for a specific chain including cache and chainSpecs.

ChainContext

constructor (

client:Client ,

chainId:string,

chainSpec:ChainSpec [])

Context for a specific chain including cache and chainSpecs.

string

chainId

the chainId

ChainSpec []

chainSpec

the chainSpec

Client

client

the client

genericCache

the genericCache

number

lastValidatorChange

the lastValidatorChange

Module

module

the module

string

registryId

the registryId (optional)

void

clearCache (

prefix:string)

clear cache

ChainSpec

getChainSpec (

block:number)

returns the chainspec for th given block number

string

getFromCache (

key:string)

get from cache

Promise<RPCResponse>

handleIntern (

request:RPCRequest )

this function is calleds before the server is asked.

If it returns a promise than the request is handled internally otherwise the server will handle the response.

this function should be overriden by modules that want to handle calls internally

void

initCache ()

init cache

void

putInCache (

key:string,

value:string)

put in cache

void

updateCache (

whiteList:Set<string> ,

whiteListContract:string)

update cache

Type Module¶

Source: client/modules.ts

string

name

the name

ChainContext

createChainContext (

client:Client ,

chainId:string,

spec:ChainSpec [])

Context for a specific chain including cache and chainSpecs.

Promise<boolean>

verifyProof (

request:RPCRequest ,

response:RPCResponse ,

allowWithoutProof:boolean,

ctx:ChainContext )

general verification-function which handles it according to its given type.

Type Proof¶

Source: index.ts

the Proof-data as part of the in3-section the Proof-data as part of the in3-section

accounts

a map of addresses and their AccountProof (optional)

string

block

the serialized blockheader as hex, required in most proofs

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b (optional)

any []

finalityBlocks

the serialized blockheader as hex, required in case of finality asked

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b (optional)

LogProof

logProof

the Log Proof in case of a Log-Request (optional)

string []

merkleProof

the serialized merle-noodes beginning with the root-node (optional)

string []

merkleProofPrev

the serialized merkle-noodes beginning with the root-node of the previous entry (only for full proof of receipts) (optional)

Signature []

signatures

requested signatures (optional)

any []

transactions

the list of transactions of the block

example: (optional)

number

txIndex

the transactionIndex within the block

example: 4 (optional)

string []

txProof

the serialized merkle-nodes beginning with the root-node in order to prrof the transactionIndex (optional)

'transactionProof'

| 'receiptProof'

| 'blockProof'

| 'accountProof'

| 'callProof'

| 'logProof'

type

the type of the proof

example: accountProof

any []

uncles

the list of uncle-headers of the block

example: (optional)

Type RPCRequest¶

Source: index.ts

a JSONRPC-Request with N3-Extension a JSONRPC-Request with N3-Extension

number | string

id

the identifier of the request

example: 2 (optional)

IN3RPCRequestConfig

in3

the IN3-Config (optional)

'2.0'

jsonrpc

the version

string

method

the method to call

example: eth_getBalance

any []

params

the params

example: 0xe36179e2286ef405e929C90ad3E70E649B22a945,latest (optional)

Type RPCResponse¶

Source: index.ts

a JSONRPC-Responset with N3-Extension a JSONRPC-Responset with N3-Extension

string

error

in case of an error this needs to be set (optional)

string | number

id

the id matching the request

example: 2

IN3ResponseConfig

in3

the IN3-Result (optional)

IN3NodeConfig

in3Node

the node handling this response (internal only) (optional)

'2.0'

jsonrpc

the version

any

result

the params

example: 0xa35bc (optional)

Type ServerList¶

Source: index.ts

a List of nodes a List of nodes

string

contract

IN3 Registry (optional)

number

lastBlockNumber

last Block number (optional)

IN3NodeConfig []

nodes

the list of nodes

Proof

proof

the proof (optional)

string

registryId

registry id of the contract (optional)

number

totalServers

number of servers (optional)

Type Signature¶

Source: index.ts

Verified ECDSA Signature. Signatures are a pair (r, s). Where r is computed as the X coordinate of a point R, modulo the curve order n. Verified ECDSA Signature. Signatures are a pair (r, s). Where r is computed as the X coordinate of a point R, modulo the curve order n.

string

address

the address of the signing node

example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679 (optional)

number

block

the blocknumber

example: 3123874

string

blockHash

the hash of the block

example: 0x6C1a01C2aB554930A937B0a212346037E8105fB47946c679

string

msgHash

hash of the message

example: 0x9C1a01C2aB554930A937B0a212346037E8105fB47946AB5D

string

r

Positive non-zero Integer signature.r

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1f

string

s

Positive non-zero Integer signature.s

example: 0x6d17b34aeaf95fee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda

number

v

Calculated curve point, or identity element O.

example: 28

Type Transport¶

Source: index.ts

= _transporttype

Package modules/eth¶

Type EthAPI¶

Source: modules/eth/api.ts

EthAPI

constructor (

client:Client )

constructor

Client

client

the client

Signer

signer

the signer (optional)

Promise<number>

blockNumber ()

Returns the number of most recent block. (as number)

Promise<string>

call (

tx:Transaction ,

block:BlockType )

Executes a new message call immediately without creating a transaction on the block chain.

Promise<any>

callFn (

to:Address ,

method:string,

args:any [])

Executes a function of a contract, by passing a [method-signature](https://github.com/ethereumjs/ethereumjs-abi/blob/master/README.md#simple-encoding-and-decoding) and the arguments, which will then be ABI-encoded and send as eth_call.

Promise<string>

chainId ()

Returns the EIP155 chain ID used for transaction signing at the current best block. Null is returned if not available.

contractAt (

abi:ABI [],

address:Address )

contract at

any

decodeEventData (

log:Log ,

d:ABI )

decode event data

Promise<number>

estimateGas (

tx:Transaction )

Makes a call or transaction, which won’t be added to the blockchain and returns the used gas, which can be used for estimating the used gas.

Promise<number>

gasPrice ()

Returns the current price per gas in wei. (as number)

Promise<BN>

getBalance (

address:Address ,

block:BlockType )

Returns the balance of the account of given address in wei (as hex).

Promise<Block>

getBlockByHash (

hash:Hash ,

includeTransactions:boolean)

Returns information about a block by hash.

Promise<Block>

getBlockByNumber (

block:BlockType ,

includeTransactions:boolean)

Returns information about a block by block number.

Promise<number>

getBlockTransactionCountByHash (

block:Hash )

Returns the number of transactions in a block from a block matching the given block hash.

Promise<number>

getBlockTransactionCountByNumber (

block:Hash )

Returns the number of transactions in a block from a block matching the given block number.

Promise<string>

getCode (

address:Address ,

block:BlockType )

Returns code at a given address.

Promise<>

getFilterChanges (

id:Quantity )

Polling method for a filter, which returns an array of logs which occurred since last poll.

Promise<>

getFilterLogs (

id:Quantity )

Returns an array of all logs matching filter with given id.

Promise<>

getLogs (

filter:LogFilter )

Returns an array of all logs matching a given filter object.

Promise<string>

getStorageAt (

address:Address ,

pos:Quantity ,

block:BlockType )

Returns the value from a storage position at a given address.

Promise<TransactionDetail>

getTransactionByBlockHashAndIndex (

hash:Hash ,

pos:Quantity )

Returns information about a transaction by block hash and transaction index position.

Promise<TransactionDetail>

getTransactionByBlockNumberAndIndex (

block:BlockType ,

pos:Quantity )

Returns information about a transaction by block number and transaction index position.

Promise<TransactionDetail>

getTransactionByHash (

hash:Hash )

Returns the information about a transaction requested by transaction hash.

Promise<number>

getTransactionCount (

address:Address ,

block:BlockType )

Returns the number of transactions sent from an address. (as number)

Promise<TransactionReceipt>

getTransactionReceipt (

hash:Hash )

Returns the receipt of a transaction by transaction hash.

Note That the receipt is available even for pending transactions.

Promise<Block>

getUncleByBlockHashAndIndex (

hash:Hash ,

pos:Quantity )

Returns information about a uncle of a block by hash and uncle index position.

Note: An uncle doesn’t contain individual transactions.

Promise<Block>

getUncleByBlockNumberAndIndex (

block:BlockType ,

pos:Quantity )

Returns information about a uncle of a block number and uncle index position.

Note: An uncle doesn’t contain individual transactions.

Promise<number>

getUncleCountByBlockHash (

hash:Hash )

Returns the number of uncles in a block from a block matching the given block hash.

Promise<number>

getUncleCountByBlockNumber (

block:BlockType )

Returns the number of uncles in a block from a block matching the given block hash.

Buffer

hashMessage (

data:Data

| Buffer )

hash message

Promise<string>

newBlockFilter ()

Creates a filter in the node, to notify when a new block arrives. To check if the state has changed, call eth_getFilterChanges.

Promise<string>

newFilter (

filter:LogFilter )

Creates a filter object, based on filter options, to notify when the state changes (logs). To check if the state has changed, call eth_getFilterChanges.

Promise<string>

newPendingTransactionFilter ()

Creates a filter in the node, to notify when new pending transactions arrive.

Promise<string>

protocolVersion ()

Returns the current ethereum protocol version.

Promise<string>

sendRawTransaction (

data:Data )

Creates new message call transaction or a contract creation for signed transactions.

Promise<>

sendTransaction (

args:TxRequest )

sends a Transaction

Promise<Signature>

sign (

account:Address ,

data:Data )

signs any kind of message using the x19Ethereum Signed Message:n-prefix

Promise<>

syncing ()

Returns the current ethereum protocol version.

Promise<Quantity>

uninstallFilter (

id:Quantity )

Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren’t requested with eth_getFilterChanges for a period of time.

Type chainData¶

Source: modules/eth/chainData.ts

Promise<any>

callContract (

client:Client ,

contract:string,

chainId:string,

signature:string,

args:any [],

config:IN3Config )

call contract

Promise<>

getChainData (

client:Client ,

chainId:string,

config:IN3Config )

get chain data

Type header¶

Source: modules/eth/header.ts

Interface

AuthSpec

Authority specification for proof of authority chains

Interface

HistoryEntry

the HistoryEntry

Promise<void>

addAuraValidators (

history:DeltaHistory<string> ,

ctx:ChainContext ,

states:HistoryEntry [],

contract:string)

add aura validators

void

addCliqueValidators (

history:DeltaHistory<string> ,

ctx:ChainContext ,

states:HistoryEntry [])

add clique validators

Promise<number>

checkBlockSignatures (

blockHeaders:any [],

getChainSpec:)

verify a Blockheader and returns the percentage of finality

void

checkForFinality (

stateBlockNumber:number,

proof:AuraValidatoryProof ,

current:Buffer [],

_finality:number)

check for finality

Promise<void>

checkForValidators (

ctx:ChainContext ,

validators:DeltaHistory<string> )

check for validators

Promise<AuthSpec>

getChainSpec (

b:Block ,

ctx:ChainContext )

get chain spec

Buffer

getCliqueSigner (

data:Block )

get clique signer

Buffer

getSigner (

data:Block )

get signer

Type Signer¶

Source: modules/eth/api.ts

Promise<Transaction>

prepareTransaction (

client:Client ,

tx:Transaction )

optiional method which allows to change the transaction-data before sending it. This can be used for redirecting it through a multisig.

Promise<Signature>

sign (

data:Buffer ,

account:Address )

signing of any data.

Promise<boolean>

hasAccount (

account:Address )

returns true if the account is supported (or unlocked)

Type Transaction¶

Source: modules/eth/api.ts

any

chainId

optional chain id (optional)

string

data

4 byte hash of the method signature followed by encoded parameters. For details see Ethereum Contract ABI.

Address

from

20 Bytes - The address the transaction is send from.

Quantity

gas

Integer of the gas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.

Quantity

gasPrice

Integer of the gas price used for each paid gas.

Quantity

nonce

nonce

Address

to

(optional when creating new contract) 20 Bytes - The address the transaction is directed to.

Quantity

value

Integer of the value sent with this transaction.

Type BlockType¶

Source: modules/eth/api.ts

= number | 'latest' | 'earliest' | 'pending'

Type Address¶

Source: modules/eth/api.ts

= string

Type ABI¶

Source: modules/eth/api.ts

boolean

anonymous

the anonymous (optional)

boolean

constant

the constant (optional)

ABIField []

inputs

the inputs (optional)

string

name

the name (optional)

ABIField []

outputs

the outputs (optional)

boolean

payable

the payable (optional)

'nonpayable'

| 'payable'

| 'view'

| 'pure'

stateMutability

the stateMutability (optional)

'event'

| 'function'

| 'constructor'

| 'fallback'

type

the type

Type Log¶

Source: modules/eth/api.ts

Address

address

20 Bytes - address from which this log originated.

Hash

blockHash

Hash, 32 Bytes - hash of the block where this log was in. null when its pending. null when its pending log.

Quantity

blockNumber

the block number where this log was in. null when its pending. null when its pending log.

Data

data

contains the non-indexed arguments of the log.

Quantity

logIndex

integer of the log index position in the block. null when its pending log.

boolean

removed

true when the log was removed, due to a chain reorganization. false if its a valid log.

Data []

topics

- Array of 0 to 4 32 Bytes DATA of indexed log arguments. (In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256)), except you declared the event with the anonymous specifier.)

Hash

transactionHash

Hash, 32 Bytes - hash of the transactions this log was created from. null when its pending log.

Quantity

transactionIndex

integer of the transactions index position log was created from. null when its pending log.

Type Block¶

Source: modules/eth/api.ts

Address

author

20 Bytes - the address of the author of the block (the beneficiary to whom the mining rewards were given)

Quantity

difficulty

integer of the difficulty for this block

Data

extraData

the ‘extra data’ field of this block

Quantity

gasLimit

the maximum gas allowed in this block

Quantity

gasUsed

the total used gas by all transactions in this block

Hash

hash

hash of the block. null when its pending block

Data

logsBloom

256 Bytes - the bloom filter for the logs of the block. null when its pending block

Address

miner

20 Bytes - alias of ‘author’

Data

nonce

8 bytes hash of the generated proof-of-work. null when its pending block. Missing in case of PoA.

Quantity

number

The block number. null when its pending block

Hash

parentHash

hash of the parent block

Data

receiptsRoot

32 Bytes - the root of the receipts trie of the block

Data []

sealFields

PoA-Fields

Data

sha3Uncles

SHA3 of the uncles data in the block

Quantity

size

integer the size of this block in bytes

Data

stateRoot

32 Bytes - the root of the final state trie of the block

Quantity

timestamp

the unix timestamp for when the block was collated

Quantity

totalDifficulty

integer of the total difficulty of the chain until this block

string | []

transactions

Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter

Data

transactionsRoot

32 Bytes - the root of the transaction trie of the block

Hash []

uncles

Array of uncle hashes

Type Hash¶

Source: modules/eth/api.ts

= string

Type Quantity¶

Source: modules/eth/api.ts

= number | Hex

Type LogFilter¶

Source: modules/eth/api.ts

Address

address

(optional) 20 Bytes - Contract address or a list of addresses from which logs should originate.

BlockType

fromBlock

Quantity or Tag - (optional) (default: latest) Integer block number, or ‘latest’ for the last mined block or ‘pending’, ‘earliest’ for not yet mined transactions.

Quantity

limit

å(optional) The maximum number of entries to retrieve (latest first).

BlockType

toBlock

Quantity or Tag - (optional) (default: latest) Integer block number, or ‘latest’ for the last mined block or ‘pending’, ‘earliest’ for not yet mined transactions.

string | string [] []

topics

(optional) Array of 32 Bytes Data topics. Topics are order-dependent. It’s possible to pass in null to match any topic, or a subarray of multiple topics of which one should be matching.

Type TransactionDetail¶

Source: modules/eth/api.ts

Hash

blockHash

32 Bytes - hash of the block where this transaction was in. null when its pending.

BlockType

blockNumber

block number where this transaction was in. null when its pending.

Quantity

chainId

the chain id of the transaction, if any.

any

condition

(optional) conditional submission, Block number in block or timestamp in time or null. (parity-feature)

Address

creates

creates contract address

Address

from

20 Bytes - address of the sender.

Quantity

gas

gas provided by the sender.

Quantity

gasPrice

gas price provided by the sender in Wei.

Hash

hash

32 Bytes - hash of the transaction.

Data

input

the data send along with the transaction.

Quantity

nonce

the number of transactions made by the sender prior to this one.

any

pk

optional: the private key to use for signing (optional)

Hash

publicKey

public key of the signer.

Quantity

r

the R field of the signature.

Data

raw

raw transaction data

Quantity

standardV

the standardised V field of the signature (0 or 1).

Address

to

20 Bytes - address of the receiver. null when its a contract creation transaction.

Quantity

transactionIndex

integer of the transactions index position in the block. null when its pending.

Quantity

v

the standardised V field of the signature.

Quantity

value

value transferred in Wei.

Type TransactionReceipt¶

Source: modules/eth/api.ts

Hash

blockHash

32 Bytes - hash of the block where this transaction was in.

BlockType

blockNumber

block number where this transaction was in.

Address

contractAddress

20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null.

Quantity

cumulativeGasUsed

The total amount of gas used when this transaction was executed in the block.

Address

from

20 Bytes - The address of the sender.

Quantity

gasUsed

The amount of gas used by this specific transaction alone.

Log []

logs

Array of log objects, which this transaction generated.

Data

logsBloom

256 Bytes - A bloom filter of logs/events generated by contracts during transaction execution. Used to efficiently rule out transactions without expected logs.

Hash

root

32 Bytes - Merkle root of the state trie after the transaction has been executed (optional after Byzantium hard fork EIP609)

Quantity

status

0x0 indicates transaction failure , 0x1 indicates transaction success. Set for blocks mined after Byzantium hard fork EIP609, null before.

Address

to

20 Bytes - The address of the receiver. null when it’s a contract creation transaction.

Hash

transactionHash

32 Bytes - hash of the transaction.

Quantity

transactionIndex

Integer of the transactions index position in the block.

Type Data¶

Source: modules/eth/api.ts

= string

Type TxRequest¶

Source: modules/eth/api.ts

any []

args

the argument to pass to the method (optional)

number

confirmations

number of block to wait before confirming (optional)

Data

data

the data to send (optional)

Address

from

address of the account to use (optional)

number

gas

the gas needed (optional)

number

gasPrice

the gasPrice used (optional)

string

method

the ABI of the method to be used (optional)

number

nonce

the nonce (optional)

Hash

pk

raw private key in order to sign (optional)

Address

to

contract (optional)

Quantity

value

the value in wei (optional)

Type AuthSpec¶

Source: modules/eth/header.ts

Authority specification for proof of authority chains

Buffer []

authorities

List of validator addresses storead as an buffer array

Buffer

proposer

proposer of the block this authspec belongs

ChainSpec

spec

chain specification

Type HistoryEntry¶

Source: modules/eth/header.ts

number

block

the block

AuraValidatoryProof

| string []

proof

the proof

string []

validators

the validators

Type ABIField¶

Source: modules/eth/api.ts

boolean

indexed

the indexed (optional)

string

name

the name

string

type

the type

Type Hex¶

Source: modules/eth/api.ts

= string

Package modules/ipfs¶

Type IpfsAPI¶

Source: modules/ipfs/api.ts

simple API for IPFS

IpfsAPI

constructor (

_client:Client )

simple API for IPFS

Client

client

the client

Promise<Buffer>

get (

hash:string,

resultEncoding:string)

retrieves the conent for a hash from IPFS.

Promise<string>

put (

data:Buffer ,

dataEncoding:string)

stores the data on ipfs and returns the IPFS-Hash.

Package util¶

a collection of util classes inside incubed. They can be get directly through require('in3/js/srrc/util/util')

Type DeltaHistory¶

Source: util/DeltaHistory.ts

DeltaHistory

constructor (

init:T [],

deltaStrings:boolean)

constructor

Delta<T> []

data

the data

void

addState (

start:number,

data:T [])

add state

T []

getData (

index:number)

get data

number

getLastIndex ()

get last index

void

loadDeltaStrings (

deltas:string [])

load delta strings

string []

toDeltaStrings ()

to delta strings

Type Delta¶

Source: util/DeltaHistory.ts

This file is part of the Incubed project. Sources: https://github.com/slockit/in3

number

block

the block

T []

data

the data

number

len

the len

number

start

the start

Common Module¶

The common module (in3-common) contains all the typedefs used in the node and server.

Interface

BlockData

the BlockData

Interface

LogData

the LogData

Type

Receipt

the Receipt

Interface

ReceiptData

the ReceiptData

Type

Transaction

the Transaction

Interface

TransactionData

the TransactionData

Interface

Transport

the Transport

AxiosTransport

AxiosTransport

the AxiosTransport

value= _transport.AxiosTransport

Block

Block

the Block

value= _serialize.Block

any

address (

val:any)

converts it to a Buffer with 20 bytes length

Block

blockFromHex (

hex:string)

converts a hexstring to a block-object

any

bytes (

val:any)

converts it to a Buffer

any

bytes32 (

val:any)

converts it to a Buffer with 32 bytes length

any

bytes8 (

val:any)

converts it to a Buffer with 8 bytes length

cbor

cbor

the cbor

value= _cbor

chainAliases

the chainAliases

value= _util.aliases

number []

createRandomIndexes (

len:number,

limit:number,

seed:Buffer ,

result:number [])

create random indexes

any

createTx (

transaction:any)

creates a Transaction-object from the rpc-transaction-data

Buffer

getSigner (

data:Block )

get signer

Buffer

hash (

val:Block

| Transaction

| Receipt

| Account

| Buffer )

returns the hash of the object

index

rlp

the rlp

value= _serialize.rlp

serialize

serialize

the serialize

value= _serialize

storage

storage

the storage

value= _storage

Buffer []

toAccount (

account:AccountData )

to account

Buffer []

toBlockHeader (

block:BlockData )

create a Buffer[] from RPC-Response

Object

toReceipt (

r:ReceiptData )

create a Buffer[] from RPC-Response

Buffer []

toTransaction (

tx:TransactionData )

create a Buffer[] from RPC-Response

transport

transport

the transport

value= _transport

any

uint (

val:any)

converts it to a Buffer with a variable length. 0 = length 0

any

uint128 (

val:any)

uint128

any

uint64 (

val:any)

uint64

util

util

the util

value= _util

validate

validate

the validate

value= _validate

Promise<>

handle (

url:string,

data:RPCRequest

| RPCRequest [],

timeout:number)

handles a request by passing the data to the handler

Promise<boolean>

isOnline ()

check whether the handler is onlne.

number []

random (

count:number)

generates random numbers (between 0-1)

Package modules/eth¶

Type Block¶

encodes and decodes the blockheader

Block

constructor (

data:Buffer

| string

| BlockData )

creates a Block-Onject from either the block-data as returned from rpc, a buffer or a hex-string of the encoded blockheader

BlockHeader

raw

the raw Buffer fields of the BlockHeader

Tx []

transactions

the transaction-Object (if given)

Buffer

bloom

bloom

Buffer

coinbase

coinbase

Buffer

difficulty

difficulty

Buffer

extra

extra

Buffer

gasLimit

gas limit

Buffer

gasUsed

gas used

Buffer

number

number

Buffer

parentHash

parent hash

Buffer

receiptTrie

receipt trie

Buffer []

sealedFields

sealed fields

Buffer

stateRoot

state root

Buffer

timestamp

timestamp

Buffer

transactionsTrie

transactions trie

Buffer

uncleHash

uncle hash

Buffer

bareHash ()

the blockhash as buffer without the seal fields

Buffer

hash ()

the blockhash as buffer

Buffer

serializeHeader ()

the serialized header as buffer

Type Transaction¶

Buffer[] of the transaction = Buffer []

Type Receipt¶

Buffer[] of the Receipt = [ Buffer ,Buffer ,Buffer ,Buffer , Buffer [] , Buffer [] ]

Type Account¶

Buffer[] of the Account = Buffer []

Type serialize¶

Class

Block

encodes and decodes the blockheader

Interface

AccountData

Account-Object

Interface

BlockData

Block as returned by eth_getBlockByNumber

Interface

LogData

LogData as part of the TransactionReceipt

Interface

ReceiptData

TransactionReceipt as returned by eth_getTransactionReceipt

Interface

TransactionData

Transaction as returned by eth_getTransactionByHash

Type

Account

Buffer[] of the Account

Type

BlockHeader

Buffer[] of the header

Type

Receipt

Buffer[] of the Receipt

Type

Transaction

Buffer[] of the transaction

index

rlp

RLP-functions

value= ethUtil.rlp

any

address (

val:any)

converts it to a Buffer with 20 bytes length

Block

blockFromHex (

hex:string)

converts a hexstring to a block-object

string

blockToHex (

block:any)

converts blockdata to a hexstring

any

bytes (

val:any)

converts it to a Buffer

any

bytes256 (

val:any)

converts it to a Buffer with 256 bytes length

any

bytes32 (

val:any)

converts it to a Buffer with 32 bytes length

any

bytes8 (

val:any)

converts it to a Buffer with 8 bytes length

any

createTx (

transaction:any)

creates a Transaction-object from the rpc-transaction-data

Buffer

hash (

val:Block

| Transaction

| Receipt

| Account

| Buffer )

returns the hash of the object

Buffer

serialize (

val:Block

| Transaction

| Receipt

| Account

| any)

serialize the data

Buffer []

toAccount (

account:AccountData )

to account

Buffer []

toBlockHeader (

block:BlockData )

create a Buffer[] from RPC-Response

Object

toReceipt (

r:ReceiptData )

create a Buffer[] from RPC-Response

Buffer []

toTransaction (

tx:TransactionData )

create a Buffer[] from RPC-Response

any

uint (

val:any)

converts it to a Buffer with a variable length. 0 = length 0

any

uint128 (

val:any)

uint128

any

uint64 (

val:any)

uint64

Type storage¶

Source: modules/eth/storage.ts

any

getStorageArrayKey (

pos:number,

arrayIndex:number,

structSize:number,

structPos:number)

calc the storrage array key

any

getStorageMapKey (

pos:number,

key:string,

structPos:number)

calcs the storage Map key.

Promise<>

getStorageValue (

rpc:string,

contract:string,

pos:number,

type:'address'

| 'bytes32'

| 'bytes16'

| 'bytes4'

| 'int'

| 'string',

keyOrIndex:number

| string,

structSize:number,

structPos:number)

get a storage value from the server

string |

getStringValue (

data:Buffer ,

storageKey:Buffer )

creates a string from storage.

string

getStringValueFromList (

values:Buffer [],

len:number)

concats the storage values to a string.

BN

toBN (

val:any)

converts any value to BN

Type AccountData¶

Account-Object

string

balance

the balance

string

code

the code (optional)

string

codeHash

the codeHash

string

nonce

the nonce

string

storageHash

the storageHash

Type BlockHeader¶

Buffer[] of the header = Buffer []

Package types¶

Type RPCRequest¶

Source: types/types.ts

a JSONRPC-Request with N3-Extension

number | string

id

the identifier of the request

example: 2 (optional)

IN3RPCRequestConfig

in3

the IN3-Config (optional)

'2.0'

jsonrpc

the version

string

method

the method to call

example: eth_getBalance

any []

params

the params

example: 0xe36179e2286ef405e929C90ad3E70E649B22a945,latest (optional)

Type RPCResponse¶

Source: types/types.ts

a JSONRPC-Responset with N3-Extension

string

error

in case of an error this needs to be set (optional)

string | number

id

the id matching the request

example: 2

IN3ResponseConfig

in3

the IN3-Result (optional)

IN3NodeConfig

in3Node

the node handling this response (internal only) (optional)

'2.0'

jsonrpc

the version

any

result

the params

example: 0xa35bc (optional)

Type IN3RPCRequestConfig¶

Source: types/types.ts

additional config for a IN3 RPC-Request

string

chainId

the requested chainId

example: 0x1

any

clientSignature

the signature of the client (optional)

number

finality

if given the server will deliver the blockheaders of the following blocks until at least the number in percent of the validators is reached. (optional)

boolean

includeCode

if true, the request should include the codes of all accounts. otherwise only the the codeHash is returned. In this case the client may ask by calling eth_getCode() afterwards

example: true (optional)

number

latestBlock

if specified, the blocknumber latest will be replaced by blockNumber- specified value

example: 6 (optional)

string []

signatures

a list of addresses requested to sign the blockhash

example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679 (optional)

boolean

useBinary

if true binary-data will be used. (optional)

boolean

useFullProof

if true all data in the response will be proven, which leads to a higher payload. (optional)

boolean

useRef

if true binary-data (starting with a 0x) will be refered if occuring again. (optional)

'never'

| 'proof'

| 'proofWithSignature'

verification

defines the kind of proof the client is asking for

example: proof (optional)

string []

verifiedHashes

if the client sends a array of blockhashes the server will not deliver any signatures or blockheaders for these blocks, but only return a string with a number. (optional)

string

version

IN3 protocol version that client can specify explicitly in request

example: 1.0.0 (optional)

Type IN3ResponseConfig¶

Source: types/types.ts

additional data returned from a IN3 Server

number

currentBlock

the current blocknumber.

example: 320126478 (optional)

number

lastNodeList

the blocknumber for the last block updating the nodelist. If the client has a smaller blocknumber he should update the nodeList.

example: 326478 (optional)

number

lastValidatorChange

the blocknumber of gthe last change of the validatorList (optional)

Proof

proof

the Proof-data (optional)

string

version

the in3 protocol version.

example: 1.0.0 (optional)

Type IN3NodeConfig¶

Source: types/types.ts

a configuration of a in3-server.

string

address

the address of the node, which is the public address it iis signing with.

example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679

number

capacity

the capacity of the node.

example: 100 (optional)

string []

chainIds

the list of supported chains

example: 0x1

number

deposit

the deposit of the node in wei

example: 12350000

number

index

the index within the contract

example: 13 (optional)

number

props

the properties of the node.

example: 3 (optional)

number

registerTime

the UNIX-timestamp when the node was registered

example: 1563279168 (optional)

number

timeout

the time (in seconds) until an owner is able to receive his deposit back after he unregisters himself

example: 3600 (optional)

number

unregisterTime

the UNIX-timestamp when the node is allowed to be deregister

example: 1563279168 (optional)

string

url

the endpoint to post to

example: https://in3.slock.it

Type Proof¶

Source: types/types.ts

the Proof-data as part of the in3-section

accounts

a map of addresses and their AccountProof (optional)

string

block

the serialized blockheader as hex, required in most proofs

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b (optional)

any []

finalityBlocks

the serialized blockheader as hex, required in case of finality asked

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda6463a8f1ebb14f3aff6b19cb91acf2b8ec1ffee98c0437b4ac839d8a2ece1b18166da704b (optional)

LogProof

logProof

the Log Proof in case of a Log-Request (optional)

string []

merkleProof

the serialized merle-noodes beginning with the root-node (optional)

string []

merkleProofPrev

the serialized merkle-noodes beginning with the root-node of the previous entry (only for full proof of receipts) (optional)

Signature []

signatures

requested signatures (optional)

any []

transactions

the list of transactions of the block

example: (optional)

number

txIndex

the transactionIndex within the block

example: 4 (optional)

string []

txProof

the serialized merkle-nodes beginning with the root-node in order to prrof the transactionIndex (optional)

'transactionProof'

| 'receiptProof'

| 'blockProof'

| 'accountProof'

| 'callProof'

| 'logProof'

type

the type of the proof

example: accountProof

any []

uncles

the list of uncle-headers of the block

example: (optional)

Type LogProof¶

Source: types/types.ts

a Object holding proofs for event logs. The key is the blockNumber as hex

Type Signature¶

Source: types/types.ts

Verified ECDSA Signature. Signatures are a pair (r, s). Where r is computed as the X coordinate of a point R, modulo the curve order n.

string

address

the address of the signing node

example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679 (optional)

number

block

the blocknumber

example: 3123874

string

blockHash

the hash of the block

example: 0x6C1a01C2aB554930A937B0a212346037E8105fB47946c679

string

msgHash

hash of the message

example: 0x9C1a01C2aB554930A937B0a212346037E8105fB47946AB5D

string

r

Positive non-zero Integer signature.r

example: 0x72804cfa0179d648ccbe6a65b01a6463a8f1ebb14f3aff6b19cb91acf2b8ec1f

string

s

Positive non-zero Integer signature.s

example: 0x6d17b34aeaf95fee98c0437b4ac839d8a2ece1b18166da704b86d8f42c92bbda

number

v

Calculated curve point, or identity element O.

example: 28

Package util¶

Type AxiosTransport¶

Source: util/transport.ts

Default Transport impl sending http-requests.

AxiosTransport

constructor (

format:'json'

| 'cbor'

| 'jsonRef')

Default Transport impl sending http-requests.

'json' | 'cbor' | 'jsonRef'

format

the format

Promise<>

handle (

url:string,

data:RPCRequest

| RPCRequest [],

timeout:number)

handle

Promise<boolean>

isOnline ()

is online

number []

random (

count:number)

random

Type cbor¶

Source: util/cbor.ts

any

convertToBuffer (

val:any)

convert to buffer

any

convertToHex (

val:any)

convert to hex

T

createRefs (

val:T ,

cache:string [])

create refs

RPCRequest []

decodeRequests (

request:Buffer )

decode requests

RPCResponse []

decodeResponses (

responses:Buffer )

decode responses

Buffer

encodeRequests (

requests:RPCRequest [])

turn

Buffer

encodeResponses (

responses:RPCResponse [])

encode responses

T

resolveRefs (

val:T ,

cache:string [])

resolve refs

Type transport¶

Source: util/transport.ts

Class

AxiosTransport

Default Transport impl sending http-requests.

Interface

Transport

A Transport-object responsible to transport the message to the handler.

Type util¶

Source: util/util.ts

BN

BN

the BN

value= ethUtil.BN

any

Buffer

This file is part of the Incubed project.

Sources: https://github.com/slockit/in3-common

value= require('buffer').Buffer

T

checkForError (

res:T )

check a RPC-Response for errors and rejects the promise if found

number []

createRandomIndexes (

len:number,

limit:number,

seed:Buffer ,

result:number [])

create random indexes

string

fixLength (

hex:string)

fix length

string

getAddress (

pk:string)

returns a address from a private key

Buffer

getSigner (

data:Block )

get signer

string

padEnd (

val:string,

minLength:number,

fill:string)

padEnd for legacy

string

padStart (

val:string,

minLength:number,

fill:string)

padStart for legacy

Promise<any>

promisify (

self:any,

fn:any,

args:any [])

simple promisy-function

BN

toBN (

val:any)

convert to BigNumber

any

toBuffer (

val:any,

len:number)

converts any value as Buffer

if len === 0 it will return an empty Buffer if the value is 0 or ‘0x00’, since this is the way rlpencode works wit 0-values.

string

toHex (

val:any,

bytes:number)

converts any value as hex-string

string

toMinHex (

key:string

| Buffer

| number)

removes all leading 0 in the hexstring

number

toNumber (

val:any)

converts to a js-number

string

toSimpleHex (

val:string)

removes all leading 0 in a hex-string

string

toUtf8 (

val:any)

to utf8

JSON

``object``

the aliases

Type validate¶

Source: util/validate.ts

Ajv

ajv

the ajv instance with custom formatters and keywords

value= new Ajv()

void

validate (

ob:any,

def:any)

validate

void

validateAndThrow (

fn:Ajv.ValidateFunction ,

ob:any)

validates the data and throws an error in case they are not valid.

API Reference WASM¶

Even though the incubed client is written in C, we are using emscripten to build wasm. Together with some binding-code incubed runs in any Javascript-Runtime. Using WASM gives us 3 important features:

Performance. Since WASM runs at almost native speed it is very fast
Security Since the WASM-Module has no dependencies it reduces the risk of using a malicious dependency, which would be able to manipulate Prototypes. Also, since the real work is happening inside the wasm, trying to change Prototype would not work.
Size The current wasm-file is about 200kb. This is smaller then most other libraries and can easily be used in any app or website.

Installing¶

This client uses the in3-core sources compiled to wasm. The wasm is included into the js-file wich makes it easier to include the data. This module has no dependencies! All it needs is included inta a wasm of about 300kB.

Installing incubed is as easy as installing any other module:

npm install --save in3-wasm

WASM-support¶

Even though most browsers and javascript enviroment such as nodejs, have full support for wasm, there are ocasions, where WASM is fully supported. In case you want to run incubed within a react native app, you might face such issues. In this case you can use in3-asmjs, which has the same API, but runs on pure javascript (a bit slower and bigger, but full support everywhere).

Building from Source¶

install emscripten¶

In order to build the wasm or asmjs from source you need to install emscripten first. In case you have not done it yet:

# Get the emsdk repo
git clone https://github.com/emscripten-core/emsdk.git

# Enter that directory
cd emsdk

# install the latest-upstream sdk and activate it
./emsdk install latest-upstream && ./emsdk activate latest-upstream

# Please make sure you add this line to your .bash_profile or .zshrc 
source <PATH_TO_EMSDK>/emsdk_env.sh > /dev/null

CMake¶

With emscripten set up, you can now configure the wasm and build it (in the in3-c directory):

# create a build directory
mkdir -p build
cd build

# configure CMake
emcmake cmake -DWASM=true -DCMAKE_BUILD_TYPE=MINSIZEREL .. 

# and build it
make -j8 in3_wasm

# optionally you can also run the tests
make test

Per default the generated wasm embedded the wasm-data as base64 and resulted in the build/module. If you want to build asmjs, use the -DASMJS=true as an additional option. If you don’t want to embedd the wasm, add -DWASM_EMBED=false. If you want to set the -DCMAKE_BUILD_TYPE=DEBUG your filesize increases but all function names are kept (resulting in readable stacktraces) and emscriptten will add a lot of checks and assertions.

For more options please see the CMake Options.

Examples¶

get_block_rpc¶

source : in3-c/wasm/examples/get_block_rpc.js

read block as rpc

/// read block as rpc

const IN3 = require('in3-wasm')

async function showLatestBlock() {
    // create new incubed instance
    var c = new IN3()

    await c.setConfig({
        chainId: 0x5 // use goerli
    })

    // send raw RPC-Request
    const lastBlockResponse = await c.send({ method: 'eth_getBlockByNumber', params: ['latest', false] })

    if (lastBlockResponse.error)
        console.error("Error getting the latest block : ", lastBlockResponse.error)
    else
        console.log("latest Block: ", JSON.stringify(lastBlockResponse.result, null, 2))

    // clean up
    c.free()

}

showLatestBlock().catch(console.error)

get_block_api¶

source : in3-c/wasm/examples/get_block_api.ts

read block with API

/// read block with API

import { IN3 } from 'in3-wasm'

async function showLatestBlock() {
  // create new incubed instance
  const client = new IN3({
    chainId: 'goerli'
  })

  // send raw RPC-Request
  const lastBlock = await client.eth.getBlockByNumber()

  console.log("latest Block: ", JSON.stringify(lastBlock, null, 2))

  // clean up
  client.free()

}

showLatestBlock().catch(console.error)

use_web3¶

source : in3-c/wasm/examples/use_web3.ts

use incubed as Web3Provider in web3js

/// use incubed as Web3Provider in web3js 

// import in3-Module
import { IN3 } from 'in3-wasm'
const Web3 = require('web3')

const in3 = new IN3({
    proof: 'standard',
    signatureCount: 1,
    requestCount: 1,
    chainId: 'mainnet',
    replaceLatestBlock: 10
})

// use the In3Client as Http-Provider
const web3 = new Web3(in3.createWeb3Provider());

(async () => {

    // use the web3
    const block = await web3.eth.getBlock('latest')
    console.log("Block : ", block)

})().catch(console.error);

in3_in_browser¶

source : in3-c/wasm/examples/in3_in_browser.html

use incubed directly in html

<!-- use incubed directly in html -->
<html>

<head>
    <script src="node_modules/in3-wasm/index.js"></script>
</head>

<body>
    IN3-Demo
    <div>
        result:
        <pre id="result"> ...waiting... </pre>
    </div>
    <script>
        var in3 = new IN3({ chainId: 0x1, replaceLatestBlock: 6, requestCount: 3 });
        in3.eth.getBlockByNumber('latest', false)
            .then(block => document.getElementById('result').innerHTML = JSON.stringify(block, null, 2))
            .catch(alert)
            .finally(() => in3.free())
    </script>
</body>

</html>

Building¶

In order to run those examples, you need to install in3-wasm and typescript first. The build.sh will do this and the run the tsc-compiler

./build.sh

In order to run a example use

node build/get_block_api.ts

Incubed Module¶

This page contains a list of all Datastructures and Classes used within the IN3 WASM-Client

Importing incubed is as easy as

import {IN3} from "in3-wasm"

BufferType and BigIntType¶

The WASM-Module comes with no dependencies. This means per default it uses the standard classes provided as part of the EMCAScript-Standard.

If you work with a library which expects different types, you can change the generic-type and giving a converter:

Type BigIntType¶

Per default we use bigint. This is used whenever we work with number too big to be stored as a number-type.

If you want to change this type, use setConverBigInt() function.

Type Buffer¶

Per default we use UInt8Array. This is used whenever we work with raw bytes.

If you want to change this type, use setConverBuffer() function.

Generics¶

import {IN3Generic} from 'in3-wasm'
import BN from 'bn.js'

// create a new client by setting the Generic Types
const c = new IN3Generic<BN,Buffer>()

// set the converter-functions
IN3Generic.setConverBuffer(val => Buffer.from(val))
IN3Generic.setConverBigInt(val => new BN(val))

Package¶

While the In3Client-class is also the default import, the following imports can be used:

IN3

Class

default Incubed client with

bigint for big numbers

Uint8Array for bytes

IN3Generic

Class

the IN3Generic

SimpleSigner

Class

the SimpleSigner

BTCBlock

Interface

a full Block including the transactions

BTCBlockHeader

Interface

a Block header

BtcAPI

Interface

API for handling BitCoin data

BtcTransaction

Interface

a BitCoin Transaction.

BtcTransactionInput

Interface

a Input of a Bitcoin Transaction

BtcTransactionOutput

Interface

a Input of a Bitcoin Transaction

EthAPI

Interface

the EthAPI

IN3Config

Interface

the configuration of the IN3-Client. This can be changed at any time.

All properties are optional and will be verified when sending the next request.

IN3NodeConfig

Interface

a configuration of a in3-server.

IN3NodeWeight

Interface

a local weight of a n3-node. (This is used internally to weight the requests)

IpfsAPI

Interface

API for storing and retrieving IPFS-data.

RPCRequest

Interface

a JSONRPC-Request with N3-Extension

RPCResponse

Interface

a JSONRPC-Responset with N3-Extension

Signer

Interface

the Signer

Utils

Interface

Collection of different util-functions.

Web3Event

Interface

the Web3Event

ABI

Type literal

the ABI

ABIField

Type literal

the ABIField

Address

Type alias

a 20 byte Address encoded as Hex (starting with 0x)

Block

Type literal

the Block

BlockType

Type

BlockNumber or predefined Block

Data

Type alias

data encoded as Hex (starting with 0x)

Hash

Type alias

a 32 byte Hash encoded as Hex (starting with 0x)

Hex

Type

a Hexcoded String (starting with 0x)

Log

Type literal

the Log

LogFilter

Type literal

the LogFilter

Quantity

Type

a BigInteger encoded as hex.

Signature

Type literal

Signature

Transaction

Type literal

the Transaction

TransactionDetail

Type literal

the TransactionDetail

TransactionReceipt

Type literal

the TransactionReceipt

TxRequest

Type literal

the TxRequest

Package in3¶

Type IN3¶

Source: in3.d.ts

default Incubed client with bigint for big numbers Uint8Array for bytes

default

IN3Generic

supporting both ES6 and UMD usage

util

Utils<any>

collection of util-functions.

btc

BtcAPI<Uint8Array>

Bitcoin API.

config

IN3Config

IN3 config

eth

EthAPI<bigint,Uint8Array>

eth1 API.

ipfs

IpfsAPI<Uint8Array>

ipfs API.

signer

Signer<bigint,Uint8Array>

the signer, if specified this interface will be used to sign transactions, if not, sending transaction will not be possible.

util

Utils<Uint8Array>

collection of util-functions.

freeAll()¶

frees all Incubed instances.

static void freeAll ()

onInit()¶

registers a function to be called as soon as the wasm is ready. If it is already initialized it will call it right away.

static Promise<T> onInit (: fn:() => T )

Parameters:

fn

() => T

the function to call

Returns:

static Promise<T>

setConvertBigInt()¶

set convert big int

static any setConvertBigInt (: convert:(any) => any)

Parameters:

convert

(any) => any

convert

Returns:

static any

setConvertBuffer()¶

set convert buffer

static any setConvertBuffer (: convert:(any) => any)

Parameters:

convert

(any) => any

convert

Returns:

static any

setStorage()¶

changes the storage handler, which is called to read and write to the cache.

static void setStorage (: handler:)

Parameters:

handler

handler

setTransport()¶

changes the transport-function.

static void setTransport (: fn:(string , string , number) => Promise<string>)

Parameters:

fn

(string , string , number) => Promise<string>

the function to fetch the response for the given url

constructor()¶

creates a new client.

IN3 constructor (: config:Partial<IN3Config> )

Parameters:

config

Partial<IN3Config>

a optional config

Returns:

createWeb3Provider()¶

returns a Object, which can be used as Web3Provider.

const web3 = new Web3(new IN3().createWeb3Provider())

any createWeb3Provider ()

Returns:

any

free()¶

disposes the Client. This must be called in order to free allocated memory!

any free ()

Returns:

any

send()¶

sends a raw request. if the request is a array the response will be a array as well. If the callback is given it will be called with the response, if not a Promise will be returned. This function supports callback so it can be used as a Provider for the web3.

Promise<RPCResponse> send (: request:RPCRequest , callback:(Error , RPCResponse ) => void)

Parameters:

request

RPCRequest

a JSONRPC-Request with N3-Extension

callback

(Error , RPCResponse ) => void

callback

Returns:

Promise<RPCResponse>

sendRPC()¶

sends a RPC-Requests specified by name and params.

if the response contains an error, this will be thrown. if not the result will be returned.

Promise<any> sendRPC (: method:string, params:any [])

Parameters:

method

string

the method to call.

params

any []

params

Returns:

Promise<any>

setConfig()¶

sets configuration properties. You can pass a partial object specifieing any of defined properties.

void setConfig (: config:Partial<IN3Config> )

Parameters:

config

Partial<IN3Config>

config

Type IN3Generic¶

Source: in3.d.ts

default

IN3Generic

supporting both ES6 and UMD usage

util

Utils<any>

collection of util-functions.

btc

BtcAPI<BufferType>

Bitcoin API.

config

IN3Config

IN3 config

eth

EthAPI<BigIntType,BufferType>

eth1 API.

ipfs

IpfsAPI<BufferType>

ipfs API.

signer

Signer<BigIntType,BufferType>

the signer, if specified this interface will be used to sign transactions, if not, sending transaction will not be possible.

util

Utils<BufferType>

collection of util-functions.

freeAll()¶

frees all Incubed instances.

static void freeAll ()

onInit()¶

registers a function to be called as soon as the wasm is ready. If it is already initialized it will call it right away.

static Promise<T> onInit (: fn:() => T )

Parameters:

fn

() => T

the function to call

Returns:

static Promise<T>

setConvertBigInt()¶

set convert big int

static any setConvertBigInt (: convert:(any) => any)

Parameters:

convert

(any) => any

convert

Returns:

static any

setConvertBuffer()¶

set convert buffer

static any setConvertBuffer (: convert:(any) => any)

Parameters:

convert

(any) => any

convert

Returns:

static any

setStorage()¶

changes the storage handler, which is called to read and write to the cache.

static void setStorage (: handler:)

Parameters:

handler

handler

setTransport()¶

changes the transport-function.

static void setTransport (: fn:(string , string , number) => Promise<string>)

Parameters:

fn

(string , string , number) => Promise<string>

the function to fetch the response for the given url

constructor()¶

creates a new client.

IN3Generic constructor (: config:Partial<IN3Config> )

Parameters:

config

Partial<IN3Config>

a optional config

Returns:

IN3Generic

createWeb3Provider()¶

returns a Object, which can be used as Web3Provider.

const web3 = new Web3(new IN3().createWeb3Provider())

any createWeb3Provider ()

Returns:

any

free()¶

disposes the Client. This must be called in order to free allocated memory!

any free ()

Returns:

any

send()¶

sends a raw request. if the request is a array the response will be a array as well. If the callback is given it will be called with the response, if not a Promise will be returned. This function supports callback so it can be used as a Provider for the web3.

Promise<RPCResponse> send (: request:RPCRequest , callback:(Error , RPCResponse ) => void)

Parameters:

request

RPCRequest

a JSONRPC-Request with N3-Extension

callback

(Error , RPCResponse ) => void

callback

Returns:

Promise<RPCResponse>

sendRPC()¶

sends a RPC-Requests specified by name and params.

if the response contains an error, this will be thrown. if not the result will be returned.

Promise<any> sendRPC (: method:string, params:any [])

Parameters:

method

string

the method to call.

params

any []

params

Returns:

Promise<any>

setConfig()¶

sets configuration properties. You can pass a partial object specifieing any of defined properties.

void setConfig (: config:Partial<IN3Config> )

Parameters:

config

Partial<IN3Config>

config

Type SimpleSigner¶

Source: in3.d.ts

accounts

the accounts

constructor()¶

constructor

SimpleSigner constructor (: pks:string | BufferType [])

Parameters:

pks

string | BufferType []

pks

Returns:

SimpleSigner

prepareTransaction()¶

optiional method which allows to change the transaction-data before sending it. This can be used for redirecting it through a multisig.

Promise<Transaction> prepareTransaction (: client:IN3Generic<BigIntType,BufferType> , tx:Transaction )

Parameters:

client

IN3Generic<BigIntType,BufferType>

client

tx

Transaction

tx

Returns:

Promise<Transaction>

sign()¶

signing of any data. if hashFirst is true the data should be hashed first, otherwise the data is the hash.

Promise<BufferType> sign (: data:Hex , account:Address , hashFirst:boolean, ethV:boolean)

Parameters:

data

Hex

a Hexcoded String (starting with 0x)

account

Address

a 20 byte Address encoded as Hex (starting with 0x)

hashFirst

boolean

hash first

ethV

boolean

eth v

Returns:

addAccount()¶

add account

string addAccount (: pk:Hash )

Parameters:

pk

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

string

canSign()¶

returns true if the account is supported (or unlocked)

Promise<boolean> canSign (: address:Address )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

Returns:

Promise<boolean>

Type BTCBlock¶

Source: in3.d.ts

a full Block including the transactions

bits

string

bits (target) for the block as hex

chainwork

string

total amount of work since genesis

confirmations

number

number of confirmations or blocks mined on top of the containing block

difficulty

number

difficulty of the block

hash

string

the hash of the blockheader

height

number

block number

mediantime

string

unix timestamp in seconds since 1970

merkleroot

string

merkle root of the trie of all transactions in the block

nTx

number

number of transactions in the block

nextblockhash

string

hash of the next blockheader

nonce

number

nonce-field of the block

previousblockhash

string

hash of the parent blockheader

time

string

unix timestamp in seconds since 1970

tx

T []

the transactions

version

number

used version

versionHex

string

version as hex

Type BTCBlockHeader¶

Source: in3.d.ts

a Block header

bits

string

bits (target) for the block as hex

chainwork

string

total amount of work since genesis

confirmations

number

number of confirmations or blocks mined on top of the containing block

difficulty

number

difficulty of the block

hash

string

the hash of the blockheader

height

number

block number

mediantime

string

unix timestamp in seconds since 1970

merkleroot

string

merkle root of the trie of all transactions in the block

nTx

number

number of transactions in the block

nextblockhash

string

hash of the next blockheader

nonce

number

nonce-field of the block

previousblockhash

string

hash of the parent blockheader

time

string

unix timestamp in seconds since 1970

version

number

used version

versionHex

string

version as hex

Type BtcAPI¶

Source: in3.d.ts

API for handling BitCoin data

getBlockBytes()¶

retrieves the serialized block (bytes) including all transactions

Promise<BufferType> getBlockBytes (: blockHash:Hash )

Parameters:

blockHash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

getBlockHeader()¶

retrieves the blockheader and returns the data as json.

Promise<BTCBlockHeader> getBlockHeader (: blockHash:Hash )

Parameters:

blockHash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<BTCBlockHeader>

getBlockHeaderBytes()¶

retrieves the serialized blockheader (bytes)

Promise<BufferType> getBlockHeaderBytes (: blockHash:Hash )

Parameters:

blockHash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

getBlockWithTxData()¶

retrieves the block including all tx data as json.

Promise<BTCBlock> getBlockWithTxData (: blockHash:Hash )

Parameters:

blockHash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<BTCBlock>

getBlockWithTxIds()¶

retrieves the block including all tx ids as json.

Promise<BTCBlock> getBlockWithTxIds (: blockHash:Hash )

Parameters:

blockHash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<BTCBlock>

getTransaction()¶

retrieves the transaction and returns the data as json.

Promise<BtcTransaction> getTransaction (: txid:Hash )

Parameters:

txid

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<BtcTransaction>

getTransactionBytes()¶

retrieves the serialized transaction (bytes)

Promise<BufferType> getTransactionBytes (: txid:Hash )

Parameters:

txid

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Type BtcTransaction¶

Source: in3.d.ts

a BitCoin Transaction.

blockhash

Hash

the block hash of the block containing this transaction.

blocktime

number

The block time in seconds since epoch (Jan 1 1970 GMT)

confirmations

number

The confirmations.

hash

Hash

The transaction hash (differs from txid for witness transactions)

hex

Data

the hex representation of raw data

in_active_chain

boolean

true if this transaction is part of the longest chain

locktime

number

The locktime

size

number

The serialized transaction size

time

number

The transaction time in seconds since epoch (Jan 1 1970 GMT)

txid

Hash

The requested transaction id.

version

number

The version

vin

BtcTransactionInput []

the transaction inputs

vout

BtcTransactionOutput []

the transaction outputs

vsize

number

The virtual transaction size (differs from size for witness transactions)

weight

number

The transaction’s weight (between vsize4-3 and vsize4)

Type BtcTransactionInput¶

Source: in3.d.ts

a Input of a Bitcoin Transaction

scriptSig

the script

sequence

number

The script sequence number

txid

Hash

the transaction id

txinwitness

Data []

hex-encoded witness data (if any)

vout

number

the index of the transactionoutput

Type BtcTransactionOutput¶

Source: in3.d.ts

a Input of a Bitcoin Transaction

n

number

the index

scriptPubKey

the script

value

number

the value in BTC

vout

number

the index of the transactionoutput

Type EthAPI¶

Source: in3.d.ts

client

IN3Generic<BigIntType,BufferType>

the client

signer

Signer<BigIntType,BufferType>

the signer (optional)

blockNumber()¶

Returns the number of most recent block. (as number)

Promise<number> blockNumber ()

Returns:

Promise<number>

call()¶

Executes a new message call immediately without creating a transaction on the block chain.

Promise<string> call (: tx:Transaction , block:BlockType )

Parameters:

tx

Transaction

tx

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<string>

callFn()¶

Executes a function of a contract, by passing a method-signature and the arguments, which will then be ABI-encoded and send as eth_call.

Promise<any> callFn (: to:Address , method:string, args:any [])

Parameters:

to

Address

a 20 byte Address encoded as Hex (starting with 0x)

method

string

method

args

any []

args

Returns:

Promise<any>

chainId()¶

Returns the EIP155 chain ID used for transaction signing at the current best block. Null is returned if not available.

Promise<string> chainId ()

Returns:

Promise<string>

constructor()¶

constructor

any constructor (: client:IN3Generic<BigIntType,BufferType> )

Parameters:

client

IN3Generic<BigIntType,BufferType>

client

Returns:

any

contractAt()¶

contract at

contractAt (

abi:ABI [], address:Address )

Parameters:

abi

ABI []

abi

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

decodeEventData()¶

decode event data

any decodeEventData (: log:Log , d:ABI )

Parameters:

log

Log

log

d

ABI

d

Returns:

any

estimateGas()¶

Makes a call or transaction, which won’t be added to the blockchain and returns the used gas, which can be used for estimating the used gas.

Promise<number> estimateGas (: tx:Transaction )

Parameters:

tx

Transaction

tx

Returns:

Promise<number>

gasPrice()¶

Returns the current price per gas in wei. (as number)

Promise<number> gasPrice ()

Returns:

Promise<number>

getBalance()¶

Returns the balance of the account of given address in wei (as hex).

Promise<BigIntType> getBalance (: address:Address , block:BlockType )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<BigIntType>

getBlockByHash()¶

Returns information about a block by hash.

Promise<Block> getBlockByHash (: hash:Hash , includeTransactions:boolean)

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

includeTransactions

boolean

include transactions

Returns:

getBlockByNumber()¶

Returns information about a block by block number.

Promise<Block> getBlockByNumber (: block:BlockType , includeTransactions:boolean)

Parameters:

block

BlockType

BlockNumber or predefined Block

includeTransactions

boolean

include transactions

Returns:

Promise<TransactionDetail>

getBlockTransactionCountByHash()¶

Returns the number of transactions in a block from a block matching the given block hash.

Promise<number> getBlockTransactionCountByHash (: block:Hash )

Parameters:

block

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<number>

getBlockTransactionCountByNumber()¶

Returns the number of transactions in a block from a block matching the given block number.

Promise<number> getBlockTransactionCountByNumber (: block:Hash )

Parameters:

block

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<number>

getCode()¶

Returns code at a given address.

Promise<string> getCode (: address:Address , block:BlockType )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<string>

getFilterChanges()¶

Polling method for a filter, which returns an array of logs which occurred since last poll.

Promise<> getFilterChanges (: id:Quantity )

Parameters:

id

Quantity

a BigInteger encoded as hex.

Returns:

Promise<>

getFilterLogs()¶

Returns an array of all logs matching filter with given id.

Promise<> getFilterLogs (: id:Quantity )

Parameters:

id

Quantity

a BigInteger encoded as hex.

Returns:

Promise<>

getLogs()¶

Returns an array of all logs matching a given filter object.

Promise<> getLogs (: filter:LogFilter )

Parameters:

filter

LogFilter

filter

Returns:

Promise<>

getStorageAt()¶

Returns the value from a storage position at a given address.

Promise<string> getStorageAt (: address:Address , pos:Quantity , block:BlockType )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

pos

Quantity

a BigInteger encoded as hex.

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<string>

getTransactionByBlockHashAndIndex()¶

Returns information about a transaction by block hash and transaction index position.

Promise<TransactionDetail> getTransactionByBlockHashAndIndex (: hash:Hash , pos:Quantity )

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

pos

Quantity

a BigInteger encoded as hex.

Returns:

getTransactionByBlockNumberAndIndex()¶

Returns information about a transaction by block number and transaction index position.

Promise<TransactionDetail> getTransactionByBlockNumberAndIndex (: block:BlockType , pos:Quantity )

Parameters:

block

BlockType

BlockNumber or predefined Block

pos

Quantity

a BigInteger encoded as hex.

Returns:

Promise<TransactionDetail>

getTransactionByHash()¶

Returns the information about a transaction requested by transaction hash.

Promise<TransactionDetail> getTransactionByHash (: hash:Hash )

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<TransactionDetail>

getTransactionCount()¶

Returns the number of transactions sent from an address. (as number)

Promise<number> getTransactionCount (: address:Address , block:BlockType )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<number>

getTransactionReceipt()¶

Returns the receipt of a transaction by transaction hash. Note That the receipt is available even for pending transactions.

Promise<TransactionReceipt> getTransactionReceipt (: hash:Hash )

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<TransactionReceipt>

getUncleByBlockHashAndIndex()¶

Returns information about a uncle of a block by hash and uncle index position. Note: An uncle doesn’t contain individual transactions.

Promise<Block> getUncleByBlockHashAndIndex (: hash:Hash , pos:Quantity )

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

pos

Quantity

a BigInteger encoded as hex.

Returns:

getUncleByBlockNumberAndIndex()¶

Returns information about a uncle of a block number and uncle index position. Note: An uncle doesn’t contain individual transactions.

Promise<Block> getUncleByBlockNumberAndIndex (: block:BlockType , pos:Quantity )

Parameters:

block

BlockType

BlockNumber or predefined Block

pos

Quantity

a BigInteger encoded as hex.

Returns:

getUncleCountByBlockHash()¶

Returns the number of uncles in a block from a block matching the given block hash.

Promise<number> getUncleCountByBlockHash (: hash:Hash )

Parameters:

hash

Hash

a 32 byte Hash encoded as Hex (starting with 0x)

Returns:

Promise<number>

getUncleCountByBlockNumber()¶

Returns the number of uncles in a block from a block matching the given block hash.

Promise<number> getUncleCountByBlockNumber (: block:BlockType )

Parameters:

block

BlockType

BlockNumber or predefined Block

Returns:

Promise<number>

hashMessage()¶

a Hexcoded String (starting with 0x)

Hex hashMessage (: data:Data )

Parameters:

data

Data

data encoded as Hex (starting with 0x)

Returns:

newBlockFilter()¶

Creates a filter in the node, to notify when a new block arrives. To check if the state has changed, call eth_getFilterChanges.

Promise<string> newBlockFilter ()

Returns:

Promise<string>

newFilter()¶

Creates a filter object, based on filter options, to notify when the state changes (logs). To check if the state has changed, call eth_getFilterChanges.

A note on specifying topic filters: Topics are order-dependent. A transaction with a log with topics [A, B] will be matched by the following topic filters:

[] “anything” [A] “A in first position (and anything after)” [null, B] “anything in first position AND B in second position (and anything after)” [A, B] “A in first position AND B in second position (and anything after)” [[A, B], [A, B]] “(A OR B) in first position AND (A OR B) in second position (and anything after)”

Promise<string> newFilter (: filter:LogFilter )

Parameters:

filter

LogFilter

filter

Returns:

Promise<string>

newPendingTransactionFilter()¶

Creates a filter in the node, to notify when new pending transactions arrive.

To check if the state has changed, call eth_getFilterChanges.

Promise<string> newPendingTransactionFilter ()

Returns:

Promise<string>

protocolVersion()¶

Returns the current ethereum protocol version.

Promise<string> protocolVersion ()

Returns:

Promise<string>

resolveENS()¶

resolves a name as an ENS-Domain.

Promise<Address> resolveENS (: name:string, type:Address , registry:string)

Parameters:

name

string

the domain name

type

Address

the type (currently only addr is supported)

registry

string

optionally the address of the registry (default is the mainnet ens registry)

Returns:

Promise<Address>

sendRawTransaction()¶

Creates new message call transaction or a contract creation for signed transactions.

Promise<string> sendRawTransaction (: data:Data )

Parameters:

data

Data

data encoded as Hex (starting with 0x)

Returns:

Promise<string>

sendTransaction()¶

sends a Transaction

Promise<> sendTransaction (: args:TxRequest )

Parameters:

args

TxRequest

args

Returns:

Promise<>

sign()¶

signs any kind of message using the \x19Ethereum Signed Message:\n-prefix

Promise<BufferType> sign (: account:Address , data:Data )

Parameters:

account

Address

the address to sign the message with (if this is a 32-bytes hex-string it will be used as private key)

data

Data

the data to sign (Buffer, hexstring or utf8-string)

Returns:

syncing()¶

Returns the current ethereum protocol version.

Promise<> syncing ()

Returns:

Promise<>

uninstallFilter()¶

Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren’t requested with eth_getFilterChanges for a period of time.

Promise<Quantity> uninstallFilter (: id:Quantity )

Parameters:

id

Quantity

a BigInteger encoded as hex.

Returns:

Promise<Quantity>

web3ContractAt()¶

web3 contract at

web3ContractAt (

abi:ABI [], address:Address , options:)

Parameters:

abi

ABI []

abi

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

options

options

Type IN3Config¶

Source: in3.d.ts

the configuration of the IN3-Client. This can be changed at any time. All properties are optional and will be verified when sending the next request.

autoUpdateList

boolean

if true the nodelist will be automaticly updated if the lastBlock is newer.

default: true

(optional)

bootWeights

boolean

if true, the first request (updating the nodelist) will also fetch the current health status

and use it for blacklisting unhealthy nodes. This is used only if no nodelist is availabkle from cache.

default: false

(optional)

chainId

string

The chain-id based on EIP-155.

or the name of the supported chain.

Currently we support ‘mainnet’, ‘goerli’, ‘kovan’, ‘ipfs’ and ‘local’

While most of the chains use preconfigured chain settings,

‘local’ actually uses the local running client turning of proof.

example: ‘0x1’ or ‘mainnet’ or ‘goerli’

default: ‘mainnet’

chainRegistry

string

main chain-registry contract

example: 0xe36179e2286ef405e929C90ad3E70E649B22a945 (optional)

finality

number

the number in percent needed in order reach finality if you run on a POA-Chain.

(% of signature of the validators)

default: 0

(optional)

includeCode

boolean

if true, the request should include the codes of all accounts.

Otherwise only the the codeHash is returned.

In this case the client may ask by calling eth_getCode() afterwards

default: false

(optional)

keepIn3

boolean

if true, the in3-section of the response will be kept and returned.

Otherwise it will be removed after validating the data.

This is useful for debugging or if the proof should be used afterwards.

default: false

(optional)

key

Hash

the key to sign requests. This is required for payments. (optional)

mainChain

string

main chain-id, where the chain registry is running.

example: 0x1 (optional)

maxAttempts

number

max number of attempts in case a response is rejected.

Incubed will retry to find a different node giving a verified response.

default: 5

(optional)

minDeposit

number

min stake of the server. Only nodes owning at least this amount will be chosen.

default: 0

nodeLimit

number

the limit of nodes to store in the client. If set a random seed will be picked, which is the base for a deterministic verifiable partial nodelist.

default: 0

(optional)

nodeProps

number | Hex

a bitmask-value combining the minimal properties as filter for the selected nodes. See https://in3.readthedocs.io/en/develop/spec.html#node-structure for details.

nodes

the nodelists per chain. the chain_id will be used as key within the object. (optional)

proof

'none' | 'standard' | 'full'

if true the nodes should send a proof of the response

default: ‘standard’

(optional)

replaceLatestBlock

number

if specified, the blocknumber latest will be replaced by blockNumber- specified value

default: 6

(optional)

requestCount

number

the number of request send when getting a first answer

default: 1

rpc

string

url of a rpc-endpoints to use. If this is set proof will be turned off and it will be treated like local_chain. (optional)

signatureCount

number

number of signatures requested. The more signatures, the more security you get, but responses may take longer.

default: 0

(optional)

stats

boolean

if false, the requests will not be included in the stats of the nodes ( or marked as intern ).

default: true

(optional)

timeout

number

specifies the number of milliseconds before the request times out. increasing may be helpful if the device uses a slow connection.

default: 5000

(optional)

Type IN3NodeConfig¶

Source: in3.d.ts

a configuration of a in3-server.

address

string

the address of the node, which is the public address it iis signing with.

example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679

capacity

number

the capacity of the node.

example: 100 (optional)

chainIds

string []

the list of supported chains

example: 0x1

deposit

number

the deposit of the node in wei

example: 12350000

index

number

the index within the contract

example: 13 (optional)

props

number

the properties of the node.

example: 3 (optional)

registerTime

number

the UNIX-timestamp when the node was registered

example: 1563279168 (optional)

timeout

number

the time (in seconds) until an owner is able to receive his deposit back after he unregisters himself

example: 3600 (optional)

unregisterTime

number

the UNIX-timestamp when the node is allowed to be deregister

example: 1563279168 (optional)

url

string

the endpoint to post to

example: https://in3.slock.it

Type IN3NodeWeight¶

Source: in3.d.ts

a local weight of a n3-node. (This is used internally to weight the requests)

avgResponseTime

number

average time of a response in ms

example: 240 (optional)

blacklistedUntil

number

blacklisted because of failed requests until the timestamp

example: 1529074639623 (optional)

lastRequest

number

timestamp of the last request in ms

example: 1529074632623 (optional)

pricePerRequest

number

last price (optional)

responseCount

number

number of uses.

example: 147 (optional)

weight

number

factor the weight this noe (default 1.0)

example: 0.5 (optional)

Type IpfsAPI¶

Source: in3.d.ts

API for storing and retrieving IPFS-data.

get()¶

retrieves the content for a hash from IPFS.

Promise<BufferType> get (: multihash:string)

Parameters:

multihash

string

the IPFS-hash to fetch

Returns:

put()¶

stores the data on ipfs and returns the IPFS-Hash.

Promise<string> put (: content:BufferType )

Parameters:

content

BufferType

puts a IPFS content

Returns:

Promise<string>

Type RPCRequest¶

Source: in3.d.ts

a JSONRPC-Request with N3-Extension

id

number | string

the identifier of the request

example: 2 (optional)

jsonrpc

'2.0'

the version

method

string

the method to call

example: eth_getBalance

params

any []

the params

example: 0xe36179e2286ef405e929C90ad3E70E649B22a945,latest (optional)

Type RPCResponse¶

Source: in3.d.ts

a JSONRPC-Responset with N3-Extension

error

string

in case of an error this needs to be set (optional)

id

string | number

the id matching the request

example: 2

jsonrpc

'2.0'

the version

result

any

the params

example: 0xa35bc (optional)

Type Signer¶

Source: in3.d.ts

prepareTransaction()¶

optiional method which allows to change the transaction-data before sending it. This can be used for redirecting it through a multisig.

Promise<Transaction> prepareTransaction (: client:IN3Generic<BigIntType,BufferType> , tx:Transaction )

Parameters:

client

IN3Generic<BigIntType,BufferType>

client

tx

Transaction

tx

Returns:

Promise<Transaction>

sign()¶

signing of any data. if hashFirst is true the data should be hashed first, otherwise the data is the hash.

Promise<BufferType> sign (: data:Hex , account:Address , hashFirst:boolean, ethV:boolean)

Parameters:

data

Hex

a Hexcoded String (starting with 0x)

account

Address

a 20 byte Address encoded as Hex (starting with 0x)

hashFirst

boolean

hash first

ethV

boolean

eth v

Returns:

canSign()¶

returns true if the account is supported (or unlocked)

Promise<boolean> canSign (: address:Address )

Parameters:

address

Address

a 20 byte Address encoded as Hex (starting with 0x)

Returns:

Promise<boolean>

Type Utils¶

Source: in3.d.ts

Collection of different util-functions.

abiDecode()¶

decodes the given data as ABI-encoded (without the methodHash)

any [] abiDecode (: signature:string, data:Data )

Parameters:

signature

string

the method signature, which must contain a return description

data

Data

the data to decode

Returns:

any []

abiEncode()¶

encodes the given arguments as ABI-encoded (including the methodHash)

Hex abiEncode (: signature:string, args:any [])

Parameters:

signature

string

the method signature

args

any []

the arguments

Returns:

createSignatureHash()¶

a Hexcoded String (starting with 0x)

Hex createSignatureHash (: def:ABI )

Parameters:

def

ABI

def

Returns:

decodeEvent()¶

decode event

any decodeEvent (: log:Log , d:ABI )

Parameters:

log

Log

log

d

ABI

d

Returns:

any

ecSign()¶

create a signature (65 bytes) for the given message and kexy

BufferType ecSign (: pk:Hex | BufferType , msg:Hex | BufferType , hashFirst:boolean, adjustV:boolean)

Parameters:

pk

Hex

| BufferType

the private key

msg

Hex

| BufferType

the message

hashFirst

boolean

if true the message will be hashed first (default:true), if not the message is the hash.

adjustV

boolean

if true (default) the v value will be adjusted by adding 27

Returns:

getVersion()¶

returns the incubed version.

string getVersion ()

Returns:

string

keccak()¶

calculates the keccack hash for the given data.

BufferType keccak (: data:BufferType | Data )

Parameters:

data

BufferType

| Data

the data as Uint8Array or hex data.

Returns:

private2address()¶

generates the public address from the private key.

Address private2address (: pk:Hex | BufferType )

Parameters:

pk

Hex

| BufferType

the private key.

Returns:

Address

soliditySha3()¶

solidity sha3

string soliditySha3 (: args:any [])

Parameters:

args

any []

args

Returns:

string

splitSignature()¶

takes raw signature (65 bytes) and splits it into a signature object.

Signature splitSignature (: signature:Hex | BufferType , message:BufferType | Hex , hashFirst:boolean)

Parameters:

signature

Hex

| BufferType

the 65 byte-signature

message

BufferType

| Hex

the message

hashFirst

boolean

if true (default) this will be taken as raw-data and will be hashed first.

Returns:

Signature

toBuffer()¶

converts any value to a Buffer. optionally the target length can be specified (in bytes)

BufferType toBuffer (: data:Hex | BufferType | number | bigint, len:number)

Parameters:

data

Hex

| BufferType

| number

| bigint

data

len

number

len

Returns:

toChecksumAddress()¶

generates a checksum Address for the given address. If the chainId is passed, it will be included accord to EIP 1191

Address toChecksumAddress (: address:Address , chainId:number)

Parameters:

address

Address

the address (as hex)

chainId

number

the chainId (if supported)

Returns:

Address

toHex()¶

converts any value to a hex string (with prefix 0x). optionally the target length can be specified (in bytes)

Hex toHex (: data:Hex | BufferType | number | bigint, len:number)

Parameters:

data

Hex

| BufferType

| number

| bigint

data

len

number

len

Returns:

toMinHex()¶

removes all leading 0 in the hexstring

string toMinHex (: key:string | BufferType | number)

Parameters:

key

string

| BufferType

| number

key

Returns:

string

toNumber()¶

converts any value to a hex string (with prefix 0x). optionally the target length can be specified (in bytes)

number toNumber (: data:string | BufferType | number | bigint)

Parameters:

data

string

| BufferType

| number

| bigint

data

Returns:

number

toUint8Array()¶

converts any value to a Uint8Array. optionally the target length can be specified (in bytes)

BufferType toUint8Array (: data:Hex | BufferType | number | bigint, len:number)

Parameters:

data

Hex

| BufferType

| number

| bigint

data

len

number

len

Returns:

https://github.com/slockit/in3-example-android

toUtf8()¶

convert to String

string toUtf8 (: val:any)

Parameters:

val

any

val

Returns:

string

Type Web3Event¶

Source: in3.d.ts

address

Address

the address

blockHash

Hash

the blockHash

blockNumber

number

the blockNumber

event

string

the event

logIndex

number

the logIndex

raw

the raw

returnValues

the returnValues

signature

string

the signature

transactionHash

Hash

the transactionHash

transactionIndex

number

the transactionIndex

Type ABI¶

Source: in3.d.ts

anonymous

boolean

the anonymous (optional)

constant

boolean

the constant (optional)

inputs

ABIField []

the inputs (optional)

name

string

the name (optional)

outputs

ABIField []

the outputs (optional)

payable

boolean

the payable (optional)

stateMutability

'nonpayable'

| 'payable'

| 'view'

| 'pure'

the stateMutability (optional)

type

'event'

| 'function'

| 'constructor'

| 'fallback'

the type

Type ABIField¶

Source: in3.d.ts

indexed

boolean

the indexed (optional)

name

string

the name

type

string

the type

Type Address¶

Source: in3.d.ts

a 20 byte Address encoded as Hex (starting with 0x) a Hexcoded String (starting with 0x) = string

Type Block¶

Source: in3.d.ts

author

Address

20 Bytes - the address of the author of the block (the beneficiary to whom the mining rewards were given)

difficulty

Quantity

integer of the difficulty for this block

extraData

Data

the ‘extra data’ field of this block

gasLimit

Quantity

the maximum gas allowed in this block

gasUsed

Quantity

the total used gas by all transactions in this block

hash

Hash

hash of the block. null when its pending block

logsBloom

Data

256 Bytes - the bloom filter for the logs of the block. null when its pending block

miner

Address

20 Bytes - alias of ‘author’

nonce

Data

8 bytes hash of the generated proof-of-work. null when its pending block. Missing in case of PoA.

number

Quantity

The block number. null when its pending block

parentHash

Hash

hash of the parent block

receiptsRoot

Data

32 Bytes - the root of the receipts trie of the block

sealFields

Data []

PoA-Fields

sha3Uncles

Data

SHA3 of the uncles data in the block

size

Quantity

integer the size of this block in bytes

stateRoot

Data

32 Bytes - the root of the final state trie of the block

timestamp

Quantity

the unix timestamp for when the block was collated

totalDifficulty

Quantity

integer of the total difficulty of the chain until this block

transactions

string | []

Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter

transactionsRoot

Data

32 Bytes - the root of the transaction trie of the block

uncles

Hash []

Array of uncle hashes

Type Data¶

Source: in3.d.ts

data encoded as Hex (starting with 0x) a Hexcoded String (starting with 0x) = string

Type Hash¶

Source: in3.d.ts

a 32 byte Hash encoded as Hex (starting with 0x) a Hexcoded String (starting with 0x) = string

Type Log¶

Source: in3.d.ts

address

Address

20 Bytes - address from which this log originated.

blockHash

Hash

Hash, 32 Bytes - hash of the block where this log was in. null when its pending. null when its pending log.

blockNumber

Quantity

the block number where this log was in. null when its pending. null when its pending log.

data

Data

contains the non-indexed arguments of the log.

logIndex

Quantity

integer of the log index position in the block. null when its pending log.

removed

boolean

true when the log was removed, due to a chain reorganization. false if its a valid log.

topics

Data []

- Array of 0 to 4 32 Bytes DATA of indexed log arguments. (In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256)), except you declared the event with the anonymous specifier.)

transactionHash

Hash

Hash, 32 Bytes - hash of the transactions this log was created from. null when its pending log.

transactionIndex

Quantity

integer of the transactions index position log was created from. null when its pending log.

Type LogFilter¶

Source: in3.d.ts

address

Address

(optional) 20 Bytes - Contract address or a list of addresses from which logs should originate.

fromBlock

BlockType

Quantity or Tag - (optional) (default: latest) Integer block number, or ‘latest’ for the last mined block or ‘pending’, ‘earliest’ for not yet mined transactions.

limit

Quantity

å(optional) The maximum number of entries to retrieve (latest first).

toBlock

BlockType

Quantity or Tag - (optional) (default: latest) Integer block number, or ‘latest’ for the last mined block or ‘pending’, ‘earliest’ for not yet mined transactions.

topics

string | string [] []

(optional) Array of 32 Bytes Data topics. Topics are order-dependent. It’s possible to pass in null to match any topic, or a subarray of multiple topics of which one should be matching.

Type Signature¶

Source: in3.d.ts

Signature

message

Data

the message

messageHash

Hash

the messageHash

r

Hash

the r

s

Hash

the s

signature

Data

the signature (optional)

v

Hex

the v

Type Transaction¶

Source: in3.d.ts

chainId

any

optional chain id (optional)

data

string

4 byte hash of the method signature followed by encoded parameters. For details see Ethereum Contract ABI.

from

Address

20 Bytes - The address the transaction is send from.

gas

Quantity

Integer of the gas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.

gasPrice

Quantity

Integer of the gas price used for each paid gas.

nonce

Quantity

nonce

to

Address

(optional when creating new contract) 20 Bytes - The address the transaction is directed to.

value

Quantity

Integer of the value sent with this transaction.

Type TransactionDetail¶

Source: in3.d.ts

blockHash

Hash

32 Bytes - hash of the block where this transaction was in. null when its pending.

blockNumber

BlockType

block number where this transaction was in. null when its pending.

chainId

Quantity

the chain id of the transaction, if any.

condition

any

(optional) conditional submission, Block number in block or timestamp in time or null. (parity-feature)

creates

Address

creates contract address

from

Address

20 Bytes - address of the sender.

gas

Quantity

gas provided by the sender.

gasPrice

Quantity

gas price provided by the sender in Wei.

hash

Hash

32 Bytes - hash of the transaction.

input

Data

the data send along with the transaction.

nonce

Quantity

the number of transactions made by the sender prior to this one.

pk

any

optional: the private key to use for signing (optional)

publicKey

Hash

public key of the signer.

r

Quantity

the R field of the signature.

raw

Data

raw transaction data

standardV

Quantity

the standardised V field of the signature (0 or 1).

to

Address

20 Bytes - address of the receiver. null when its a contract creation transaction.

transactionIndex

Quantity

integer of the transactions index position in the block. null when its pending.

v

Quantity

the standardised V field of the signature.

value

Quantity

value transferred in Wei.

Type TransactionReceipt¶

Source: in3.d.ts

blockHash

Hash

32 Bytes - hash of the block where this transaction was in.

blockNumber

BlockType

block number where this transaction was in.

contractAddress

Address

20 Bytes - The contract address created, if the transaction was a contract creation, otherwise null.

cumulativeGasUsed

Quantity

The total amount of gas used when this transaction was executed in the block.

from

Address

20 Bytes - The address of the sender.

gasUsed

Quantity

The amount of gas used by this specific transaction alone.

logs

Log []

Array of log objects, which this transaction generated.

logsBloom

Data

256 Bytes - A bloom filter of logs/events generated by contracts during transaction execution. Used to efficiently rule out transactions without expected logs.

root

Hash

32 Bytes - Merkle root of the state trie after the transaction has been executed (optional after Byzantium hard fork EIP609)

status

Quantity

0x0 indicates transaction failure , 0x1 indicates transaction success. Set for blocks mined after Byzantium hard fork EIP609, null before.

to

Address

20 Bytes - The address of the receiver. null when it’s a contract creation transaction.

transactionHash

Hash

32 Bytes - hash of the transaction.

transactionIndex

Quantity

Integer of the transactions index position in the block.

Type TxRequest¶

Source: in3.d.ts

args

any []

the argument to pass to the method (optional)

confirmations

number

number of block to wait before confirming (optional)

data

Data

the data to send (optional)

from

Address

address of the account to use (optional)

gas

number

the gas needed (optional)

gasPrice

number

the gasPrice used (optional)

method

string

the ABI of the method to be used (optional)

nonce

number

the nonce (optional)

pk

Hash

raw private key in order to sign (optional)

timeout

number

number of seconds to wait for confirmations before giving up. Default: 10 (optional)

to

Address

contract (optional)

value

Quantity

the value in wei (optional)

Type Hex¶

Source: in3.d.ts

a Hexcoded String (starting with 0x) = string

Type BlockType¶

Source: in3.d.ts

BlockNumber or predefined Block = number | 'latest' | 'earliest' | 'pending'

Type Quantity¶

Source: in3.d.ts

a BigInteger encoded as hex. = number | Hex

API Reference Python¶

Python Incubed client¶

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!

Go to our readthedocs page for more.

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

Developing & Tests¶

Install dev dependencies, IDEs should automatically recognize interpreter if done like this.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Compile local libraries and run tests. Make sure you have cmake installed.

./buidl_libs.sh

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, cache_enabled=False)
address = client.ens_address(domain)
# owner = client.ens_owner(domain)
# _print()

# Instantiate In3 Client for Mainnet
chain = 'mainnet'
client = in3.Client(chain, cache_enabled=False)
address = client.ens_address(domain)
owner = client.ens_owner(domain)
_print()

# Instantiate In3 Client for Kovan
chain = 'kovan'
client = in3.Client(chain, cache_enabled=True)
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.
# By reading the terminal input, this value will stay in memory only. Don't forget to cls or clear terminal after ;)
sender_secret = input("Sender secret: ")
receiver = input("Receiver address: ")
#     1000000000000000000 == 1 ETH
#              1000000000 == 1 Gwei Check https://etherscan.io/gasTracker.
value_in_wei = 1463926659
# None for Eth mainnet
chain = 'goerli'
client = in3.Client(chain if chain else 'mainnet')
# 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
# For mainnet and paying low gas, it might take 10 minutes.
confirmation_wait_time_in_seconds = 30
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 {}. Please wait.\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))
    while True:
        try:
            print('\n[.] Waiting {} 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!\n')
            print(json.dumps(receipt.to_dict(), indent=4, sort_keys=True))
            print('[.] Mined on block {} used {} GWei.'.format(receipt.blockNumber, receipt.gasUsed))
            break
        except Exception:
            print('[!] Transaction not mined yet, check https://etherscan.io/gasTracker.')
            print('[!] Just wait some minutes longer than the average for the price paid!')
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
"""

smart_meter_write¶

source : in3-c/python/examples/smart_meter_write.py

"""
[{"type":"event","name":"NewReadStored","inputs":[{"type":"address","name":"meter","internalType":"address","indexed":true},{"type":"uint256","name":"bucket","internalType":"uint256","indexed":true},{"type":"address","name":"operator","internalType":"address","indexed":false},{"type":"uint256","name":"timestamp","internalType":"uint256","indexed":false},{"type":"bytes","name":"data","internalType":"bytes","indexed":false}],"anonymous":false},{"type":"function","stateMutability":"view","payable":false,"outputs":[{"type":"uint256","name":"","internalType":"uint256"}],"name":"DAILY_BUCKET","inputs":[],"constant":true},{"type":"function","stateMutability":"nonpayable","payable":false,"outputs":[],"name":"store","inputs":[{"type":"address","name":"meter","internalType":"address"},{"type":"bytes","name":"data","internalType":"bytes"},{"type":"uint256","name":"timestamp","internalType":"uint256"},{"type":"uint256","name":"bucket","internalType":"uint256"}],"constant":false},{"type":"function","stateMutability":"nonpayable","payable":false,"outputs":[],"name":"storeWithDailyBucket","inputs":[{"type":"address","name":"meter","internalType":"address"},{"type":"bytes","name":"data","internalType":"bytes"},{"type":"uint256","name":"timestamp","internalType":"uint256"}],"constant":false}]

0xf23FF7472FC62C6bEe2F960f5b4170Ab3C1C26d2
"""
import base64
import json

import in3
import hashlib
import random
import time

if __name__ == '__main__':

    c = in3.Client(chain='ewc', in3_config=in3.ClientConfig(transport_binary_format=True))

    smart_meter_registry_addr = '0xf23FF7472FC62C6bEe2F960f5b4170Ab3C1C26d2'
    # meter, bucket, operator, timestamp, data
    NewReadStoredEvent = 'NewReadStored(address,uint,address,uint,bytes))'
    try:
        # meter, data, timestamp
        storeWithDailyBucket = 'storeWithDailyBucket(address,bytes,uint256)'
        meter_addr = '0xb11469A59dF65312737053c4785FA7Ff28660013'
        salt = hex(random.getrandbits(64))
        secret_read = hashlib.sha512(b'1101101')
        secret_read.update(salt.encode('utf8'))
        secret_read = secret_read.hexdigest()
        # secret_read = base64.b64encode(secret_read.digest())
        timestamp = int(time.time())
        sender_secret = input("Sender secret: ")
        sender = c.eth.account.recover(sender_secret)
        encoded_contract_call = c.eth.contract.encode(storeWithDailyBucket, meter_addr, secret_read, timestamp)
        tx = in3.eth.NewTransaction(to=smart_meter_registry_addr,
                                    data=encoded_contract_call)
        tx.gasLimit = c.eth.account.estimate_gas(tx)
        tx_hash = c.eth.account.send_transaction(sender=sender, transaction=tx)
        print('https://explorer.energyweb.org/tx/{}'.format(tx_hash))
        confirmation_wait_time_in_seconds = 60
        while True:
            try:
                print('\n[.] Waiting {} seconds for confirmation.\n'.format(confirmation_wait_time_in_seconds))
                time.sleep(confirmation_wait_time_in_seconds)
                receipt: in3.eth.TransactionReceipt = c.eth.transaction_receipt(tx_hash)
                print('[.] Transaction was sent successfully!\n')
                print(json.dumps(receipt.to_dict(), indent=4, sort_keys=True))
                print('[.] Mined on block {} used {} GWei.'.format(receipt.blockNumber, receipt.gasUsed))
                break
            except Exception:
                print('[!] Transaction not mined yet, check https://etherscan.io/gasTracker.')
                print('[!] Just wait some minutes longer than the average for the price paid!')
    except in3.PrivateKeyNotFoundException as e:
        print(str(e))
    except in3.ClientException as e:
        print('Client returned error: ', str(e))
        print('Please try again.')

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,
cache_enabled: bool = True,
transport=<function https_transport at 0x101898e60>)

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:

chain str - Ethereum chain to connect to. Defaults to mainnet. Options: ‘mainnet’, ‘kovan’, ‘goerli’, ‘ewc’.
in3_config ClientConfig or str - (optional) Configuration for the client. If not provided, default is loaded.
cache_enabled bool - False will disable local storage caching.
transport function - Transport function for custom request routing. Defaults to https.

refresh_node_list¶

Client.refresh_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.

config¶

Client.config()

Client configuration dictionary.

Returns:

config dict - Client configuration keys and values.

ens_namehash¶

Client.ens_namehash(domain_name: str)

Name format based on EIP-137

Arguments:

domain_name - ENS supported domain. mydomain.ens, mydomain.xyz, etc

Returns:

node str - Formatted string referred as node in ENS documentation

ens_address¶

Client.ens_address(domain_name: str, registry: str = None)

Resolves ENS domain name to what account that domain points to.

Arguments:

domain_name - ENS supported domain. mydomain.ens, mydomain.xyz, etc
registry - ENS registry contract address. i.e. 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e

Returns:

address str - Ethereum address corresponding to what account that domain points to.

ens_owner¶

Client.ens_owner(domain_name: str, registry: str = None)

Resolves ENS domain name to Ethereum address of domain owner.

Arguments:

domain_name - ENS supported domain. i.e mydomain.eth
registry - ENS registry contract address. i.e. 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e

Returns:

owner_address str - Ethereum address corresponding to domain owner.

ens_resolver¶

Client.ens_resolver(domain_name: str, registry: str = None)

Resolves ENS domain name to Smart-contract address of the resolver registered for that domain.

Arguments:

domain_name - ENS supported domain. i.e mydomain.eth
registry - ENS registry contract address. i.e. 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e

Returns:

resolver_contract_address str - Smart-contract address of the resolver registered for that domain.

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,
transport_binary_format: bool = None,
transport_ignore_tls: bool = None,
cached_blocks: int = None,
cached_code_bytes: int = None,
boot_weights: bool = 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 use set_account_sk) example: 0x387a8233c96e1fc0ad5e284353276177af2186e7afa85296f106336e376669f7
node_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 node_signatures <= 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 Wei
node_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 nodes
request_timeout int - Milliseconds before a request times out. example: 100000 ms
request_retries int - Maximum times the client will retry to contact a certain node. example: 10 retries
response_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.
transport_binary_format - If true, the client will communicate with the server using a binary payload instead of json.
transport_ignore_tls - The client usually verify https tls certificates. To communicate over insecure http, turn this on.
cached_blocks int - Maximum blocks kept in memory. example: 100 last requested blocks
cached_code_bytes int - Maximum number of bytes used to cache EVM code in memory. example: 100000 bytes
boot_weights bool - if true, the first request (updating the nodelist) will also fetch the current health status and use it for blacklisting unhealthy nodes. This is used only if no nodelist is availabkle from cache.
in3_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.it
index int - Index within the contract example: 13
address in3.Account - Address of the node, which is the public address it is signing with. example: 0x6C1a01C2aB554930A937B0a2E8105fB47946c679
deposit int - Deposit of the node in wei example: 12350000
props int - Properties of the node. example: 3
timeout int - Time (in seconds) until an owner is able to receive his deposit back after he unregisters himself example: 3600
registerTime 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 nodes
contract Account - incubed registry contract from which the list was taken
registryId str - uuid of this incubed network. one chain could contain more than one incubed networks.
lastBlockNumber int - last block signed by the network
totalServers int - Total servers number (for integrity?)

EthAccountApi¶

EthAccountApi(self, runtime: In3Runtime, factory: EthObjectFactory)

Manages accounts and smart-contracts

create¶

EthAccountApi.create(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¶

EthAccountApi.recover(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. Use recover_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)

balance¶

EthAccountApi.balance(address: str, at_block: int = 'latest')

Returns the balance of the account of given address.

Arguments:

address str - address to check for balance
at_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.

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.

transaction_count¶

EthAccountApi.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 address
at_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

call¶

EthContractApi.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.

storage_at¶

EthContractApi.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 address
position int - Position index, 0x0 up to 0x64
at_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.

code¶

EthContractApi.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 address
at_block int or str - Block number

Returns:

bytecode str - Smart-Contract bytecode in hexadecimal.

encode¶

EthContractApi.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”

decode¶

EthContractApi.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) or getBalance(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

block_by_hash¶

EthereumApi.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 hash
get_full_block bool - If true, returns the full transaction objects, otherwise only its hashes.

Returns:

block Block - Desired block, if exists.

block_by_number¶

EthereumApi.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.

transaction_by_hash¶

EthereumApi.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.

transaction_receipt¶

EthereumApi.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.

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 by gasPrice. 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 as tx 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_sendTransaction
blockHash 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 as tx 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, cache_enabled: bool, transport_fn)

Instantiate libin3 and frees it when garbage collected.

Arguments:

chain_id int - Chain-id based on EIP-155. Default is 0x1 for Ethereum mainNet.
cache_enabled bool - False will disable local storage cache.
transport_fn - Transport function to handle the HTTP Incubed Network requests.

in3.libin3.rpc_api¶

Load libin3 shared library for the current system, map function ABI, sets in3 network transport functions.

libin3_new¶

libin3_new(chain_id: int, cache_enabled: bool,
transport_fn: <function CFUNCTYPE at 0x10182ce60>)

Instantiate new In3 Client instance.

Arguments:

chain_id int - Chain id as integer
cache_enabled bool - False will disable local storage cache.
transport_fn - Transport function for the in3 network requests
storage_fn - Cache Storage function for node list and requests caching

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_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_new
fn_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_new
private_key - 256 bit number.

libin3_in3_req_add_response¶

libin3_in3_req_add_response(*args)

Transport function that registers a response to a request.

Arguments:

*args:

libin3_new_bytes_t¶

libin3_new_bytes_t(value: bytes, length: int)

C Bytes struct

Arguments:

length - byte array length
value - byte array

Returns:

ptr_addr - address of the instance of this struct

API Reference Java¶

Installing¶

The Incubed Java client uses JNI in order to call native functions. But all the native-libraries are bundled inside the jar-file. This jar file ha no dependencies and can even be used standalone:

like

java -cp in3.jar in3.IN3 eth_getBlockByNumber latest false

Downloading¶

The jar file can be downloaded from the latest release. here.

Alternatively, If you wish to download Incubed using the maven package manager, add this to your pom.xml

<dependency>
  <groupId>it.slock</groupId>
  <artifactId>in3</artifactId>
  <version>2.21</version>
</dependency> 

After which, install in3 with mvn install.

Building¶

For building the shared library you need to enable java by using the -DJAVA=true flag:

git clone git@github.com:slockit/in3-c.git
mkdir -p in3-c/build
cd in3-c/build
cmake -DJAVA=true .. && make

You will find the in3.jar in the build/lib - folder.

Android¶

In order to use Incubed in android simply follow these steps:

Step 1: Create a top-level CMakeLists.txt in android project inside app folder and link this to gradle. Follow the steps using this guide on howto link.

The Content of the CMakeLists.txt should look like this:

cmake_minimum_required(VERSION 3.4.1)

# turn off FAST_MATH in the evm.
ADD_DEFINITIONS(-DIN3_MATH_LITE)

# loop through the required module and cretae the build-folders
foreach(module 
  c/src/core 
  c/src/verifier/eth1/nano 
  c/src/verifier/eth1/evm 
  c/src/verifier/eth1/basic 
  c/src/verifier/eth1/full 
  java/src
  c/src/third-party/crypto 
  c/src/third-party/tommath 
  c/src/api/eth1)
        file(MAKE_DIRECTORY in3-c/${module}/outputs)
        add_subdirectory( in3-c/${module} in3-c/${module}/outputs )
endforeach()

Step 2: clone in3-c into the app-folder or use this script to clone and update in3:

#!/usr/bin/env sh

#github-url for in3-c
IN3_SRC=https://github.com/slockit/in3-c.git

cd app

# if it exists we only call git pull
if [ -d in3-c ]; then
    cd in3-c
    git pull
    cd ..
else
# if not we clone it
    git clone $IN3_SRC
fi


# copy the java-sources to the main java path
cp -r in3-c/java/src/in3 src/main/java/

Step 3: Use methods available in app/src/main/java/in3/IN3.java from android activity to access IN3 functions.

Here is example how to use it:

Examples¶

CallFunction¶

source : in3-c/java/examples/CallFunction.java

Calling Functions of Contracts

// This Example shows how to call functions and use the decoded results. Here we get the struct from the registry.

import in3.*;
import in3.eth1.*;

public class CallFunction {
  //
  public static void main(String[] args) {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also dthe default)

    // call a contract, which uses eth_call to get the result.
    Object[] result = (Object[]) in3.getEth1API().call(                      // call a function of a contract
        "0x2736D225f85740f42D17987100dc8d58e9e16252",                        // address of the contract
        "servers(uint256):(string,address,uint256,uint256,uint256,address)", // function signature
        1);                                                                  // first argument, which is the index of the node we are looking for.

    System.out.println("url     : " + result[0]);
    System.out.println("owner   : " + result[1]);
    System.out.println("deposit : " + result[2]);
    System.out.println("props   : " + result[3]);
  }
}

Configure¶

source : in3-c/java/examples/Configure.java

Changing the default configuration

// In order to change the default configuration, just use the classes inside in3.config package.

package in3;

import in3.*;
import in3.config.*;
import in3.eth1.Block;

public class Configure {
  //
  public static void main(String[] args) {
    // create incubed client
    IN3 in3 = IN3.forChain(Chain.GOERLI); // set it to goerli

    // Setup a Configuration object for the client
    ClientConfiguration clientConfig = in3.getConfig();
    clientConfig.setReplaceLatestBlock(6); // define that latest will be -6
    clientConfig.setAutoUpdateList(false); // prevents node automatic update
    clientConfig.setMaxAttempts(1);        // sets max attempts to 1 before giving up
    clientConfig.setProof(Proof.none);     // does not require proof (not recommended)

    // Setup the ChainConfiguration object for the nodes on a certain chain
    ChainConfiguration chainConfiguration = new ChainConfiguration(Chain.GOERLI, clientConfig);
    chainConfiguration.setNeedsUpdate(false);
    chainConfiguration.setContract("0xac1b824795e1eb1f6e609fe0da9b9af8beaab60f");
    chainConfiguration.setRegistryId("0x23d5345c5c13180a8080bd5ddbe7cde64683755dcce6e734d95b7b573845facb");

    in3.setConfig(clientConfig);

    Block block = in3.getEth1API().getBlockByNumber(Block.LATEST, true);
    System.out.println(block.getHash());
  }
}

GetBalance¶

source : in3-c/java/examples/GetBalance.java

getting the Balance with or without API

import in3.*;
import in3.eth1.*;
import java.math.BigInteger;
import java.util.*;

public class GetBalance {

  static String AC_ADDR = "0xc94770007dda54cF92009BFF0dE90c06F603a09f";

  public static void main(String[] args) throws Exception {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also dthe default)

    System.out.println("Balance API" + getBalanceAPI(in3).longValue());

    System.out.println("Balance RPC " + getBalanceRPC(in3));
  }

  static BigInteger getBalanceAPI(IN3 in3) {
    return in3.getEth1API().getBalance(AC_ADDR, Block.LATEST);
  }

  static String getBalanceRPC(IN3 in3) {
    return in3.sendRPC("eth_getBalance", new Object[] {AC_ADDR, "latest"});
  }
}

GetBlockAPI¶

source : in3-c/java/examples/GetBlockAPI.java

getting a block with API

import in3.*;
import in3.eth1.*;
import java.math.BigInteger;
import java.util.*;

public class GetBlockAPI {
  //
  public static void main(String[] args) throws Exception {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also dthe default)

    // read the latest Block including all Transactions.
    Block latestBlock = in3.getEth1API().getBlockByNumber(Block.LATEST, true);

    // Use the getters to retrieve all containing data
    System.out.println("current BlockNumber : " + latestBlock.getNumber());
    System.out.println("minded at : " + new Date(latestBlock.getTimeStamp()) + " by " + latestBlock.getAuthor());

    // get all Transaction of the Block
    Transaction[] transactions = latestBlock.getTransactions();

    BigInteger sum = BigInteger.valueOf(0);
    for (int i = 0; i < transactions.length; i++)
      sum = sum.add(transactions[i].getValue());

    System.out.println("total Value transfered in all Transactions : " + sum + " wei");
  }
}

GetBlockRPC¶

source : in3-c/java/examples/GetBlockRPC.java

getting a block without API

import in3.*;
import in3.eth1.*;
import java.math.BigInteger;
import java.util.*;

public class GetBlockRPC {
  //
  public static void main(String[] args) throws Exception {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also the default)

    // read the latest Block without the Transactions.
    String result = in3.sendRPC("eth_getBlockByNumber", new Object[] {"latest", false});

    // print the json-data
    System.out.println("current Block : " + result);
  }
}

GetTransaction¶

source : in3-c/java/examples/GetTransaction.java

getting a Transaction with or without API

import in3.*;
import in3.eth1.*;
import java.math.BigInteger;
import java.util.*;

public class GetTransaction {

  static String TXN_HASH = "0xdd80249a0631cf0f1593c7a9c9f9b8545e6c88ab5252287c34bc5d12457eab0e";

  public static void main(String[] args) throws Exception {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also dthe default)

    Transaction txn = getTransactionAPI(in3);
    System.out.println("Transaction API #blockNumber: " + txn.getBlockNumber());

    System.out.println("Transaction RPC :" + getTransactionRPC(in3));
  }

  static Transaction getTransactionAPI(IN3 in3) {
    return in3.getEth1API().getTransactionByHash(TXN_HASH);
  }

  static String getTransactionRPC(IN3 in3) {
    return in3.sendRPC("eth_getTransactionByHash", new Object[] {TXN_HASH});
  }
}

GetTransactionReceipt¶

source : in3-c/java/examples/GetTransactionReceipt.java

getting a TransactionReceipt with or without API

import in3.*;
import in3.eth1.*;
import java.math.BigInteger;
import java.util.*;

public class GetTransactionReceipt {
  static String TRANSACTION_HASH = "0xdd80249a0631cf0f1593c7a9c9f9b8545e6c88ab5252287c34bc5d12457eab0e";

  //
  public static void main(String[] args) throws Exception {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also the default)

    TransactionReceipt txn = getTransactionReceiptAPI(in3);
    System.out.println("TransactionRerceipt API : for txIndex " + txn.getTransactionIndex() + " Block num " + txn.getBlockNumber() + " Gas used " + txn.getGasUsed() + " status " + txn.getStatus());

    System.out.println("TransactionReceipt RPC : " + getTransactionReceiptRPC(in3));
  }

  static TransactionReceipt getTransactionReceiptAPI(IN3 in3) {
    return in3.getEth1API().getTransactionReceipt(TRANSACTION_HASH);
  }

  static String getTransactionReceiptRPC(IN3 in3) {
    return in3.sendRPC("eth_getTransactionReceipt", new Object[] {TRANSACTION_HASH});
  }
}

SendTransaction¶

source : in3-c/java/examples/SendTransaction.java

Sending Transactions

// In order to send, you need a Signer. The SimpleWallet class is a basic implementation which can be used.

package in3;

import in3.*;
import in3.eth1.*;
import java.io.IOException;
import java.math.BigInteger;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

public class SendTransaction {
  //
  public static void main(String[] args) throws IOException {
    // create incubed
    IN3 in3 = IN3.forChain(Chain.MAINNET); // set it to mainnet (which is also dthe default)

    // create a wallet managing the private keys
    SimpleWallet wallet = new SimpleWallet();

    // add accounts by adding the private keys
    String keyFile      = "myKey.json";
    String myPassphrase = "<secrect>";

    // read the keyfile and decoded the private key
    String account = wallet.addKeyStore(
        Files.readString(Paths.get(keyFile)),
        myPassphrase);

    // use the wallet as signer
    in3.setSigner(wallet);

    String     receipient = "0x1234567890123456789012345678901234567890";
    BigInteger value      = BigInteger.valueOf(100000);

    // create a Transaction
    TransactionRequest tx = new TransactionRequest();
    tx.setFrom(account);
    tx.setTo("0x1234567890123456789012345678901234567890");
    tx.setFunction("transfer(address,uint256)");
    tx.setParams(new Object[] {receipient, value});

    String txHash = in3.getEth1API().sendTransaction(tx);

    System.out.println("Transaction sent with hash = " + txHash);
  }
}

Building¶

In order to run those examples, you only need a Java SDK installed.

./build.sh

will build all examples in this directory.

In order to run a example use

java -cp $IN3/build/lib/in3.jar:. GetBlockAPI

Package in3¶

class BlockID¶

fromHash¶

public static BlockID fromHash(String hash);

arguments:

String hash

fromNumber¶

public static BlockID fromNumber(long number);

arguments:

long number

getNumber¶

public Long getNumber();

setNumber¶

public void setNumber(long block);

arguments:

long block

getHash¶

public String getHash();

setHash¶

public void setHash(String hash);

arguments:

String hash

toJSON¶

public String toJSON();

toString¶

public String toString();

This is the main class creating the incubed client.

The client can then be configured.

IN3¶

public IN3();

getConfig¶

returns the current configuration.

any changes to the configuration will be applied witth the next request.

public ClientConfiguration getConfig();

setSigner¶

sets the signer or wallet.

public void setSigner(Signer signer);

arguments:

Signer

signer

getSigner¶

returns the signer or wallet.

public Signer getSigner();

getIpfs¶

gets the ipfs-api

public in3.ipfs.API getIpfs();

getBtcAPI¶

gets the btc-api

public in3.btc.API getBtcAPI();

getEth1API¶

gets the ethereum-api

public in3.eth1.API getEth1API();

getCrypto¶

gets the utils/crypto-api

public Crypto getCrypto();

setStorageProvider¶

provides the ability to cache content like nodelists, contract codes and validatorlists

public void setStorageProvider(StorageProvider val);

arguments:

StorageProvider

val

getStorageProvider¶

provides the ability to cache content

public StorageProvider getStorageProvider();

setTransport¶

sets The transport interface.

This allows to fetch the result of the incubed in a different way.

public void setTransport(IN3Transport newTransport);

arguments:

IN3Transport newTransport

getTransport¶

returns the current transport implementation.

public IN3Transport getTransport();

getChainId¶

servers to filter for the given chain.

The chain-id based on EIP-155.

public native long getChainId();

setChainId¶

sets the chain to be used.

The chain-id based on EIP-155.

public native void setChainId(long val);

arguments:

long val

send¶

send a request.

The request must a valid json-string with method and params

public String send(String request);

arguments:

String request

sendobject¶

send a request but returns a object like array or map with the parsed response.

The request must a valid json-string with method and params

public Object sendobject(String request);

arguments:

String request

sendRPC¶

send a RPC request by only passing the method and params.

It will create the raw request from it and return the result.

public String sendRPC(String method, Object[] params);

arguments:

`String`	method
`Object[]`	params

sendRPCasObject¶

public Object sendRPCasObject(String method, Object[] params, boolean useEnsResolver);

arguments:

`String`	method
`Object[]`	params
`boolean`	useEnsResolver

sendRPCasObject¶

send a RPC request by only passing the method and params.

It will create the raw request from it and return the result.

public Object sendRPCasObject(String method, Object[] params);

arguments:

`String`	method
`Object[]`	params

cacheClear¶

clears the cache.

public boolean cacheClear();

nodeList¶

restrieves the node list

public IN3Node[] nodeList();

sign¶

request for a signature of an already verified hash.

public SignedBlockHash[] sign(BlockID[] blocks, String[] dataNodeAdresses);

arguments:

BlockID[]	blocks
`String[]`	dataNodeAdresses

forChain¶

create a Incubed client using the chain-config.

if chainId is Chain.MULTICHAIN, the client can later be switched between different chains, for all other chains, it will be initialized only with the chainspec for this one chain (safes memory)

public static IN3 forChain(long chainId);

arguments:

long chainId

getVersion¶

returns the current incubed version.

public static native String getVersion();

main¶

public static void main(String[] args);

arguments:

String[] args

class IN3DefaultTransport¶

handle¶

public byte[][] handle(String[] urls, byte[] payload);

arguments:

`String[]`	urls
`byte[]`	payload

class IN3Node¶

getUrl¶

public String getUrl();

getAddress¶

public String getAddress();

getIndex¶

public int getIndex();

getDeposit¶

public String getDeposit();

getProps¶

public long getProps();

getTimeout¶

public int getTimeout();

getRegisterTime¶

public int getRegisterTime();

getWeight¶

public int getWeight();

class IN3Props¶

IN3Props¶

public IN3Props();

setDataNodes¶

public void setDataNodes(String[] adresses);

arguments:

String[] adresses

setSignerNodes¶

public void setSignerNodes(String[] adresses);

arguments:

String[] adresses

toString¶

public String toString();

toJSON¶

public String toJSON();

class Loader¶

loadLibrary¶

public static void loadLibrary();

class NodeList¶

getNodes¶

returns an array of IN3Node

public IN3Node[] getNodes();

class NodeProps¶

public String getBlockHash();

getBlock¶

public long getBlock();

getR¶

public String getR();

getS¶

public String getS();

getV¶

public long getV();

getMsgHash¶

public String getMsgHash();

enum Proof¶

The Proof type indicating how much proof is required.

The enum type contains the following values:

none	0	No Verification.
standard	1	Standard Verification of the important properties.
full	2	Full Verification including even uncles wich leads to higher payload.

interface IN3Transport¶

handle¶

public byte[][] handle(String[] urls, byte[] payload);

arguments:

`String[]`	urls
`byte[]`	payload

Package in3.btc¶

class API¶

API for handling BitCoin data.

Use it when connected to Chain.BTC.

API¶

creates a btc.API using the given incubed instance.

public API(IN3 in3);

arguments:

ChainConfigurationHashMap< Long, , >

in3

getTransaction¶

Retrieves the transaction and returns the data as json.

public Transaction getTransaction(String txid);

arguments:

String txid

getTransactionBytes¶

Retrieves the serialized transaction (bytes).

public byte[] getTransactionBytes(String txid);

arguments:

String txid

getBlockHeader¶

Retrieves the blockheader.

public BlockHeader getBlockHeader(String blockHash);

arguments:

String blockHash

getBlockHeaderBytes¶

Retrieves the byte array representing teh serialized blockheader data.

public byte[] getBlockHeaderBytes(String blockHash);

arguments:

String blockHash

getBlockWithTxData¶

Retrieves the block including the full transaction data.

Use Api::GetBlockWithTxIds” for only the transaction ids.

public Block getBlockWithTxData(String blockHash);

arguments:

String blockHash

getBlockWithTxIds¶

Retrieves the block including only transaction ids.

Use Api::GetBlockWithTxData for the full transaction data.

public Block getBlockWithTxIds(String blockHash);

arguments:

String blockHash

getBlockBytes¶

Retrieves the serialized block in bytes.

public byte[] getBlockBytes(String blockHash);

arguments:

String blockHash

class Block¶

A Block.

getTransactions¶

Transactions or Transaction of a block.

public Transaction[] getTransactions();

getTransactionHashes¶

Transactions or Transaction ids of a block.

public String[] getTransactionHashes();

getSize¶

Size of this block in bytes.

public long getSize();

getWeight¶

Weight of this block in bytes.

public long getWeight();

class BlockHeader¶

A Block header.

getHash¶

The hash of the blockheader.

public String getHash();

getConfirmations¶

Number of confirmations or blocks mined on top of the containing block.

public long getConfirmations();

getHeight¶

Block number.

public long getHeight();

getVersion¶

Used version.

public long getVersion();

getVersionHex¶

Version as hex.

public String getVersionHex();

getMerkleroot¶

Merkle root of the trie of all transactions in the block.

public String getMerkleroot();

getTime¶

Unix timestamp in seconds since 1970.

public long getTime();

getMediantime¶

Unix timestamp in seconds since 1970.

public long getMediantime();

getNonce¶

Nonce-field of the block.

public long getNonce();

getBits¶

Bits (target) for the block as hex.

public String getBits();

getDifficulty¶

Difficulty of the block.

public float getDifficulty();

getChainwork¶

Total amount of work since genesis.

public String getChainwork();

getNTx¶

Number of transactions in the block.

public long getNTx();

getPreviousblockhash¶

Hash of the parent blockheader.

public String getPreviousblockhash();

getNextblockhash¶

Hash of the next blockheader.

public String getNextblockhash();

class ScriptPubKey¶

Script on a transaction output.

getAsm¶

The hash of the blockheader.

public String getAsm();

getHex¶

The raw hex data.

public String getHex();

getReqSigs¶

The required sigs.

public long getReqSigs();

getType¶

The type e.g.

: pubkeyhash.

public String getType();

getAddresses¶

List of addresses.

public String[] getAddresses();

class ScriptSig¶

Script on a transaction input.

ScriptSig¶

public ScriptSig(JSON data);

arguments:

JSON

data

getAsm¶

The asm data.

public String getAsm();

getHex¶

The raw hex data.

public String getHex();

class Transaction¶

A BitCoin Transaction.

asTransaction¶

public static Transaction asTransaction(Object o);

arguments:

Object o

asTransactions¶

public static Transaction[] asTransactions(Object o);

arguments:

Object o

getTxid¶

Transaction Id.

public String getTxid();

getHash¶

The transaction hash (differs from txid for witness transactions).

public String getHash();

getVersion¶

The version.

public long getVersion();

getSize¶

The serialized transaction size.

public long getSize();

getVsize¶

The virtual transaction size (differs from size for witness transactions).

public long getVsize();

getWeight¶

The transactions weight (between vsize4-3 and vsize4).

public long getWeight();

getLocktime¶

The locktime.

public long getLocktime();

getHex¶

The hex representation of raw data.

public String getHex();

getBlockhash¶

The block hash of the block containing this transaction.

public String getBlockhash();

getConfirmations¶

The confirmations.

public long getConfirmations();

getTime¶

The transaction time in seconds since epoch (Jan 1 1970 GMT).

public long getTime();

getBlocktime¶

The block time in seconds since epoch (Jan 1 1970 GMT).

public long getBlocktime();

getVin¶

The transaction inputs.

public TransactionInput[] getVin();

getVout¶

The transaction outputs.

public TransactionOutput[] getVout();

class TransactionInput¶

Input of a transaction.

getTxid¶

The transaction id.

public String getTxid();

getYout¶

The index of the transactionoutput.

public long getYout();

getScriptSig¶

The script.

public ScriptSig getScriptSig();

getTxinwitness¶

Hex-encoded witness data (if any).

public String[] getTxinwitness();

getSequence¶

The script sequence number.

public long getSequence();

class TransactionOutput¶

A BitCoin Transaction.

TransactionOutput¶

public TransactionOutput(JSON data);

arguments:

JSON

data

getValue¶

The value in bitcoins.

public float getValue();

getN¶

The index in the transaction.

public long getN();

getScriptPubKey¶

The script of the transaction.

public ScriptPubKey getScriptPubKey();

Package in3.config¶

class ChainConfiguration¶

Part of the configuration hierarchy for IN3 Client.

Holds the configuration a node group in a particular Chain.

nodesConfig¶

Type: NodeConfigurationArrayList< , >

ChainConfiguration¶

public ChainConfiguration(long chain, ClientConfiguration config);

arguments:

`long`	chain
ClientConfiguration	config

getChain¶

public long getChain();

isNeedsUpdate¶

public Boolean isNeedsUpdate();

setNeedsUpdate¶

public void setNeedsUpdate(boolean needsUpdate);

arguments:

boolean needsUpdate

getContract¶

public String getContract();

setContract¶

public void setContract(String contract);

arguments:

String contract

getRegistryId¶

public String getRegistryId();

setRegistryId¶

public void setRegistryId(String registryId);

arguments:

String registryId

getWhiteListContract¶

public String getWhiteListContract();

setWhiteListContract¶

public void setWhiteListContract(String whiteListContract);

arguments:

String whiteListContract

getWhiteList¶

public String[] getWhiteList();

setWhiteList¶

public void setWhiteList(String[] whiteList);

arguments:

String[] whiteList

toJSON¶

generates a json-string based on the internal data.

public String toJSON();

toString¶

public String toString();

class ClientConfiguration¶

Configuration Object for Incubed Client.

It holds the state for the root of the configuration tree. Should be retrieved from the client instance as IN3::getConfig()

getRequestCount¶

public Integer getRequestCount();

setRequestCount¶

sets the number of requests send when getting a first answer

public void setRequestCount(int requestCount);

arguments:

int requestCount

isAutoUpdateList¶

public Boolean isAutoUpdateList();

setAutoUpdateList¶

activates the auto update.if true the nodelist will be automaticly updated if the lastBlock is newer

public void setAutoUpdateList(boolean autoUpdateList);

arguments:

boolean autoUpdateList

getProof¶

public Proof getProof();

setProof¶

sets the type of proof used

public void setProof(Proof proof);

arguments:

Proof

proof

getMaxAttempts¶

public Integer getMaxAttempts();

setMaxAttempts¶

sets the max number of attempts before giving up

public void setMaxAttempts(int maxAttempts);

arguments:

int maxAttempts

getSignatureCount¶

public Integer getSignatureCount();

setSignatureCount¶

sets the number of signatures used to proof the blockhash.

public void setSignatureCount(int signatureCount);

arguments:

int signatureCount

isStats¶

public Boolean isStats();

setStats¶

if true (default) the request will be counted as part of the regular stats, if not they are not shown as part of the dashboard.

public void setStats(boolean stats);

arguments:

boolean stats

getFinality¶

public Integer getFinality();

setFinality¶

sets the number of signatures in percent required for the request

public void setFinality(int finality);

arguments:

int finality

isIncludeCode¶

public Boolean isIncludeCode();

setIncludeCode¶

public void setIncludeCode(boolean includeCode);

arguments:

boolean includeCode

isBootWeights¶

public Boolean isBootWeights();

setBootWeights¶

if true, the first request (updating the nodelist) will also fetch the current health status and use it for blacklisting unhealthy nodes.

This is used only if no nodelist is availabkle from cache.

public void setBootWeights(boolean value);

arguments:

boolean value

isKeepIn3¶

public Boolean isKeepIn3();

setKeepIn3¶

public void setKeepIn3(boolean keepIn3);

arguments:

boolean keepIn3

isUseHttp¶

public Boolean isUseHttp();

setUseHttp¶

public void setUseHttp(boolean useHttp);

arguments:

boolean useHttp

getTimeout¶

public Long getTimeout();

setTimeout¶

specifies the number of milliseconds before the request times out.

increasing may be helpful if the device uses a slow connection.

public void setTimeout(long timeout);

arguments:

long timeout

getMinDeposit¶

public Long getMinDeposit();

setMinDeposit¶

sets min stake of the server.

Only nodes owning at least this amount will be chosen.

public void setMinDeposit(long minDeposit);

arguments:

long minDeposit

getNodeProps¶

public Long getNodeProps();

setNodeProps¶

public void setNodeProps(long nodeProps);

arguments:

long nodeProps

getNodeLimit¶

public Long getNodeLimit();

setNodeLimit¶

sets the limit of nodes to store in the client.

public void setNodeLimit(long nodeLimit);

arguments:

long nodeLimit

getReplaceLatestBlock¶

public Integer getReplaceLatestBlock();

setReplaceLatestBlock¶

replaces the latest with blockNumber- specified value

public void setReplaceLatestBlock(int replaceLatestBlock);

arguments:

int replaceLatestBlock

getRpc¶

public String getRpc();

setRpc¶

setup an custom rpc source for requests by setting Chain to local and proof to none

public void setRpc(String rpc);

arguments:

String rpc

getNodesConfig¶

public ChainConfigurationHashMap< Long, , > getNodesConfig();

setChainsConfig¶

public void setChainsConfig(HashMap< Long, ChainConfiguration >);

arguments:

chainsConfig

markAsSynced¶

public void markAsSynced();

isSynced¶

public boolean isSynced();

toString¶

public String toString();

toJSON¶

generates a json-string based on the internal data.

public String toJSON();

class NodeConfiguration¶

Configuration Object for Incubed Client.

It represents the node of a nodelist.

NodeConfiguration¶

public NodeConfiguration(ChainConfiguration config);

arguments:

ChainConfiguration

config

getUrl¶

public String getUrl();

setUrl¶

public void setUrl(String url);

arguments:

String url

getProps¶

public long getProps();

setProps¶

public void setProps(long props);

arguments:

long props

getAddress¶

public String getAddress();

setAddress¶

public void setAddress(String address);

arguments:

String address

toString¶

public String toString();

interface Configuration¶

an Interface class, which is able to generate a JSON-String.

toJSON¶

generates a json-string based on the internal data.

public String toJSON();

Package in3.eth1¶

class API¶

a Wrapper for the incubed client offering Type-safe Access and additional helper functions.

API¶

creates an eth1.API using the given incubed instance.

public API(IN3 in3);

arguments:

in3

getBlockByNumber¶

finds the Block as specified by the number.

use Block.LATEST for getting the lastest block.

public Block getBlockByNumber(long block, boolean includeTransactions);

arguments:

`long`	block
`boolean`	includeTransactions	< the Blocknumber < if true all Transactions will be includes, if not only the transactionhashes

getBlockByHash¶

Returns information about a block by hash.

public Block getBlockByHash(String blockHash, boolean includeTransactions);

arguments:

`String`	blockHash
`boolean`	includeTransactions	< the Blocknumber < if true all Transactions will be includes, if not only the transactionhashes

getBlockNumber¶

the current BlockNumber.

public long getBlockNumber();

getGasPrice¶

the current Gas Price.

public long getGasPrice();

getChainId¶

Returns the EIP155 chain ID used for transaction signing at the current best block.

Null is returned if not available.

public String getChainId();

call¶

calls a function of a smart contract and returns the result.

public Object call(TransactionRequest request, long block);

arguments:

TransactionRequest	request
`long`	block	< the transaction to call. < the Block used to for the state.

returns: Object : the decoded result. if only one return value is expected the Object will be returned, if not an array of objects will be the result.

estimateGas¶

Makes a call or transaction, which won’t be added to the blockchain and returns the used gas, which can be used for estimating the used gas.

public long estimateGas(TransactionRequest request, long block);

arguments:

TransactionRequest	request
`long`	block	< the transaction to call. < the Block used to for the state.

returns: long : the gas required to call the function.

getBalance¶

Returns the balance of the account of given address in wei.

public BigInteger getBalance(String address, long block);

arguments:

`String`	address
`long`	block

getCode¶

Returns code at a given address.

public String getCode(String address, long block);

arguments:

`String`	address
`long`	block

getStorageAt¶

Returns the value from a storage position at a given address.

public String getStorageAt(String address, BigInteger position, long block);

arguments:

`String`	address
`BigInteger`	position
`long`	block

getBlockTransactionCountByHash¶

Returns the number of transactions in a block from a block matching the given block hash.

public long getBlockTransactionCountByHash(String blockHash);

arguments:

String blockHash

getBlockTransactionCountByNumber¶

Returns the number of transactions in a block from a block matching the given block number.

public long getBlockTransactionCountByNumber(long block);

arguments:

long block

getFilterChangesFromLogs¶

Polling method for a filter, which returns an array of logs which occurred since last poll.

public Log[] getFilterChangesFromLogs(long id);

arguments:

long id

getFilterChangesFromBlocks¶

Polling method for a filter, which returns an array of logs which occurred since last poll.

public String[] getFilterChangesFromBlocks(long id);

arguments:

long id

getFilterLogs¶

Polling method for a filter, which returns an array of logs which occurred since last poll.

public Log[] getFilterLogs(long id);

arguments:

long id

getLogs¶

Polling method for a filter, which returns an array of logs which occurred since last poll.

public Log[] getLogs(LogFilter filter);

arguments:

LogFilter

filter

getTransactionByBlockHashAndIndex¶

Returns information about a transaction by block hash and transaction index position.

public Transaction getTransactionByBlockHashAndIndex(String blockHash, int index);

arguments:

`String`	blockHash
`int`	index

getTransactionByBlockNumberAndIndex¶

Returns information about a transaction by block number and transaction index position.

public Transaction getTransactionByBlockNumberAndIndex(long block, int index);

arguments:

`long`	block
`int`	index

getTransactionByHash¶

Returns the information about a transaction requested by transaction hash.

public Transaction getTransactionByHash(String transactionHash);

arguments:

String transactionHash

getTransactionCount¶

Returns the number of transactions sent from an address.

public BigInteger getTransactionCount(String address, long block);

arguments:

`String`	address
`long`	block

getTransactionReceipt¶

Returns the number of transactions sent from an address.

public TransactionReceipt getTransactionReceipt(String transactionHash);

arguments:

String transactionHash

getUncleByBlockNumberAndIndex¶

Returns information about a uncle of a block number and uncle index position.

Note: An uncle doesn’t contain individual transactions.

public Block getUncleByBlockNumberAndIndex(long block, int pos);

arguments:

`long`	block
`int`	pos

getUncleCountByBlockHash¶

Returns the number of uncles in a block from a block matching the given block hash.

public long getUncleCountByBlockHash(String block);

arguments:

String block

getUncleCountByBlockNumber¶

Returns the number of uncles in a block from a block matching the given block hash.

public long getUncleCountByBlockNumber(long block);

arguments:

long block

newBlockFilter¶

Creates a filter in the node, to notify when a new block arrives.

To check if the state has changed, call eth_getFilterChanges.

public long newBlockFilter();

newLogFilter¶

Creates a filter object, based on filter options, to notify when the state changes (logs).

To check if the state has changed, call eth_getFilterChanges.

A note on specifying topic filters: Topics are order-dependent. A transaction with a log with topics [A, B] will be matched by the following topic filters:

[] “anything” [A] “A in first position (and anything after)” [null, B] “anything in first position AND B in second position (and anything after)” [A, B] “A in first position AND B in second position (and anything after)” [[A, B], [A, B]] “(A OR B) in first position AND (A OR B) in second position (and anything after)”

public long newLogFilter(LogFilter filter);

arguments:

LogFilter

filter

uninstallFilter¶

uninstall filter.

public boolean uninstallFilter(long filter);

arguments:

long filter

sendRawTransaction¶

Creates new message call transaction or a contract creation for signed transactions.

public String sendRawTransaction(String data);

arguments:

String data

returns: String : transactionHash

abiEncode¶

encodes the arguments as described in the method signature using ABI-Encoding.

public String abiEncode(String signature, String[] params);

arguments:

`String`	signature
`String[]`	params

abiDecode¶

decodes the data based on the signature.

public String[] abiDecode(String signature, String encoded);

arguments:

`String`	signature
`String`	encoded

checksumAddress¶

converts the given address to a checksum address.

public String checksumAddress(String address);

arguments:

String address

checksumAddress¶

converts the given address to a checksum address.

Second parameter includes the chainId.

public String checksumAddress(String address, Boolean useChainId);

arguments:

`String`	address
`Boolean`	useChainId

ens¶

resolve ens-name.

public String ens(String name);

arguments:

String name

ens¶

resolve ens-name.

Second parameter especifies if it is an address, owner, resolver or hash.

public String ens(String name, ENSMethod type);

arguments:

`String`	name
ENSMethod	type

sendTransaction¶

sends a Transaction as described by the TransactionRequest.

This will require a signer to be set in order to sign the transaction.

public String sendTransaction(TransactionRequest tx);

arguments:

TransactionRequest

tx

call¶

the current Gas Price.

public Object call(String to, String function, Object... params);

arguments:

`String`	to
`String`	function
`Object...`	params

returns: Object : the decoded result. if only one return value is expected the Object will be returned, if not an array of objects will be the result.

class Block¶

represents a Block in ethereum.

LATEST¶

The latest Block Number.

Type: static long

EARLIEST¶

The Genesis Block.

Type: static long

getTotalDifficulty¶

returns the total Difficulty as a sum of all difficulties starting from genesis.

public BigInteger getTotalDifficulty();

getGasLimit¶

the gas limit of the block.

public BigInteger getGasLimit();

getExtraData¶

the extra data of the block.

public String getExtraData();

getDifficulty¶

the difficulty of the block.

public BigInteger getDifficulty();

getAuthor¶

the author or miner of the block.

public String getAuthor();

getTransactionsRoot¶

the roothash of the merkletree containing all transaction of the block.

public String getTransactionsRoot();

getTransactionReceiptsRoot¶

the roothash of the merkletree containing all transaction receipts of the block.

public String getTransactionReceiptsRoot();

getStateRoot¶

the roothash of the merkletree containing the complete state.

public String getStateRoot();

getTransactionHashes¶

the transaction hashes of the transactions in the block.

public String[] getTransactionHashes();

getTransactions¶

the transactions of the block.

public Transaction[] getTransactions();

getTimeStamp¶

the unix timestamp in seconds since 1970.

public long getTimeStamp();

getSha3Uncles¶

the roothash of the merkletree containing all uncles of the block.

public String getSha3Uncles();

getSize¶

the size of the block.

public long getSize();

getSealFields¶

the seal fields used for proof of authority.

public String[] getSealFields();

getHash¶

the block hash of the of the header.

public String getHash();

getLogsBloom¶

the bloom filter of the block.

public String getLogsBloom();

getMixHash¶

the mix hash of the block.

(only valid of proof of work)

public String getMixHash();

getNonce¶

the mix hash of the block.

(only valid of proof of work)

public String getNonce();

getNumber¶

the block number

public long getNumber();

getParentHash¶

the hash of the parent-block.

public String getParentHash();

getUncles¶

returns the blockhashes of all uncles-blocks.

public String[] getUncles();

hashCode¶

public int hashCode();

equals¶

public boolean equals(Object obj);

arguments:

Object obj

class Log¶

a log entry of a transaction receipt.

isRemoved¶

true when the log was removed, due to a chain reorganization.

false if its a valid log.

public boolean isRemoved();

getLogIndex¶

integer of the log index position in the block.

null when its pending log.

public int getLogIndex();

gettTansactionIndex¶

integer of the transactions index position log was created from.

null when its pending log.

public int gettTansactionIndex();

getTransactionHash¶

Hash, 32 Bytes - hash of the transactions this log was created from.

null when its pending log.

public String getTransactionHash();

getBlockHash¶

Hash, 32 Bytes - hash of the block where this log was in.

null when its pending. null when its pending log.

public String getBlockHash();

getBlockNumber¶

the block number where this log was in.

null when its pending. null when its pending log.

public long getBlockNumber();

getAddress¶

20 Bytes - address from which this log originated.

public String getAddress();

getTopics¶

Array of 0 to 4 32 Bytes DATA of indexed log arguments.

(In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256)), except you declared the event with the anonymous specifier.)

public String[] getTopics();

class LogFilter¶

Log configuration for search logs.

getFromBlock¶

public long getFromBlock();

setFromBlock¶

public void setFromBlock(long fromBlock);

arguments:

long fromBlock

getToBlock¶

public long getToBlock();

setToBlock¶

public void setToBlock(long toBlock);

arguments:

long toBlock

getAddress¶

public String getAddress();

setAddress¶

public void setAddress(String address);

arguments:

String address

getTopics¶

public Object[] getTopics();

setTopics¶

public void setTopics(Object[] topics);

arguments:

Object[] topics

getLimit¶

public int getLimit();

setLimit¶

public void setLimit(int limit);

arguments:

int limit

toString¶

creates a JSON-String.

public String toString();

class SimpleWallet¶

a simple Implementation for holding private keys to sing data or transactions.

addRawKey¶

adds a key to the wallet and returns its public address.

public String addRawKey(String data);

arguments:

String data

addKeyStore¶

adds a key to the wallet and returns its public address.

public String addKeyStore(String jsonData, String passphrase);

arguments:

`String`	jsonData
`String`	passphrase

prepareTransaction¶

optiional method which allows to change the transaction-data before sending it.

This can be used for redirecting it through a multisig.

public TransactionRequest prepareTransaction(IN3 in3, TransactionRequest tx);

arguments:

IN3	in3
TransactionRequest	tx

canSign¶

returns true if the account is supported (or unlocked)

public boolean canSign(String address);

arguments:

String address

sign¶

signing of the raw data.

public String sign(String data, String address);

arguments:

`String`	data
`String`	address

class Transaction¶

represents a Transaction in ethereum.

asTransaction¶

public static Transaction asTransaction(Object o);

arguments:

Object o

getBlockHash¶

the blockhash of the block containing this transaction.

public String getBlockHash();

getBlockNumber¶

the block number of the block containing this transaction.

public long getBlockNumber();

getChainId¶

the chainId of this transaction.

public String getChainId();

getCreatedContractAddress¶

the address of the deployed contract (if successfull)

public String getCreatedContractAddress();

getFrom¶

the address of the sender.

public String getFrom();

getHash¶

the Transaction hash.

public String getHash();

getData¶

the Transaction data or input data.

public String getData();

getNonce¶

the nonce used in the transaction.

public long getNonce();

getPublicKey¶

the public key of the sender.

public String getPublicKey();

getValue¶

the value send in wei.

public BigInteger getValue();

getRaw¶

the raw transaction as rlp encoded data.

public String getRaw();

getTo¶

the address of the receipient or contract.

public String getTo();

getSignature¶

the signature of the sender - a array of the [ r, s, v]

public String[] getSignature();

getGasPrice¶

the gas price provided by the sender.

public long getGasPrice();

getGas¶

the gas provided by the sender.

public long getGas();

class TransactionReceipt¶

represents a Transaction receipt in ethereum.

getBlockHash¶

the blockhash of the block containing this transaction.

public String getBlockHash();

getBlockNumber¶

the block number of the block containing this transaction.

public long getBlockNumber();

getCreatedContractAddress¶

the address of the deployed contract (if successfull)

public String getCreatedContractAddress();

getFrom¶

the address of the sender.

public String getFrom();

getTransactionHash¶

the Transaction hash.

public String getTransactionHash();

getTransactionIndex¶

the Transaction index.

public int getTransactionIndex();

getTo¶

20 Bytes - The address of the receiver.

null when it’s a contract creation transaction.

public String getTo();

getGasUsed¶

The amount of gas used by this specific transaction alone.

public long getGasUsed();

getLogs¶

Array of log objects, which this transaction generated.

public Log[] getLogs();

getLogsBloom¶

256 Bytes - A bloom filter of logs/events generated by contracts during transaction execution.

Used to efficiently rule out transactions without expected logs

public String getLogsBloom();

getRoot¶

32 Bytes - Merkle root of the state trie after the transaction has been executed (optional after Byzantium hard fork EIP609).

public String getRoot();

getStatus¶

success of a Transaction.

true indicates transaction failure , false indicates transaction success. Set for blocks mined after Byzantium hard fork EIP609, null before.

public boolean getStatus();

class TransactionRequest¶

represents a Transaction Request which should be send or called.

getFrom¶

public String getFrom();

setFrom¶

public void setFrom(String from);

arguments:

String from

getTo¶

public String getTo();

setTo¶

public void setTo(String to);

arguments:

String to

getValue¶

public BigInteger getValue();

setValue¶

public void setValue(BigInteger value);

arguments:

BigInteger value

getNonce¶

public long getNonce();

setNonce¶

public void setNonce(long nonce);

arguments:

long nonce

getGas¶

public long getGas();

setGas¶

public void setGas(long gas);

arguments:

long gas

getGasPrice¶

public long getGasPrice();

setGasPrice¶

public void setGasPrice(long gasPrice);

arguments:

long gasPrice

getFunction¶

public String getFunction();

setFunction¶

public void setFunction(String function);

arguments:

String function

getParams¶

public Object[] getParams();

setParams¶

public void setParams(Object[] params);

arguments:

Object[] params

setData¶

public void setData(String data);

arguments:

String data

getData¶

creates the data based on the function/params values.

public String getData();

getTransactionJson¶

public String getTransactionJson();

getResult¶

public Object getResult(String data);

arguments:

String data

enum ENSMethod¶

The enum type contains the following values:

addr	0
resolver	1
hash	2
owner	3

Package in3.ipfs¶

class API¶

API for ipfs custom methods.

To be used along with “Chain.IPFS” on in3 instance.

API¶

creates a ipfs.API using the given incubed instance.

public API(IN3 in3);

arguments:

in3

get¶

Returns the content associated with specified multihash on success OR NULL on error.

public byte[] get(String multihash);

arguments:

String multihash

put¶

Returns the IPFS multihash of stored content on success OR NULL on error.

public String put(String content);

arguments:

String content

put¶

Returns the IPFS multihash of stored content on success OR NULL on error.

public String put(byte[] content);

arguments:

byte[] content

Package in3.ipfs.API¶

enum Encoding¶

The enum type contains the following values:

base64	0
hex	1
utf8	2

Package in3.utils¶

class Account¶

Pojo that represents the result of an ecrecover operation (see: Crypto class).

getAddress¶

address from ecrecover operation.

public String getAddress();

getPublicKey¶

public key from ecrecover operation.

public String getPublicKey();

class Crypto¶

a Wrapper for crypto-related helper functions.

Crypto¶

public Crypto(IN3 in3);

arguments: