From 926cbe59028209762bea95d9de3e8f4f70951aa2 Mon Sep 17 00:00:00 2001 From: Alisina Bahadori Date: Mon, 17 Apr 2023 12:11:56 -0400 Subject: [PATCH] Update README,LICENSE and Utils --- LICENSE | 202 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 134 +++++++++++++++++++++++++++-- config/config.exs | 2 + config/dev.exs | 2 - lib/ethers/utils.ex | 34 ++++++++ mix.exs | 2 +- 6 files changed, 365 insertions(+), 11 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..57bc88a --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + diff --git a/README.md b/README.md index 0ea7ea8..126a15c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,139 @@ -# Ethers +# Elixir Ethers -**TODO: Add description** +Elixir Ethers is a comprehensive library for interacting with the Ethereum blockchain and its ecosystem. +Heavily inspired by the [ethers.js](https://github.com/ethers-io/ethers.js/) library, Elixir Ethers leverages macros to convert +Ethereum contract ABIs into first-class Elixir modules during compile time, complete with documentation and type-specs. ## Installation -If [available in Hex](https://hex.pm/docs/publish), the package can be installed -by adding `ethers` to your list of dependencies in `mix.exs`: +You can install the package by adding `ethers` to the list of dependencies in your `mix.exs` file:: ```elixir def deps do [ - {:ethers, "~> 0.1.0"} + {:ethers, "~> 0.1.0-dev", github: "alisinabh/elixir-ethers"} ] end ``` -Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) -and published on [HexDocs](https://hexdocs.pm). Once published, the docs can -be found at . +The complete documentation is available on [hexdocs](https://hexdocs.pm/ethers). +## Requirements + + +To use Elixir Ethers, ensure you have a configured JSON-RPC endpoint. +By default, Ethers utilizes [Cloudflare's Ethereum Gateway](https://developers.cloudflare.com/web3/ethereum-gateway/reference/supported-networks/). + +To send transactions, you need a wallet client capable of signing transactions and exposing a JSON-RPC endpoint. +Configure the endpoint using the following config parameter (you can also specify the endpoint per-call): + +```elixir +# config.exs +import Config + +config :ethereumex, url: "[URL_HERE]" +``` + +For more information, refer to [ethereumex](https://github.com/mana-ethereum/ethereumex). + +## Usage + +To use Elixir Ethers, you must have your contract's ABI, which can be obtained from [etherscan.io](https://etherscan.io). +This library also supports standard contract interfaces such as `ERC20`, `ERC721` and some more (refer to built-in contracts in hex-doc). + +Create a module for your contract as follows: + +```elixir +defmodule MyERC20Token do + use Ethers.Contract, abi_file: "path/to/abi.json", default_address: "[Token address here (optional)]" +end +``` + +### Calling contract functions + +After defining the module, all the functions can be called like any other Elixir module. +The documentation is also available giving the developer a first-class experience. + +``` +iex> MyERC20Token.name() +{:ok, ["Token Name"]} + +iex> h MyERC20Token.name + def name(overrides \\ []) + + @spec name(Keyword.t()) :: + {:ok, [String.t()]} + | {:ok, Ethers.Types.t_transaction_hash()} + | {:ok, Ethers.Contract.t_function_output()} + +Executes name() on the contract. + +## Parameters + + • overrides: Overrides and options for the call. + • :to: The address of the recipient contract. (Required) + • :action: Type of action for this function (:call, :send or + :prepare) Default: :call. + • :rpc_opts: Options to pass to the RCP client e.g. :url. + + +## Return Types + + • :string +``` + +### Sending transaction + + +Sending transactions is also straightforward, as Elixir Ethers automatically determines whether a function is a view function or a state-changing function, using `eth_call` or `eth_sendTransaction` accordingly. +You can override this behavior with the `:action` override. + +Ensure that you specify a `from` option to inform your client which account to use: + + +``` +iex> MyERC20Token.transfer("0x[Recipient Address Here]", Ethers.Utils.to_wei(1), from: "0x[Your address here]") +{:ok, "0xf313ff7ff54c6db80ad44c3ad58f72ff0fea7ce88e5e9304991ebd35a6e76000"} +``` + + +### Getting Logs (Events) + +Elixir Ethers provides functionality for creating event filters and fetching events from the RPC endpoint using `eth_getLogs`. +Each contract in Ethers generates an `EventFilters` module (e.g. `MyERC20Token.EventFilter`s) that can be used to create filters for events. + +To create an event filter and use the `Ethers.get_logs` function, follow this example: + +``` +iex> {:ok, filter} = MyERC20Token.EventFilters.transfer("0x[From Address Here]", nil) +``` + +Also `nil` can be used for a parameter in EventFilters functions to show that it should not be filtered. + +Then you can simply list the logs. + +``` +iex> Ethers.get_logs(filter) +{:ok, + [ + %{ + "address" => "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", + "blockHash" => "0xd04d7d39f0dd6913260f1682e1863eda9b5dc0a5d4cf2dca4ef6961147a77f39", + "blockNumber" => "0x1046dd0", + "data" => [1274604842999873536], + "logIndex" => "0x0", + "removed" => false, + "topics" => ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x0000000000000000000000006b75d8af000000e20b7a7ddf000ba900b4009a80", + "0x0000000000000000000000009b3df8eae6e1ed1b931086852860d3c6375d7ae6"], + "transactionHash" => "0xd00e58a817c42f46709bea153c44b7908d88d4763472836a85e7c740dd481d69", + "transactionIndex" => "0x3" + }, + ... + ] +} +``` + +## License + +[Apache License 2.0](/LICENSE) diff --git a/config/config.exs b/config/config.exs index d1186fe..14326db 100644 --- a/config/config.exs +++ b/config/config.exs @@ -1,3 +1,5 @@ import Config +config :ethereumex, url: "https://cloudflare-eth.com/v1/mainnet" + import_config "#{config_env()}.exs" diff --git a/config/dev.exs b/config/dev.exs index d196f18..becde76 100644 --- a/config/dev.exs +++ b/config/dev.exs @@ -1,3 +1 @@ import Config - -config :ethereumex, url: "https://cloudflare-eth.com/v1/mainnet" diff --git a/lib/ethers/utils.ex b/lib/ethers/utils.ex index 5a1cd70..554fb3a 100644 --- a/lib/ethers/utils.ex +++ b/lib/ethers/utils.ex @@ -3,6 +3,8 @@ defmodule Ethers.Utils do Utilities for interacting with ethereum blockchain """ + @wei_multiplier trunc(:math.pow(10, 18)) + @doc """ Encode to hex with 0x prefix. @@ -66,6 +68,38 @@ defmodule Ethers.Utils do "0x" <> Integer.to_string(integer, 16) end + @doc """ + Converts ETH to WEI + + ## Examples + + iex> Ethers.Utils.to_wei(1) + 1000000000000000000 + + iex> Ethers.Utils.to_wei(3.14) + 3140000000000000000 + """ + @spec to_wei(number()) :: non_neg_integer() + def to_wei(number) when number > 0 do + trunc(number * @wei_multiplier) + end + + @doc """ + Convert WEI to ETH + + ## Examples + + iex> Ethers.Utils.from_wei(1000000000000000000) + 1.0 + + iex> Ethers.Utils.from_wei(3140000000000000000) + 3.14 + """ + @spec from_wei(non_neg_integer()) :: float() + def from_wei(number) when is_integer(number) and number > 0 do + number / @wei_multiplier + end + @doc """ Adds gas limit estimation to the parameters if not already exists """ diff --git a/mix.exs b/mix.exs index fdb63ac..996dacf 100644 --- a/mix.exs +++ b/mix.exs @@ -2,7 +2,7 @@ defmodule Ethers.MixProject do use Mix.Project @version "0.0.1-dev" - @source_url "https://github.com/alisinabh/ethers" + @source_url "https://github.com/alisinabh/elixir_ethers" def project do [