Skip to content
πŸ”Œ TypeScript bindings for Ethereum smart contracts
TypeScript JavaScript Shell
Branch: master
Clone or download
Latest commit 0f720de Nov 24, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci build package during CI Sep 13, 2018
__snapshots__ rewrite all targets to work with new contract interface Sep 28, 2019
docs/images add nf logo Aug 14, 2018
packages bump version Nov 24, 2019
patches add snapshot testing for generated files Aug 30, 2018
scripts
test upgrade web3, deal with breaking changes Nov 24, 2019
typings add snapshot testing for generated files Aug 30, 2018
.coveralls.yml changelog, update circleci and code coverage badge, add monthly downl… Sep 17, 2018
.gitignore
.npmignore fix few bugs in generator code, improve npmignore config, improve readme Mar 20, 2018
.nycrc nycrc fix Sep 28, 2019
.prettierignore add prettier Dec 7, 2017
.prettierrc prettier works Sep 28, 2019
CHANGELOG.md add changelog note Apr 8, 2019
LICENSE add license file May 1, 2018
README.md update readme Nov 7, 2019
package.json
tsconfig.json
tsconfig.prod.json Rename web3-1.0.0 target test files too, plus some missed occurences Oct 10, 2019
tslint.json
yarn.lock upgrade web3, deal with breaking changes Nov 24, 2019

README.md

TypeChain

TypeChain

πŸ”Œ TypeScript bindings for Ethereum smartcontracts

Build Status Coverage Downloads Prettier Software License

Medium post | DappCon Video

Contributed with:
Neufund

Features ⚑

  • static typing - you will never call not existing method again
  • IDE support - works with any IDE supporting Typescript
  • extendible - work with many different APIs: ethers.js, truffle, Web3.js 1.0 or you can create your own target
  • frictionless - works with simple, JSON ABI files as well as with Truffle style ABIs

Installation

npm install --save-dev typechain

You will also need to install a desired target for example typechain-target-ethers. Learn more about targets

Packages πŸ“¦

Package Version Description
typechain npm Core package
typechain-target-ethers npm Ethers support
typechain-target-truffle npm Truffle support
typechain-target-web3-v1 npm Web3 version 1.x.x support

Usage

CLI

typechain --target=(ethers|truffle|web3-v1|path-to-custom-target) [glob]
  • glob - pattern that will be used to find ABIs, remember about adding quotes: typechain "**/*.json"
  • --target - ethers, truffle, web3-v1 or path to your custom target. typechain will try to load package named typechain-target-${target}, so make sure that desired package is installed.
  • --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 ethers --outDir app/contracts './node_modules/neufund-contracts/build/contracts/*.json'

Demo 🏎️

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

Step by step guide

Install typechain with yarn add --dev typechain and install desired target.

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 🎯

Ethers.js

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

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. Typings for library itself are now part of Web3 1.0.0 library so nothing additional is needed. For now it needs explicit cast as shown here, this will be fixed after improving official typings.

Your own target

This might be useful when you're creating a library for users of your smartcontract and you don't want to lock yourself into any API provided by Web3 access providing library. You can generate basically any code (even for different languages than TypeScript!) that based on smartcontract's ABI.

Migration guide

For users of 0.x.x versions: the only breaking change is extraction of targets for separate packages so now you need to install typechain-target-${name} for each 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 code?

A: You can create your own target and generate basically any 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 { tsGenerator } from "ts-generator";
import { TypeChain } from "typechain/dist/TypeChain";

async function main() {
  const cwd = process.cwd();

  await tsGenerator(
    { cwd },
    new TypeChain({
      cwd,
      rawConfig: {
        files: "your-glob-here",
        outDir: "optional out dir path",
        target: "your-target",
      },
    }),
  );
}

main().catch(console.error);

Running tests

yarn           # install all dependencies
yarn test      # runs tests + linting
yarn test:fix  # autofix any errors + run tests

Debugging 🐞

DEBUG=typechain typechain

Licence

Krzysztof Kaczor (krzkaczor) MIT | Github | Twitter

You can’t perform that action at this time.