nostr 0.4.0 → 0.6.0

data/docs/core/keys.md

@@ -0,0 +1,136 @@
+# Keys
+
+To [sign events](#signing-an-event), you need a **private key**. To verify signatures, you need a **public key**. The combination of a
+private and a public key is called a **keypair**.
+
+Both public and private keys are 64-character hexadecimal strings. They can be represented in bech32 format,
+which is a human-readable format that starts with `nsec` for private keys and `npub` for public keys.
+
+There are a few ways to generate a keypair.
+
+## a) Generating a keypair
+
+If you don't have any keys, you can generate a keypair using the
+[`Nostr::Keygen`](https://www.rubydoc.info/gems/nostr/Nostr/Keygen) class:
+
+```ruby
+keygen  = Nostr::Keygen.new
+keypair = keygen.generate_key_pair
+
+keypair.private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+keypair.public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## b) Generating a private key and a public key
+
+Alternatively, if you have already generated a private key, you can extract the corresponding public key by calling
+`Keygen#extract_public_key`:
+
+```ruby
+keygen  = Nostr::Keygen.new
+
+private_key = keygen.generate_private_key
+public_key  = keygen.extract_public_key(private_key)
+
+private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## c) Using existing hexadecimal keys
+
+If you already have a private key and a public key in hexadecimal format, you can create a keypair using the
+`Nostr::KeyPair` class:
+
+```ruby
+keypair = Nostr::KeyPair.new(
+  private_key: Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+  public_key: Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+)
+
+keypair.private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+keypair.public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+### d) Use existing bech32 keys
+
+If you already have a private key and a public key in bech32 format, you can create a keypair using the
+`Nostr::KeyPair` class:
+
+```ruby
+keypair = Nostr::KeyPair.new(
+  private_key: Nostr::PrivateKey.from_bech32('nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5'),
+  public_key: Nostr::PublicKey.from_bech32('npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'),
+)
+
+keypair.private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+keypair.public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## e) Using an existing hexadecimal private key
+
+If you already have a private key in hexadecimal format, you can create a keypair using the method
+[`Nostr::Keygen#get_key_pair_from_private_key`](https://www.rubydoc.info/gems/nostr/Nostr/Keygen#get_key_pair_from_private_key-instance_method):
+
+```ruby
+private_key = Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa')
+
+keygen= Nostr::Keygen.new
+keypair = keygen.get_key_pair_from_private_key(private_key)
+
+keypair.private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+keypair.public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## f) Using an existing bech32 private key
+
+If you already have a private key in bech32 format, you can create a keypair using the methods
+[`Nostr::PrivateKey.from_bech32`](https://www.rubydoc.info/gems/nostr/Nostr/PrivateKey.from_bech32-class_method) and
+[`Nostr::Keygen#get_key_pair_from_private_key`](https://www.rubydoc.info/gems/nostr/Nostr/Keygen#get_key_pair_from_private_key-instance_method):
+
+```ruby
+private_key = Nostr::PrivateKey.from_bech32('nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5')
+
+keygen= Nostr::Keygen.new
+keypair = keygen.get_key_pair_from_private_key(private_key)
+
+keypair.private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+keypair.public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## Signing an event
+
+KeyPairs are used to sign [events](../events). To create a signed event, you need to instantiate a
+[`Nostr::User`](https://www.rubydoc.info/gems/nostr/Nostr/User) with a keypair:
+
+```ruby{8,11-14}
+# Use an existing keypair
+keypair = Nostr::KeyPair.new(
+  private_key: Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+  public_key: Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+)
+
+# Add the keypair to a user
+user = Nostr::User.new(keypair: keypair)
+
+# Create signed events
+text_note = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+```
+
+::: details Click me to view the text_note
+
+```ruby
+# text_note.to_h
+{
+  id: '030fbc71151379e5b58e7428ed6e7f2884e5dfc9087fd64d1dc4cc677f5097c8',
+  pubkey: '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e', # from the keypair
+  created_at: 1700119819,
+  kind: 1, # Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+  sig: '586877896ef6f7d54fa4dd2ade04e3fdc4dfcd6166dd0df696b3c3c768868c0b690338f5baed6ab4fc717785333cb487363384de9fb0f740ac4775522cb4acb3' # signed with the private key from the keypair
+}
+```
+:::

data/docs/core/user.md

@@ -0,0 +1,43 @@
+# User
+
+The class [`Nostr::User`](https://www.rubydoc.info/gems/nostr/Nostr/User) is an abstraction to facilitate the creation
+of signed events. It is not required to use it to create events, but it is recommended.
+
+Here's an example of how to create a signed event without the class `Nostr::User`:
+
+```ruby
+event = Nostr::Event.new(
+  pubkey: keypair.public_key,
+  kind: Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+)
+event.sign(keypair.private_key)
+```
+
+::: details Click me to view the event
+
+```ruby
+# event.to_h
+{
+  id: '5feb10973dbcf5f210cfc1f0aa338fee62bed6a29696a67957713599b9baf0eb',
+  pubkey: 'b9b9821074d1b60b8fb4a3983632af3ef9669f55b20d515bf982cda5c439ad61',
+  created_at: 1699847447,
+  kind: 1, # Nostr::EventKind::TEXT_NOTE,
+  tags: [],
+  content: 'Your feedback is appreciated, now pay $8',
+  sig: 'e30f2f08331f224e41a4099d16aefc780bf9f2d1191b71777e1e1789e6b51fdf7bb956f25d4ea9a152d1c66717a9d68c081ce6c89c298c3c5e794914013381ab'
+}
+```
+:::
+
+And here's how to create it with the class `Nostr::User`:
+
+```ruby
+user = Nostr::User.new(keypair: keypair)
+
+event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+```

data/docs/events/contact-list.md

@@ -0,0 +1,29 @@
+# Contact List
+
+## Creating/updating your contact list
+
+Every new contact list that gets published overwrites the past ones, so it should contain all entries.
+
+```ruby
+# Creating a contact list event with 2 contacts
+update_contacts_event = user.create_event(
+  kind: Nostr::EventKind::CONTACT_LIST,
+  tags: [
+    [
+      "p", # mandatory
+      "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245", # public key of the user to add to the contacts
+      "wss://alicerelay.com/", # can be an empty string or can be omitted
+      "alice" # can be an empty string or can be omitted
+    ],
+    [
+      "p", # mandatory
+      "3efdaebb1d8923ebd99c9e7ace3b4194ab45512e2be79c1b7d68d9243e0d2681", # public key of the user to add to the contacts
+      "wss://bobrelay.com/nostr", # can be an empty string or can be omitted
+      "bob" # can be an empty string or can be omitted
+    ],
+  ],
+)
+
+# Send it to the Relay
+client.publish(update_contacts_event)
+```

data/docs/events/encrypted-direct-message.md

@@ -0,0 +1,28 @@
+# Encrypted Direct Message
+
+## Sending an encrypted direct message
+
+```ruby
+sender_private_key = '3185a47e3802f956ca5a2b4ea606c1d51c7610f239617e8f0f218d55bdf2b757'
+
+encrypted_direct_message = Nostr::Events::EncryptedDirectMessage.new(
+   sender_private_key: sender_private_key,
+   recipient_public_key: '6c31422248998e300a1a457167565da7d15d0da96651296ee2791c29c11b6aa0',
+   plain_text: 'Your feedback is appreciated, now pay $8',
+   previous_direct_message: 'ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460' # optional
+)
+
+encrypted_direct_message.sign(sender_private_key)
+
+# #<Nostr::Events::EncryptedDirectMessage:0x0000000104c9fa68
+# @content="mjIFNo1sSP3KROE6QqhWnPSGAZRCuK7Np9X+88HSVSwwtFyiZ35msmEVoFgRpKx4?iv=YckChfS2oWCGpMt1uQ4GbQ==",
+#   @created_at=1676456512,
+#   @id="daac98826d5eb29f7c013b6160986c4baf4fe6d4b995df67c1b480fab1839a9b",
+#   @kind=4,
+#   @pubkey="8a9d69c56e3c691bec8f9565e4dcbe38ae1d88fffeec3ce66b9f47558a3aa8ca",
+#   @sig="028bb5f5bab0396e2065000c84a4bcce99e68b1a79bb1b91a84311546f49c5b67570b48d4a328a1827e7a8419d74451347d4f55011a196e71edab31aa3d6bdac",
+#   @tags=[["p", "6c31422248998e300a1a457167565da7d15d0da96651296ee2791c29c11b6aa0"], ["e", "ccf9fdf3e1466d7c20969c71ec98defcf5f54aee088513e1b73ccb7bd770d460"]]>
+
+# Send it to the Relay
+client.publish(encrypted_direct_message)
+```

data/docs/events/recommend-server.md

@@ -0,0 +1,32 @@
+# Recommend Server
+
+The `Recommend Server` event, has a set of tags with the following structure `['e', <event-id>, <relay-url>, <marker>]`
+
+Where:
+
+- `<event-id>` is the id of the event being referenced.
+- `<relay-url>` is the URL of a recommended relay associated with the reference. Clients SHOULD add a valid `<relay-URL>`
+field, but may instead leave it as `''`.
+- `<marker>` is optional and if present is one of `'reply'`, `'root'`, or `'mention'`.
+Those marked with `'reply'` denote the id of the reply event being responded to. Those marked with `'root'` denote the
+root id of the reply thread being responded to. For top level replies (those replying directly to the root event),
+only the `'root'` marker should be used. Those marked with `'mention'` denote a quoted or reposted event id.
+
+A direct reply to the root of a thread should have a single marked `'e'` tag of type `'root'`.
+
+## Recommending a server
+
+```ruby
+recommend_server_event = user.create_event(
+  kind: Nostr::EventKind::RECOMMEND_SERVER,
+  tags: [
+    [
+      'e',
+      '461544014d87c9eaf3e76e021240007dff2c7afb356319f99c741b45749bf82f',
+      'wss://relay.damus.io'
+    ],
+  ]
+)
+
+client.publish(recommend_server_event)
+```

data/docs/events/set-metadata.md

@@ -0,0 +1,20 @@
+# Set Metadata
+
+In the `Metadata` event, the `content` is set to a stringified JSON object
+`{name: <username>, about: <string>, picture: <url, string>}` describing the [user](../core/user) who created the event. A relay may
+delete older events once it gets a new one for the same pubkey.
+
+## Setting the user's metadata
+
+```ruby
+metadata_event = user.create_event(
+  kind: Nostr::EventKind::SET_METADATA,
+  content: {
+    name: 'Wilson Silva',
+    about: 'Used to make hydrochloric acid bombs in high school.',
+    picture: 'https://thispersondoesnotexist.com/'
+  }
+)
+
+client.publish(metadata_event)
+```

data/docs/events/text-note.md

@@ -0,0 +1,15 @@
+# Text Note
+
+In the `Text Note` event, the `content` is set to the plaintext content of a note (anything the user wants to say).
+Content that must be parsed, such as Markdown and HTML, should not be used.
+
+## Sending a text note event
+
+```ruby
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+client.publish(text_note_event)
+```

data/docs/events.md

@@ -0,0 +1,11 @@
+# Events
+
+## Event Kinds
+
+| kind          | description                                                    | NIP                                                            |
+| ------------- |----------------------------------------------------------------| -------------------------------------------------------------- |
+| `0`           | [Metadata](./events/set-metadata)                              | [1](https://github.com/nostr-protocol/nips/blob/master/01.md)  |
+| `1`           | [Short Text Note](./events/text-note)                          | [1](https://github.com/nostr-protocol/nips/blob/master/01.md)  |
+| `2`           | [Recommend Relay](./events/recommend-server)                   |                                                                |
+| `3`           | [Contacts](./events/contact-list)                              | [2](https://github.com/nostr-protocol/nips/blob/master/02.md)  |
+| `4`           | [Encrypted Direct Messages](./events/encrypted-direct-message) | [4](https://github.com/nostr-protocol/nips/blob/master/04.md)  |

data/docs/getting-started/installation.md

@@ -0,0 +1,21 @@
+# Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add nostr
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```shell
+gem install nostr
+```
+
+## Requiring the gem
+
+All examples in this guide assume that the gem has been required:
+
+```ruby
+require 'nostr'
+```

data/docs/getting-started/overview.md

@@ -0,0 +1,171 @@
+---
+editLink: true
+---
+
+# Getting started
+
+This gem abstracts the complexity that you would face when trying to connect to relays web sockets, send and receive
+events, handle events callbacks and much more.
+
+## Visual overview
+
+Begin your journey with an overview of the essential functions. A visual representation below maps out the key
+components we'll delve into in this section.
+
+```mermaid
+classDiagram
+    class Client {
+        connect(relay)
+        publish(event)
+        subscribe(subscription_id, filter)
+        unsubscribe(subscription_id)
+    }
+    class Relay {
+        url
+        name
+    }
+    class Event {
+        pubkey
+        created_at
+        kind
+        tags
+        content
+        add_event_reference(event_id)
+        add_pubkey_reference(pubkey)
+        serialize()
+        to_h()
+        sign(private_key)
+        verify_signature()
+    }
+    class Subscription {
+        id
+        filter
+    }
+    class Filter {
+        ids
+        authors
+        kinds
+        since
+        until
+        limit
+        to_h()
+    }
+    class EventKind {
+        <<Enumeration>>
+        SET_METADATA
+        TEXT_NOTE
+        RECOMMEND_SERVER
+        CONTACT_LIST
+        ENCRYPTED_DIRECT_MESSAGE
+    }
+    class KeyPair {
+        private_key
+        public_key
+    }
+    class Keygen {
+        generate_key_pair()
+        generate_private_key()
+        extract_public_key(private_key)
+    }
+    class User {
+        keypair
+        create_event(event_attributes)
+    }
+
+    Client --> Relay : connects via <br> WebSockets to
+    Client --> Event : uses WebSockets to <br> publish and receive
+    Client --> Subscription : receives Events via
+    Subscription --> Filter : uses
+    Event --> EventKind : is of kind
+    User --> KeyPair : has
+    User --> Event : creates and signs
+    User --> Keygen : uses to generate keys
+    Keygen --> KeyPair : generates
+```
+
+## Code overview
+
+Explore the provided code snippet to learn about initializing the Nostr [client](../core/client.md), generating
+a [keypair](../core/keys), [publishing](../relays/publishing-events) an event, and
+efficiently [managing event subscriptions](../subscriptions/creating-a-subscription) (including event reception,
+filtering, and WebSocket event handling).
+
+```ruby
+# Require the gem
+require 'nostr'
+
+# Instantiate a client
+client = Nostr::Client.new
+
+# a) Use an existing keypair
+keypair = Nostr::KeyPair.new(
+  private_key: Nostr::PrivateKey.new('your-hex-private-key'),
+  public_key: Nostr::PublicKey.new('your-hex-public-key'),
+)
+
+# b) Or build a keypair from a private key
+keygen = Nostr::Keygen.new
+keypair = keygen.get_key_pair_from_private_key(
+  Nostr::PrivateKey.new('your-hex-private-key')
+)
+
+# c) Or create a new keypair
+keygen = Nostr::Keygen.new
+keypair = keygen.generate_key_pair
+
+# Create a user with the keypair
+user = Nostr::User.new(keypair: keypair)
+
+# Create a signed event
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+# Connect asynchronously to a relay
+relay = Nostr::Relay.new(url: 'wss://nostr.wine', name: 'Wine')
+client.connect(relay)
+
+# Listen asynchronously for the connect event
+client.on :connect do
+  # Send the event to the Relay
+  client.publish(text_note_event)
+
+  # Create a filter to receive the first 20 text notes
+  # and encrypted direct messages from the relay that
+  # were created in the previous hour
+  filter = Nostr::Filter.new(
+    kinds: [
+      Nostr::EventKind::TEXT_NOTE,
+      Nostr::EventKind::ENCRYPTED_DIRECT_MESSAGE
+    ],
+    since: Time.now.to_i - 3600, # 1 hour ago
+    until: Time.now.to_i,
+    limit: 20,
+  )
+
+  # Subscribe to events matching conditions of a filter
+  subscription = client.subscribe(filter: filter)
+
+  # Unsubscribe from events matching the filter above
+  client.unsubscribe(subscription.id)
+end
+
+# Listen for incoming messages and print them
+client.on :message do |message|
+  puts message
+end
+
+# Listen for error messages
+client.on :error do |error_message|
+  # Handle the error
+end
+
+# Listen for the close event
+client.on :close do |code, reason|
+  # You may attempt to reconnect to the relay here
+end
+```
+
+Beyond what's covered here, the Nostr protocol and this gem boast a wealth of additional functionalities. For an
+in-depth exploration of these capabilities, proceed to the next page.

data/docs/implemented-nips.md

@@ -0,0 +1,9 @@
+# Implemented NIPs
+
+NIPs stand for Nostr Implementation Possibilities. They exist to document what may be implemented by Nostr-compatible
+relay and client software.
+
+- [NIP-01: Basic protocol flow description](https://github.com/nostr-protocol/nips/blob/master/01.md)
+- [NIP-02: Contact List and Petnames](https://github.com/nostr-protocol/nips/blob/master/02.md)
+- [NIP-04: Encrypted Direct Message](https://github.com/nostr-protocol/nips/blob/master/04.md)
+- [NIP-19: Bech32-encoded entities](https://github.com/nostr-protocol/nips/blob/master/19.md)

data/docs/index.md

@@ -0,0 +1,42 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Nostr"
+  text: "Ruby"
+  tagline: "The Nostr protocol implemented in a Ruby gem."
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started/overview
+    - theme: alt
+      text: View on Github
+      link: https://github.com/wilsonsilva/nostr
+    - theme: alt
+      text: View on RubyDoc
+      link: https://www.rubydoc.info/gems/nostr
+    - theme: alt
+      text: View on RubyGems
+      link: https://rubygems.org/gems/nostr
+
+features:
+  - title: Asynchronous
+    details: Non-blocking I/O for maximum performance.
+    icon: ⚡
+  - title: Lightweight
+    details: Minimal runtime dependencies.
+    icon: 🪶
+  - title: Intuitive
+    details: The API mirrors the Nostr protocol specification domain language.
+    icon: 💡
+  - title: Fully documented
+    details: All code is documented from both the maintainer's as well as the consumer's perspective.
+    icon: 📚
+  - title: Fully tested
+    details: All code is tested with 100% coverage.
+    icon: 🧪
+  - title: Fully typed
+    details: All code is typed with <a href="https://rubygems.org/gems/rbs" target="_blank">RBS</a> with the help of <a href="https://rubygems.org/gems/typeprof" target="_blank">TypeProf</a>. Type correctness is enforced by <a href="https://rubygems.org/gems/steep" target="_blank">Steep</a>.
+    icon: ✅
+---

data/docs/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

data/docs/package.json

@@ -0,0 +1,12 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "mermaid": "^10.6.1",
+    "vitepress": "^1.0.0-rc.25",
+    "vitepress-plugin-mermaid": "^2.0.15"
+  }
+}

data/docs/relays/connecting-to-a-relay.md

@@ -0,0 +1,21 @@
+# Connecting to a Relay
+
+You must connect your nostr [Client](../core/client) to a relay in order to send and receive [Events](../events).
+Instantiate a [`Nostr::Client`](https://www.rubydoc.info/gems/nostr/Nostr/Client) and a
+[`Nostr::Relay`](https://www.rubydoc.info/gems/nostr/Nostr/Relay) giving it the `url` of your relay. The `name`
+attribute is just descriptive.
+Calling [`Client#connect`](https://www.rubydoc.info/gems/nostr/Nostr/Client#connect-instance_method) attempts to
+establish a WebSocket connection between the Client and the Relay.
+
+```ruby
+client = Nostr::Client.new
+relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+
+# Listen for the connect event
+client.on :connect do
+  # When this block executes, you're connected to the relay
+end
+
+# Connect to a relay asynchronously
+client.connect(relay)
+```