From 83448036c88636a9ecf8816493ff9430fb4f4e2c Mon Sep 17 00:00:00 2001
From: Piper Merriam <pipermerriam@gmail.com>
Date: Sun, 31 Jul 2016 17:23:00 -0600
Subject: [PATCH] brief docs on contract events

---
 README.md | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index a8e0ee0..818f794 100644
--- a/README.md
+++ b/README.md
@@ -99,17 +99,28 @@ web3.config.defaultBlock = "latest"
 ... 23212
 ```
 
-### Timeouts, blocking and nonblocking requests
-
-
-All function and property requests block until a respose is received.  Asynchronous function calling has not yet been implemented.
+You can listen for events using the `on` and `pastEvents` functions on a
+contract.
 
 ```python
-# Blocks indefinitely
->>> web3.eth.getBalance("0xaddress", timeout=None)
-23423234
+def transfer_callback(log_entry):
+    ...  # do something with the log.
+
+# create a filter and register a callback.
+filter = MyContract.on("Transfer", {})
+filter.watch(transfer_callback)
+
+filter.stop_watching()
 ```
 
+The underlying asynchronous operations are managed by `gevent`.
+
+
+### Timeouts, blocking and nonblocking requests
+
+Web3.py does not currently support asynchronous calling patterns.
+
+
 ### `web3`
 
 #### web3.db.*