From 5cc1f4b71d9ac0e62a67ffec847957afd094b2c0 Mon Sep 17 00:00:00 2001
From: Mark Spanbroek <mark@spanbroek.net>
Date: Wed, 2 Feb 2022 17:49:50 +0100
Subject: [PATCH] Add documentation about events

---
 Readme.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Readme.md b/Readme.md
index 83cd42d..f8f882f 100644
--- a/Readme.md
+++ b/Readme.md
@@ -90,6 +90,44 @@ await writableToken.transfer(accounts[7], 42.u256)
 
 Which transfers 42 tokens from account 3 to account 7
 
+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.
+
+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()
+```
+
+Subscriptions are currently only supported when using a JSON RPC provider that
+is created with a websockets URL such as `ws://localhost:8545`.
+
 Thanks
 ------