{"id":13509492,"url":"https://github.com/mana-ethereum/ethereumex","last_synced_at":"2025-12-12T00:30:45.210Z","repository":{"id":40404364,"uuid":"93236142","full_name":"mana-ethereum/ethereumex","owner":"mana-ethereum","description":"Elixir JSON-RPC client for the Ethereum blockchain","archived":false,"fork":false,"pushed_at":"2023-12-12T19:10:14.000Z","size":364,"stargazers_count":374,"open_issues_count":8,"forks_count":69,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-05-01T14:58:43.709Z","etag":null,"topics":["elixir","ethereum","ethereum-client","json-rpc"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/mana-ethereum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-03T08:50:10.000Z","updated_at":"2024-04-25T01:33:13.000Z","dependencies_parsed_at":"2023-02-10T05:45:53.195Z","dependency_job_id":"5152362e-860c-48fc-b89b-1231823eb95f","html_url":"https://github.com/mana-ethereum/ethereumex","commit_stats":null,"previous_names":["exthereum/ethereumex"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mana-ethereum%2Fethereumex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mana-ethereum%2Fethereumex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mana-ethereum%2Fethereumex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mana-ethereum%2Fethereumex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mana-ethereum","download_url":"https://codeload.github.com/mana-ethereum/ethereumex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246324044,"owners_count":20759067,"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":["elixir","ethereum","ethereum-client","json-rpc"],"created_at":"2024-08-01T02:01:08.551Z","updated_at":"2025-12-12T00:30:45.168Z","avatar_url":"https://github.com/mana-ethereum.png","language":"Elixir","funding_links":[],"categories":["Third Party APIs","Roadmap","Elixir"],"sub_categories":[],"readme":"# Ethereumex\n\n[![Module Version](https://img.shields.io/hexpm/v/ethereumex.svg)](https://hex.pm/packages/ethereumex)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ethereumex/)\n[![Total Download](https://img.shields.io/hexpm/dt/ethereumex.svg)](https://hex.pm/packages/ethereumex)\n[![License](https://img.shields.io/hexpm/l/ethereumex.svg)](https://github.com/mana-ethereum/ethereumex/blob/master/LICENSE.md)\n[![Last Updated](https://img.shields.io/github/last-commit/mana-ethereum/ethereumex.svg)](https://github.com/mana-ethereum/ethereumex/commits/master)\n\n\u003c!-- MDOC !--\u003e\n\nElixir JSON-RPC client for the Ethereum blockchain.\n\nCheck out the documentation [here](https://hexdocs.pm/ethereumex/Ethereumex.html#content).\n\n## Installation\n\nAdd `:ethereumex` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:ethereumex, \"~\u003e 0.12.1\"},\n    # json library is configurable\n    {:jason, \"~\u003e 1.4\"}\n  ]\nend\n```\n\n## Configuration\n\n### HTTP\n\nIn `config/config.exs`, add Ethereum protocol host params to your config file\n\n```elixir\nconfig :ethereumex,\n  url: \"http://localhost:8545\"\n```\n\nYou can also configure the `HTTP` request timeout for requests sent to the Ethereum JSON-RPC\n(you can also overwrite this configuration in `opts` used when calling the client).\n\n```elixir\nconfig :ethereumex,\n  http_options: [pool_timeout: 5000, receive_timeout: 15_000],\n  http_headers: [{\"Content-Type\", \"application/json\"}]\n```\n\n`:pool_timeout` - This timeout is applied when we check out a connection from the pool. Default value is `5_000`.\n`:receive_timeout` - The maximum time to wait for a response before returning an error. Default value is `15_000`\n`:enable_request_error_logs` - Optional request error logs. Default value is false\n\n### IPC\n\nIf you want to use IPC you will need to set a few things in your config.\n\nFirst, specify the `:client_type`:\n\n```elixir\nconfig :ethereumex,\n  client_type: :ipc\n```\n\nThis will resolve to `:http` by default.\n\nSecond, specify the `:ipc_path`:\n\n```elixir\nconfig :ethereumex,\n  ipc_path: \"/path/to/ipc\"\n```\n\nThe IPC client type mode opens a pool of connection workers (default is 5 and 2, respectively). You can configure the pool size.\n\n```elixir\nconfig :ethereumex,\n  ipc_worker_size: 5,\n  ipc_max_worker_overflow: 2,\n  ipc_request_timeout: 60_000\n```\n\n### WebSocket\n\nThe WebSocket client supports both standard JSON-RPC requests and real-time subscriptions.\nTo use it, configure your application with:\n\n```elixir\nconfig :ethereumex,\n  websocket_url: \"ws://localhost:8545\",\n  client_type: :websocket\n```\n\n#### Standard RPC Calls\n\nAll standard RPC methods work the same as with HTTP:\n\n```elixir\niex\u003e Ethereumex.WebsocketClient.eth_block_number()\n{:ok, \"0x1234\"}\n```\n\n#### Real-time Subscriptions\n\nSubscribe to various blockchain events:\n\n```elixir\n# Subscribe to new block headers\niex\u003e {:ok, subscription_id} = Ethereumex.WebsocketClient.subscribe(:newHeads)\n{:ok, \"0x9cef478923ff08bf67fde6c64013158d\"}\n\n# Subscribe to logs/events from specific contracts\niex\u003e filter = %{\n...\u003e   address: \"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd\",\n...\u003e   topics: [\"0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902\"]\n...\u003e }\niex\u003e {:ok, subscription_id} = Ethereumex.WebsocketClient.subscribe(:logs, filter)\n{:ok, \"0x4a8a4c0517381924f9838102c5a4dcb7\"}\n\n# Subscribe to pending transactions\niex\u003e {:ok, subscription_id} = Ethereumex.WebsocketClient.subscribe(:newPendingTransactions)\n{:ok, \"0x1234567890abcdef1234567890abcdef\"}\n\n# Receive notifications in your process\nreceive do\n  %{\n    \"method\" =\u003e \"eth_subscription\",\n    \"params\" =\u003e %{\n      \"subscription\" =\u003e subscription_id,\n      \"result\" =\u003e result\n    }\n  } -\u003e handle_notification(result)\nend\n\n# Unsubscribe when done\niex\u003e Ethereumex.WebsocketClient.unsubscribe(subscription_id)\n{:ok, true}\n```\n\nAvailable subscription types:\n\n- `:newHeads` - New block headers\n- `:logs` - Contract events/logs with optional filtering\n- `:newPendingTransactions` - Pending transaction hashes\n\n### Telemetry\n\nIf you want to count the number of RPC calls per RPC method or overall,\nyou can attach yourself to executed telemetry events.\nThere are two events you can attach yourself to:\n`[:ethereumex]` # has RPC method name in metadata\nEmitted event: `{:event, [:ethereumex], %{counter: 1}, %{method_name: \"method_name\"}}`\n\nor more granular\n`[:ethereumex, \u003crpc_method\u003e]` # %{} metadata\nEmitted event: `{:event, [:ethereumex, :method_name_as_atom], %{counter: 1}, %{}}`\n\nEach event caries a single ticker that you can pass into your counters (like `Statix.increment/2`).\nBe sure to add :telemetry as project dependency.\n\n\n### Json library\n\nThe default json library is set to `jason` but that can be overridden with a different module. The module should implement functions `encode/1`, `decode/2`, `encode!/`, `decode!/1`\n\n```elixir\nconfig :ethereumex, json_module: MyCustomJson\n```\n\n## Test\n\nDownload `parity` and initialize the password file\n\n```\n$ make setup\n```\n\nRun `parity`\n\n```\n$ make run\n```\n\nRun tests\n\n```\n$ make test\n```\n\n## Usage\n\n### Available methods:\n\n- [`web3_clientVersion`](https://eth.wiki/json-rpc/API#web3_clientversion)\n- [`web3_sha3`](https://eth.wiki/json-rpc/API#web3_sha3)\n- [`net_version`](https://eth.wiki/json-rpc/API#net_version)\n- [`net_peerCount`](https://eth.wiki/json-rpc/API#net_peercount)\n- [`net_listening`](https://eth.wiki/json-rpc/API#net_listening)\n- [`eth_protocolVersion`](https://eth.wiki/json-rpc/API#eth_protocolversion)\n- [`eth_syncing`](https://eth.wiki/json-rpc/API#eth_syncing)\n- [`eth_coinbase`](https://eth.wiki/json-rpc/API#eth_coinbase)\n- [`eth_chainId`](https://eth.wiki/json-rpc/API#eth_chainId)\n- [`eth_mining`](https://eth.wiki/json-rpc/API#eth_mining)\n- [`eth_hashrate`](https://eth.wiki/json-rpc/API#eth_hashrate)\n- [`eth_gasPrice`](https://eth.wiki/json-rpc/API#eth_gasprice)\n- [`eth_accounts`](https://eth.wiki/json-rpc/API#eth_accounts)\n- [`eth_blockNumber`](https://eth.wiki/json-rpc/API#eth_blocknumber)\n- [`eth_getBalance`](https://eth.wiki/json-rpc/API#eth_getbalance)\n- [`eth_getStorageAt`](https://eth.wiki/json-rpc/API#eth_getstorageat)\n- [`eth_getTransactionCount`](https://eth.wiki/json-rpc/API#eth_gettransactioncount)\n- [`eth_getBlockTransactionCountByHash`](https://eth.wiki/json-rpc/API#eth_getblocktransactioncountbyhash)\n- [`eth_getBlockTransactionCountByNumber`](https://eth.wiki/json-rpc/API#eth_getblocktransactioncountbynumber)\n- [`eth_getUncleCountByBlockHash`](https://eth.wiki/json-rpc/API#eth_getunclecountbyblockhash)\n- [`eth_getUncleCountByBlockNumber`](https://eth.wiki/json-rpc/API#eth_getunclecountbyblocknumber)\n- [`eth_getCode`](https://eth.wiki/json-rpc/API#eth_getcode)\n- [`eth_sign`](https://eth.wiki/json-rpc/API#eth_sign)\n- [`eth_sendTransaction`](https://eth.wiki/json-rpc/API#eth_sendtransaction)\n- [`eth_sendRawTransaction`](https://eth.wiki/json-rpc/API#eth_sendrawtransaction)\n- [`eth_call`](https://eth.wiki/json-rpc/API#eth_call)\n- [`eth_estimateGas`](https://eth.wiki/json-rpc/API#eth_estimategas)\n- [`eth_getBlockByHash`](https://eth.wiki/json-rpc/API#eth_getblockbyhash)\n- [`eth_getBlockByNumber`](https://eth.wiki/json-rpc/API#eth_getblockbynumber)\n- [`eth_getTransactionByHash`](https://eth.wiki/json-rpc/API#eth_gettransactionbyhash)\n- [`eth_getTransactionByBlockHashAndIndex`](https://eth.wiki/json-rpc/API#eth_gettransactionbyblockhashandindex)\n- [`eth_getTransactionByBlockNumberAndIndex`](https://eth.wiki/json-rpc/API#eth_gettransactionbyblocknumberandindex)\n- [`eth_getTransactionReceipt`](https://eth.wiki/json-rpc/API#eth_gettransactionreceipt)\n- [`eth_getUncleByBlockHashAndIndex`](https://eth.wiki/json-rpc/API#eth_getunclebyblockhashandindex)\n- [`eth_getUncleByBlockNumberAndIndex`](https://eth.wiki/json-rpc/API#eth_getunclebyblocknumberandindex)\n- [`eth_getCompilers`](https://eth.wiki/json-rpc/API#eth_getcompilers)\n- [`eth_compileLLL`](https://eth.wiki/json-rpc/API#eth_compilelll)\n- [`eth_compileSolidity`](https://eth.wiki/json-rpc/API#eth_compilesolidity)\n- [`eth_compileSerpent`](https://eth.wiki/json-rpc/API#eth_compileserpent)\n- [`eth_newFilter`](https://eth.wiki/json-rpc/API#eth_newfilter)\n- [`eth_newBlockFilter`](https://eth.wiki/json-rpc/API#eth_newblockfilter)\n- [`eth_newPendingTransactionFilter`](https://eth.wiki/json-rpc/API#eth_newpendingtransactionfilter)\n- [`eth_uninstallFilter`](https://eth.wiki/json-rpc/API#eth_uninstallfilter)\n- [`eth_getFilterChanges`](https://eth.wiki/json-rpc/API#eth_getfilterchanges)\n- [`eth_getFilterLogs`](https://eth.wiki/json-rpc/API#eth_getfilterlogs)\n- [`eth_getLogs`](https://eth.wiki/json-rpc/API#eth_getlogs)\n- eth_getProof\n- [`eth_getWork`](https://eth.wiki/json-rpc/API#eth_getwork)\n- [`eth_submitWork`](https://eth.wiki/json-rpc/API#eth_submitwork)\n- [`eth_submitHashrate`](https://eth.wiki/json-rpc/API#eth_submithashrate)\n- [`db_putString`](https://eth.wiki/json-rpc/API#db_putstring)\n- [`db_getString`](https://eth.wiki/json-rpc/API#db_getstring)\n- [`db_putHex`](https://eth.wiki/json-rpc/API#db_puthex)\n- [`db_getHex`](https://eth.wiki/json-rpc/API#db_gethex)\n- [`shh_post`](https://eth.wiki/json-rpc/API#shh_post)\n- [`shh_version`](https://eth.wiki/json-rpc/API#shh_version)\n- [`shh_newIdentity`](https://eth.wiki/json-rpc/API#shh_newidentity)\n- [`shh_hasIdentity`](https://eth.wiki/json-rpc/API#shh_hasidentity)\n- [`shh_newGroup`](https://eth.wiki/json-rpc/API#shh_newgroup)\n- [`shh_addToGroup`](https://eth.wiki/json-rpc/API#shh_addtogroup)\n- [`shh_newFilter`](https://eth.wiki/json-rpc/API#shh_newfilter)\n- [`shh_uninstallFilter`](https://eth.wiki/json-rpc/API#shh_uninstallfilter)\n- [`shh_getFilterChanges`](https://eth.wiki/json-rpc/API#shh_getfilterchanges)\n- [`shh_getMessages`](https://eth.wiki/json-rpc/API#shh_getmessages)\n\n#### WebSocket Subscription Methods\n\n- [`eth_subscribe`](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub#create-subscriptions) - Subscribe to real-time events\n- [`eth_unsubscribe`](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub#cancel-subscriptions) - Unsubscribe from events\n\n### IpcClient\n\nYou can follow along with any of these examples using IPC by replacing `HttpClient` with `IpcClient`.\n\n### Examples\n\n```elixir\niex\u003e Ethereumex.HttpClient.web3_client_version\n{:ok, \"Parity//v1.7.2-beta-9f47909-20170918/x86_64-macos/rustc1.19.0\"}\n\n# Using the url option will overwrite the configuration\niex\u003e Ethereumex.HttpClient.web3_client_version(url: \"http://localhost:8545\")\n{:ok, \"Parity//v1.7.2-beta-9f47909-20170918/x86_64-macos/rustc1.19.0\"}\n\niex\u003e Ethereumex.HttpClient.web3_sha3(\"wrong_param\")\n{:error, %{\"code\" =\u003e -32602, \"message\" =\u003e \"Invalid params: invalid format.\"}}\n\niex\u003e Ethereumex.HttpClient.eth_get_balance(\"0x407d73d8a49eeb85d32cf465507dd71d507100c1\")\n{:ok, \"0x0\"}\n```\n\nNote that all method names are snakecases, so, for example, shh_getMessages method has corresponding Ethereumex.HttpClient.shh_get_messages/1 method. Signatures can be found in Ethereumex.Client.Behaviour. There are more examples in tests.\n\n#### eth_call example - Read only smart contract calls\n\nIn order to call a smart contract using the JSON-RPC interface you need to properly hash the data attribute (this will need to include the contract method signature along with arguments if any). You can do this manually or use a hex package like [ABI](https://hex.pm/packages/ex_abi) to parse your smart contract interface or encode individual calls.\n\n```elixir\ndefp deps do\n  [\n    ...\n    {:ethereumex, \"~\u003e 0.9\"},\n    {:ex_abi, \"~\u003e 0.5\"}\n    ...\n  ]\nend\n```\n\nNow load the ABI and pass the method signature. Note that the address needs to be converted to bytes:\n\n```elixir\naddress           = \"0xF742d4cE7713c54dD701AA9e92101aC42D63F895\" |\u003e String.slice(2..-1) |\u003e Base.decode16!(case: :mixed)\ncontract_address  = \"0xC28980830dD8b9c68a45384f5489ccdAF19D53cC\"\nabi_encoded_data  = ABI.encode(\"balanceOf(address)\", [address]) |\u003e Base.encode16(case: :lower)\n```\n\nNow you can use eth_call to execute this smart contract command:\n\n```elixir\nbalance_bytes = Ethereumex.HttpClient.eth_call(%{\n  data: \"0x\" \u003c\u003e abi_encoded_data,\n  to: contract_address\n})\n```\n\nTo convert the balance into an integer:\n\n```elixir\nbalance_bytes\n|\u003e String.slice(2..-1)\n|\u003e Base.decode16!(case: :lower)\n|\u003e TypeDecoder.decode_raw([{:uint, 256}])\n|\u003e List.first\n```\n\n### Custom requests\n\nMany Ethereum protocol implementations support additional JSON-RPC API methods. To use them, you should call Ethereumex.HttpClient.request/3 method.\n\nFor example, let's call parity's personal_listAccounts method.\n\n```elixir\niex\u003e Ethereumex.HttpClient.request(\"personal_listAccounts\", [], [])\n{:ok,\n [\"0x71cf0b576a95c347078ec2339303d13024a26910\",\n  \"0x7c12323a4fff6df1a25d38319d5692982f48ec2e\"]}\n```\n\n### Batch requests\n\nTo send batch requests use Ethereumex.HttpClient.batch_request/1 or Ethereumex.HttpClient.batch_request/2 method.\n\n```elixir\nrequests = [\n   {:web3_client_version, []},\n   {:net_version, []},\n   {:web3_sha3, [\"0x68656c6c6f20776f726c64\"]}\n ]\n Ethereumex.HttpClient.batch_request(requests)\n {\n   :ok,\n   [\n     {:ok, \"Parity//v1.7.2-beta-9f47909-20170918/x86_64-macos/rustc1.19.0\"},\n     {:ok, \"42\"},\n     {:ok, \"0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad\"}\n   ]\n }\n```\n\n\u003c!-- MDOC !--\u003e\n\n## Built on Ethereumex\n\nIf you are curious what others are building with ethereumex, you might want to take a look at these projects:\n\n- [ethers](https://github.com/ExWeb3/elixir_ethers) - Interacting with EVM contracts like first-class Elixir functions similar to Ethers.js\n\n## Contributing\n\n1. [Fork it!](http://github.com/ayrat555/ethereumex/fork)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## Copyright and License\n\nCopyright (c) 2018 Ayrat Badykov\n\nReleased under the MIT License, which can be found in the repository in\n[LICENSE.md](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmana-ethereum%2Fethereumex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmana-ethereum%2Fethereumex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmana-ethereum%2Fethereumex/lists"}