npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@supermojo-official/dethcrypto-eth-sdk

v0.4.0

Published

🛠 Generate type-safe, lightweight SDK for your Ethereum smart contracts

Downloads

83

Readme

  • minimal - just provide addresses of contracts that you wish to interact with
  • easy to use - ABIs will be automatically downloaded from Etherscan
  • familiar API - Generates ethers.js contract wrappers
  • type-safe - Leverages TypeChain for maximum type-safety

Installation

yarn add --dev @dethcrypto/eth-sdk @dethcrypto/eth-sdk-client

eth-sdk uses ethers.js and TypeScript, so these dependencies have to be installed as well.

Usage

eth-sdk [options]

CLI Options

Options:

  • -p, --path <path> working directory (default: ./eth-sdk)

    eth-sdk looks for the config file in this directory, and saves downloaded ABIs there.

Getting started

eth-sdk takes a JSON config file with ethereum addresses and generates a fully type-safe SDK that you can use right away. The SDK is an object consisting of ethers.js contracts initialized with ABIs provided by etherscan and with types generated via TypeChain.

The first step is to create a config file specifying contracts that we wish to interact with. Default path to this file is eth-sdk/config.ts.

import { defineConfig } from '@dethcrypto/eth-sdk'

export default defineConfig({
  contracts: {
    mainnet: {
      dai: '0x6b175474e89094c44da98b954eedeac495271d0f',
    },
  },
})

The key directly under "contracts" is a network identifier, eth-sdk needs it to query ABI information automatically. Following are key-value pairs of contract names and addresses. These can be deeply nested.

Now you're ready to run yarn eth-sdk. Few things will happen under the hood:

  1. Etherscan API will be queried in search of ABIs corresponding to the addresses. ABIs will be downloaded into eth-sdk directory (you should commit them to git to speed up the process in the future).
  2. Minimal SDK will be generated with functions like getMainnetSdk exposed. These functions wire addresses with ABIs and create ethers.js contract instances.
  3. TypeScript types will be generated for SDK using TypeChain.
  4. SDK is generated directly into node_modules, access it as @dethcrypto/eth-sdk-client.

Using generated sdk is as simple as it gets:

import { getMainnetSdk } from '@dethcrypto/eth-sdk-client' // yay, our SDK! It's tailored especially for our needs
import { ethers } from 'ethers'

async function main() {
  const mainnetProvider = ethers.getDefaultProvider('mainnet')
  const defaultSigner = ethers.Wallet.createRandom().connect(mainnetProvider)

  const sdk = getMainnetSdk(defaultSigner) // default signer will be wired with all contract instances
  // sdk is an object like { dai: DaiContract }

  const balance = sdk.dai.balanceOf(defaultSigner.address)
}

main()
  .then(() => console.log('DONE'))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })

Configuration

eth-sdk looks for a file named config or eth-sdk.config with .ts, .json, .js or .cjs extension inside of the directory specified by --path CLI argument.

You can use exports from @dethcrypto/eth-sdk to leverage your IDE's intellisense. Exported types are EthSdkConfig, EthSdkContracts, NestedAddresses and Address.

import type { EthSdkConfig } from '@dethcrypto/eth-sdk'
const config: EthSdkConfig = {
  // ...
}
export default config

Alternatively, you can use defineConfig function to write your config in a typesafe way without need for annotations.

import { defineConfig } from '@dethcrypto/eth-sdk'
export default defineConfig({
  // ...
})

contracts

A map from network identifier into deeply nested key-value pairs of contract names and addresses.

{
  "contracts": {
    "mainnet": {
      "dai": "0x6b175474e89094c44da98b954eedeac495271d0f",
      "dao": {
        "mkr": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2"
      }
    }
  }
}

Predefined network identifiers are:

"mainnet"            "ropsten"            "rinkeby"
"goerli"             "kovan"              "bsc"
"bscTestnet"         "heco"               "hecoTestnet"
"opera"              "ftmTestnet"         "optimism"
"optimismKovan"      "polygon"            "polygonMumbai"
"arbitrumOne"        "arbitrumTestnet"    "sepolia"

You can use other networks, but you will need to configure Etherscan URLs for them in etherscanURLs or provide networkIds when using Sourcify as abiSource.

outputPath

Output directory for generated SDK.

Defaults to ./node_modules/.dethcrypto/eth-sdk

{
  "outputPath": "./node_modules/.dethcrypto/eth-sdk"
}

etherscanKeys

Etherscan API keys

Defaults to eth-sdk's own keys.

{
  "etherscanKeys": {
    // API key for https://etherscan.io
    "mainnet": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    // API key for https://polygonscan.com
    "polygon": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
  }
}

etherscanURLs

Key-value pairs of network identifier and Etherscan API URL to fetch ABIs from.

{
  "etherscanURLs": {
    "helloworld": "https://api.etherscan.io/api"
  },
  "contracts": {
    "helloworld": {}
  }
}

rpc

Configuration for Ethereum JSON-RPC provider needed for following proxies.

{
  "rpc": {
    "mainnet": "https://mainnet.infura.io/v3/00000000000000000000000000000000",
    "kovan": "https://kovan.infura.io/v3/00000000000000000000000000000000"
  }
}

For every contract address, eth-sdk checks if it's a proxy, and if it is, it saves the ABI of the implementation contract instead of the ABI of the proxy.

noFollowProxies

You can opt out of proxy following by setting noFollowProxies flag in your config to true.

{
  "noFollowProxies": true
}

abiSource

Default: "etherscan"

One of "etherscan", "sourcify". Specifies the source to fetch contract ABIs from.

networkIds

As Sourcify /files endpoint requires network identifier, you will need to provide one when using a custom network.

{
  "abiSource": "sourcify",
  "networkIds": {
    "myNetwork": 3
  },
  "contracts": {
    "myNetwork": {
      "dai": "0x6b175474e89094c44da98b954eedeac495271d0f"
    }
  }
}

eth-sdk already knows ids of 19 commonly used networks, including mainnet, testnets, Optimism and Arbitrum, so you won't need to provide them. You can find the list of all predefined networks in contracts documentation.

Examples

Check out examples of using eth-sdk in /examples directory.

Videos

Motivation and use cases

The primary motivation for the project is reducing the ceremony needed to interact with smart contracts on Ethereum while using JavaScript or TypeScript. It takes care of boring parts like ABI management and auto-generates all the boilerplate required to set up ethers.js contract instances. Finally, it makes DX great by ensuring that all contracts have type information so your IDE can assist you.

It works well with all sorts of scripts, backend services, and even frontend apps. Note: If you develop smart contracts it's better to use TypeChain directly (especially via HardHat integration).

Contributing

Check out our contributing guidelines.

License

deth (@dethcrypto) MIT