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

     1  // Copyright 2016, 2024 The TrueBlocks Authors. All rights reserved.
     2  // Use of this source code is governed by a license that can
     3  // be found in the LICENSE file.
     4  /*
     5   * Parts of this file were auto generated. Edit only those parts of
     6   * the code inside of 'EXISTING_CODE' tags.
     7   */
     8  
     9  // monitorsPkg implements the chifra monitors command.
    10  //
    11  // chifra monitors has two purposes: (1) to display information about the current set of monitors, and (2)
    12  // to --watch a set of addresses. The --watch function allows one to "follow" an address (or set
    13  // of addresses) and keep an off-chain database fresh.
    14  //
    15  // ### Crud commands
    16  //
    17  // chifra list creates a new monitor. See that tool's help file for more information.
    18  //
    19  // 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.
    20  //
    21  // Use the --remove command to permanently remove a monitor from your computer. This is an
    22  // irreversible operation and requires the monitor to have been previously deleted.
    23  //
    24  // The --decache option will remove not only the monitor but all of the cached data associated with
    25  // the monitor (for example, transactions or traces). This is an irreversible operation (except
    26  // for the fact that the cache can be easily re-created with chifra list <address>). The monitor need not have been previously deleted.
    27  //
    28  // ### Watching addresses
    29  //
    30  // 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:
    31  //
    32  // [bash]
    33  // 0x5e349eca2dc61abcd9dd99ce94d04136151a09ee
    34  // trueblocks.eth
    35  // 0x855b26bc8ebabcdbefe82ee5e9d40d20a1a4c11f
    36  // etc.
    37  //
    38  // 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.)
    39  //
    40  // 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:
    41  //
    42  // [bash]
    43  // chifra list [{ADDRESS}]
    44  // chifra export --logs [{ADDRESS}]
    45  // etc.
    46  //
    47  // The [{ADDRESS}] token is a stand-in for all addresses in the --watchlist. Addresses are processed in groups of batch_size (default 8).
    48  //
    49  // 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.
    50  package monitorsPkg