NaNoWriMo Promotes Manuscription

    ethereum-abi-types-generator
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.2 • Public • Published

    npm version downloads

    ethereum-abi-types-generator

    Dev typings for all your ethereum ABI contract methods and events with 1 liner integrations with web3 and ethers 👏👏👏👏. Never have to have a runtime error again and bring them into compile time errors in 2 minutes.

    Demo gif can be seen on the github readme

    A CLI tool which allows you to convert an ABI json file into fully loaded interfaces types.

    Features 🚀

    🚀 Compile time errors, never make easy dynamic mistakes again.
    🚀 Easy 1 line solution to get working
    🚀 Use the same interfaces as the provider your use to, no changes in how you develop
    🚀 Works with just a simple ABI json file
    🚀 Supports ethers and web3 out the box
    🚀 0 bundle increase, its all dev dependencies so get all the benefit with no negative impact on your build size
    🚀 Nice easy CLI to allow you to generate these however you like, build scripts, watch file change events its up to you
    🚀 Supported multidimensional return types aka bytes32[4] >[string, string, string, string, string]`
    🚀 Automatic documentation generated on each method outputting all the details about it which is on the ABI - no jumping back and forth
    🚀 Generated event typings

    Supports

    • Web3 1.x and 2.x
    • Ethers 5.x
    • Ethers 4.x
    • Hardhat

    ethereum-abi-types-generator vs TypeChain

    The first question I normally get is “have you seen TypeChain”, yes I have of course and it is a great tool but it was missing and did a few things which I didn't want as a developer. The main differences with this ethereum-abi-types-generator vs typechain are:

    No bundle size at all added

    With TypeChain you have a class factory you have to connect to adding size into the final bundle. This package is all interfaces meaning nothing is added to your final bundle size.

    Exposes proper typed interfaces meaning you can use them in your application

    TypeChain has dynamic interfaces aka public contractCall(): Promise<{ foo: BigNumber }> so if you wanted to use that interface somewhere in your app its not exported so can not be used. This lib generates response interfaces which are exported aka:

    export interface ContractCallResponse {
      foo: BigNumber
    }
    
    public contractCall(): Promise<ContractCallResponse>

    This means you can use this interface anywhere in your app as its just exported for you. The naming for this is ${contractCallMethodName}Response aka if a method was called HelloWorld the response interface would be HelloWorldResponse. This also follows suit on the request interfaces aka:

    export interface FooRequest {
      foo: BigNumber,
      boo: string;
    }
    
    public contractCall(request: FooRequest): Promise<ContractCallResponse>

    If you have worked with dynamic interfaces you understand the pain it brings having to recreate everytime.

    Use your provider interface your use too

    TypeChain you have to connect to the factory then use the contract that way. With this lib you just use web3 or ethers interface for every contract call meaning you don't have to get use to another process it just works and zero code changes just cast and you got compile time errors for contracts.

    Motivation

    Blockchain development in JavaScript is already super hard. You have all these tools like truffle, ethers, web3 (the list goes on) which you have to get use to and the learning curve is already quite high. On top of this, you have loads of other tools to get things to work as you need. TypeScript allows you to bring runtime errors in the compiler but on contract calls most developers have to either build their own types meaning maintaining them and easily getting out of sync or have no compile type errors using the dreaded any hoping and praying you don't break anything. The idea was to not have to make the developer wrap any kind of web3 or ethers instance or use a new tool to get this working but with a simple 1 line change you can use all the same libraries interfaces as what the developer is use to but with types auto-generated for you to bring back compile-time errors on any contract calls with super ease.

    The ABI file is the source of truth for all contract calls so by building types from this file we can be assured our types correct.

    Installation

    npm:

    $ npm install ethereum-abi-types-generator --save-dev

    yarn:

    $ yarn add ethereum-abi-types-generator --dev

    You can install this globally as well but you must make sure wherever the --output location is which generates the typings file has ethereum-abi-types-generator installed in that project, as it uses imports from this package to map the ContractContext to make your life easier handling the generic type build up automatically. We suggest always running this tool inside a project context.

    Tsconfig compile time issues

    If you get compile time errors due to it waiting web3 dependencies when using ethers please set skipLibCheck: true in the tsconfig.json compiler options and this should fix that issue.

    CLI usage

    Web3 1.x and 2.x & Ethers 5.x & Ethers 4.x

    $ abi-types-generator <abiFileLocation>
    $ abi-types-generator <abiFileLocation> --name=ABI_NAME
    $ abi-types-generator <abiFileLocation> --watch
    $ abi-types-generator <abiFileLocation> --name=ABI_NAME --watch
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --watch
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --name=ABI_NAME
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --name=ABI_NAME --watch
    $ abi-types-generator <abiFileLocation> --provider=web3|ethers|ethers_v5
    $ abi-types-generator <abiFileLocation> --provider=web3|ethers|ethers_v5 --watch
    $ abi-types-generator <abiFileLocation> --name=ABI_NAME --provider=web3|ethers|ethers_v5
    $ abi-types-generator <abiFileLocation> --name=ABI_NAME --provider=web3|ethers|ethers_v5 --watch
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --provider=web3|ethers|ethers_v5
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --provider=web3|ethers|ethers_v5 --watch
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --name=ABI_NAME --provider=web3|ethers|ethers_v5
    $ abi-types-generator <abiFileLocation> --output=PATH_DIRECTORY --name=ABI_NAME --provider=web3|ethers|ethers_v5 --watch

    Hardhat

    $ abi-types-generator hardhat

    We suggest running these within the script commands in npm or yarn this way you will not lose your commands and can be run on build agents as well. Also you will not get confused with sharing the script and others running in the wrong paths. Examples below:

    {
      "name": "examples",
      "version": "1.0.0",
      "description": "",
      "main": "index.js",
      "scripts": {
        "web3-example": "abi-types-generator './abi-examples/fake-contract-abi.json' --output='./web3/fake-contract-example/generated-typings' --name=fake-contract",
        "web3-token-abi": "abi-types-generator './abi-examples/token-abi.json' --output='./web3/uniswap-example/generated-typings' --name=token-contract",
        "web3-uniswap-exchange-abi": "abi-types-generator './abi-examples/uniswap-exchange-abi.json' --output='./web3/uniswap-example/generated-typings' --name=uniswap-exchange-contract",
        "web3-uniswap-factory-abi": "abi-types-generator './abi-examples/uniswap-factory-abi.json' --output='./web3/uniswap-example/generated-typings' --name=uniswap-factory-contract",
        "web3-uniswap": "npm run web3-token-abi && npm run web3-uniswap-exchange-abi && npm run web3-uniswap-factory-abi",
        "ethers-example": "abi-types-generator './abi-examples/fake-contract-abi.json' --output='./ethers/fake-contract-example/generated-typings' --name=fake-contract --provider=ethers",
        "ethers-token-abi": "abi-types-generator './abi-examples/token-abi.json' --output='./ethers/uniswap-example/generated-typings' --name=token-contract --provider=ethers",
        "ethers-uniswap-exchange-abi": "abi-types-generator './abi-examples/uniswap-exchange-abi.json' --output='./ethers/uniswap-example/generated-typings' --name=uniswap-exchange-contract --provider=ethers",
        "ethers-uniswap-factory-abi": "abi-types-generator './abi-examples/uniswap-factory-abi.json' --output='./ethers/uniswap-example/generated-typings' --name=uniswap-factory-contract --provider=ethers",
        "ethers-uniswap": "npm run ethers-token-abi && npm run ethers-uniswap-exchange-abi && npm run ethers-uniswap-factory-abi",
        "ethers-v5-example": "abi-types-generator './abi-examples/fake-contract-abi.json' --output='./ethers_v5/fake-contract-example/generated-typings' --name=fake-contract --provider=ethers_v5",
        "ethers-v5-token-abi": "abi-types-generator './abi-examples/token-abi.json' --output='./ethers_v5/uniswap-example/generated-typings' --name=token-contract --provider=ethers_v5",
        "ethers-v5-uniswap-exchange-abi": "abi-types-generator './abi-examples/uniswap-exchange-abi.json' --output='./ethers_v5/uniswap-example/generated-typings' --name=uniswap-exchange-contract --provider=ethers_v5",
        "ethers-v5-uniswap-factory-abi": "abi-types-generator './abi-examples/uniswap-factory-abi.json' --output='./ethers_v5/uniswap-example/generated-typings' --name=uniswap-factory-contract --provider=ethers_v5",
        "ethers-v5-uniswap": "npm run ethers-token-abi && npm run ethers-uniswap-exchange-abi && npm run ethers-uniswap-factory-abi",
        "hardhat-example": "abi-types-generator hardhat"
      }
    }

    Arguments

    <abiFileLocation> * required

    The ABI json file path location. Must be a JSON file path.

    --name=ABI_NAME

    The ABI ts file you want it to be named as, this will also name interface and enums as this. It will remove any - and . for the ts interfaces and enum names.

    If not supplied it will take the file name and use that as the abi name throughout.

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json

    generates: ./examples/abi-examples/uniswap-factory-abi.ts

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --name=foo-abi

    generates: ./examples/abi-examples/foo-abi.ts

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --name=foo.abi

    generates: ./examples/abi-examples/foo.abi.ts

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --name=foo

    generates: ./examples/abi-examples/foo.ts

    --output=PATH_DIRECTORY

    Where you want the .ts to be generated and saved to.

    If not supplied it will use the directory of the <abiFileLocation> and generate it there.

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json

    generates in: ./examples/abi-examples/uniswap-factory-abi.ts

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --output=./examples/ethers/generated-typings

    generates in: ./examples/ethers/generated-typings/uniswap-factory-abi.ts

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --output=./examples/ethers/generated-typings --name=foo

    generates: ./examples/ethers/generated-typings/foo.ts

    --provider=web3|ethers|ethers_v5

    What contract support you want to generate. This is the library you are using on your dapp and the lib you use to call any contract calls.

    export enum Provider {
      web3 = 'web3',
      ethers = 'ethers',
      ethers_v5 = 'ethers_v5',
    }

    If not supplied it will fallback to web3

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json

    generates the web3 contract typings based on the web3 lib.

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --provider=ethers

    generates the ethers contract typings based on the ethers 4 lib.

    Example:

    $ abi-types-generator ./examples/abi-examples/uniswap-factory-abi.json --provider=ethers_v5

    generates the ethers contract typings based on the ethers 5 lib.

    --watch

    This will watch the <abiFileLocation> for changes and if anything does change it will regenerate the typings and resave them in the --output defined or use the default one if one is not defined.

    Formatting

    We use prettier to format all files, to make sure it matches your coding style just make sure you have a .prettierrc defined in the root of your project and it will use that. If it can not find any it will take these default prettier:

    {
        parser: 'typescript',
        trailingComma: 'es5',
        singleQuote: true,
        bracketSpacing: true,
        printWidth: 80,
    }
    Running tslint as well

    Right now the package does not try to find any of your tslint.json settings. It will support this soon. For now if you get any tslint errors when running the linter it's best to ignore any generated file in the linterOptions > exclude of the tslint.json. I tend to put all my generated files in 1 place so I can ignore the entire folder.

    Using with hardhat

    First you create a script in your package.json that runs the abi-types-generator script after it compiles everytime.

    {
      "scripts": {
        "compile": "npx hardhat compile && abi-types-generator hardhat"
      }
    }

    If your contracts are ready to compile run:

    $ npm run compile

    You types are now created within the root of your hardhat project in a folder called ethereum-abi-types and you can use them throughout your tests/scripts or anything ts related.

    Test example

    import { expect } from 'chai';
    import { ethers } from 'hardhat';
    import {
      ContractContext as MyVeryFirstContract,
      GetFooResponse,
      GetFooRequest,
    } from '../ethereum-abi-types/MyVeryFirstContract';
    
    describe('Example test', function () {
      let contract: MyVeryFirstContract;
      beforeEach(async () => {
        const contractFactory = await ethers.getContractFactory(
          'MyVeryFirstContract'
        );
    
        // thats it you now have full typings on your contract
        contract =
          (await contractFactory.deploy()) as unknown as MyVeryFirstContract;
      });
    
      it('I love to write unit tests', async () => {
        const foo: GetFooRequest = { fooBoo: true };
        const result: GetFooResponse = await contract.getFoo(foo);
    
        expect(result).to.equal(
          { fooResponse: 'boo' }
      });
    });

    Using with web3 and ethers

    Web3 - https://www.npmjs.com/package/web3

    Uniswap full example:

    https://github.com/joshstevens19/ethereum-abi-types-generator/blob/master/examples/web3/uniswap-example/uniswap-contract-strongly-typed-example.ts

    Below is just a fake contract example just so you can understand how the typings improve your development.

    The cli tool will generate all your typings for you and expose them in the generated file. Its super easy to start using strongly typed interfaces for all your ABI calls.

    Lets say i run the cli command:

    $ abi-types-generator ./abi-examples/fake-contract-abi.json  --output=./generated-typings --name=fake-contract

    This will generate an ts file of ./generated-typings/fake-contract.ts which has all your strongly typed methods and events.

    All you meed to do is cast your new web3.eth.Contract code to an ContractContext which is exposed in where you defined the --output path to. In this example it is ./generated-typings/fake-contract.ts

    Example:

    import Web3 from 'web3';
    import { AbiExamples } from '../../abi-examples';
    import { ContractContext } from './generated-typings/fake-contract';
    
    const web3 = new Web3(
      'https://mainnet.infura.io/v3/280bb5b627394709938a7cc0b71a4a58'
    );
    
    // Has to cast to unknown as we have made some typings changes to the
    // contract interfaces which conflicts with `web3` typings.
    // This all work great but the compiler gets confused.
    // Casting to unknown first then the `ContractContext` solves this.
    const contract = new web3.eth.Contract(
      AbiExamples.YOUR_ABI,
      AbiExamples.YOUR_CONTRACT_ADDRESS
    ) as unknown as ContractContext;

    Easy as that 🔥🔥

    Full example:

    import Web3 from 'web3';
    import { AbiExamples } from '../../abi-examples';
    import {
      ContractContext,
      TupleInputOnlyRequest,
      TupleNoInputNamesResponse,
    } from './generated-typings/fake-contract';
    
    const example = async () => {
      const mockEthereumAddress = '0x419D0d8BdD9aF5e606Ae2232ed285Aff190E711b';
    
      const web3 = new Web3(
        'https://mainnet.infura.io/v3/280bb5b627394709938a7cc0b71a4a58'
      );
    
      // Has to cast to unknown as we have made some typings changes to the
      // contract interfaces which conflicts with `web3` typings.
      // This all work great but the compiler gets confused.
      // Casting to unknown first then the `ContractContext` solves this.
      const contract = new web3.eth.Contract(
        AbiExamples.YOUR_ABI,
        AbiExamples.YOUR_CONTRACT_ADDRESS
      ) as unknown as ContractContext;
    
      // you now have full typings on `contract.methods` which has generated docs
      const simpleCall = await contract.methods
        .easyExample(true, mockEthereumAddress, new Date().getTime())
        .call();
    
      console.log(simpleCall);
    
      // build up a proper typed request object with the interface importable
      // from the typings file generated
      const tupleExampleRequest: TupleInputOnlyRequest = {
        address: mockEthereumAddress,
        timestamps: [
          new Date().getTime(),
          new Date().getTime(),
          new Date().getTime(),
        ],
      };
    
      // encode abi method all exposed
      const data = contract.methods.tupleInputOnly(tupleExampleRequest).encodeABI();
      console.log(data);
    
      // any none constant methods will have the correct interface on them as well
      // aka you cant call `.call()` here and the compile will show you this.
      // will also expose the event emitters for your typings to still work with web3
      contract.methods
        .tupleInputOnly(tupleExampleRequest)
        .send({ from: mockEthereumAddress })
        .on('transactionHash', (hash) => {
          console.log(hash);
        });
    
      const result: TupleNoInputNamesResponse = await contract.methods
        .tupleNoInputNames(mockEthereumAddress, mockEthereumAddress)
        .call();
    
      console.log(result);
    
      // full typings on your events with even the filter indexs which will
      // not compile if supply it incorrectly and only expose the correct ones for you
      contract.events
        .Event1({ filter: { token: '0x00' } })
        .on('changed', (event) => {
          console.log(event);
        });
    
      // can any past events only allowing you to query events which actually exist
      const event = await contract.getPastEvents('Event1', {
        filter: { token: '0x00' },
      });
    
      console.log(event);
    };
    
    example();

    If the ABI changes and I run the CLI command again or have a --watch on the file, when you try to compile it will flag any errors with your typings for you.

    Ethers - https://www.npmjs.com/package/ethers

    Uniswap full example:

    https://github.com/joshstevens19/ethereum-abi-types-generator/blob/master/examples/ethers/uniswap-example/uniswap-contract-strongly-typed-example.ts

    Below is just a fake contract example just so you can understand how the typings improve your development.

    The cli tool will generate all your typings for you and expose them in the generated file. Its super easy to start using strongly typed interfaces for all your ABI calls.

    Lets say i run the cli command:

    Ethers v4

    $ abi-types-generator ./abi-examples/fake-contract-abi.json  --output=./generated-typings --name=fake-contract --provider=ethers

    Ethers v5

    $ abi-types-generator ./abi-examples/fake-contract-abi.json  --output=./generated-typings --name=fake-contract --provider=ethers_v5

    This will generate an ts file of ./generated-typings/fake-contract.ts which has all your strongly typed methods and events.

    All you meed to do is cast your new ethers.Contract code to an ContractContext which is exposed in where you defined the --output path to. In this example it is ./generated-typings/fake-contract.ts

    Example:

    import { ethers } from 'ethers';
    import { AbiExamples } from '../../abi-examples';
    import { ContractContext } from './generated-typings/fake-contract';
    
    // Connect to the network
    const customHttpProvider = new ethers.providers.JsonRpcProvider(
      'https://mainnet.infura.io/v3/280bb5b627394709938a7cc0b71a4a58'
    );
    
    // Has to cast to unknown as we have made some typings changes to the
    // contract interfaces which conflicts with `ethers` typings.
    // This all work great but the compiler gets confused.
    // Casting to unknown first then the `ContractContext` solves this.
    const contract = new ethers.Contract(
      AbiExamples.YOUR_CONTRACT_ADDRESS,
      AbiExamples.YOUR_ABI,
      customHttpProvider
    ) as unknown as ContractContext;

    Easy as that 🔥🔥

    Full example:

    import { ethers, utils } from 'ethers';
    import { AbiExamples } from '../../abi-examples';
    import {
      ContractContext,
      TupleInputOnlyRequest,
      TupleNoInputNamesResponse,
    } from './generated-typings/fake-contract';
    
    const example = async () => {
      const mockEthereumAddress = '0x419D0d8BdD9aF5e606Ae2232ed285Aff190E711b';
    
      // Connect to the network
      const customHttpProvider = new ethers.providers.JsonRpcProvider(
        'https://mainnet.infura.io/v3/280bb5b627394709938a7cc0b71a4a58'
      );
    
      // Has to cast to unknown as we have made some typings changes to the
      // contract interfaces which conflicts with `ethers` typings.
      // This all work great but the compiler gets confused.
      // Casting to unknown first then the `ContractContext` solves this.
      const contract = new ethers.Contract(
        AbiExamples.YOUR_CONTRACT_ADDRESS,
        AbiExamples.YOUR_ABI,
        customHttpProvider
      ) as unknown as ContractContext;
    
      // you now have full typings on `contract.x` which has generated docs
      const simpleCall = await contract.easyExample(
        true,
        mockEthereumAddress,
        new Date().getTime()
      );
    
      console.log(simpleCall);
    
      // you can use the same etherjs flows to send and sign transactions
      // `contract.connect` will return a `ContractContext` so will still have
      // all the typings exposed for you
      const privateKey =
        '0x0123456789012345678901234567890123456789012345678901234567890123';
      const wallet = new ethers.Wallet(privateKey, customHttpProvider);
    
      // Create a new instance of the Contract with a Signer, which allows
      // update methods
      const contractWithSigner = contract.connect(wallet);
    
      // build up a proper typed request object with the interface importable
      // from the typings file generated
      const tupleExampleRequest: TupleInputOnlyRequest = {
        address: mockEthereumAddress,
        timestamps: [
          new Date().getTime(),
          new Date().getTime(),
          new Date().getTime(),
        ],
      };
    
      // strongly typed optional overrides as well for both `calls` and `transactions`
      const tx = await contractWithSigner.tupleInputOnly(tupleExampleRequest, {
        // The maximum units of gas for the transaction to use
        gasLimit: 23000,
    
        // The price (in wei) per unit of gas
        gasPrice: utils.parseUnits('9.0', 'gwei'),
    
        // The nonce to use in the transaction
        nonce: 123,
    
        // The amount to send with the transaction (i.e. msg.value)
        value: utils.parseEther('1.0'),
    
        // The chain ID (or network ID) to use
        chainId: 1,
      });
      console.log(tx.hash);
      // "0xaf0068dcf728afa5accd02172867627da4e6f946dfb8174a7be31f01b11d5364"
    
      // The operation is NOT complete yet; we must wait until it is mined
      await tx.wait();
    
      const result: TupleNoInputNamesResponse = await contract.tupleNoInputNames(
        mockEthereumAddress,
        mockEthereumAddress
      );
    
      console.log(result);
    
      // full typings on your events
      contract.on(
        'Event1',
        (author: string, oldValue: string, newValue: string, event: any) => {
          // Called when anyone changes the value
    
          console.log(author);
          // "0x14791697260E4c9A71f18484C9f997B308e59325"
    
          console.log(oldValue);
          // "Hello World"
    
          console.log(newValue);
          // "I like turtles."
    
          console.log(event.blockNumber);
          // 4115004
        }
      );
    
      // filter that matches my signer as the author
      const filter = contract.filters.Event1(wallet.address);
    
      // full typings on filter interfaces as well
      contract.filters.Event1(
        filter,
        (author: string, oldValue: string, newValue: string, event: any) => {
          // Called ONLY when your account changes the value
    
          console.log(author);
          // "0x14791697260E4c9A71f18484C9f997B308e59325"
    
          console.log(oldValue);
          // "Hello World"
    
          console.log(newValue);
          // "I like turtles."
    
          console.log(event.blockNumber);
          // 4115004
        }
      );
    };
    
    example();

    If the ABI changes and I run the CLI command again or have a --watch on the file, when you try to compile it will flag any errors with your typings for you.

    Issues

    Please raise any issues in the below link.

    https://github.com/joshstevens19/ethereum-abi-types-generator/issues

    Thanks And Support

    This package is brought to you by Josh Stevens. My aim is to be able to keep creating these awesome packages to help the Ethereum space grow with easier-to-use tools to allow the learning curve to get involved with blockchain development easier and making Ethereum ecosystem better. If you want to help with that vision and allow me to invest more time into creating cool packages or if this package has saved you a lot of development time donations are welcome, every little helps. By donating, you are supporting me to be able to maintain existing packages, extend existing packages (as Ethereum matures), and allowing me to build more packages for Ethereum due to being able to invest more time into it. Thanks, everyone!

    Direct donations

    Direct donations any token accepted - Eth address > 0x699c2daD091ffcF18f3cd9E8495929CA3a64dFe1

    Github sponsors

    sponsor me via github using fiat money

    Install

    npm i ethereum-abi-types-generator

    DownloadsWeekly Downloads

    1,666

    Version

    1.3.2

    License

    MIT

    Unpacked Size

    356 kB

    Total Files

    184

    Last publish

    Collaborators

    • joshstevens19