|
| 1 | +# How-to cheat sheet |
| 2 | + |
| 3 | +## How to run a processor against a different chain? |
| 4 | + |
| 5 | +You will need to have WebSocket endpoint to connect to the chain node and a Squid Archive. For a registry of Squid Archives, check this community-owned [Archive Registry](https://github.com/subsquid/archive-registry) |
| 6 | + |
| 7 | +If you don't find a suitable Squid Archive in the registry, set up your own Squid archive. There are multiple examples in this [repo](https://github.com/subsquid/squid-archive-setup) |
| 8 | + |
| 9 | +Once set up, we encourage to contribute to the Squid community and make a PR to the [Archive Registry](https://github.com/subsquid/archive-registry). |
| 10 | + |
| 11 | + |
| 12 | +## Where do I get a type bundle for my chain? |
| 13 | + |
| 14 | +Most chains publish their type bundles as an npm package. One of the best places to check for the latest version is the [polkadot-js/app repo](https://github.com/polkadot-js/apps/tree/master/packages/apps-config). Note, however, that a types bundle is only needed for pre-Metadata v14 blocks, so for recently deployed chains it may be not needed. |
| 15 | + |
| 16 | +Note that the type bundle format for typegen is slightly different from `OverrideBundleDefinition` of `polkadot.js`. The structure is as follows, all the fields are optional. |
| 17 | + |
| 18 | +```javascript |
| 19 | +{ |
| 20 | + types: {}, // top-level type definitions, as `.types` option of `ApiPromise` |
| 21 | + typesAlias: {}, // top-level type alieases, as `.typesAlias` option of `ApiPromise` |
| 22 | + versions: [ // spec version specific overrides, same as `OverrideBundleDefinition.types` of `polkadot.js` |
| 23 | + { |
| 24 | + minmax: [0, 1010] // spec range |
| 25 | + types: {}, // type overrides for the spec range |
| 26 | + typesAlias: {}, // type alias overrides for the spec range |
| 27 | + } |
| 28 | + ] |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | + |
| 33 | +## How do I write the schema? |
| 34 | + |
| 35 | +The schema file defines the shape of the final GraphQL API and has very few limitations. Designing the schema file is very similar to the design of the database schema. As a rule of thumb, the schema should represent high level domain specific entities and relations between them, to make data fetching and filtering easy for the API consumers. |
| 36 | + |
| 37 | +Typically, the API is consumed by the frontend and mobile apps, so it's a good idea to design the schema even before you go on with implementing the processor mappings. In fact, the processor is completely indpendent from the GraphQL server serving the API, so you can experiment how the API looks like. |
| 38 | + |
| 39 | +## How do I update my schema? |
| 40 | + |
| 41 | +TL;DR: If you're ok dropping the database, simply update `schema.graphql` and run: |
| 42 | + |
| 43 | +```sh |
| 44 | +bash reset-schema.sh |
| 45 | +``` |
| 46 | + |
| 47 | +OBS! The database will be wiped out, so if it's not an option, read below. |
| 48 | + |
| 49 | + |
| 50 | +Here's a step-by-step instruction. First, generated the model files: |
| 51 | + |
| 52 | +```sh |
| 53 | +npx sqd codegen |
| 54 | +npm run build |
| 55 | +``` |
| 56 | + |
| 57 | +Now you have to options: either create a migration for an incremental schema update or recreate the whole schema from scratch. |
| 58 | + |
| 59 | +During the development process, recreating the schema is often more convenient. However, if you already have a running API in production and don't want to resync it, having an incremental update is preferrable (but requires data backfilling). |
| 60 | + |
| 61 | +### Option 1: Recreate schema from scratch |
| 62 | + |
| 63 | +Run |
| 64 | + |
| 65 | +```sh |
| 66 | +bash reset-db.sh |
| 67 | +``` |
| 68 | + |
| 69 | +### Option 2: Make an incremental update to the schema |
| 70 | + |
| 71 | +Generate a migration for the incremental changes and apply it |
| 72 | + |
| 73 | +```sh |
| 74 | +npx sqd db create-migration AddMyAwesomeNewField |
| 75 | +npx sqd db migrate |
| 76 | +``` |
| 77 | + |
| 78 | +You can find the newly generated and applied migration in `db/migrations`. |
| 79 | + |
| 80 | + |
| 81 | +## How do I run and test the GraphQL API? |
| 82 | + |
| 83 | +Once the migrations are applied, simply run |
| 84 | + |
| 85 | +``` |
| 86 | +npx squid-graphql-server |
| 87 | +``` |
| 88 | + |
| 89 | +Observe the port (4350 by default) and navigate to `localhost:4350/graphql` to explore your API. However, you need to run the processor to start populating the database. |
| 90 | + |
| 91 | + |
| 92 | +## How do I start the processor? |
| 93 | + |
| 94 | +First, make sure you have compiled your project with |
| 95 | +``` |
| 96 | +npm run build |
| 97 | +``` |
| 98 | + |
| 99 | +Then simply run |
| 100 | +``` |
| 101 | +node -r dotenv/config lib/processor.js |
| 102 | +``` |
| 103 | + |
| 104 | +Note that `-r dotenv/config` ensures that the database settings are picked up from `.env`. If you the environment variables them elsewhere, skip it. |
| 105 | + |
| 106 | +## How do I deploy my API to the Subsquid Hosted service? |
| 107 | + |
| 108 | +Login to the [Subsquid Hosted Service](https://app.subsquid.io) with your github handle to obtain a deployment key. Then create a Squid (that is, your deployment) and follow the instructions. |
| 109 | + |
| 110 | +## How do I know which events and extrinsics I need for the handlers? |
| 111 | + |
| 112 | +This part depends on the runtime business-logic of the chain. The primary and the most reliable source of information is thus the Rust sources for the pallets used by the chain. |
| 113 | +For a quick lookup of the documentation and the data format it is often useful to check `Runtime` section of Subscan, e.g. for [Statemine](https://statemine.subscan.io/runtime). One can see the deployed pallets and drill down to events and extrinsics from there. One can also choose the spec version on the drop down. |
| 114 | + |
| 115 | +## How do I decode the event data? And how to deal with runtime upgrades? |
| 116 | + |
| 117 | +Runtime upgrades may change the event data and even the event logic altogether, but Squid gets you covered with a first-class support for runtime upgrades. |
| 118 | + |
| 119 | +Subsquid SDK comes with a tool called metadata explorer which makes it easy to keep track of all runtime upgrades happen so far. |
| 120 | + |
| 121 | +The basic usage of the explorer is as follows (check README for details): |
| 122 | + |
| 123 | +```sh |
| 124 | +npx squid-substrate-metadata-explorer \ |
| 125 | + --chain <chain endpoint here> \ |
| 126 | + --archive <archive endpoint here> \ |
| 127 | + --out metadataVersions.json |
| 128 | +``` |
| 129 | + |
| 130 | +Once the exploration is done, you should define all events and calls of interest in `typegen.json`, then adjust the bundle and metadata history references and run: |
| 131 | + |
| 132 | +```sh |
| 133 | +npx squid-substrate-typegen typegen.json |
| 134 | +``` |
| 135 | + |
| 136 | +A type-safe definition for each and every version of the event will be generated. Most of the times, one should be able to infer a normalized interface together with some glue code to make it fit the runtime specific versions. For example, for Kusama `balances.Transfer` event, `squid-substrate-typegen` generated three slightly different versions that can be reconciled as follows: |
| 137 | + |
| 138 | +```typescript |
| 139 | +/** |
| 140 | + * Normalized `balances.Transfer` event data |
| 141 | + */ |
| 142 | +interface TransferEvent { |
| 143 | + from: Uint8Array |
| 144 | + to: Uint8Array |
| 145 | + amount: bigint |
| 146 | +} |
| 147 | + |
| 148 | +function getTransferEvent(ctx: EventHandlerContext): TransferEvent { |
| 149 | + // instanciate type-safe facade around event data |
| 150 | + let event = new BalancesTransferEvent(ctx) |
| 151 | + // initial version, with runtime spec 1020 |
| 152 | + if (event.isV1020) { |
| 153 | + let [from, to, amount, fee] = event.asV1020 |
| 154 | + return {from, to, amount} |
| 155 | + // first upgrade at runtime spec version 1050 |
| 156 | + } else if (event.isV1050) { |
| 157 | + let [from, to, amount] = event.asV1050 |
| 158 | + return {from, to, amount} |
| 159 | + } else { // current version |
| 160 | + // This cast will assert, |
| 161 | + // that the type of a given event matches |
| 162 | + // the type of generated facade. |
| 163 | + return event.asLatest |
| 164 | + } |
| 165 | +} |
| 166 | +``` |
0 commit comments