# NAME
eth-monitor - Cache, index and monitor transactions with an EVM node rpc
# SYNOPSIS
**eth-monitor** \[ --skip-history \] \[ --single \] \[ p *eth_provider*
\] \[ --includes-file *file* \] \[ -i chain_spec \] **eth-monitor** \[
--skip-history \] \[ --single \] \[ p *eth_provider* \] \[
--excludes-file *file* \] \[ --include-default \] \[ -i chain_spec \]
# DESCRIPTION
The **eth-monitor** has fulfills three distinct but related functions:
> 1\. A customizable view of on transactions of interest.
>
> 2\. A block and transaction cache.
>
> 3\. Arbitrary code executions using a transaction (and its block) as
> input.
Using an EVM RPC endpoint, the **eth-monitor** tool will retrieve blocks
within a given range and provides arbitrary processing of each
transaction.
A collection of options is provided to control the behavior of which
block ranges to sync, which criteria to use for display and cache, and
what code to execute for matching transactions. Details on each topic
can be found in the **SYNCING**, **MATCHING ADDRESSES** and **DEFINING
FILTERS** sections below, respectively.
Example executions of the tool can be found in the **EXAMPLES** section.
## OPTIONS
**-0**
Omit newline to output
**--address ***address*
Add an address of interest to match any role. Complements
**--address-file***.*
**-c ***config_dir, ***--config ***config_dir*
Load configuration files from given directory. All files with an .ini
extension will be loaded, of which all must contain valid ini file data.
**--dumpconfig ***format*
Output configuration settings rendered from environment and inputs.
Valid arguments are *ini for ini file output, and env for environment
variable output. See ***CONFIGURATION***.*
**--env-prefix**
Environment prefix for variables to overwrite configuration. Example: If
**--env-prefix*** is set to ***FOO*** then configuration variable
***BAR_BAZ*** would be set by environment variable ***FOO_BAZ_BAR***.
Also see ***ENVIRONMENT***.*
**--excludes-file ***file*
Load address exclude matching rules from file. See **MATCHING
ADDRESSES***.*
**--exec ***address*
Add an address of interest to executable address array. Complements
**--address-file***.*
**--filter ***module*
Add code execution filter to all matched transactions. The argument must
be a python module path. Several filters may be added by supplying the
option multiple times. Filters will be executed in the order the options
are given. See **DEFINING FILTERS*** section of ***eth-monitor (1)***
for more details.*
**--height**
Block height at which to query state for. Does not apply to
transactions.
**-i ***chain_spec, ***--chain-spec ***chain_spec*
Chain specification string, in the format
\<engine\>:\<fork\>:\<chain_id\>:\<common_name\>. Example:
"evm:london:1:ethereum". Overrides the *RPC_CREDENTIALS configuration
setting.*
**--include-default **
Match all addresses by default. Addresses may be excluded using
--excludes-file. If this is set, --input, --output, --exec and
--includes-file will have no effect.
**--includes-file ***file*
Load address include matching rules from file. See **MATCHING
ADDRESSES***.*
**--input ***address*
Add an address of interest to inputs (recipients) array. Complements
**--address-file***.*
**-n ***namespace, ***--namespace ***namespace*
Load given configuration namespace. Configuration will be loaded from
the immediate configuration subdirectory with the same name.
**--no-logs**
Turn of logging completely. Negates **-v*** and ***-vv**
**--output ***address*
Add an address of interest to outputs (sender) array. Complements
**--address-file***.*
**-p***, ***--rpc-provider**
Fully-qualified URL of RPC provider. Overrides the *RPC_PROVIDER
configuration setting.*
**--raw**
Produce output most optimized for machines.
**--renderer ***module*
Add output renderer filter to all matched transactions. The argument
must be a python module path. Several renderers may be added by
supplying the option multiple times. See **RENDERERS*** section of
***eth-monitor (1)*** for more details.*
**--rpc-dialect**
RPC backend dialect. If specified it *may help with encoding and
decoding issues. Overrides the RPC_DIALECT configuration setting.*
**--store-block-data **
Store block data in cache for matching transactions. Requires
**--cache-dir***.*
**--store-tx-data **
Store transaction data in cache for matching transactions. Requires
**--cache-dir***.*
**-u***, ***--unsafe**
Allow addresses that do not pass checksum.
**-v**
Verbose. Show logs for important state changes.
**-vv**
Very verbose. Show logs with debugging information.
**--x-address ***address*
Add an address of interest to match any role.
**--x-exec ***address*
Add an address of disinterest to executable address array.
**--x-input ***address*
Add an address of disinterest to inputs (recipients) array.
**--x-output ***address*
Add an address of disinterest to outputs (sender) array.
# CONFIGURATION
All configuration settings may be overriden both by environment
variables, or by overriding settings with the contents of ini-files in
the directory defined by the **-c*** option.*
The active configuration, with values assigned from environment and
arguments, can be output using the **--dumpconfig*** format option. Note
that entries having keys prefixed with underscore (e.g. \_SEQ) are not
actual configuration settings, and thus cannot be overridden with
environment variables.*
To refer to a configuration setting by environment variables, the
*section and key are concatenated together with an underscore, and
transformed to upper-case. For example, the configuration variable
FOO_BAZ_BAR refers to an ini-file entry as follows:*
[foo]
bar_baz = xyzzy
In the **ENVIRONMENT*** section below, the relevant configuration
settings for this tool is listed along with a short description of its
meaning.*
Some configuration settings may also be overriden by command line
options. Also note that the use of the **-n*** and ***--env-prefix***
options affect how environment and configuration is read. The effects of
options on how configuration settings are affective is described in the
respective ***OPTIONS*** section.*
# MATCHING ADDRESSES
By default, addresses to match against transactions need to be
explicitly specified. This behavior can be reversed with the
**--include-default*** option. Addresses to match are defined using the
***--input***, ***--output*** and ***--exec*** options. Addresses
specified multiple times will be deduplicated.*
Inclusion rules may also be loaded from file by specifying the
**--includes-file*** and ***--excludes-file*** options. Each file must
specify the outputs, inputs and exec addresses as comma separated lists
respectively, separated by tabs.*
In the current state of this tool, address matching will affect all
parts of the processing; cache, code execution and rendering.
# SYNCING
When a sync is initiated, the state of this sync is persisted. This way,
previous syncs that did not complete for some reason will be resumed
where they left off.
A special sync type **--head*** starts syncing at the current head of
the chain, and continue to sync until interrupted. When resuming sync, a
new sync range between the current block head and the block height at
which the previous ***--head*** sync left off will automatically be
created.*
Syncs can be forced to (re)run for ranges regardless of previous state
by using the **--single*** option. However, there is no protection in
place from preventing code filters from being executed again on the same
transaction when this is done. See ***DEFINING FILTERS*** below.*
# CACHE
When syncing, the hash of a block and transaction matching the address
criteria will be stored in the cache. The hashes can be used for future
data lookups.
If **--store-block-data*** and/or ***--store-tx-data*** is set, a copy
of the block and/or transaction data will also be stored, respectively.*
# RENDERING
Rendering in the context of **eth-monitor*** refers to a formatted
output stream that occurs independently of caching and code execution.*
Filters for rendering may be specified by specifying python modules to
the **--renderer*** option. This option may be specified multiple
times.*
Rendering filters will be executed in order, and the first filter to
return *False*
# DEFINING FILTERS
A python module used for filter must fulfill two conditions:
> 1\. It must provide a class named *Filter in the package base
> namespace.*
>
> 2\. The *Filter class must include a method named filter with the
> signature def filter(self, conn, block, tx, db_session=None). *
Filters will strictly be executed in the order which they are defined on
the command line.
# FURTHER READING
Refer to the **chainsyncer*** chapter n info chaintool for in-depth
information on the subjects of syncing and filtering.*
# ENVIRONMENT
*CHAIN_SPEC*
String specifying the type of chain connected to, in the format
*\<engine\>:\<fork\>:\<network_id\>:\<common_name\>. For EVM nodes the
engine value will always be evm.*
*RPC_DIALECT*
Enables translations of EVM node specific formatting and response codes.
*RPC_PROVIDER*
Fully-qualified URL to the RPC endpoint of the blockchain node.
# LICENSE
This documentation and its source is licensed under the Creative Commons
Attribution-Sharealike 4.0 International license.
The source code of the tool this documentation describes is licensed
under the GNU General Public License 3.0.
# COPYRIGHT
Louis Holbrook \<dev@holbrook.no\> (https://holbrook.no) PGP:
59A844A484AC11253D3A3E9DCDCBD24DD1D0E001
# SOURCE CODE
https://git.defalsify.org
Raw data
{
"_id": null,
"home_page": "https://git.defalsify.org/eth-monitor",
"name": "eth-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dlt, blockchain, cryptocurrency, ethereum",
"author": "Louis Holbrook",
"author_email": "dev@holbrook.no",
"download_url": "https://files.pythonhosted.org/packages/08/66/02fe1b9deb675de09db89e9cd441162a45ccac987a1d3ce7c433595c1943/eth-monitor-0.8.9.tar.gz",
"platform": null,
"description": "# NAME\n\neth-monitor - Cache, index and monitor transactions with an EVM node rpc\n\n# SYNOPSIS\n\n**eth-monitor** \\[ --skip-history \\] \\[ --single \\] \\[ p *eth_provider*\n\\] \\[ --includes-file *file* \\] \\[ -i chain_spec \\] **eth-monitor** \\[\n--skip-history \\] \\[ --single \\] \\[ p *eth_provider* \\] \\[\n--excludes-file *file* \\]\u00a0\\[ --include-default \\] \\[ -i chain_spec \\]\u00a0\n\n# DESCRIPTION\n\nThe **eth-monitor** has fulfills three distinct but related functions:\n\n> 1\\. A customizable view of on transactions of interest.\n>\n> 2\\. A block and transaction cache.\n>\n> 3\\. Arbitrary code executions using a transaction (and its block) as\n> input.\n\nUsing an EVM RPC endpoint, the **eth-monitor** tool will retrieve blocks\nwithin a given range and provides arbitrary processing of each\ntransaction.\n\nA collection of options is provided to control the behavior of which\nblock ranges to sync, which criteria to use for display and cache, and\nwhat code to execute for matching transactions. Details on each topic\ncan be found in the **SYNCING**, **MATCHING ADDRESSES** and **DEFINING\nFILTERS** sections below, respectively.\n\nExample executions of the tool can be found in the **EXAMPLES** section.\n\n## OPTIONS\n\n**-0** \nOmit newline to output\n\n**--address ***address* \nAdd an address of interest to match any role. Complements\n**--address-file***.*\n\n**-c ***config_dir, ***--config ***config_dir* \nLoad configuration files from given directory. All files with an .ini\nextension will be loaded, of which all must contain valid ini file data.\n\n**--dumpconfig ***format* \nOutput configuration settings rendered from environment and inputs.\nValid arguments are *ini for ini file output, and env for environment\nvariable output. See ***CONFIGURATION***.*\n\n**--env-prefix** \nEnvironment prefix for variables to overwrite configuration. Example: If\n**--env-prefix*** is set to ***FOO*** then configuration variable\n***BAR_BAZ*** would be set by environment variable ***FOO_BAZ_BAR***.\nAlso see ***ENVIRONMENT***.*\n\n**--excludes-file ***file* \nLoad address exclude matching rules from file. See **MATCHING\nADDRESSES***.*\n\n**--exec ***address* \nAdd an address of interest to executable address array. Complements\n**--address-file***.*\n\n**--filter ***module* \nAdd code execution filter to all matched transactions. The argument must\nbe a python module path. Several filters may be added by supplying the\noption multiple times. Filters will be executed in the order the options\nare given. See **DEFINING FILTERS*** section of ***eth-monitor (1)***\nfor more details.*\n\n**--height** \nBlock height at which to query state for. Does not apply to\ntransactions.\n\n**-i ***chain_spec, ***--chain-spec ***chain_spec* \nChain specification string, in the format\n\\<engine\\>:\\<fork\\>:\\<chain_id\\>:\\<common_name\\>. Example:\n\"evm:london:1:ethereum\". Overrides the *RPC_CREDENTIALS configuration\nsetting.*\n\n**--include-default ** \nMatch all addresses by default. Addresses may be excluded using\n--excludes-file. If this is set, --input, --output, --exec and\n--includes-file will have no effect.\n\n**--includes-file ***file* \nLoad address include matching rules from file. See **MATCHING\nADDRESSES***.*\n\n**--input ***address* \nAdd an address of interest to inputs (recipients) array. Complements\n**--address-file***.*\n\n**-n ***namespace, ***--namespace ***namespace* \nLoad given configuration namespace. Configuration will be loaded from\nthe immediate configuration subdirectory with the same name.\n\n**--no-logs** \nTurn of logging completely. Negates **-v*** and ***-vv**\n\n**--output ***address* \nAdd an address of interest to outputs (sender) array. Complements\n**--address-file***.*\n\n**-p***, ***--rpc-provider** \nFully-qualified URL of RPC provider. Overrides the *RPC_PROVIDER\nconfiguration setting.*\n\n**--raw** \nProduce output most optimized for machines.\n\n**--renderer ***module* \nAdd output renderer filter to all matched transactions. The argument\nmust be a python module path. Several renderers may be added by\nsupplying the option multiple times. See **RENDERERS*** section of\n***eth-monitor (1)*** for more details.*\n\n**--rpc-dialect** \nRPC backend dialect. If specified it *may help with encoding and\ndecoding issues. Overrides the RPC_DIALECT configuration setting.*\n\n**--store-block-data ** \nStore block data in cache for matching transactions. Requires\n**--cache-dir***.*\n\n**--store-tx-data ** \nStore transaction data in cache for matching transactions. Requires\n**--cache-dir***.*\n\n**-u***, ***--unsafe** \nAllow addresses that do not pass checksum.\n\n**-v** \nVerbose. Show logs for important state changes.\n\n**-vv** \nVery verbose. Show logs with debugging information.\n\n**--x-address ***address* \nAdd an address of interest to match any role.\n\n**--x-exec ***address* \nAdd an address of disinterest to executable address array.\n\n**--x-input ***address* \nAdd an address of disinterest to inputs (recipients) array.\n\n**--x-output ***address* \nAdd an address of disinterest to outputs (sender) array.\n\n# CONFIGURATION\n\nAll configuration settings may be overriden both by environment\nvariables, or by overriding settings with the contents of ini-files in\nthe directory defined by the **-c*** option.*\n\nThe active configuration, with values assigned from environment and\narguments, can be output using the **--dumpconfig*** format option. Note\nthat entries having keys prefixed with underscore (e.g. \\_SEQ) are not\nactual configuration settings, and thus cannot be overridden with\nenvironment variables.*\n\nTo refer to a configuration setting by environment variables, the\n*section and key are concatenated together with an underscore, and\ntransformed to upper-case. For example, the configuration variable\nFOO_BAZ_BAR refers to an ini-file entry as follows:*\n\n [foo]\n bar_baz = xyzzy\n\nIn the **ENVIRONMENT*** section below, the relevant configuration\nsettings for this tool is listed along with a short description of its\nmeaning.*\n\nSome configuration settings may also be overriden by command line\noptions. Also note that the use of the **-n*** and ***--env-prefix***\noptions affect how environment and configuration is read. The effects of\noptions on how configuration settings are affective is described in the\nrespective ***OPTIONS*** section.*\n\n# MATCHING ADDRESSES\n\nBy default, addresses to match against transactions need to be\nexplicitly specified. This behavior can be reversed with the\n**--include-default*** option. Addresses to match are defined using the\n***--input***, ***--output*** and ***--exec*** options. Addresses\nspecified multiple times will be deduplicated.*\n\nInclusion rules may also be loaded from file by specifying the\n**--includes-file*** and ***--excludes-file*** options. Each file must\nspecify the outputs, inputs and exec addresses as comma separated lists\nrespectively, separated by tabs.*\n\nIn the current state of this tool, address matching will affect all\nparts of the processing; cache, code execution and rendering.\n\n# SYNCING\n\nWhen a sync is initiated, the state of this sync is persisted. This way,\nprevious syncs that did not complete for some reason will be resumed\nwhere they left off.\n\nA special sync type **--head*** starts syncing at the current head of\nthe chain, and continue to sync until interrupted. When resuming sync, a\nnew sync range between the current block head and the block height at\nwhich the previous ***--head*** sync left off will automatically be\ncreated.*\n\nSyncs can be forced to (re)run for ranges regardless of previous state\nby using the **--single*** option. However, there is no protection in\nplace from preventing code filters from being executed again on the same\ntransaction when this is done. See ***DEFINING FILTERS*** below.*\n\n# CACHE\n\nWhen syncing, the hash of a block and transaction matching the address\ncriteria will be stored in the cache. The hashes can be used for future\ndata lookups.\n\nIf **--store-block-data*** and/or ***--store-tx-data*** is set, a copy\nof the block and/or transaction data will also be stored, respectively.*\n\n# RENDERING\n\nRendering in the context of **eth-monitor*** refers to a formatted\noutput stream that occurs independently of caching and code execution.*\n\nFilters for rendering may be specified by specifying python modules to\nthe **--renderer*** option. This option may be specified multiple\ntimes.*\n\nRendering filters will be executed in order, and the first filter to\nreturn *False*\n\n# DEFINING FILTERS\n\nA python module used for filter must fulfill two conditions:\n\n> 1\\. It must provide a class named *Filter in the package base\n> namespace.*\n>\n> 2\\. The *Filter class must include a method named filter with the\n> signature def filter(self, conn, block, tx, db_session=None). *\n\nFilters will strictly be executed in the order which they are defined on\nthe command line.\n\n# FURTHER READING\n\nRefer to the **chainsyncer*** chapter n info chaintool for in-depth\ninformation on the subjects of syncing and filtering.*\n\n# ENVIRONMENT\n\n*CHAIN_SPEC* \nString specifying the type of chain connected to, in the format\n*\\<engine\\>:\\<fork\\>:\\<network_id\\>:\\<common_name\\>. For EVM nodes the\nengine value will always be evm.*\n\n*RPC_DIALECT* \nEnables translations of EVM node specific formatting and response codes.\n\n*RPC_PROVIDER* \nFully-qualified URL to the RPC endpoint of the blockchain node.\n\n# LICENSE\n\nThis documentation and its source is licensed under the Creative Commons\nAttribution-Sharealike 4.0 International license.\n\nThe source code of the tool this documentation describes is licensed\nunder the GNU General Public License 3.0.\n\n# COPYRIGHT\n\nLouis Holbrook \\<dev@holbrook.no\\> (https://holbrook.no) PGP:\n59A844A484AC11253D3A3E9DCDCBD24DD1D0E001\n\n# SOURCE CODE\n\nhttps://git.defalsify.org\n",
"bugtrack_url": null,
"license": "AGPLv3+",
"summary": "Monitor and cache transactions using match filters",
"version": "0.8.9",
"project_urls": {
"Homepage": "https://git.defalsify.org/eth-monitor"
},
"split_keywords": [
"dlt",
" blockchain",
" cryptocurrency",
" ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "086602fe1b9deb675de09db89e9cd441162a45ccac987a1d3ce7c433595c1943",
"md5": "b366bf922984cefa2236331a85721092",
"sha256": "465348ec438a04e6a707788c9eba68cd8da42c473d311f1cbf6a47a1a8855e53"
},
"downloads": -1,
"filename": "eth-monitor-0.8.9.tar.gz",
"has_sig": false,
"md5_digest": "b366bf922984cefa2236331a85721092",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43636,
"upload_time": "2024-04-02T11:37:58",
"upload_time_iso_8601": "2024-04-02T11:37:58.320747Z",
"url": "https://files.pythonhosted.org/packages/08/66/02fe1b9deb675de09db89e9cd441162a45ccac987a1d3ce7c433595c1943/eth-monitor-0.8.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 11:37:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "eth-monitor"
}
JSON