Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kodadot/snek

Implementation of Basilisk NFT pallet
https://github.com/kodadot/snek

basilisk graphql subsquid

Last synced: 3 days ago
JSON representation

Implementation of Basilisk NFT pallet

Host: GitHub
URL: https://github.com/kodadot/snek
Owner: kodadot
License: gpl-3.0
Created: 2022-03-24T11:26:12.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2023-09-27T19:51:45.000Z (about 1 year ago)
Last Synced: 2023-09-29T01:02:56.800Z (about 1 year ago)
Topics: basilisk, graphql, subsquid
Language: TypeScript
Homepage:
Size: 910 KB
Stars: 3
Watchers: 2
Forks: 11
Open Issues: 35
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Snek

**Implementation of the best NFT marketplace with locked balances.**

![image](https://user-images.githubusercontent.com/5887929/217077078-b0469706-1348-48ae-a4dc-9ee7598d8a3c.png)

## Prerequisites

* node 16.x
* docker

## Quickly running the sample

Example commands below use [make(1)](https://www.gnu.org/software/make/).
Please, have a look at commands in [Makefile](Makefile) if your platform doesn't support it.
On Windows we recommend to use [WSL](https://docs.microsoft.com/en-us/windows/wsl/).

```bash
# 1. Install dependencies
npm ci

# 2. Compile typescript files
make build

# 3. Start target Postgres database and detach
make up

# 4. Apply database migrations from db/migrations
make migrate

# 5. Start the processor
make process

# 6. The command above will block the terminal
# being busy with fetching the chain data,
# transforming and storing it in the target database.
#
# To start the graphql server open the separate terminal
# and run
make serve

# 7. Now you can see the results by visiting the localhost:4350/graphql
```

## Dev flow

### 1. Define database schema

Start development by defining the schema of the target database via `schema.graphql`.
Schema definition consists of regular graphql type declarations annotated with custom directives.
Full description of `schema.graphql` dialect is available [here](https://docs.subsquid.io/docs/develop-a-squid/define-a-squid-schema).

### 2. Generate TypeORM classes

Mapping developers use [TypeORM](https://typeorm.io) entities
to interact with the target database during data processing. All necessary entity classes are
generated by the squid framework from `schema.graphql`. This is done by running `npx squid-typeorm-codegen`
command.

### 3. Generate database migration

All database changes are applied through migration files located at `db/migrations`.
`squid-typeorm-migration(1)` tool provides several commands to drive the process.
It is all [TypeORM](https://typeorm.io/#/migrations) under the hood.

```bash
# Connect to database, analyze its state and generate migration to match the target schema.
# The target schema is derived from entity classes generated earlier.
# Don't forget to compile your entity classes beforehand!
npx squid-typeorm-migration generate

# Create template file for custom database changes
npx squid-typeorm-migration create

# Apply database migrations from `db/migrations`
npx squid-typeorm-migration apply

# Revert the last performed migration
npx squid-typeorm-migration revert
```

### 4. Generate TypeScript definitions for substrate events, calls and storage

This is an optional part, but it is very advisable.

Event, call and runtime storage data come to mapping handlers as raw untyped json.
While it is possible to work with raw untyped json data,
it's extremely error-prone and the json structure may change over time due to runtime upgrades.

Squid framework provides tools for generating type-safe wrappers around events, calls and runtime storage items for
each historical change in the spec version.

The end result looks like this:

```typescript
/**
* Normalized `balances.Transfer` event data
*/
interface TransferEvent {
from: Uint8Array
to: Uint8Array
amount: bigint
}

function getTransferEvent(ctx: EventHandlerContext): TransferEvent {
// instanciate type-safe facade around event data
let event = new BalancesTransferEvent(ctx)
if (event.isV1020) {
let [from, to, amount, fee] = event.asV1020
return {from, to, amount}
} else if (event.isV1050) {
let [from, to, amount] = event.asV1050
return {from, to, amount}
} else {
// This cast will assert,
// that the type of a given event matches
// the type of generated facade.
return event.asLatest
}
}
```

Generation of type-safe wrappers for events and calls is currently a two-step process.

First, you need to explore the chain to find blocks which introduce new spec version and
fetch corresponding metadata.

```bash
npx squid-substrate-metadata-explorer \
--chain wss://kusama-rpc.polkadot.io \
--archive https://kusama.indexer.gc.subsquid.io/v4/graphql \
--out kusamaVersions.json
```

In the above command `--archive` parameter is optional, but it speeds up the process
significantly. From scratch exploration of kusama network without archive takes 20-30 minutes.

You can pass the result of previous exploration to `--out` parameter. In that case exploration will
start from the last known block and thus will take much less time.

After chain exploration is complete you can use `squid-substrate-typegen(1)` to generate
required wrappers.

```bash
npx squid-substrate-typegen typegen.json
```

Where `typegen.json` config file has the following structure:

```json5
{
"outDir": "src/types",
"chainVersions": "kusamaVersions.json", // the result of chain exploration
"typesBundle": "kusama", // see types bundle section below
"events": [ // list of events to generate
"balances.Transfer"
],
"calls": [ // list of calls to generate
"timestamp.set"
]
}
```

## 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.

## Types bundle

Substrate chains which have blocks with metadata versions below 14 don't provide enough
information to decode their data. For those chains external
[type definitions](https://polkadot.js.org/docs/api/start/types.extend) are required.

Type definitions (`typesBundle`) can be given to squid tools in two forms:

1. as a name of a known chain (currently only `kusama`)
2. as a json file of a structure described below.

```json5
{
"types": {
"AccountId": "[u8; 32]"
},
"typesAlias": {
"assets": {
"Balance": "u64"
}
},
"versions": [
{
"minmax": [0, 1000], // block range with inclusive boundaries
"types": {
"AccountId": "[u8; 16]"
},
"typesAlias": {
"assets": {
"Balance": "u32"
}
}
}
]
}
```

* `.types` - scale type definitions similar to [polkadot.js types](https://polkadot.js.org/docs/api/start/types.extend#extension)
* `.typesAlias` - similar to [polkadot.js type aliases](https://polkadot.js.org/docs/api/start/types.extend#type-clashes)
* `.versions` - per-block range overrides/patches for above fields.

All fields in types bundle are optional and applied on top of a fixed set of well known
frame types.

## Differences from polkadot.js

Polkadot.js provides lots of [specialized classes](https://polkadot.js.org/docs/api/start/types.basics) for various types of data.
Even primitives like `u32` are exposed through special classes.
In contrast, squid framework works only with plain js primitives and objects.
This allows to decrease coupling and also simply dictated by the fact, that
there is not enough information in substrate metadata to distinguish between
interesting cases.

Account addresses is one example where such difference shows up.
From substrate metadata (and squid framework) point of view account address is simply a fixed length
sequence of bytes. On other hand, polkadot.js creates special wrapper for account addresses which
aware not only of address value, but also of its
[ss58](https://docs.substrate.io/v3/advanced/ss58/) formatting rules.
Mapping developers should handle such cases themselves.

## Graphql server extensions

It is possible to extend `squid-graphql-server(1)` with custom
[type-graphql](https://typegraphql.com) resolvers and to add request validation.
More details will be added later.

## Archival nodes

Because subsquid requires an archival indexer to be fast, there are currently 3 options how to do it:

1. Leave it as it is

there is already indexer for base basilisk

2. using archival node for Koda BSX Sandbox :snake:

```.env
ARCHIVE_URL=https://basilisk-test.indexer.gc.subsquid.io/v4/graphql
```

3. running your own

```bash
git clone [email protected]:subsquid/squid-archive-setup.git;
cd squid-archive-setup/basilisk
```

in `docker-compose.yml` set url for the chain

```
- - WS_PROVIDER_ENDPOINT_URI=wss://basilisk.api.onfinality.io/public-ws
+ - WS_PROVIDER_ENDPOINT_URI=wss://basilisk-kodadot.hydration.cloud
```

then just

```bash
docker compose up
```

and set

```.env
ARCHIVE_URL=http://localhost:4010/v1/graphql
```