ethers-rs/README.md

89 lines
3.1 KiB
Markdown
Raw Normal View History

2020-06-15 14:43:32 +00:00
# <h1 align="center"> ethers.rs </h1>
2020-05-22 18:37:21 +00:00
**Complete Ethereum and Celo wallet implementation and utilities in Rust**
2020-06-15 14:43:32 +00:00
![Github Actions](https://github.com/gakonst/ethers-rs/workflows/Tests/badge.svg)
2020-06-15 14:43:32 +00:00
## Documentation
Extensive documentation and examples are available [here](https://docs.rs/ethers).
2020-06-15 14:43:32 +00:00
Alternatively, you may clone the repository and run `cd ethers/ && cargo doc --open`
## Add ethers-rs to your repository
```toml
[dependencies]
ethers = { git = "https://github.com/gakonst/ethers-rs" }
2020-06-15 14:43:32 +00:00
```
</details>
2020-05-22 18:37:21 +00:00
## Running the tests
Tests require the following installed:
1. [`solc`](https://solidity.readthedocs.io/en/latest/installing-solidity.html)
2. [`ganache-cli`](https://github.com/trufflesuite/ganache-cli#installation)
In addition, it is recommended that you set the `ETHERSCAN_API_KEY` environment variable
for [the abigen via Etherscan](https://github.com/gakonst/ethers-rs/blob/master/ethers/tests/major_contracts.rs) tests.
You can get one [here](https://etherscan.io/apis).
### Celo Support
[Celo](http://celo.org/) support is turned on via the feature-flag `celo`:
```toml
[dependencies]
ethers = { git = "https://github.com/gakonst/ethers-rs", features = ["celo"] }
```
Celo's transactions differ from Ethereum transactions by including 3 new fields:
- `fee_currency`: The currency fees are paid in (None for CELO, otherwise it's an Address)
- `gateway_fee_recipient`: The address of the fee recipient (None for no gateway fee paid)
- `gateway_fee`: Gateway fee amount (None for no gateway fee paid)
The feature flag enables these additional fields in the transaction request builders and
in the transactions which are fetched over JSON-RPC.
2020-05-24 18:56:10 +00:00
## Features
2020-05-22 18:37:21 +00:00
2020-06-15 14:43:32 +00:00
- [x] Ethereum JSON-RPC Client
- [x] Interacting and deploying smart contracts
- [x] Type safe smart contract bindings code generation
2020-05-26 11:00:56 +00:00
- [x] Querying past events
2020-06-15 14:43:32 +00:00
- [x] Event monitoring as `Stream`s
- [x] ENS as a first class citizen
- [x] Celo support
2020-11-30 16:01:17 +00:00
- [x] Websockets / `eth_subscribe`
2020-11-23 08:43:30 +00:00
- [x] Hardware Wallet Support
- [x] Parity APIs (`tracing`, `parity_blockWithReceipts`)
- [x] Geth TxPool API
2020-06-15 14:43:32 +00:00
- [ ] WASM Bindings
- [ ] FFI Bindings
- [ ] CLI for common operations
## Getting Help
First, see if the answer to your question can be found in the [API documentation](https://docs.rs/ethers). If the answer
2020-06-15 14:43:32 +00:00
is not there, try opening an [issue](https://github.com/gakonst/ethers-rs/issues/new) with the question.
## Contributing
2020-05-22 18:37:21 +00:00
2020-06-15 14:43:32 +00:00
Thanks for your help improving the project! We are so happy to have you! We have
[a contributing guide](https://github.com/gakonst/ethers-rs/blob/master/CONTRIBUTING.md) to
help you get involved in the ethers-rs project.
2020-05-26 11:00:56 +00:00
2020-06-15 14:43:32 +00:00
## Related Projects
2020-06-15 14:43:32 +00:00
This library would not have been possibly without the great work done in:
2020-06-17 16:18:46 +00:00
- [`ethers.js`](https://github.com/ethers-io/ethers.js/)
2020-06-15 14:43:32 +00:00
- [`rust-web3`](https://github.com/tomusdrw/rust-web3/)
- [`ethcontract-rs`](https://github.com/gnosis/ethcontract-rs/)
- [`guac_rs`](https://github.com/althea-net/guac_rs/tree/master/web3/src/jsonrpc)
2020-06-15 14:43:32 +00:00
A lot of the code was inspired and adapted from them, to a unified and opinionated interface,
built with async/await and std futures from the ground up.