{"id":23790218,"url":"https://github.com/pilagod/ethers-token","last_synced_at":"2025-09-06T08:31:27.085Z","repository":{"id":42863670,"uuid":"506875768","full_name":"pilagod/ethers-token","owner":"pilagod","description":"A token util based on ethers.js to help developers code in a semantic manner.","archived":false,"fork":false,"pushed_at":"2022-07-07T16:19:36.000Z","size":381,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-10T07:57:01.081Z","etag":null,"topics":["erc20","ethereum","ethers","ethers-token","javascript","token","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/pilagod/ethers-token","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pilagod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-24T04:22:45.000Z","updated_at":"2023-10-07T09:37:38.000Z","dependencies_parsed_at":"2022-07-09T01:30:19.705Z","dependency_job_id":null,"html_url":"https://github.com/pilagod/ethers-token","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilagod%2Fethers-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilagod%2Fethers-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilagod%2Fethers-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilagod%2Fethers-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pilagod","download_url":"https://codeload.github.com/pilagod/ethers-token/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232105450,"owners_count":18473304,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["erc20","ethereum","ethers","ethers-token","javascript","token","typescript"],"created_at":"2025-01-01T17:20:10.808Z","updated_at":"2025-01-01T17:20:11.643Z","avatar_url":"https://github.com/pilagod.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ethers-token ![Build Status](https://github.com/pilagod/ethers-token/actions/workflows/ci.yaml/badge.svg?branch=main) [![Coverage Status](https://coveralls.io/repos/github/pilagod/ethers-token/badge.svg?branch=main\u0026kill_cache=1)](https://coveralls.io/github/pilagod/ethers-token?branch=main)\n\nA token util based on [ethers.js](https://github.com/ethers-io/ethers.js) to help developers code in a semantic manner.\n\n## Installation\n\n```bash\n$ npm install ethers-token\n```\n\n## Usage\n\nUse `Factory` to create token constructor:\n\n```typescript\nimport { Factory } from \"ethers-token\"\n\n// Use provider to create factory instance\nconst factory = Factory.use(provider)\n\n// Create native token (e.g., ETH) constructor\nconst ETH = factory.createNativeCtor({\n    // Address is served as placeholder for native token\n    address: \"0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE\",\n    decimals: 18,\n    symbol: \"ETH\",\n})\n\n// Access metadata on native token constructor\nETH.address // 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE\nETH.decimals // 18\nETH.symbol // ETH\n\n// Create ERC20 token constructor\nconst DAI = factory.createERC20Ctor({\n    address: \"0x6B175474E89094C44Da98b954EedeAC495271d0F\",\n    decimals: 18,\n    symbol: \"DAI\",\n})\n\n// Access metadata on ERC20 token constructor\nDAI.abi // ERC20 abi (conforming to [ERC20](https://eips.ethereum.org/EIPS/eip-20))\nDAI.address // 0x6B175474E89094C44Da98b954EedeAC495271d0F\nDAI.decimals // 18\nDAI.symbol // DAI\nDAI.contract // DAI contract (with abi conforming to [ERC20](https://eips.ethereum.org/EIPS/eip-20))\n```\n\nToken constructor is a functional constructor, which means it can be instantiated without `new`. The instance created by token constructor represents specific amount of token, and you can directly treat it as a `BigNumber`. For example:\n\n```typescript\n// Auto translate decimals\nDAI(100).eq(ethers.utils.parseUnits(\"100\", 18))\n\n// Support arithmetic\nDAI(100).add(DAI(50)) // DAI(150)\nDAI(100).sub(DAI(50)) // DAI(50)\nDAI(100).mul(2) // DAI(200)\nDAI(100).div(2) // DAI(50)\n\n// Interact with contract directly\n// Quote 100 USDC for DAI on UniswapV2\nconst USDC = factory.createERC20Ctor({\n    address: \"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\",\n    decimals: 6,\n    symbol: \"USDC\",\n})\nconst [, daiAmountOut] = await UniswapV2Router.getAmountsOut(USDC(100), [\n    USDC.address,\n    DAI.address,\n])\n\n// Be careful that amount received from contract will be plain BigNumber\n// Use `raw` on token constructor to convert plain BigNumber to token instance\nDAI.raw(daiAmountOut)\n\n// `raw` will not translate decimals\nDAI.raw(1).eq(BigNumber.from(1))\n```\n\nMoreover, there are some helpful utils on token constructor and instance. Amounts returned from these utils are all wrapped as token instances:\n\n\u003e All the arguments related to address are typed as [Addressable](https://github.com/pilagod/ethers-token/blob/main/src/address.ts), which accepts address string, object with address property, or instance implements `getAddress` method.\n\n```typescript\n// Utils on native token constructor\nawait ETH.balanceOf(owner)\n\n// Utils on native token instance\nawait ETH(100).from(owner).transfer(spender)\n\n// Utils on ERC20 token constructor\nawait DAI.allowanceOf(owner, spender)\nawait DAI.approveMax(owner, spender)\nawait DAI.balanceOf(owner)\n\n// Utils on ERC20 token instance\nawait DAI(100).from(owner).approve(spender)\nawait DAI(100).from(owner).transfer(spender)\nawait DAI(100).from(spender).transferFrom(owner, spender)\n```\n\n## Advanced Usage\n\nSome ERC20 tokens implement additional methods to extend the ERC20 specification, `ethers-token` also supports token customization:\n\n```typescript\nimport { ERC20 } from \"ethers-token\"\n\n// Define custom ERC20 token class\nclass DAIMintable extends ERC20 {\n    // Extend abi at need\n    public static abi = [\n        ...ERC20.abi,\n        {\n            name: \"mint\",\n            type: \"function\",\n            inputs: [\n                // usr, wad\n            ],\n        },\n    ]\n\n    // Extend utils on token constructor by static function\n    public static async mint(owner: Signer, amount: BigNumberish) {\n        return this.contract\n            .connect(owner)\n            .mint(await owner.getAddress(), amount)\n    }\n\n    // Extend utils on token instance by class function\n    public async mint() {\n        // Access class static props and utils by `this.static\u003cT\u003e(): T`\n        const { contract } = this.static\u003ctypeof ERC20\u003e()\n        const owner = this.mustGetOwner()\n        // Token instance itself is a BigNumber\n        // We can directly pass `this` as amount argument to contract method\n        return contract.connect(owner).mint(owner.address, this)\n    }\n}\n\n// Specify custom ERC20 token class at the first argument\nconst DAI = factory.createERC20Ctor(DAIMintable, {\n    address: \"0x6B175474E89094C44Da98b954EedeAC495271d0F\",\n    decimals: 18,\n    symbol: \"DAI\",\n})\n\n// Use extended utils on token constructor and instance\nawait DAI.mint(owner, DAI(100))\nawait DAI(100).from(owner).mint()\n```\n\n## License\n\n© Cyan Ho (pilagod), 2022-NOW\n\nReleased under the [MIT License](https://github.com/pilagod/ethers-token/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilagod%2Fethers-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpilagod%2Fethers-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilagod%2Fethers-token/lists"}