Local Fusion

This package contains the tooling required to execute a Notifi fusion source locally on a developer machine, or via the Notifi dev container environments.

Usage

Note: The npx command is temporarily broken so you will need to install ts-node in the parser sources packahe and run the command with

node --loader ts-node/esm <node_modules_directory>/@notifi-network/local-fusion/dist/cli/bin.js <commands> [options]

The package exposes a CLI tool that can be used to execute a fusion source locally. The tool can be invoked with the following command:

npx local-fusion-cli <command> [options]

The following commands are available:

1. 'EVM' - Executes a fusion source in the EVM environment

EVM

The EVM command is used to execute an EVM fusion source locally. The command can be invoked with the following command:

npx local-fusion-cli EVM [options]

| Option | Description | Type | Default | Required | | ------------------ | --------------------------------------------------- | ------- | ------------------------------------------- | -------- | | rpcUrl | EVM RPC URL (Websocket or HTTP) | string | N/A | true* | | blockchainType | Blockchain Type | number | N/A | true* | | parserFilePath | Absolute path to parser file (relative or absolute) | string | './src/parser.ts' | false | | parserConfigPath | File path to fusion parser config | string | N/A | false | | bcmUrl | Blockchain manager URL | string | N/A | false | | ephemeralUrl | Ephemeral storage URL | string | N/A | false | | persistentUrl | Persistent storage URL | string | N/A | false | | logOutput | Log output from parser | boolean | true | false | | blockTag | Block number or tag to execute parser at | number | 'latest' | false | | filter | Fusion filter to trigger parser execution | string | '{"contractAddresses":[],"topicHashes":[]}' | false |

Note: The rpcUrl and blockchainType options can be omitted, but only if the parserConfigPath option is provided. If the parserConfigPath option is provided, the fusion parser config will be used to determine the rpcUrl, blockchainType and other options. If the parserConfigPath option is not provided, the rpcUrl and blockchainType options must be provided.

Filter Types

At the heart of fusion lies a scheduling mechanism which detects when a parser should be executed. This is done by defining a filter which is used to determine whether a parser should be triggered by some on-chain event or not. The filter is defined as a string and is parsed by the fusion scheduler. The following filter types are supported:

| Filter Type | Type Definition | Description | Default | | ----------------- | ------------------------------------------------------ | -------------------------- | ----------------------------------------- | | EvmFusionFilter | {contractAddresses: string[], topicHashes: string[]} | TODO: Add description here | {contractAddresses: [],topicHashes: []} |

Supported Blockchains

Note:: Within fusion we refer to different Blockchains by their enum value in the BlockchainType enum. This list is subject to change as we add support for more blockchains, please verify by looking at the source code for the BlockchainType enum inside the @notifi-network/fusion-types package and the source code within this repo.

Below is a table of the support status for each supported blockchain, alongside their enums and the FilterType that is used to trigger parser execution.

| Blockchain Name | BlockchainType | FilterType | Status | | --------------- | -------------- | ----------------- | ----------- | | Ethereum | 3 | EvmFusionFilter | In Progress | | Polygon | 5 | EvmFusionFilter | In Progress | | Arbitrum | 6 | EvmFusionFilter | In Progress | | Bnb | 7 | EvmFusionFilter | In Progress | | Avalanche | 10 | EvmFusionFilter | In Progress | | Optimism | 12 | EvmFusionFilter | In Progress | | ZkSync | 16 | EvmFusionFilter | In Progress |

Additional Exports

Aside from exposing the CLI tool, this package also exports the lib directory which contains various helper functions, and the LocalEvmHost class which can be used to execute a fusion source locally in the EVM environment.

TODO's

• [ ] Fix the npx command
• [ ] Add better support for subscriptions: users should be able to provide a list of subscribed addresses AND/OR a real endpoint which serves the subscriptions.
• [ ] Add a real storage layer to the local host environment - we can stub out calls to our admin GraphQL endpoints rather than using the real Storage interfaces.
• [ ] Add support for other blockchains (incl. FilterTypes, host environments, etc.)