github.com/TrueBlocks/trueblocks-core/src/apps/chifra@v0.0.0-20241022031540-b362680128f7/internal/monitors/README.md (about)

     1  ## chifra monitors
     2  
     3  `chifra monitors` has two purposes: (1) to display information about the current set of monitors, and (2)
     4  to `--watch` a set of addresses. The `--watch` function allows one to "follow" an address (or set
     5  of addresses) and keep an off-chain database fresh.
     6  
     7  ### Crud commands
     8  
     9  `chifra list` creates a new monitor. See that tool's help file for more information.
    10  
    11  The `chifra monitors --delete` command deletes (or `--undelete` if already deleted) an address but does not remove it from your hard drive. The monitor is marked as being deleted, making it invisible to other tools.
    12  
    13  Use the `--remove` command to permanently remove a monitor from your computer. This is an
    14  irreversible operation and requires the monitor to have been previously deleted.
    15  
    16  The `--decache` option will remove not only the monitor but all of the cached data associated with
    17  the monitor (for example, transactions or traces). This is an irreversible operation (except
    18  for the fact that the cache can be easily re-created with `chifra list <address>`). The monitor need not have been previously deleted.
    19  
    20  ### Watching addresses
    21  
    22  The `--watch` command is special. It starts a long-running process that continually reads the blockchain looking for appearances of the addresses it is instructed to watch. It command requires two additional parameters: `--watchlist <filename>` and `--commands <filename>`. The `--watchlist` file is simply a list of addresses or ENS names, one per line:
    23  
    24  ```[bash]
    25  0x5e349eca2dc61abcd9dd99ce94d04136151a09ee
    26  trueblocks.eth
    27  0x855b26bc8ebabcdbefe82ee5e9d40d20a1a4c11f
    28  etc.
    29  ```
    30  
    31  You may monitor as many addresses as you wish, however, if the commands you specify take longer than the `--sleep` amount you specify (14 seconds by default), the results are undefined. (Adjust `--sleep` if necessary.)
    32  
    33  The `--commands` file may contain a list of any valid `chifra` command that operates on addresses. (Currently `export`, `list`, `state`, `tokens`.) Each command in the `--commands` file is executed once for each address in the `--watchlist` file. The `--commands` file may contain any number of commands, one per line with the above proviso. For example:
    34  
    35  ```[bash]
    36  chifra list [{ADDRESS}]
    37  chifra export --logs [{ADDRESS}]
    38  etc.
    39  ```
    40  
    41  The `[{ADDRESS}]` token is a stand-in for all addresses in the `--watchlist`. Addresses are processed in groups of `batch_size` (default 8).
    42  
    43  Invalid commands or invalid addresses are ignored. If a command fails, the process continues with the next command. If a command fails for a particular address, the process continues with the next address. A warning is generated.
    44  
    45  ```[plaintext]
    46  Purpose:
    47    Add, remove, clean, and list address monitors.
    48  
    49  Usage:
    50    chifra monitors [flags] <address> [address...]
    51  
    52  Arguments:
    53    addrs - one or more addresses (0x...) to process
    54  
    55  Flags:
    56        --delete             delete a monitor, but do not remove it
    57        --undelete           undelete a previously deleted monitor
    58        --remove             remove a previously deleted monitor
    59    -C, --clean              clean (i.e. remove duplicate appearances) from monitors, optionally clear stage
    60    -l, --list               list monitors in the cache (--verbose for more detail)
    61    -c, --count              show the number of active monitors (included deleted but not removed monitors)
    62    -S, --staged             for --clean, --list, and --count options only, include staged monitors
    63    -w, --watch              continually scan for new blocks and extract data as per the command file
    64    -a, --watchlist string   available with --watch option only, a file containing the addresses to watch
    65    -d, --commands string    available with --watch option only, the file containing the list of commands to apply to each watched address
    66    -b, --batch_size uint    available with --watch option only, the number of monitors to process in each batch (default 8)
    67    -u, --run_count uint     available with --watch option only, run the monitor this many times, then quit
    68    -s, --sleep float        available with --watch option only, the number of seconds to sleep between runs (default 14)
    69    -D, --decache            removes related items from the cache
    70    -x, --fmt string         export format, one of [none|json*|txt|csv]
    71    -v, --verbose            enable verbose output
    72    -h, --help               display this help screen
    73  
    74  Notes:
    75    - An address must be either an ENS name or start with '0x' and be forty-two characters long.
    76    - If no address is presented to the --clean command, all existing monitors will be cleaned.
    77    - The --watch option requires two additional parameters to be specified: --watchlist and --commands.
    78    - Addresses provided on the command line are ignored in --watch mode.
    79    - Providing the value existing to the --watchlist monitors all existing monitor files (see --list).
    80  ```
    81  
    82  Data models produced by this tool:
    83  
    84  - [message](/data-model/other/#message)
    85  - [monitor](/data-model/accounts/#monitor)
    86  - [monitorclean](/data-model/admin/#monitorclean)
    87  
    88  ### Other Options
    89  
    90  All tools accept the following additional flags, although in some cases, they have no meaning.
    91  
    92  ```[plaintext]
    93    -v, --version         display the current version of the tool
    94        --output string   write the results to file 'fn' and return the filename
    95        --append          for --output command only append to instead of replace contents of file
    96        --file string     specify multiple sets of command line options in a file
    97  ```
    98  
    99  **Note:** For the `--file string` option, you may place a series of valid command lines in a file using any
   100  valid flags. In some cases, this may significantly improve performance. A semi-colon at the start
   101  of any line makes it a comment.
   102  
   103  **Note:** If you use `--output --append` option and at the same time the `--file` option, you may not switch
   104  export formats in the command file. For example, a command file with two different commands, one with `--fmt csv`
   105  and the other with `--fmt json` will produce both invalid CSV and invalid JSON.
   106  
   107  *Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.*