TypeChain

🔌 Typescript bindings for Ethereum smartcontracts

Contributed with:

Features ⚡

static typing - you will never call not existing method again
IDE support - works with any IDE supporting Typescript
works with multiple libraries - use truffle,Web3.js 1.0, ethers.js, Web3.js 0.20.x
frictionless - works with simple, JSON ABI files as well as with Truffle style ABIs

Installation

npm install --save-dev typechain

yarn add --dev typechain

Usage

CLI

typechain --target=(truffle|web3-1.0.0|legacy) [glob]

glob - pattern that will be used to find ABIs, remember about adding quotes: typechain "**/*.json"
--target - truffle, web3-1.0.0, ethers or legacy
--outDir - put all generated files to a specific dir

Typechain always will rewrite existing files. You should not commit them. Read more in FAQ section.

Example:

typechain --target --outDir app/contracts './node_modules/neufund-contracts/build/contracts/*.json'

ts-generator unified config

Typechain is a plugin to ts-generator meaning that you can as well create unified config.

ts-generator.json file:

[
  {
    "generator": "typechain",
    "files": "./build/**/*.json",
    "target": "truffle"
  }
]

then just run ts-generator (you need to have ts-generator installed in your project).

This can be a great way to run more code generation plugins (css modules types, graphql types etc. ) at the same time.

Demo 🏎️

Example usage

Getting started 📚

Motivation

Interacting with blockchain in Javascript is a pain. Web3 interface is sluggish and when using it with Typescript it gets even worse. Often, you can't be sure what given method call will actually do without looking at ABI file. TypeChain is here to solve these problems (as long as you use Typescript).

How does it work?

TypeChain is code generator - provide ABI file and you will get Typescript class with flexible interface for interacting with blockchain. Depending on the target parameter it can generate typings for truffle, web3 1.0.0 or web3 0.20.x (legacy target).

Step by step guide

Install typechain with yarn add --dev typechain.

Run typechain --target=your_target (you might need to make sure that it's available in your path if you installed it only locally), it will automatically find all .abi files in your project and generate Typescript classes based on them. You can specify your glob pattern: typechain --target=your_target "**/*.abi.json". node_modules are always ignored. We recommend git ignoring these generated files and making typechain part of your build process.

That's it! Now, just import contract bindings as any other file import { MyAwesomeContract } from './contracts/MyAwesomeContract' and start interacting with it. We use named exports because of this.

Targets 🎯

Truffle

Truffle target is great when you use truffle contracts already. Check out truffle-typechain-example for more details. It require installing typings for truffle library itself.

Now you can simply use your contracts as you did before and get full type safety, yay!

Web3-1.0.0

Generates typings for contracts compatible with latest Web3.js version. It requires official typings from @types/web3 installed. For now it needs explicit cast as shown here, this will be fixed after improving official typings.

Ethers.js

Use ethers target to generate wrappers for ethers.js lib.

Legacy (Web3 0.2.x)

This was default and only target for typechain 0.2.x. It requires Web3.js 0.20.x to be installed in your project and it generates promise based wrappers. It's nice upgrade comparing to raw callbacks but in the near future Typechain will support Web3js 1.0 target.

FAQ 🤔

Q: Should I commit generated files to my repository?

A: NO — we believe that no generated files should go to git repository. You should git ignore them and make typechain run automatically for example in post install hook in package.json:

"postinstall":"typechain"

When you update ABI, just regenerate files with TypeChain and Typescript compiler will find any breaking changes for you.

Q: How do I customize generated classes? (legacy target only)

A: You can create your own class that extends generated one and adds additional methods etc.

Currently we discuss various ideas around extendibility including APIs files (adding semantics to ABIs for covering popular cases like working with dates) or using user-defined templates for generated code.

Q: Generated files won't match current codestyle of my project :(

A: We will automatically format generated classes with prettier to match your coding preferences (just make sure to use .prettierrc file).

Furthermore, we will silent tslint for generated files with /* tslint:disable */ comments.

Usage as API

You may want to use ts-generator api to kick off whole process by api:

import { tsGen } from "ts-generator";
import { Typechain } from "typechain";

async function main() {
  await tsGen({ cwd }, new Typechain({ cwd, rawConfig: { files: "your-glob-here", outDir: "optional out dir path" } }));
}

Running tests

yarn        # install all dependencies
yarn test   # runs tests + linting

Debugging 🐞

DEBUG=typechain typechain

Licence

Krzysztof Kaczor (krzkaczor) MIT | Github | Twitter

cryptokat/TypeChain