From e34bab919886f1175330b572d8ce4f21e55a295e Mon Sep 17 00:00:00 2001 From: James Bayly Date: Fri, 13 Oct 2023 13:55:42 +0800 Subject: [PATCH] Update Astar WASM Docs --- docs/build/substrate-evm.md | 191 +++++++++++------- docs/build/substrate-wasm.md | 108 ++++++---- .../quickstart_chains/polkadot-astar.md | 161 +++++++++------ 3 files changed, 280 insertions(+), 180 deletions(-) diff --git a/docs/build/substrate-evm.md b/docs/build/substrate-evm.md index 2d9e56e2703..92c6db602f3 100644 --- a/docs/build/substrate-evm.md +++ b/docs/build/substrate-evm.md @@ -4,18 +4,15 @@ We provide a custom data source processor for [Parity's Frontier EVM](https://gi **Tested and Supported networks** -| Network Name | Websocket Endpoint | Dictionary Endpoint | -| -------------- | -------------------------------------------------- | ----------------------------------------------------------------------- | -| Moonbeam | `wss://moonbeam.api.onfinality.io/public-ws` | `https://api.subquery.network/sq/subquery/moonbeam-dictionary` | -| Moonriver | `wss://moonriver.api.onfinality.io/public-ws` | `https://api.subquery.network/sq/subquery/moonriver-dictionary` | -| Moonbase Alpha | `wss://moonbeam-alpha.api.onfinality.io/public-ws` | `https://api.subquery.network/sq/subquery/moonbase-alpha-dictionary` | -| Astar | `wss://astar.api.onfinality.io/public-ws` | `https://explorer.subquery.network/subquery/subquery/astar-dictionary` | -| Shiden | `wss://shiden.api.onfinality.io/public-ws` | `https://explorer.subquery.network/subquery/subquery/shiden-dictionary` | -| Acala | `wss://acala-polkadot.api.onfinality.io/public-ws` | `https://explorer.subquery.network/subquery/subquery/acala-dictionary` | -| Karura | `wss://karura.api.onfinality.io/public-ws` | `https://explorer.subquery.network/subquery/subquery/karura-dictionary` | - -Theoretically the following networks should also be supported since they implement Parity's Frontier EVM. Please let us know if you verify this and we can add them to the known support: - +Theoretically all the following networks (and more) should also be supported since they implement Parity's Frontier EVM. Please let us know if you verify this and we can add them to the known support: + +- Moonbeam +- Moonriver +- Moonbase Alpha +- Acala +- Karura +- Astar +- Shiden - Automata - Bitcountry - Clover @@ -41,7 +38,7 @@ Theoretically the following networks should also be supported since they impleme 1. Add the custom datasource as a dependency: - Create a new project from an EVM template though `subql init` OR -- For existing projects, `yarn add @subql/frontier-evm-processor` or `npm i @subql/acala-evm-processor`. +- For existing projects, `yarn add -D @subql/frontier-evm-processor` or `npm i @subql/acala-evm-processor --save-dev`. 2. Add exports to your `package.json` like below in order for IPFS deployments to work @@ -54,6 +51,32 @@ Theoretically the following networks should also be supported since they impleme } ``` +3. Import processor file to your `project.ts` like below + +```ts +import { FrontierEvmDatasource } from "@subql/frontier-evm-processor"; + +const project: SubstrateProject = { + ... + dataSources: [ + { + // This is the datasource for Moonbeam's Native Substrate processor + kind: "substrate/FrontierEvm", + startBlock: 752073, + processor: { + file: "./node_modules/@subql/frontier-evm-processor/dist/bundle.js", + options: { + abi: "erc20", + address: "0xe3e43888fa7803cdc7bea478ab327cf1a0dc11a7", // FLARE token https://moonscan.io/token/0xe3e43888fa7803cdc7bea478ab327cf1a0dc11a7 + }, + }, + assets: new Map([["erc20", { file: "./abis/erc20.abi.json" }]]), + mapping: {...}, + }, + ], +} +``` + 3. Add a custom data source as described below. 4. Add handlers for the custom data source to your code. @@ -240,74 +263,88 @@ This is an extract from the `project.ts` manifest file. ::: code-tabs @tab Frontier EVM -```yaml -dataSources: - - kind: substrate/FrontierEvm - startBlock: 752073 - processor: - file: "./node_modules/@subql/frontier-evm-processor/dist/bundle.js" - options: - # Must be a key of assets - abi: erc20 - # Contract address (or recipient if transfer) to filter, if `null` should be for contract creation - address: "0x6bd193ee6d2104f14f94e2ca6efefae561a4334b" - assets: - erc20: - file: ./erc20.abi.json - mapping: - file: ./dist/index.js - handlers: - - handler: handleFrontierEvmEvent - kind: substrate/FrontierEvmEvent - filter: - topics: - - "Transfer(address indexed from,address indexed to,uint256 value)" - - null - - null - - null - - handler: handleFrontierEvmCall - kind: substrate/FrontierEvmCall - filter: - ## The function can either be the function fragment or signature - # function: '0x095ea7b3' - # function: '0x7ff36ab500000000000000000000000000000000000000000000000000000000' - # function: approve(address,uint256) - function: "approve(address to,uint256 value)" +```ts +{ + dataSources: [ + { + // This is the datasource for Moonbeam's Native Substrate processor + kind: "substrate/FrontierEvm", + startBlock: 752073, + processor: { + file: "./node_modules/@subql/frontier-evm-processor/dist/bundle.js", + options: { + abi: "erc20", + address: "0xe3e43888fa7803cdc7bea478ab327cf1a0dc11a7", // FLARE token https://moonscan.io/token/0xe3e43888fa7803cdc7bea478ab327cf1a0dc11a7 + }, + }, + assets: new Map([["erc20", { file: "./erc20.abi.json" }]]), + mapping: { + file: "./dist/index.js", + handlers: [ + { + handler: "handleEvmEvent", + kind: "substrate/FrontierEvmEvent", + filter: { + topics: [ + "Transfer(address indexed from,address indexed to,uint256 value)", + ], + }, + }, + { + handler: "handleEvmCall", + kind: "substrate/FrontierEvmCall", + filter: { + function: "approve(address to,uint256 value)", + }, + }, + ], + }, + }, + ], +} ``` @tab Acala EVM+ -```yaml -dataSources: - - kind: substrate/AcalaEvm - startBlock: 752073 - processor: - file: "./node_modules/@subql/contract-processors/dist/acalaEvm.js" - options: - # Must be a key of assets - abi: erc20 - # Contract address (or recipient if transfer) to filter, if `null` should be for contract creation - address: "0x6bd193ee6d2104f14f94e2ca6efefae561a4334b" - assets: - erc20: - file: "./erc20.abi.json" - mapping: - file: "./dist/index.js" - handlers: - - handler: handleAcalaEvmEvent - kind: substrate/AcalaEvmEvent - filter: - topics: - - Transfer(address indexed from,address indexed to,uint256 value) - - handler: handleAcalaEvmCall - kind: substrate/AcalaEvmCall - filter: - ## The function can either be the function fragment or signature - # function: '0x095ea7b3' - # function: '0x7ff36ab500000000000000000000000000000000000000000000000000000000' - # function: approve(address,uint256) - function: approve(address to,uint256 value) - from: "0x6bd193ee6d2104f14f94e2ca6efefae561a4334b" +```ts +{ + dataSources: [ + { + // This is the datasource for Acala's EVM processor + kind: "substrate/AcalaEvm", + startBlock: 1000000, + processor: { + file: "./node_modules/@subql/acala-evm-processor/dist/bundle.js", + options: { + abi: "erc20", + address: "0x0000000000000000000100000000000000000000", // ACA Token https://blockscout.acala.network/address/0x0000000000000000000100000000000000000000 + }, + }, + assets: new Map([["erc20", { file: "./erc20.abi.json" }]]), + mapping: { + file: "./dist/index.js", + handlers: [ + { + handler: "handleAcalaEvmEvent", + kind: "substrate/AcalaEvmEvent", + filter: { + topics: [ + "Transfer(address indexed from,address indexed to,uint256 value)", + ], + }, + }, + { + handler: "handleAcalaEvmCall", + kind: "substrate/AcalaEvmCall", + filter: { + function: "approve(address to,uint256 value)", + }, + }, + ], + }, + }, + ], +} ``` ::: diff --git a/docs/build/substrate-wasm.md b/docs/build/substrate-wasm.md index 31e5000fdbb..617af6322b7 100644 --- a/docs/build/substrate-wasm.md +++ b/docs/build/substrate-wasm.md @@ -6,29 +6,35 @@ We provide a custom data source processor for [Substrate WASM contract](https:// There is a [friendly quick start guide that introduces SubQuery's Substrate WASM support by using an example project in Astar Network](../quickstart/quickstart_chains/polkadot-astar.md). This guide covers most of the topics shown in the following guide in a format more easy to understand. You can return here when you need specific technical support for the Substrate WASM data source processor. ::: -**Tested and Supported networks** - -| Network Name | Websocket Endpoint | Dictionary Endpoint | -| ------------ | -------------------------------------------- | -------------------------------------------------------------- | -| Astar | Coming soon | Coming soon | -| Shiden | `wss://shiden.api.onfinality.io/public-ws` | `https://api.subquery.network/sq/subquery/shiden-dictionary` | -| Shibuya | | `https://api.subquery.network/sq/subquery/shibuya-dictionary` | -| Edgeware | `wss://edgeware.api.onfinality.io/public-ws` | `https://api.subquery.network/sq/subquery/edgeware-dictionary` | - -**You can also refer to the basic [Substrate WASM](https://github.com/subquery/subql-starter/tree/main/Astar/astar-evm-starter) example projects with an event and call handler.** This project is also hosted live in the SubQuery Explorer [here](https://explorer.subquery.network/subquery/subquery/tutorial-substrate-wasm-starter). +**You can also refer to the basic [Substrate WASM](../quickstart/quickstart_chains/polkadot-astar.md) example projects with an event and call handler.** This project is also hosted live in the SubQuery Explorer [here](https://explorer.subquery.network/subquery/subquery/tutorial-substrate-wasm-starter). ## Getting started -1. Add the custom datasource as a dependency. Create a new project from an WASM starter template though `subql init` OR for existing projects, `yarn add @subql/substrate-wasm-processor`. +1. Add the custom datasource as a dependency. Create a new project from an WASM starter template though `subql init` OR for existing projects, `yarn add -D @subql/substrate-wasm-processor`. 2. Import processor file to your `project.ts` like below -```yaml +```ts +import { WasmDatasource } from "@subql/substrate-wasm-processor"; + +const project: SubstrateProject = { ... - dataSources: - - kind: substrate/Wasm - startBlock: 970733 - processor: - file: ./node_modules/@subql/substrate-wasm-processor/dist/bundle.js + dataSources: [ + { + // This is the datasource for Astar's Wasm processor + kind: "substrate/Wasm", + startBlock: 3281780, + processor: { + file: "./node_modules/@subql/substrate-wasm-processor/dist/bundle.js", + options: { + abi: "erc20", + contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc", // Mainnet, + }, + }, + assets: new Map([["erc20", { file: "./abis/erc20Metadata.abi.json" }]]), + mapping: {...}, + }, + ], +} ``` 3. Add a custom data source as described below. @@ -172,32 +178,48 @@ export async function handleSubstrateWasmEvent( This is an extract from the `project.ts` manifest file. -```yaml -dataSources: - - kind: substrate/Wasm - startBlock: 970733 - processor: - file: ./node_modules/@subql/substrate-wasm-processor/dist/bundle.js - options: - abi: erc20 - contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" - assets: - erc20: - file: ./erc20Metadata.json - mapping: - file: ./dist/index.js - handlers: - - handler: handleSubstrateWasmEvent - kind: substrate/WasmEvent - filter: - # from: 'xxxx' - contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" - identifier: "Transfer" - - handler: handleSubstrateCall - kind: substrate/WasmCall - filter: - selector: "0x681266a0" - method: "approve" +```ts +{ + dataSources: [ + { + // This is the datasource for Astar's Native Substrate processor + kind: "substrate/Wasm", + // This is the datasource for Astar's Wasm processor + startBlock: 3281780, + processor: { + file: "./node_modules/@subql/substrate-wasm-processor/dist/bundle.js", + options: { + abi: "erc20", + // contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" // Shibuya + contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc", // Mainnet, + }, + }, + assets: new Map([["erc20", { file: "./abis/erc20Metadata.abi.json" }]]), + mapping: { + file: "./dist/index.js", + handlers: [ + { + handler: "handleWasmEvent", + kind: "substrate/WasmEvent", + filter: { + // contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" // Shibuya + contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc", // Mainnet + identifier: "Transfer", + }, + }, + { + handler: "handleWasmCall", + kind: "substrate/WasmEvent", + filter: { + selector: "0x681266a0", + method: "approve", + }, + }, + ], + }, + }, + ], +} ``` ## Querying contracts diff --git a/docs/quickstart/quickstart_chains/polkadot-astar.md b/docs/quickstart/quickstart_chains/polkadot-astar.md index 86c60be98fd..c772d97956a 100644 --- a/docs/quickstart/quickstart_chains/polkadot-astar.md +++ b/docs/quickstart/quickstart_chains/polkadot-astar.md @@ -4,6 +4,12 @@ This quick start guide introduces SubQuery's Substrate WASM support by using an example project in Astar Network. The example project indexes all Transactions and Approvals from the [Astar Wasm based lottery contract](https://astar.subscan.io/account/bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc), as well as dApp staking events from [Astar's dApp Staking](https://docs.astar.network/docs/dapp-staking/) functions. +::: tip Note + +The final code of this project can be found [here](https://github.com/subquery/subql-starter/tree/main/Astar/astar-wasm-starter). + +::: + This project is unique, as it indexes data from both Astar's Substrate execution layer (native Astar pallets and runtime), with smart contract data from Astar's WASM smart contract layer, within the same SubQuery project and into the same dataset. A very similar approach can be take with indexing Astar's EVM layer too. Previously, in the [1. Create a New Project](../quickstart.md) section, [3 key files](../quickstart.md#_3-make-changes-to-your-project) were mentioned. Let's take a closer look at these files. @@ -92,34 +98,53 @@ For [EVM](../../build/substrate-evm.md) and [WASM](../../build/substrate-wasm.md **Since we are planning to index all Polkadot transfers, we need to update the `datasources` section as follows:** -```yaml -dataSources: - - kind: substrate/Runtime - # This is the datasource for Astar's Native Substrate processor - startBlock: 1 - mapping: - file: ./dist/index.js - handlers: - - handler: handleNewContract - kind: substrate/EventHandler - filter: - module: dappsStaking - method: NewContract - - handler: handleBondAndStake - kind: substrate/EventHandler - filter: - module: dappsStaking - method: BondAndStake - - handler: handleUnbondAndUnstake - kind: substrate/EventHandler - filter: - module: dappsStaking - method: UnbondAndUnstake - - handler: handleReward - kind: substrate/EventHandler - filter: - module: dappsStaking - method: Reward +```ts +{ + dataSources: [ + { + // This is the datasource for Astar's Native Substrate processor + kind: SubstrateDatasourceKind.Runtime, + startBlock: 87073, + mapping: { + file: "./dist/index.js", + handlers: [ + { + kind: SubstrateHandlerKind.Event, + handler: "handleNewContract", + filter: { + module: "dappsStaking", + method: "NewContract", + }, + }, + { + kind: SubstrateHandlerKind.Event, + handler: "handleBondAndStake", + filter: { + module: "dappsStaking", + method: "BondAndStake", + }, + }, + { + kind: SubstrateHandlerKind.Event, + handler: "handleUnbondAndUnstake", + filter: { + module: "dappsStaking", + method: "UnbondAndUnstake", + }, + }, + { + kind: SubstrateHandlerKind.Event, + handler: "handleReward", + filter: { + module: "dappsStaking", + method: "Reward", + }, + }, + ], + }, + }, + ]; +} ``` This indicates that you will be running a `handleNewContract` mapping function whenever there is an event emitted from the `NewContract` method on the `dappsStaking` pallet. Similarly we will run other mapping functions for the three other events being emitted from the `dappsStaking` to other mapping functions. This covers most interactions with the dApp staking feature that we are interested in. @@ -130,41 +155,51 @@ Check out our [Manifest File](../../build/manifest/polkadot.md) documentation to If you're not using the [WASM starter template](https://github.com/subquery/subql-starter/tree/main/Astar/astar-wasm-starter) then please add the Wasm Datasource as a dependency using `yarn add @subql/substrate-wasm-processor`. -We are indexing all transfers and approve contract call events from the Astar contract `bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc`. First, you will need to import the contract ABI defintion. You can copy the entire JSON and save it as a file `./erc20Metadata.json` in the `abis` directory. +We are indexing all transfers and approve contract call events from the Astar contract `bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc`. First, you will need to import the contract ABI defintion. You can copy the entire JSON and save it as a file `./erc20Metadata.abi.json` in the `abis` directory. This section in the Project Manifest now imports all the correct definitions and lists the triggers that we look for on the blockchain when indexing. We add another section the datasource beneath the above [substrate manifest section](#substrate-manifest-section). -```yaml -dataSources: - - kind: substrate/Runtime - # This is the datasource for Astar's Native Substrate processor - ... - - kind: substrate/Wasm - # This is the datasource for Astar's Wasm processor - startBlock: 3281780 - processor: - file: ./node_modules/@subql/substrate-wasm-processor/dist/bundle.js - options: - abi: erc20 - # contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" # Shibuya - contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc" # Mainnet - assets: - erc20: - file: ./abis/erc20Metadata.json - mapping: - file: ./dist/index.js - handlers: - - handler: handleWasmEvent - kind: substrate/WasmEvent - filter: - # contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" # Shibuya - contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc" # Mainnet - identifier: "Transfer" - - handler: handleWasmCall - kind: substrate/WasmCall - filter: - selector: "0x681266a0" - method: "approve" +```ts +{ + dataSources: [ + { + // This is the datasource for Astar's Wasm processor + kind: "substrate/Wasm", + startBlock: 3281780, + processor: { + file: "./node_modules/@subql/substrate-wasm-processor/dist/bundle.js", + options: { + abi: "erc20", + // contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" // Shibuya + contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc", // Mainnet, + }, + }, + assets: new Map([["erc20", { file: "./abis/erc20Metadata.abi.json" }]]), + mapping: { + file: "./dist/index.js", + handlers: [ + { + handler: "handleWasmEvent", + kind: "substrate/WasmEvent", + filter: { + // contract: "a6Yrf6jAPUwjoi5YvvoTE4ES5vYAMpV55ZCsFHtwMFPDx7H" // Shibuya + contract: "bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc", // Mainnet + identifier: "Transfer", + }, + }, + { + handler: "handleWasmCall", + kind: "substrate/WasmEvent", + filter: { + selector: "0x681266a0", + method: "approve", + }, + }, + ], + }, + }, + ], +} ``` The above code indicates that you will be running a `handleWasmEvent` mapping function whenever there is an `Transfer` event on any transaction from the Astar contract. Similarly, we will run the `handleWasmCall` mapping function whenever there is a `approve` log on the same contract. @@ -352,6 +387,12 @@ You should see results similar to below: } ``` +::: tip Note + +The final code of this project can be found [here](https://github.com/subquery/subql-starter/tree/main/Astar/astar-wasm-starter). + +::: + ## What's next? Congratulations! You have now a locally running SubQuery project that accepts GraphQL API requests for events from the lottery smart contract at [`bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc`](https://astar.subscan.io/account/bZ2uiFGTLcYyP8F88XzXa13xu5Mmp13VLiaW1gGn7rzxktc?tab=wasm_transaction).