# Migration to Hydra v2

## Versioning

All 0.x Hydra packages (a bit counter-intuitively) are considered Hydra v1. Since Hydra v2 (that is, versions 2.x) all Hydra packages (`hydra-cli`, `hydra-common`, `hydra-typegen` etc) recieve the same version on each release. So, say, Hydra version 2.0.1 means that all the packages together with the Docker images `hydra-indexer` and `hydra-indexer-gateway` are taged `2.0.1`

## What's new in Hydra v2

The key differences to keep in mind while migrating from v1 to v2:

* Hydra Processor is NOT generated by `hydra-cli` in v2
* Hydra Processor is run against a manifest file `manifest.yml`
* Mappings should be transpiled into a JS module
* `hydra-indexer` and `hydra-indexer-gateway` should be updated to v2

See examples of Hydra v2 in action [here](https://github.com/Joystream/hydra/tree/master/examples/v2)

## Migration

* Install the latest `hydra-cli` v2
* Run `hydra-cli  scaffold --silent` to generate a stub of a v2 Hydra project
* Run `yarn`

### Codegen

Nothing new here. Simply run `yarn codegen`

### Typegen for events

Update typegen section in `manifest.yml`

* List events and calls to which the types should be generated
* Add `customTypes` if needed: 
  * `lib`: from where the generated classes should import additional substrate types
  * `typedefsLoc`: path the type definitions

Install the types library: `cd mappings && yarn add <type library>`

Run `yarn typegen`

### Mapping files

Change mappings arguments: `DB` should be converted to `DatabaseManager` imported from `@dzlzv/hydra-db-utils`

Replace `event: SubstrateEvent` with a typed class generated by typegen in the previous step. The event data is now available at `event.data`

Whenever the corresponding extrinsic data is needed, use `event.ctx.extrinsic` and create a type-safe `Call` class out of it. Here is an example:

```typescript
import { DatabaseManager } from '@dzlzv/hydra-db-utils'
import { Post } from '../generated/graphql-server/src/modules/post/post.model'

import { Posts } from './generated/types'
export async function postCreated(
  db: DatabaseManager,
  event: Posts.PostCreatedEvent
) {
  const post = new Post()
  post.author = event.data.accountId.toHex()
  post.id = event.data.postId.toString()
  if (event.ctx.extrinsic === undefined) {
    throw new Error(`No extrinsic has been provided`)
  }
  // get type-safe call data out of the untyped extrinsic data
  const call = new Posts.CreatePostCall(event.ctx)
  post.content = call.args.content.toString()
  await db.save<Post>(post)
}
```

Add and install all the necessary dependencies for the mappings (e.g. the types library) and build the mappings:

```
yarn workspace sample-mappings add ...
yarn workspace sample-mappings install
yarn mappings:build
```

### Manifest file

Inspect and update the default `manifest.yml`

* (Optional)  Update `dataSource.chain`
* For each mapping, update the function name and the event it is handling
* Add `extrinsicHandlers` if needed

### Indexer and Indexer-Gateway

Use the latest v2.x Docker images (2.0.1-beta.9 at the time of writing). Check the indexer status by running the following GraphQL query:

```graphql
query {
  indexerStatus {
    chainHeight
    head
    hydraVersion
  }
}
```