eth-monitor-sync.1 (11487B)
1 .TH eth-monitor 1 2 3 .SH NAME 4 eth-monitor \- Cache, index and monitor transactions with an EVM node rpc 5 6 .SH SYNOPSIS 7 .SY eth-monitor 8 [ --skip-history ] [ --single ] [ p \fIeth_provider\fP ] [ --includes-file \fIfile\fP ] [ -i chain_spec ] 9 .YS 10 .SY eth-monitor 11 [ --skip-history ] [ --single ] [ p \fIeth_provider\fP ] [ --excludes-file \fIfile\fP ] [ --include-default ] [ -i chain_spec ] 12 .YS 13 14 15 .SH DESCRIPTION 16 The \fBeth-monitor\fP has fulfills three distinct but related functions: 17 .IP 18 1. A customizable view of on transactions of interest. 19 .IP 20 2. A block and transaction cache. 21 .IP 22 3. Arbitrary code executions using a transaction (and its block) as input. 23 24 .P 25 Using an EVM RPC endpoint, the \fBeth-monitor\fP tool will retrieve blocks within a given range and provides arbitrary processing of each transaction. 26 .P 27 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 \fBSYNCING\fP, \fBMATCHING ADDRESSES\fP and \fBDEFINING FILTERS\fP sections below, respectively. 28 .P 29 Example executions of the tool can be found in the \fBEXAMPLES\fP section. 30 .P 31 32 33 .SS OPTIONS 34 35 .TP 36 \fB-0\fP 37 Omit newline to output 38 39 .TP 40 \fB--address \fI\fIaddress 41 \fP\fP 42 Add an address of interest to match any role. Complements \fB--address-file\fP. 43 44 .TP 45 \fB-c \fI\fIconfig_dir\fP\fP, \fB--config \fI\fIconfig_dir\fP\fP 46 Load configuration files from given directory. All files with an .ini extension will be loaded, of which all must contain valid ini file data. 47 48 .TP 49 \fB--context-key \fI\fIkey=value 50 \fP\fP 51 Add a key-value pair that gets passed to the syncer context. May be specified several times. 52 53 .TP 54 \fB--dumpconfig \fI\fIformat\fP\fP 55 Output configuration settings rendered from environment and inputs. Valid arguments are \fIini\fP for ini file output, and \fIenv\fP for environment variable output. See \fBCONFIGURATION\fP. 56 57 .TP 58 \fB--env-prefix\fP 59 Environment prefix for variables to overwrite configuration. Example: If \fB--env-prefix\fP is set to \fBFOO\fP then configuration variable \fBBAR_BAZ\fP would be set by environment variable \fBFOO_BAZ_BAR\fP. Also see \fBENVIRONMENT\fP. 60 61 .TP 62 \fB--excludes-file \fI\fIfile 63 \fP\fP 64 Load address exclude matching rules from file. See \fBMATCHING ADDRESSES\fP. 65 66 .TP 67 \fB--exec \fI\fIaddress 68 \fP\fP 69 Add an address of interest to executable address array. Complements \fB--address-file\fP. 70 71 .TP 72 \fB--filter \fI\fImodule 73 \fP\fP 74 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 \fBDEFINING FILTERS\fP section of \fBeth-monitor (1)\fP for more details. 75 76 .TP 77 \fB--height\fP 78 Block height at which to query state for. Does not apply to transactions. 79 80 .TP 81 \fB-i \fI\fIchain_spec\fP\fP, \fB--chain-spec \fI\fIchain_spec\fP\fP 82 Chain specification string, in the format <engine>:<fork>:<chain_id>:<common_name>. Example: "evm:london:1:ethereum". Overrides the \fIRPC_CREDENTIALS\fP configuration setting. 83 84 .TP 85 \fB--include-default \fI\fI 86 \fP\fP 87 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. 88 89 .TP 90 \fB--includes-file \fI\fIfile 91 \fP\fP 92 Load address include matching rules from file. See \fBMATCHING ADDRESSES\fP. 93 94 .TP 95 \fB--input \fI\fIaddress 96 \fP\fP 97 Add an address of interest to inputs (recipients) array. Complements \fB--address-file\fP. 98 99 .TP 100 \fB-n \fI\fInamespace\fP\fP, \fB--namespace \fI\fInamespace\fP\fP 101 Load given configuration namespace. Configuration will be loaded from the immediate configuration subdirectory with the same name. 102 103 .TP 104 \fB--no-logs\fP 105 Turn of logging completely. Negates \fB-v\fP and \fB-vv\fP 106 107 .TP 108 \fB--output \fI\fIaddress 109 \fP\fP 110 Add an address of interest to outputs (sender) array. Complements \fB--address-file\fP. 111 112 .TP 113 \fB-p\fP, \fB--rpc-provider\fP 114 Fully-qualified URL of RPC provider. Overrides the \fIRPC_PROVIDER\fP configuration setting. 115 116 .TP 117 \fB--raw\fP 118 Produce output most optimized for machines. 119 120 .TP 121 \fB--renderer \fI\fImodule 122 \fP\fP 123 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 \fBRENDERERS\fP section of \fBeth-monitor (1)\fP for more details. 124 125 .TP 126 \fB--rpc-batch-limit\fP 127 Set number of RPC requests that can be set to the RPC provider as a batch request. This is made available through settings to any request builder implementing batch requests. A value of 1 means no batch will be used. A value of 0 indicates that the limit is not relevant. Any other positive value signals the maximum number of requests to be batched together. Overrides the \fIRPC_BATCH_LIMIT\fP configuration setting. 128 129 .TP 130 \fB--rpc-dialect\fP 131 RPC backend dialect. If specified it \fImay\fP help with encoding and decoding issues. Overrides the \fIRPC_DIALECT\fP configuration setting. 132 133 .TP 134 \fB--store-block-data \fI\fI 135 \fP\fP 136 Store block data in cache for matching transactions. Requires \fB--cache-dir\fP. 137 138 .TP 139 \fB--store-tx-data \fI\fI 140 \fP\fP 141 Store transaction data in cache for matching transactions. Requires \fB--cache-dir\fP. 142 143 .TP 144 \fB--txhash \fI\fIhash 145 \fP\fP 146 Add a tx hash of interest to match 147 148 .TP 149 \fB-u\fP, \fB--unsafe\fP 150 Allow addresses that do not pass checksum. 151 152 .TP 153 \fB-v\fP 154 Verbose. Show logs for important state changes. 155 156 .TP 157 \fB-vv\fP 158 Very verbose. Show logs with debugging information. 159 160 .TP 161 \fB--x-address \fI\fIaddress 162 \fP\fP 163 Add an address of interest to match any role. 164 165 .TP 166 \fB--x-exec \fI\fIaddress 167 \fP\fP 168 Add an address of disinterest to executable address array. 169 170 .TP 171 \fB--x-input \fI\fIaddress 172 \fP\fP 173 Add an address of disinterest to inputs (recipients) array. 174 175 .TP 176 \fB--x-output \fI\fIaddress 177 \fP\fP 178 Add an address of disinterest to outputs (sender) array. 179 180 .TP 181 \fB--x-txhash \fI\fIhash 182 \fP\fP 183 Add a tx hash of disinterest to match 184 185 .SH CONFIGURATION 186 187 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 \fB-c\fP option. 188 189 The active configuration, with values assigned from environment and arguments, can be output using the \fB--dumpconfig\fP \fIformat\fP 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. 190 191 To refer to a configuration setting by environment variables, the \fIsection\fP and \fIkey\fP are concatenated together with an underscore, and transformed to upper-case. For example, the configuration variable \fIFOO_BAZ_BAR\fP refers to an ini-file entry as follows: 192 193 .EX 194 [foo] 195 bar_baz = xyzzy 196 .EE 197 198 In the \fBENVIRONMENT\fP section below, the relevant configuration settings for this tool is listed along with a short description of its meaning. 199 200 Some configuration settings may also be overriden by command line options. Also note that the use of the \fB-n\fP and \fB--env-prefix\fP options affect how environment and configuration is read. The effects of options on how configuration settings are affective is described in the respective \fBOPTIONS\fP section. 201 202 .SH MATCHING ADDRESSES 203 By default, addresses to match against transactions need to be explicitly specified. This behavior can be reversed with the \fB--include-default\fP option. Addresses to match are defined using the \fB--input\fP, \fB--output\fP and \fB--exec\fP options. Addresses specified multiple times will be deduplicated. 204 .P 205 Inclusion rules may also be loaded from file by specifying the \fB--includes-file\fP and \fB--excludes-file\fP options. Each file must specify the outputs, inputs and exec addresses as comma separated lists respectively, separated by tabs. 206 .P 207 In the current state of this tool, address matching will affect all parts of the processing; cache, code execution and rendering. 208 209 .SH SYNCING 210 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. 211 .P 212 A special sync type \fB--head\fP 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 \fB--head\fP sync left off will automatically be created. 213 .P 214 Syncs can be forced to (re)run for ranges regardless of previous state by using the \fB--single\fP 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 \fBDEFINING FILTERS\fP below. 215 216 217 .SH CACHE 218 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. 219 .P 220 If \fB--store-block-data\fP and/or \fB--store-tx-data\fP is set, a copy of the block and/or transaction data will also be stored, respectively. 221 222 223 .SH RENDERING 224 Rendering in the context of \fBeth-monitor\fP refers to a formatted output stream that occurs independently of caching and code execution. 225 .P 226 Filters for rendering may be specified by specifying python modules to the \fB--renderer\fP option. This option may be specified multiple times. 227 .P 228 Rendering filters will be executed in order, and the first filter to return \fIFalse\fP 229 230 231 .SH DEFINING FILTERS 232 233 Filters will strictly be executed in the order which they are defined on the command line. 234 235 A python module used for filter must fulfill two conditions: 236 237 .IP 238 1. It must provide a class named \fIFilter\fP in the package base namespace. 239 .IP 240 2. The \fIFilter\fP class must extend the \fIchainsyncer.filter.SyncFilter\fP interface, and at least override the \fIfilter\fP method. 241 242 243 .SS SYNCER AND FILTER CONTEXT 244 245 Key-value pairs specified with `--context-key` will be passed to the filter's \fIprepare\fP method, aswell as the \fIctx\fP parameter of the \fIfilter\fP method. 246 247 248 .SH FURTHER READING 249 250 Refer to the \fBchainsyncer\fP chapter n \fIinfo chaintool\fP for in-depth information on the subjects of syncing and filtering. 251 .SH ENVIRONMENT 252 253 254 .TP 255 \fICHAIN_SPEC\fP 256 String specifying the type of chain connected to, in the format \fI<engine>:<fork>:<network_id>:<common_name>\fP. For EVM nodes the \fIengine\fP value will always be \fIevm\fP. 257 258 .TP 259 \fIRPC_BATCH_LIMIT\fP 260 Set number of RPC requests that can be set to the RPC provider as a batch request. This is made available through settings to any request builder implementing batch requests. A value of 1 means no batch will be used. A value of 0 indicates that the limit is not relevant. Any other positive value signals the maximum number of requests to be batched together. 261 262 .TP 263 \fIRPC_DIALECT\fP 264 Enables translations of EVM node specific formatting and response codes. 265 266 .TP 267 \fIRPC_PROVIDER\fP 268 Fully-qualified URL to the RPC endpoint of the blockchain node. 269 270 .SH LICENSE 271 272 This documentation and its source is licensed under the Creative Commons Attribution-Sharealike 4.0 International license. 273 274 The source code of the tool this documentation describes is licensed under the GNU General Public License 3.0. 275 276 .SH COPYRIGHT 277 278 Louis Holbrook <dev@holbrook.no> (https://holbrook.no) 279 PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001 280 281 282 283 .SH SOURCE CODE 284 285 https://git.defalsify.org 286