Add quickstart for stream creation

README.md

@@ -37,6 +37,97 @@ pytest
 ```
 Note that tests/libp2p/test_libp2p.py contains an end-to-end messaging test between two libp2p hosts, which is the bulk of our proof of concept.
 
+## Quickstart Guide
+
+This quickstart guide will teach you how to quickly get py-libp2p up and running, and how to take advantage of its various features. Since libp2p at its core is a distributed systems library, this quickstart guide will use explain all concepts with nodes. These two libp2p nodes that are labelled node1 and node2, respectively.
+
+### Creating a libp2p node
+
+A libp2p node, at a high-level, is used for connecting and communicating with peers running libp2p. Connecting with peers implies opening a connection to a peer over which communication via streams (discussed in next section) can take place.
+
+First, we create a libp2p instance on node1 and start listening on port 8000:
+```
+node1
+-----
+import multiaddr
+from libp2p import new_node
+
+host = await new_node()
+await host.get_network().listen(multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8000"))
+```
+
+Then, we create a libp2p instance on node2 and start listening on port 8001
+```
+node2
+-----
+import multiaddr
+from libp2p import new_node
+
+host = await new_node()
+await host.get_network().listen(multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8001"))
+```
+
+Now, we have two libp2p nodes. Next, let's make them connect.
+
+### Connecting two libp2p nodes
+
+In order to connect node1 to node2, node1 must have node2 as a peer. This is so that the nodes know who they are connecting to. So, let's add node2 as a peer of node1 and let's add node1 as a peer of node2. TODO: dicuss p2p IDs
+
+```
+node1
+-----
+from libp2p.peer.peerinfo import info_from_p2p_addr
+
+# Add node2 as a peer of node1
+addr_of_node2 = multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/8001/p2p/TODO")
+info_node2 = info_from_p2p_addr(addr_of_node2)
+
+# Connect node1 to node2
+await node1.connect(info_node2)
+```
+
+### Streams between two peers
+
+The central component to the libp2p paradigm is the stream, which represents a channel for communication over an underlying connection. There can be multiple streams over the same underlying connection. Here, we will go over how to setup two nodes to communicate over streams. When we create a new stream, we need to specify what protocol we would like to communicate over. In order for the opposing node to accept the new stream request, the opposing node needs to support at least one of the protocols specified in the new stream creation message.
+
+First, node2 creates a stream handler for each protocol it supports. The stream handler will be hit when a new stream, initiated by an outside node, is successfully created on that particular protocol. For now, node2 will only support '/foo/1.0.0'.
+
+```
+node2
+-----
+async def stream_handler(stream):
+    read_data = await stream.read()
+    read_str = read_data.decode()
+
+    # Print read_str
+    print(read_str)
+
+node2.set_stream_handler("/foo/1.0.0", stream_handler)
+```
+
+Next, node1 creates a new stream to node2 by specifiying node2's peer ID and the list of protocol node1 is willing to communicate with node2 over. Since, node2 only has a stream handler '/foo/1.0.0', node1 and node2 will agree to communicate over '/foo/1.0.0'.
+
+```
+node1
+-----
+supported_protocols = ["/foo/1.0.0", "/bar/1.0.0"]
+stream = await node1.new_stream(node_b.get_id(), supported_protocols)
+
+# Print out protocol id so we can see which protocol we will be communicating over
+print(stream.protocol_id)
+
+# Write data to stream
+encoded_str = "I <3 libp2p".encode()
+await stream.write(encoded_str)
+```
+
+Woohoo! We have successfully written data from node1 to node2. Streams can be used for much more complex communication than just prints. Also, node1 and node2 can open many streams to each other using this same code but with different supported protocols and stream handlers.
+
+Note: In order for node2 to open a stream to node1, node2 must have node1 as a peer (remember, we only added node2 as a peer of node1 earlier). -- TODO: update this statement if we change this
+
+
+### Floodsub between two peers
+
 ## Feature Breakdown
 py-libp2p aims for conformity with [the standard libp2p modules](https://github.com/libp2p/libp2p/blob/master/REQUIREMENTS.md#libp2p-modules-implementations). Below is a breakdown of the modules we have developed, are developing, and may develop in the future.