Generate type-safe, lightweight SDK for your Ethereum smart contracts
\n
The quickest and easiest way to interact with Ethereum
\n\n\n
Features âš¡
\n\n- minimal - just provide addresses of contracts that you wish to interact with\n- easy to use - ABIs will be automatically downloaded from Etherscan\n- familiar API - Generates ethers.js contract wrappers\n- type-safe - Leverages TypeChain for maximum type-safety\n\n## Fork notice\n\nThis is a community fork of [@dethcrypto/eth-sdk](https://github.com/dethcrypto/eth-sdk) for making it ethers v6\ncompatible.\n\neth-sdk has been created and maintained by deth (@dethcrypto).\n\n### License\n\ndeth (@dethcrypto) MIT\n\nwith contributions by Gnosis Guild (@gnosisguild) MIT\n\n---\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [CLI Options](#cli-options)\n - [Getting started](#getting-started)\n - [Configuration](#configuration)\n - [`contracts`](#contracts)\n - [`outputPath`](#outputpath)\n- [Examples](#examples)\n - [Videos](#videos)\n- [Motivation and use cases](#motivation-and-use-cases)\n- [Contributing](#contributing)\n- [License](#license)\n\n# Installation\n\n```\nyarn add --dev @gnosis-guild/eth-sdk @gnosis-guild/eth-sdk-client\n```\n\n`eth-sdk` uses ethers v6 and TypeScript, so these dependencies have to be installed as well.\n\n# Usage\n\n```bash\neth-sdk [options]\n```\n\n## CLI Options\n\nOptions:\n\n- `-p, --path ` working directory (default: `./eth-sdk`)\n\n `eth-sdk` looks for the config file in this directory, and saves downloaded ABIs there.\n\n## Getting started\n\n`eth-sdk` takes a JSON config file with ethereum addresses and generates a fully type-safe SDK that you can use right\naway. The SDK is an object consisting of ethers.js contracts initialized with ABIs provided by etherscan and with types\ngenerated via TypeChain.\n\nThe first step is to create a config file specifying contracts that we wish to interact with. Default path to this file\nis `eth-sdk/config.ts`.\n\n```ts\nimport { defineConfig } from '@gnosis-guild/eth-sdk'\n\nexport default defineConfig({\n contracts: {\n mainnet: {\n dai: '0x6b175474e89094c44da98b954eedeac495271d0f',\n },\n },\n})\n```\n\nThe key directly under `\"contracts\"` is a network identifier, `eth-sdk` needs it to query ABI information automatically.\nFollowing are key-value pairs of contract names and addresses. These can be deeply nested.\n\nNow you're ready to run `yarn eth-sdk`. Few things will happen under the hood:\n\n1. Etherscan API will be queried in search of ABIs corresponding to the addresses. ABIs will be downloaded into\n `eth-sdk` directory (you should commit them to git to speed up the process in the future).\n2. Minimal SDK will be generated with functions like `getMainnetSdk` exposed. These functions wire addresses with ABIs\n and create ethers.js contract instances.\n3. TypeScript types will be generated for SDK using TypeChain.\n4. SDK is generated directly into `node_modules`, access it as `@gnosis-guild/eth-sdk-client`.\n\nUsing generated sdk is as simple as it gets:\n\n```typescript\nimport { getMainnetSdk } from '@gnosis-guild/eth-sdk-client' // yay, our SDK! It's tailored especially for our needs\nimport { ethers } from 'ethers'\n\nasync function main() {\n const mainnetProvider = ethers.getDefaultProvider('mainnet')\n const defaultSigner = ethers.Wallet.createRandom().connect(mainnetProvider)\n\n const sdk = getMainnetSdk(defaultSigner) // default signer will be wired with all contract instances\n // sdk is an object like { dai: DaiContract }\n\n const balance = sdk.dai.balanceOf(defaultSigner.address)\n}\n\nmain()\n .then(() => console.log('DONE'))\n .catch((error) => {\n console.error(error)\n process.exit(1)\n })\n```\n\n## Configuration\n\n`eth-sdk` looks for a file named `config` or `eth-sdk.config` with `.ts`, `.json`, `.js` or `.cjs` extension inside of\nthe directory specified by `--path` CLI argument.\n\nYou can use exports from `@gnosis-guild/eth-sdk` to leverage your IDE's intellisense. Exported types are `EthSdkConfig`,\n`EthSdkContracts`, `NestedAddresses` and `Address`.\n\n```ts\nimport type { EthSdkConfig } from '@gnosis-guild/eth-sdk'\nconst config: EthSdkConfig = {\n // ...\n}\nexport default config\n```\n\nAlternatively, you can use `defineConfig` function to write your config in a typesafe way without need for annotations.\n\n```ts\nimport { defineConfig } from '@gnosis-guild/eth-sdk'\nexport default defineConfig({\n // ...\n})\n```\n\n### `contracts`\n\nA map from network identifier into deeply nested key-value pairs of contract names and addresses.\n\n```json\n{\n \"contracts\": {\n \"eth\": {\n \"dai\": \"0x6b175474e89094c44da98b954eedeac495271d0f\",\n \"dao\": {\n \"mkr\": \"0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2\"\n }\n }\n }\n}\n```\n\nSupported network identifiers are:\n\n```\n\"eth\" \"holesky\" \"sep\"\n\"gno\" \"base\" \"basesep\"\n\"bsc\" \"oeth\" \"matic\"\n\"arb1\" \"avax\" \"celo\"\n\"sonic\" \"berachain\" \"mantle\"\n\"zkevm\" \"unichain\" \"wc\"\n\"bob\" \"hemi\" \"katana\"\n\"linea\" \"ink\" \"blast\"\n\"flare\"\n```\n\n### `outputPath`\n\nOutput directory for generated SDK.\n\n**Defaults to `./node_modules/.gnosisguild/eth-sdk`**\n\n```json\n{\n \"outputPath\": \"./node_modules/.gnosisguild/eth-sdk\"\n}\n```\n\n# Examples\n\nCheck out examples of using `eth-sdk` in [`/examples`][examples] directory.\n\n- [Hardhat example](https://github.com/gnosisguild/eth-sdk/tree/master/examples/hardhat)\n- [Vite + React example](https://github.com/gnosisguild/eth-sdk/tree/master/examples/vite-react)\n\n[examples]: https://github.com/gnosisguild/eth-sdk/tree/master/examples\n\n## Videos\n\n- [EthGlobal's DevSummit (2021)](https://www.youtube.com/watch?v=G5URGgZQ9do)\n\n# Motivation and use cases\n\nThe primary motivation for the project is reducing the ceremony needed to interact with smart contracts on Ethereum\nwhile using JavaScript or TypeScript. It takes care of boring parts like ABI management and auto-generates all the\nboilerplate required to set up ethers.js contract instances. Finally, it makes DX great by ensuring that all contracts\nhave type information so your IDE can assist you.\n\nIt works well with all sorts of scripts, backend services, and even frontend apps. Note: If you develop smart contracts\nit's better to use TypeChain directly (especially via HardHat integration).\n\n# Contributing\n\nCheck out our [contributing guidelines](./CONTRIBUTING.md).\n","readmeFilename":"README.md","_rev":"1-127bd5f904da4bee59334e8d926afe20"}
![\"\"](\"https://github.com/gnosisguild/eth-sdk/blob/master/docs/logo.png?raw=true\"){kind=logo}
\n