{"id":20660912,"url":"https://github.com/exweb3/elixir_ethers","last_synced_at":"2025-05-16T03:02:25.482Z","repository":{"id":153356025,"uuid":"538766924","full_name":"ExWeb3/elixir_ethers","owner":"ExWeb3","description":"A comprehensive Web3 library for interacting with smart contracts on Ethereum using Elixir.","archived":false,"fork":false,"pushed_at":"2025-05-09T17:36:44.000Z","size":778,"stargazers_count":111,"open_issues_count":6,"forks_count":22,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-10T03:14:41.290Z","etag":null,"topics":["blockchain","elixir","ethereum","ethereum-rpc","evm","smart-contracts","web3"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/ethers","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ExWeb3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-20T01:47:55.000Z","updated_at":"2025-05-09T17:35:25.000Z","dependencies_parsed_at":"2023-11-18T22:24:15.716Z","dependency_job_id":"8bca5d06-14c1-482e-b74f-4df384f0336c","html_url":"https://github.com/ExWeb3/elixir_ethers","commit_stats":null,"previous_names":["exweb3/elixir_ethers","alisinabh/elixir_ethers"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExWeb3%2Felixir_ethers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExWeb3%2Felixir_ethers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExWeb3%2Felixir_ethers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExWeb3%2Felixir_ethers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ExWeb3","download_url":"https://codeload.github.com/ExWeb3/elixir_ethers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301814,"owners_count":22047970,"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":["blockchain","elixir","ethereum","ethereum-rpc","evm","smart-contracts","web3"],"created_at":"2024-11-16T19:06:30.541Z","updated_at":"2025-05-16T03:02:25.474Z","avatar_url":"https://github.com/ExWeb3.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg height=\"120\" align=\"left\" src=\"https://github.com/ExWeb3/elixir_ethers/raw/main/assets/ethers_logo.png\" alt=\"Ethers Elixir\"\u003e\n\n# Elixir Ethers\n\n[![example workflow](https://github.com/ExWeb3/elixir_ethers/actions/workflows/elixir.yml/badge.svg)](https://github.com/ExWeb3/elixir_ethers)\n[![Coverage Status](https://coveralls.io/repos/github/ExWeb3/elixir_ethers/badge.svg?branch=main)](https://coveralls.io/github/ExWeb3/elixir_ethers?branch=main)\n[![Module Version](https://img.shields.io/hexpm/v/ethers.svg)](https://hex.pm/packages/ethers)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ethers/)\n[![License](https://img.shields.io/hexpm/l/ethers.svg)](https://github.com/ExWeb3/elixir_ethers/blob/master/LICENSE.md)\n[![Last Updated](https://img.shields.io/github/last-commit/ExWeb3/elixir_ethers.svg)](https://github.com/ExWeb3/elixir_ethers/commits/main)\n\nEthers is a powerful Web3 library for Elixir that makes interacting with Ethereum and other\nEVM-based blockchains simple and intuitive.\nIt leverages Elixir's metaprogramming capabilities to provide a seamless developer experience.\n\n## Key Features\n\n- **Smart Contract Integration**: Generate Elixir modules from contract ABIs with full documentation\n- **Built-in Contracts**: Ready-to-use interfaces for [ERC20](https://hexdocs.pm/ethers/Ethers.Contracts.ERC20.html), [ERC721](https://hexdocs.pm/ethers/Ethers.Contracts.ERC721.html), [ERC1155](https://hexdocs.pm/ethers/Ethers.Contracts.ERC1155.html), and more\n- **Multi-chain Support**: Works with any EVM-compatible blockchain\n- **Flexible Signing**: Extensible signer support with [built-in ones](https://hexdocs.pm/ethers/readme.html#signing-transactions)\n- **Event Handling**: Easy filtering and retrieval of blockchain events\n- **Multicall Support**: Ability to easily perform multiple `eth_call`s using [Multicall 2/3](https://hexdocs.pm/ethers/Ethers.Multicall.html)\n- **Type Safety**: Native Elixir types for all contract interactions\n- **ENS Support**: Out of the box [Ethereum Name Service (ENS)](https://ens.domains/) support\n- **Comprehensive Documentation**: Auto-generated docs for all contract functions\n\n## Installation\n\nAdd `ethers` to your dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:ethers, \"~\u003e 0.6.7\"},\n    # Uncomment next line if you want to use local signers\n    # {:ex_secp256k1, \"~\u003e 0.7.2\"}\n  ]\nend\n```\n\nFor upgrading from versions prior to `0.6.0`, see our [Upgrade Guide](guides/upgrading.md).\n\n## Quick Start\n\n1. **Configure your RPC endpoint**:\n\n```elixir\n# config/config.exs\nconfig :ethereumex, url: \"https://eth.llamarpc.com\"\n```\n\n2. **Create a contract module**:\n\n```elixir\ndefmodule MyContract do\n  use Ethers.Contract,\n    abi_file: \"path/to/abi.json\",\n    default_address: \"0x...\" # Optional contract address\nend\n```\n\n3. **Start interacting with the blockchain**:\n\n```elixir\n# Read contract state\n{:ok, result} =\n  MyContract.my_function(\"0x...\")\n  |\u003e Ethers.call()\n\n# Send a transaction\n{:ok, tx_hash} =\n  MyToken.my_function(\"0x...\", 1000)\n  |\u003e Ethers.send_transaction(from: \"0x...\")\n```\n\nRead full documentation of Ethers for detailed information at [HexDocs](https://hexdocs.pm/ethers).\n\n## Common Use Cases\n\n### Reading Contract State\n\n```elixir\n{:ok, erc20_symbol} =\n  Ethers.Contracts.ERC20.symbol()\n  |\u003e Ethers.call()\n\n# With parameters\n{:ok, balance} =\n  Ethers.Contracts.ERC20.balance_of(\"0x[Wallet]\")\n  |\u003e Ethers.call()\n```\n\nSee `Ethers.Multicall` if you want to perform multiple calls in a single\neth_call request.\n\n### Writing to Contracts\n\n```elixir\n# Simple transaction\n{:ok, tx_hash} =\n  MyContract.set_value(123)\n  |\u003e Ethers.send_transaction(from: address)\n\n# With Ether (chain native token) transfer (value is in wei)\n{:ok, tx_hash} =\n  MyContract.deposit()\n  |\u003e Ethers.send_transaction(from: address, value: 1_000_000)\n```\n\n### Working with Events\n\n```elixir\n# Create an event filter (nil = any)\nfilter = MyToken.EventFilters.transfer(from_address, nil)\n\n# Get matching events\n{:ok, events} = Ethers.get_logs(filter)\n```\n\n## Documentation\n\nComplete API documentation is available at [HexDocs](https://hexdocs.pm/ethers).\n\n- [Configuration Guide](guides/configuration.md) - Detailed configuration options\n- [Upgrade Guide](guides/upgrading.md) - Version upgrade instructions\n- [Built-in Contracts](#built-in-contract-interfaces-in-ethers) - Standard contract interfaces\n\n## Configuration\n\nTo get started with Ethers, you'll need to configure a JSON-RPC endpoint. Here's a minimal configuration:\n\n```elixir\n# Configure the JSON-RPC endpoint URL\nconfig :ethereumex, url: \"https://your-ethereum-node.com\"\n```\n\nYou can use one of the RPC URLs for your chain/wallet of choice or try out one from\n[chainlist.org](https://chainlist.org/).\n\nFor detailed configuration options, environment-specific setups, best practices, and\ntroubleshooting, please refer to our [Configuration Guide](guides/configuration.md).\n\n## Custom ABIs\n\nTo use Elixir Ethers, you must have your contract's ABI in json format, which can be obtained from\n[etherscan.io](https://etherscan.io). This library also contains standard contract interfaces such\nas `ERC20`, `ERC721` and some more by default (refer to built-in contracts in\n[hexdocs](https://hexdocs.pm/ethers)).\n\nCreate a module for your contract as follows:\n\n```elixir\ndefmodule MyContract do\n  use Ethers.Contract,\n    abi_file: \"path/to/abi.json\",\n    default_address: \"0x[Contract address here (optional)]\"\n\n  # You can also add more code here in this module if you wish\nend\n```\n\n### Calling contract functions\n\nAfter defining the module, all the functions can be called like any other Elixir module. These\nfunctions will return an `Ethers.TxData` struct which can be used later on to perform on-chain\ncalls or send transactions.\n\nTo fetch the results (return value(s)) of a function you can pass your function result to the\n[`Ethers.call/2`](https://hexdocs.pm/ethers/Ethers.html#call/2) function.\n\n#### Example\n\n```elixir\n# Calling functions on the blockchain\niex\u003e MyContract.balance_of(\"0x[Address]\") |\u003e Ethers.call()\n{:ok, 654294510138460920346}\n```\n\nRefer to [Ethers.call/2](https://hexdocs.pm/ethers/Ethers.html#call/2) for more information.\n\n### Sending transaction\n\nTo send transaction (eth_sendTransaction) to the blockchain, you can use the\n[`Ethers.send_transaction/2`](https://hexdocs.pm/ethers/Ethers.html#send_transaction/2) function.\n\nEnsure that you specify a `from` option to inform your client which account to use as the signer:\n\n#### Example\n\n```elixir\niex\u003e MyContract.transfer(\"0x[Recipient]\", 1000) |\u003e Ethers.send_transaction(from: \"0x[Sender]\")\n{:ok, \"0xf313ff7ff54c6db80ad44c3ad58f72ff0fea7ce88e5e9304991ebd35a6e76000\"}\n```\n\nRefer to [Ethers.send_transaction/2](https://hexdocs.pm/ethers/Ethers.html#send_transaction/2) for more information.\n\n### Getting Logs (Events)\n\nEthers provides functionality for creating event filters and fetching related events from the\nblockchain. Each contract generated by Ethers also will have `EventFilters` module\n(e.g. `MyERC20Token.EventFilters`) that can be used to create filters for events.\n\nTo create an event filter and then use\n[`Ethers.get_logs/2`](https://hexdocs.pm/ethers/Ethers.html#get_logs/2) function like the below\nexample.\n\n#### Example\n\n```elixir\n# Create The Event Filter\n# (`nil` can be used for a parameter in EventFilters functions to indicate no filtering)\niex\u003e filter = MyContract.EventFilters.transfer(\"0x[From Address Here]\", nil)\n\n# Then you can simply list the logs using `Ethers.get_logs/2`\n\niex\u003e Ethers.get_logs(filter)\n{:ok,\n [\n   %Ethers.Event{\n     address: \"0x5883c66ca442461d406f330775d42954bfcf7d92\",\n     block_hash: \"0x83de67fd285067b838790406ea68f21a3afbc0ade534047725b5ccfb904c9ed3\",\n     block_number: 17077047,\n     topics: [\"Transfer(address,address,uint256)\",\n      \"0x6b75d8af000000e20b7a7ddf000ba900b4009a80\",\n      \"0x230507f6a391ae5ac0ec124f1c5b8ce454fe3f3d\"],\n     topics_raw: [\"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\n      \"0x0000000000000000000000006b75d8af000000e20b7a7ddf000ba900b4009a80\",\n      \"0x000000000000000000000000230507f6a391ae5ac0ec124f1c5b8ce454fe3f3d\"],\n     transaction_hash: \"0xaa6fb2e1bbb27f667e76b03e8cde23db694207e06b9aa810d4c20c1f109a58e5\",\n     transaction_index: 0,\n     data: [761112156078097834180608],\n     log_index: 0,\n     removed: false\n   },\n   %Ethers.Event{...},\n    ...\n ]}\n```\n\n### Resolving Ethereum names (ENS domains) using Ethers\n\nTo resolve ENS or any other name service provider (which are ENS compatible) in the blockchain\nyou can simply use [`Ethers.NameService`](https://hexdocs.pm/ethers/Ethers.NameService.html) module.\n\n```elixir\niex\u003e Ethers.NameService.resolve(\"vitalik.eth\")\n{:ok, \"0xd8da6bf26964af9d7eed9e03e53415d37aa96045\"}\n```\n\n### Built-in contract ABIs in Ethers\n\nEthers already includes some of the well-known contract interface standards for you to use.\nHere is a list of them.\n\n- [ERC20](https://hexdocs.pm/ethers/Ethers.Contracts.ERC20.html) - The well know fungible token standard\n- [ERC165](https://hexdocs.pm/ethers/Ethers.Contracts.ERC165.html) - Standard Interface detection\n- [ERC721](https://hexdocs.pm/ethers/Ethers.Contracts.ERC721.html) - Non-Fungible tokens (NFTs) standard\n- [ERC777](https://hexdocs.pm/ethers/Ethers.Contracts.ERC777.html) - Improved fungible token standard\n- [ERC1155](https://hexdocs.pm/ethers/Ethers.Contracts.ERC1155.html) - Multi-Token standard (Fungible, Non-Fungible or Semi-Fungible)\n- [Multicall](https://hexdocs.pm/ethers/Ethers.Multicall.html) - [Multicall3](https://www.multicall3.com/)\n\nTo use them you just need to specify the target contract address (`:to` option) of your token and\ncall the functions. Example:\n\n```elixir\niex\u003e tx_data = Ethers.Contracts.ERC20.balance_of(\"0x[Holder Address]\")\n#Ethers.TxData\u003c\n  function balanceOf(\n    address _owner \"0x[Holder Address]\"\n  ) view returns (\n    uint256 balance\n  )\n\u003e\n\niex\u003e Ethers.call(tx_data, to: \"0x[Token Address]\")\n{:ok, 123456}\n```\n\n### Generated documentation for functions and event filters\n\nEthers generates documentation for all the functions and event filters based on the ABI data.\nTo get the documentation you can either use the `h/1` IEx helper function or generate HTML/epub\ndocs using ExDoc.\n\n#### Get the documentation of a contract function\n\n```elixir\niex(3)\u003e h MyERC20Token.balance_of\n\n                             def balance_of(owner)\n\n  @spec balance_of(Ethers.Types.t_address()) :: Ethers.TxData.t()\n\nPrepares balanceOf(address _owner) call parameters on the contract.\n\nThis function should only be called for result and never in a transaction on\nits own. (Use Ethers.call/2)\n\nState mutability: view\n\n## Function Parameter Types\n\n  • _owner: `:address`\n\n## Return Types (when called with `Ethers.call/2`)\n\n  • balance: {:uint, 256}\n```\n\n#### Inspecting TxData and EventFilter structs\n\nOne cool and potentially useful feature of Ethers is how you can inspect the call\n\n#### Get the documentation of a event filter\n\n```elixir\niex(4)\u003e h MyERC20Token.EventFilters.transfer\n\n                             def transfer(from, to)\n\n  @spec transfer(Ethers.Types.t_address(), Ethers.Types.t_address()) ::\n          Ethers.EventFilter.t()\n\nCreate event filter for Transfer(address from, address to, uint256 value)\n\nFor each indexed parameter you can either pass in the value you want to filter\nor nil if you don't want to filter.\n\n## Parameter Types (Event indexed topics)\n\n  • from: :address\n  • to: :address\n\n## Event `data` Types (when called with `Ethers.get_logs/2`)\n\nThese are non-indexed topics (often referred to as data) of the event log.\n\n  • value: {:uint, 256}\n```\n\n## Signing Transactions\n\nBy default, Ethers will rely on the default blockchain endpoint to handle the signing (using `eth_sendTransaction` RPC function). Obviously public endpoints cannot help you with signing the transactions since they do not hold your private keys.\n\nTo sign transactions on Ethers, You can specify a `signer` module when sending/signing transactions. A signer module is a module which implements the [Ethers.Signer](lib/ethers/signer.ex) behaviour.\n\nEthers has these built-in signers to use:\n\n- `Ethers.Signer.Local`: A local signer which loads a private key from `signer_opts` and signs the transactions.\n- `Ethers.Signer.JsonRPC`: Uses `eth_signTransaction` Json RPC function to sign transactions. (Using services like [Consensys/web3signer](https://github.com/Consensys/web3signer) or [geth](https://geth.ethereum.org/))\n\nFor more information on signers, visit [hexdocs](https://hexdocs.pm/ethers/Ethers.Signer.html).\n\n### Example\n\n```elixir\nMyERC20Token.transfer(\"0x[Recipient]\", 1000)\n|\u003e Ethers.send_transaction(\n  from: \"0x[Sender]\",\n  signer: Ethers.Signer.Local,\n  signer_opts: [private_key: \"0x...\"]\n)\n```\n\n## Switching the ex_keccak library\n\n`ex_keccak` is a Rustler NIF that brings keccak256 hashing to elixir.\nIt is the default used library in `ex_abi` and `ethers`. If for some reason you need to use a\ndifferent library (e.g. target does not support rustler) you can use the Application config value\nand on top of that set the environment variable `SKIP_EX_KECCAK=true` so ex_keccak is marked as\noptional in hex dependencies.\n\n```elixir\n# config.exs\nconfig :ethers, keccak_module: MyKeccakModule\n\n# Also make sure to set SKIP_EX_KECCAK=true when fetching dependencies and building them\n```\n\n## Contributing\n\nAll contributions are very welcome (as simple as fixing typos). Please feel free to open issues and\npush Pull Requests. Just remember to be respectful to everyone!\n\nTo run the tests locally, follow below steps:\n\n- Install [ethereum](https://geth.ethereum.org/docs/getting-started/installing-geth) and [solc](https://docs.soliditylang.org/en/latest/installing-solidity.html). For example, on MacOS\n\n```\nbrew install ethereum\nnpm install -g solc\n```\n\n- Run [anvil (from foundry)](https://book.getfoundry.sh/getting-started/installation).\n  After installing anvil, just run the following in a new window\n\n```\n\u003e anvil\n```\n\n- Prepare the tests (only needs to be ran once)\n\n```\n\u003e mix run test/test_prepare.exs\n```\n\nThen you should be able to run tests through `mix test`.\n\n## Acknowledgements\n\nEthers was possible to make thanks to the great contributors of the following libraries.\n\n- [ABI](https://github.com/poanetwork/ex_abi)\n- [Ethereumex](https://github.com/mana-ethereum/ethereumex)\n- [ExKeccak](https://github.com/tzumby/ex_keccak)\n\nAnd also all the people who contributed to this project in any ways.\n\n## License\n\n[Apache License 2.0](https://github.com/ExWeb3/elixir_ethers/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexweb3%2Felixir_ethers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexweb3%2Felixir_ethers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexweb3%2Felixir_ethers/lists"}