doc: add install and getting started documentation

examples/doc-examples/example_encryption_insecure.py

@@ -0,0 +1,54 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.security.insecure.transport import (
+    PLAINTEXT_PROTOCOL_ID,
+    InsecureTransport,
+)
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create an insecure transport (not recommended for production)
+    insecure_transport = InsecureTransport(
+        # local_key_pair: The key pair used for libp2p identity
+        local_key_pair=key_pair,
+        # secure_bytes_provider: Optional function to generate secure random bytes
+        # (defaults to secrets.token_bytes)
+        secure_bytes_provider=None,  # Use default implementation
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {PLAINTEXT_PROTOCOL_ID: insecure_transport}
+
+    # Create a host with the key pair and insecure transport
+    host = new_host(key_pair=key_pair, sec_opt=security_options)
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print(
+            "libp2p has started with insecure transport "
+            "(not recommended for production)"
+        )
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_encryption_noise.py

@@ -0,0 +1,53 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.security.noise.transport import PROTOCOL_ID as NOISE_PROTOCOL_ID
+from libp2p.security.noise.transport import Transport as NoiseTransport
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a Noise security transport
+    noise_transport = NoiseTransport(
+        # local_key_pair: The key pair used for libp2p identity and authentication
+        libp2p_keypair=key_pair,
+        # noise_privkey: The private key used for Noise protocol encryption
+        noise_privkey=key_pair.private_key,
+        # early_data: Optional data to send during the handshake
+        # (None means no early data)
+        early_data=None,
+        # with_noise_pipes: Whether to use Noise pipes for additional security features
+        with_noise_pipes=False,
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {NOISE_PROTOCOL_ID: noise_transport}
+
+    # Create a host with the key pair and Noise security
+    host = new_host(key_pair=key_pair, sec_opt=security_options)
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started with Noise encryption")
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_encryption_secio.py

@@ -0,0 +1,49 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.security.secio.transport import ID as SECIO_PROTOCOL_ID
+from libp2p.security.secio.transport import Transport as SecioTransport
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a SECIO security transport
+    secio_transport = SecioTransport(
+        # local_key_pair: The key pair used for libp2p identity and authentication
+        local_key_pair=key_pair,
+        # secure_bytes_provider: Optional function to generate secure random bytes
+        # (defaults to secrets.token_bytes)
+        secure_bytes_provider=None,  # Use default implementation
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {SECIO_PROTOCOL_ID: secio_transport}
+
+    # Create a host with the key pair and SECIO security
+    host = new_host(key_pair=key_pair, sec_opt=security_options)
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started with SECIO encryption")
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_multiplexer.py

@@ -0,0 +1,62 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.security.noise.transport import PROTOCOL_ID as NOISE_PROTOCOL_ID
+from libp2p.security.noise.transport import Transport as NoiseTransport
+from libp2p.stream_muxer.mplex.mplex import (
+    MPLEX_PROTOCOL_ID,
+)
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a Noise security transport
+    noise_transport = NoiseTransport(
+        # local_key_pair: The key pair used for libp2p identity and authentication
+        libp2p_keypair=key_pair,
+        # noise_privkey: The private key used for Noise protocol encryption
+        noise_privkey=key_pair.private_key,
+        # early_data: Optional data to send during the handshake
+        # (None means no early data)
+        early_data=None,
+        # with_noise_pipes: Whether to use Noise pipes for additional security features
+        with_noise_pipes=False,
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {NOISE_PROTOCOL_ID: noise_transport}
+
+    # Create a muxer options dictionary mapping protocol ID to muxer class
+    # We don't need to instantiate the muxer here, the host will do that for us
+    muxer_options = {MPLEX_PROTOCOL_ID: None}
+
+    # Create a host with the key pair, Noise security, and mplex multiplexer
+    host = new_host(
+        key_pair=key_pair, sec_opt=security_options, muxer_opt=muxer_options
+    )
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started with Noise encryption and mplex multiplexing")
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_peer_discovery.py

@@ -0,0 +1,82 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.peer.peerinfo import (
+    info_from_p2p_addr,
+)
+from libp2p.security.noise.transport import PROTOCOL_ID as NOISE_PROTOCOL_ID
+from libp2p.security.noise.transport import Transport as NoiseTransport
+from libp2p.stream_muxer.mplex.mplex import (
+    MPLEX_PROTOCOL_ID,
+)
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a Noise security transport
+    noise_transport = NoiseTransport(
+        # local_key_pair: The key pair used for libp2p identity and authentication
+        libp2p_keypair=key_pair,
+        # noise_privkey: The private key used for Noise protocol encryption
+        noise_privkey=key_pair.private_key,
+        # early_data: Optional data to send during the handshake
+        # (None means no early data)
+        early_data=None,
+        # with_noise_pipes: Whether to use Noise pipes for additional security features
+        with_noise_pipes=False,
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {NOISE_PROTOCOL_ID: noise_transport}
+
+    # Create a muxer options dictionary mapping protocol ID to muxer class
+    # We don't need to instantiate the muxer here, the host will do that for us
+    muxer_options = {MPLEX_PROTOCOL_ID: None}
+
+    # Create a host with the key pair, Noise security, and mplex multiplexer
+    host = new_host(
+        key_pair=key_pair, sec_opt=security_options, muxer_opt=muxer_options
+    )
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started")
+        print("libp2p is listening on:", host.get_addrs())
+
+        # Connect to bootstrap peers manually
+        bootstrap_list = [
+            "/dnsaddr/bootstrap.libp2p.io/p2p/"
+            + "QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
+            "/dnsaddr/bootstrap.libp2p.io/p2p/"
+            + "QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
+        ]
+
+        for addr in bootstrap_list:
+            try:
+                peer_info = info_from_p2p_addr(multiaddr.Multiaddr(addr))
+                await host.connect(peer_info)
+                print(f"Connected to {peer_info.peer_id.to_string()}")
+            except Exception as e:
+                print(f"Failed to connect to {addr}: {e}")
+
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_running.py

@@ -0,0 +1,62 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+from libp2p.security.noise.transport import PROTOCOL_ID as NOISE_PROTOCOL_ID
+from libp2p.security.noise.transport import Transport as NoiseTransport
+from libp2p.stream_muxer.mplex.mplex import (
+    MPLEX_PROTOCOL_ID,
+)
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a Noise security transport
+    noise_transport = NoiseTransport(
+        # local_key_pair: The key pair used for libp2p identity and authentication
+        libp2p_keypair=key_pair,
+        # noise_privkey: The private key used for Noise protocol encryption
+        noise_privkey=key_pair.private_key,
+        # early_data: Optional data to send during the handshake
+        # (None means no early data)
+        early_data=None,
+        # with_noise_pipes: Whether to use Noise pipes for additional security features
+        with_noise_pipes=False,
+    )
+
+    # Create a security options dictionary mapping protocol ID to transport
+    security_options = {NOISE_PROTOCOL_ID: noise_transport}
+
+    # Create a muxer options dictionary mapping protocol ID to muxer class
+    # We don't need to instantiate the muxer here, the host will do that for us
+    muxer_options = {MPLEX_PROTOCOL_ID: None}
+
+    # Create a host with the key pair, Noise security, and mplex multiplexer
+    host = new_host(
+        key_pair=key_pair, sec_opt=security_options, muxer_opt=muxer_options
+    )
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started")
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)

examples/doc-examples/example_transport.py

@@ -0,0 +1,35 @@
+import secrets
+
+import multiaddr
+import trio
+
+from libp2p import (
+    new_host,
+)
+from libp2p.crypto.secp256k1 import (
+    create_new_key_pair,
+)
+
+
+async def main():
+    # Create a key pair for the host
+    secret = secrets.token_bytes(32)
+    key_pair = create_new_key_pair(secret)
+
+    # Create a host with the key pair
+    host = new_host(key_pair=key_pair)
+
+    # Configure the listening address
+    port = 8000
+    listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/tcp/{port}")
+
+    # Start the host
+    async with host.run(listen_addrs=[listen_addr]):
+        print("libp2p has started with TCP transport")
+        print("libp2p is listening on:", host.get_addrs())
+        # Keep the host running
+        await trio.sleep_forever()
+
+
+# Run the async function
+trio.run(main)