readme and example improvement suggestions (#39)

* readme-suggestions

* chore: update readme

* Update README.md

* chore: reword

* remove brownie example

* add example diagram

* chore: refactor

* improve diagram

* improve diagram

* feat: add testimonial from tonkers

Co-authored-by: BobTheBuidler <70677534+BobTheBuidler@users.noreply.github.com>

README.md

@@ -1,35 +1,43 @@
-Dank Mids automatically collects your RPC calls and batches them together in jsonrpc batch calls.
+# Dank Mids
 
-All eth_call calls will be batched into multicalls prior to jsonrpc batching.
+Dank Mids is a EVM RPC batching library that helps reduce the number of HTTP requests to a node, saving time and resources. It automatically collects eth_call calls into multicalls and bundles all RPC calls together in jsonrpc batch calls.
 
-<hr>
-You only need to know one thing to use Dank Mids - `setup_dank_w3_from_sync`.
+The goal of this tool is to reduce the workload on RPC nodes and allow users to make calls to their preferred node more efficiently. This optimization is especially useful for developers writing scripts that perform large-scale blockchain analysis, as it can save development time and resources.
 
-Use `setup_dank_w3_from_sync` to wrap a sync Web3 instance for async use.
+![](https://i.imgur.com/o9FUmAn.jpg)
 
-Brownie's `web3` object, for example, is a sync Web3 instance. You can patch brownie Contracts with `patch_contract` for use with Dank Mids.
-<hr>
+### Installation
 
-using with brownie:
-```
-from brownie import Contract, web3
-from dank_mids.brownie_patch import patch_contract
-from dank_mids import setup_dank_w3_from_sync
+To install Dank Mids, use pip:
 
-dank_w3 = setup_dank_w3_from_sync(web3)
-weth = patch_contract(Contract(0x1234), dank_w3)
-total_supply = await weth.totalSupply.coroutine(block_identifier=12345)
-```
+`pip install dank-mids`
 
-using with web3py:
-```
+### Usage with web3.py
+
+The primary function you need to use Dank Mids is `setup_dank_w3_from_sync`. This function takes a sync Web3 instance and wraps it for async use.
+
+Example usage of Dank Mids with web3py:
+
+```python
 from dank_mids import setup_dank_w3_from_sync
 dank_w3 = setup_dank_w3_from_sync(w3)
 random_block = await dank_w3.eth.get_block(123)
 ```
 
-COMING SOON:
-using with ape
+### Usage with eth-brownie
+
+- [Dank Brownie Example Commented Code](./examples/dank_brownie_example.py)
+
+### Usage with ape
+
+- COMING SOON: Dank Mids will also work with [ape](https://github.com/ApeWorX/ape).
+
+### Testimonials
+
+[Yearn](https://yearn.finance) big brain [Tonkers Kuma](https://github.com/tonkers-kuma) had this to say:
+
+![image](https://user-images.githubusercontent.com/70677534/211255488-e76e641c-a0fe-461c-a4e5-27c45a3fea5b.png)
+
+### Notes
 
-NOTES:
-    - You can set DANK_MIDS_DEMO_MODE=True to see a visual represenataion of the batching in real time on your console.
+You can also set `DANK_MIDS_DEMO_MODE=True` to see a visual representation of the batching in real time on your console.

examples/dank_brownie_example.py

@@ -5,6 +5,8 @@
 This is how you ensure that all of the various parts of your code are running at the same time, and are therefore batchable.
 """
 
+# Import the necessary packages and set up the dank_w3 instance.
+# This instance wraps your sync Web3 instance and injects the dank middleware for batching
 import asyncio
 
 from brownie import Contract, web3
@@ -13,6 +15,8 @@
 
 dank_w3 = setup_dank_w3_from_sync(web3)
 
+# Define the main function and the blocks we want to get information from.
+# Also define the Uniswap pools we want to get data from.
 def main():
     asyncio.run(_main())
 
@@ -25,17 +29,22 @@ async def _main():
         "0xA478c2975Ab1Ea89e8196811F51A7B7Ade33eB11",
     ]
 
+# Initialize the pools as brownie Contract objects and patch them to define an additional coroutine method for each ContractCall.
     uniswap_pool_contracts = [Contract(pool) for pool in uniswap_pools]
     dank_pool_contracts = [patch_contract(pool, dank_w3) for pool in uniswap_pool_contracts]
+
+# Use asyncio.gather to collect the data from the various pools and blocks and store them in variables.
     tokens, timestamps, balances = await asyncio.gather(
         asyncio.gather(*[get_tokens_for_pool(pool) for pool in dank_pool_contracts]),
         asyncio.gather(*[get_timestamp_at_block(block) for block in blocks]),
         asyncio.gather(*[get_balances_for_blocks(pool, blocks) for pool in dank_pool_contracts])
     )
-    # Now we do stuff with the outputs
-    # stuff = more_stuff
-    # do_stuff()
 
+# Now we can do stuff with the outputs
+# stuff = more_stuff
+# do_stuff()
+
+# Functions that we used to get the data from the pools and blocks:
 async def get_balances_for_blocks(pool, blocks):
     return await asyncio.gather(*[pool.getReserves.coroutine(block_identifier=block) for block in blocks])