nim-ethers/Readme.md

178 lines
4.7 KiB
Markdown

Nim Ethers
==========
A port of the [ethers.js][0] library to Nim. Allows you to connect to an
Ethereum node.
This is very much a work in progress; expect to see many things that are
incomplete or wrong. Use at your own risk.
Installation
------------
Use the [Nimble][2] package manager to add `ethers` to an existing
project. Add the following to its .nimble file:
```nim
requires "ethers >= 0.8.0 & < 0.9.0"
```
Usage
-----
To connect to an Ethereum node, you require a `Provider`. Currently, only a
JSON-RPC provider is supported:
```nim
import ethers
import chronos
let provider = JsonRpcProvider.new("ws://localhost:8545")
let accounts = await provider.listAccounts()
```
To interact with a smart contract, you need to define the contract functions in
Nim. For example, to interact with an ERC20 token, you could define the
following:
```nim
type Erc20 = ref object of Contract
proc totalSupply(token: Erc20): UInt256 {.contract, view.}
proc balanceOf(token: Erc20, account: Address): UInt256 {.contract, view.}
proc transfer(token: Erc20, recipient: Address, amount: UInt256) {.contract.}
proc allowance(token: Erc20, owner, spender: Address): UInt256 {.contract, view.}
proc approve(token: Erc20, spender: Address, amount: UInt256) {.contract.}
proc transferFrom(token: Erc20, sender, recipient: Address, amount: UInt256) {.contract.}
```
Notice how some functions are annotated with a `{.view.}` pragma. This indicates
that the function does not modify the blockchain. See also the Solidity
documentation on [state mutability][3]
Now that you've defined the contract interface, you can create an instance of
it using its deployed address:
```nim
let address = Address.init("0x.....")
let token = Erc20.new(address, provider)
```
The functions that you defined earlier can now be called asynchronously:
```nim
let supply = await token.totalSupply()
let balance = await token.balanceOf(accounts[0])
```
These invocations do not yet change the state of the blockchain, even when we
invoke those functions that lack a `{.view.}` pragma. To allow these changes to
happen, we require an instance of a `Signer` first.
For example, to use the 4th account on the Ethereum node to sign transactions,
you'd instantiate the signer as follows:
```nim
let signer = provider.getSigner(accounts[3])
```
And then connect the contract and signer:
```nim
let writableToken = token.connect(signer)
```
This allows you to make changes to the state of the blockchain:
```nim
await writableToken.transfer(accounts[7], 42.u256)
```
Which transfers 42 tokens from account 3 to account 7
And lastly, don't forget to close the provider when you're done:
```nim
await provider.close()
```
Events
------
You can subscribe to events that are emitted by a smart contract. For instance,
to get notified about token transfers you define the `Transfer` event:
```nim
type Transfer = object of Event
sender {.indexed.}: Address
receiver {.indexed.}: Address
value: UInt256
```
Notice that `Transfer` inherits from `Event`, and that some event parameters are
marked with `{.indexed.}` to match the definition in Solidity.
Note that valid types of indexed parameters are:
```nim
uint8 | uint16 | uint32 | uint64 | UInt256 | UInt128 |
int8 | int16 | int32 | int64 | Int256 | Int128 |
bool | Address | array[ 1..32, byte]
```
Distinct types of valid types are also supported for indexed fields, eg:
```nim
type
DistinctAlias = distinct array[32, byte]
MyEvent = object of Event
a {.indexed.}: DistinctAlias
b: DistinctAlias # also allowed for non-indexed fields
```
You can now subscribe to Transfer events by calling `subscribe` on the contract
instance.
```nim
proc handleTransfer(transfer: Transfer) =
echo "received transfer: ", transfer
let subscription = await token.subscribe(Transfer, handleTransfer)
```
When a Transfer event is emitted, the `handleTransfer` proc that you just
defined will be called.
When you're no longer interested in these events, you can unsubscribe:
```nim
await subscription.unsubscribe()
```
Utilities
---------
This library ships with some optional modules that provides convenience utilities for you such as:
- `ethers/erc20` module provides you with ERC20 token implementation and its events
Contribution
------------
If you want to run the tests, then before running `nimble test`, you have to
have installed NodeJS and started a testing node:
```shell
$ cd testnode
$ npm ci
$ npm start
```
Thanks
------
This library is inspired by the great work done by the [ethers.js][0] (no
affiliation) and [nim-web3][1] developers.
[0]: https://docs.ethers.io/
[1]: https://github.com/status-im/nim-web3
[2]: https://github.com/nim-lang/nimble
[3]: https://docs.soliditylang.org/en/v0.8.11/contracts.html#state-mutability