docs/getting-started/overview.md
---
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
# This line keeps the background client from exiting immediately.
gets
```
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.