cerc-io/watcher-ts
16
1
Fork 0
mirror of https://github.com/cerc-io/watcher-ts synced 2024-11-19 20:36:19 +00:00
Code Issues Packages Projects Releases Wiki Activity
62521d7ccc
watcher-ts/packages/codegen/README.md
prathamesh0 a846917f1d Export-import watcher state and IPFS integration (#289) 
* Add export-watcher CLI generation

* Export snapshot block and add import-watcher CLI gen

* Update codegen docs with export and import commands

* Use different function to get latest checkpoint in export CLI

* Update generated watcher docs with import state instructions

* Push IPLDBlocks to IPFS

* Change ts type for data column to Buffer

* Add checkpoint hook

* Push CLI checkpoint to IPFS

* Fix latest IPLDBlock query to filter out irrelevant blocks

* Add CLI to inspect a CID

* Decode data before exporting

* Encode data in JSON for getState GQL API

* Use go-ipfs and export cbor-encoded buffer

* Remove empty post-block methods from existing watchers

* Call hooks and checkpoint job complete handlers in fill

* Remove subscription to hooks queue from existing watchers
2021-12-28 16:08:04 +05:30

5.2 KiB
Raw Blame History

Code Generator

Setup

  • In root of the repository:

    • Install required packages:

      yarn

    • Build files:

      yarn build

Run

  • Run the following command to generate a watcher from a contract file:

    yarn codegen --input-file <input-file-path> --contract-name <contract-name> --output-folder [output-folder] --mode [eth_call | storage | all] --flatten [true | false] --kind [lazy | active] --port [server-port]
    • input-file(alias: i): Input contract file path or an URL (required).
    • contract-name(alias: c): Main contract name (required).
    • output-folder(alias: o): Output folder path. (logs output using stdout if not provided).
    • mode(alias: m): Code generation mode (default: all).
    • flatten(alias: f): Flatten the input contract file (default: true).
    • kind (alias: k): Kind of watcher (default: active).
    • port (alias: p): Server port (default: 3008).

    Note: When passed an URL as input-file, it is assumed that it points to an already flattened contract file.

    Examples:

    Generate code in storage mode, lazy kind.

    yarn codegen --input-file ./test/examples/contracts/ERC721.sol --contract-name ERC721 --output-folder ../my-erc721-watcher --mode storage --kind lazy

    Generate code in eth_call mode using a contract provided by an URL.

    yarn codegen --input-file https://git.io/Jupci --contract-name ERC721 --output-folder ../my-erc721-watcher --mode eth_call

    Generate code for ERC721 in both eth_call and storage mode, active kind.

    yarn codegen --input-file ../../node_modules/@openzeppelin/contracts/token/ERC721/ERC721.sol --contract-name ERC721 --output-folder ../demo-erc721-watcher --mode all --kind active

    Generate code for ERC20 contract in both eth_call and storage mode, active kind:

    yarn codegen --input-file ../../node_modules/@openzeppelin/contracts/token/ERC20/ERC20.sol --contract-name ERC20 --output-folder ../demo-erc20-watcher --mode all --kind active

    This will create a folder called demo-erc20-watcher containing the generated code at the specified path. Follow the steps in Run Generated Watcher to setup and run the generated watcher.

Run Generated Watcher

Setup

  • Run the following command to install required packages:

    yarn

  • Run the IPFS (go-ipfs version 0.9.0) daemon:

    ipfs daemon

  • Create the databases configured in environments/local.toml.

  • Update the state checkpoint settings in environments/local.toml.

  • Update the IPFS API address in environments/local.toml.

Customize

  • Indexing on an event:

    • Edit the custom hook function handleEvent (triggered on an event) in src/hooks.ts to perform corresponding indexing using the Indexer object.

    • While using the indexer storage methods for indexing, pass diff as true if default state is desired to be generated using the state variables being indexed.

  • Generating state:

    • Edit the custom hook function createInitialCheckpoint (triggered on watch-contract, checkpoint: true) in src/hooks.ts to save an initial checkpoint IPLDBlock using the Indexer object.

    • Edit the custom hook function createStateDiff (triggered on a block) in src/hooks.ts to save the state in a diff IPLDBlock using the Indexer object. The default state (if exists) is updated.

    • Edit the custom hook function createStateCheckpoint (triggered just before default and CLI checkpoint) in src/hooks.ts to save the state in a checkpoint IPLDBlock using the Indexer object.

  • The existing example hooks in src/hooks.ts are for an ERC20 contract.

Run

  • Run lint:

    yarn lint

  • Run the watcher:

    yarn server

  • If the watcher is an active watcher:

    • Run the job-runner:

      yarn job-runner

    • To watch a contract:

      yarn watch:contract --address <contract-address> --kind <contract-kind> --checkpoint <true | false> --starting-block [block-number]

    • To fill a block range:

      yarn fill --start-block <from-block> --end-block <to-block>

    • To create a checkpoint for a contract:

      yarn checkpoint --address <contract-address> --block-hash [block-hash]

    • To reset the watcher to a previous block number:

      • Reset state:

        yarn reset state --block-number <previous-block-number>

      • Reset job-queue:

        yarn reset job-queue --block-number <previous-block-number>

    • To export the watcher state:

      yarn export-state --export-file [export-file-path]

    • To import the watcher state:

      yarn import-state --import-file <import-file-path>

    • To inspect a CID:

      yarn inspect-cid --cid <cid>

Known Issues

  • Currently, node-fetch v2.6.2 is being used to fetch from URLs as v3.0.0 is an ESM-only module and ts-node transpiles to import it using require.