Reef Explorer squid

Substrate processor, including support for EVM events. Built upon squid Frontier EVM template and adapted to be used with Reef network.

Quickstart

# 1. Install dependencies
npm install

# 2. Compile typescript files
make build

# 3. Start target Postgres database and detach
#    DB will be available at localhost:23799/evm_events
make up

# 4. Start the processor
make process

# 5. In a separate terminal, start graphql server
#    GraphQL API will be available at http://localhost:4350/graphql
make serve

# 6. Stop and destroy target Postgres database
make down

Dev flow

1. Define database schema

Delete migration files from db/migrations directory and define the schema of the target database via schema.graphql file, replacing the sample definition. Schema definition consists of regular graphql type declarations annotated with custom directives. Full description of schema.graphql dialect is available here.

2. Generate TypeORM classes

Mapping developers use TypeORM EntityManager to interact with target database during data processing. All necessary entity classes are generated by the squid framework from schema.graphql. This is done by running the following command:

make codegen

3. Import ABI contract and generate interfaces to decode events

It is necessary to import the respective ABI definition to decode EVM logs.

Delete all the contents in src/abi and insert the JSON ABI definition of the contract to index.

To generate a type-safe facade class to decode EVM logs execute the following command:

npx squid-evm-typegen src/abi src/abi/{YOUR_CONTRACT_NAME}.json

And replace the following code in generated the generated abi.support.ts file:

let result = await this._chain.client.call('eth_call', [
      { to: this.address, data },
      '0x' + this.blockHeight.toString(16)
])

by

let result = await this._chain.client.call('evm_call', [
      {to: this.address, data, from: undefined, storageLimit: 0}
])

Project conventions

Squid tools assume a certain project layout.

• All compiled js files must reside in lib and all TypeScript sources in src. The layout of lib must reflect src.
• All TypeORM classes must be exported by src/model/index.ts (lib/model module).
• Database schema must be defined in schema.graphql.
• Database migrations must reside in db/migrations and must be plain js files.
• sqd(1) and squid-*(1) executables consult .env file for a number of environment variables.

Graphql server extensions

It is possible to extend squid-graphql-server(1) with custom type-graphql resolvers and to add request validation. More details will be added later.

Deployment

Deploy a Squid

• To deploy a Squid execute sqd deploy -m <path_to_manifest_file>.
• By default, when a Squid is deployed, the processor performs an update of all accounts and token holders when head block is reached. This is shortens the indexing time for new Squids. However, if we are redeploying an existing Squid, we can disable this behavior setting the environment variable HEAD_REACHED=true.

Import verified contracts

The data related with verified contract comes from an off-chain source, so when a new Squid is deployed this data has to be imported.

The ReefScan API stores all the verified contracts and provides an end point to update the data related with verified contracts in the prod version of Reef Explorer Squid. This end point is protected by a password and is meant to be called after a new Squid has been deployed and the head block has been reached.

URL : <reefscan_api_base_url>/verification/verify-from-backup

Method : POST

Request body: { password: <admin_pass> }