hydra
Search…
Hydra Typegen
A tool for generating type-safe TypeScript classes for runtime events and extrinsic calls

Motivation

Hydra Typegen is a code generation tool for creating Typescript types for substrate events and extrinsics. Its primary use-case is to provide type-safe interfaces for Hydra mappings. For example, once a typescript class for the Balances.Transfer event is generated, a mapping can look like
1
export async function balancesTransfer({
2
event
3
}: EventContext & StoreContext ) {
4
const [from, to, value] = new Balances.TransferEvent(event).params
5
const { dest, value } = new Balances.TransferCall(event).args
6
...
7
}
Copied!

Quickstart

A minimal example for generating classes for the Balances.Transfer and Treasury.Deposit events in Kusama:
1
hydra-typegen typegen --metadata wss://kusama-rpc.polkadot.io Balances.Transfer
Copied!
It is also possible to run hydra-typegen against a YAML config file
1
hydra-typegen typegen typegen.yml --debug
Copied!

Typegen config

Typegen config file has the following structure:
Field
Type
Description
metadata.source
string
Where typegen will source node metadata. Can either be a ws endpoint or a path to a static json file with the same content as the result of state_getMetadata RPC call
metadata.blockHash
string
(optional) If metadata.source is a WS endpoint, hash of the block from which metadata will be sourced, in hex format
events
[string]
A list of events for which TS classes will be generated, in the format <section>.<name>
calls
[string]
A list of extrinsics (calls) for which TS classes will be generated, in the format <section>.<method>
outDir
string
Root directory for the generated classes
strict
boolean
Default: false
If true, the event/extrinsic constructor throws an error if the raw data does not match the format in metadata (e.g. due to a runtime upgrade).
customTypes.lib
string
(optional) Import path for custom types that will be used in the generated sources
customTypes.typedefs
string
(optional) Path to a JSON file with custom type definitions, as expected by polkadot.js createApi method
The config file typegen.yml can look like this:
1
# Typegen will pull the metadata from Kusama at block with the given hash
2
metadata:
3
source: wss://kusama-rpc.polkadot.io
4
blockHash: '0x45eb7ddd324361adadd4f8cfafadbfb7e0a26393a70a70e5bee6204fc46af62e'
5
# events and calls for which the typescript types will be generated
6
events:
7
- Balances.Transfer
8
calls:
9
- Balances.transfer
10
outDir: ./generated
Copied!

Custom types

Hydra Typegen supports custom substrate types via the --typedefs flag. The provided .json file should include type definitions for the arguments and parameters of the events and extrinsics to be generated. The type definitions file is copied to the generated sources.
In the config file, place the definition into the customTypes section. It assumes that all the custom runtime types are already available for import from a library, so that e.g. the generated import statement
1
import { MyCustomRuntimeClass } from 'my/types/library'
Copied!
is correctly resolved.
1
...
2
customTypes:
3
lib: 'my/types/library',
4
typedefs: my-types-json,
Copied!
Note, that when used in the mappings, the library with custom types (here my/types/library) must be added as a dependency for the mappings module in mappings/package.json

Commands

hydra-typegen help [COMMAND]

display help for hydra-typegen
1
USAGE
2
$ hydra-typegen help [COMMAND]
3
4
ARGUMENTS
5
COMMAND command to show help for
6
7
OPTIONS
8
--all see all commands in CLI
Copied!
See code: @oclif/plugin-help

hydra-typegen typegen [CONFIG]

Generate Typescript classes for the Substrate events
1
USAGE
2
$ hydra-typegen typegen [CONFIG]
3
4
ARGUMENTS
5
CONFIG Path to YML config file. Overrides the flag options
6
7
OPTIONS
8
-c, --calls=calls Comma-separated list of substrate calls in the format <module>.<name>
9
-d, --debug Output debug info
10
-e, --events=events Comma-separated list of substrate events in the formation <module>.<name>
11
12
-h, --blockHash=blockHash Hash of the block from which the metadata will be fetched. Only applied if metadata is
13
pulled via an RPC call
14
15
-i, --typelib=typelib A JavaScript module from which the custom types should be imported, e.g.
16
'@joystream/types/augment'
17
18
-m, --metadata=metadata [default: metadata.json] Chain metadata source. If starts with ws:// or wss:// the metadata
19
is pulled by an RPC call to the provided endpoint. Otherwise a relative path to a json file
20
matching the RPC call response is expected
21
22
-o, --outDir=outDir [default: generated/types] A relative path the root folder where the generated files will
23
be generated
24
25
-s, --[no-]strict Strict mode. If on, the generated code throws an error if the input event argument types
26
don't much the metadata definiton
27
28
-t, --typedefs=typedefs A relative path to a file with JSON definitions for custom types used by the chain
Copied!
A full sample Hydra project can be found here
Last modified 4mo ago