nostr 0.4.0 → 0.6.0

data/docs/.vitepress/config.mjs

@@ -0,0 +1,114 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from "vitepress-plugin-mermaid";
+
+// https://vitepress.dev/reference/site-config
+// https://www.npmjs.com/package/vitepress-plugin-mermaid
+export default defineConfig(withMermaid({
+  title: "Nostr",
+  description: "Documentation of the Nostr Ruby gem",
+  // https://vitepress.dev/reference/site-config#head
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }]
+  ],
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-last-updated
+    lastUpdated: true,
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/getting-started/overview' }
+    ],
+
+    // https://vitepress.dev/reference/default-theme-search
+    search: {
+      provider: 'local'
+    },
+
+    // https://vitepress.dev/reference/default-theme-sidebar
+    sidebar: [
+      {
+        text: 'Getting started',
+        collapsed: false,
+        items: [
+          { text: 'Overview', link: '/getting-started/overview' },
+          { text: 'Installation', link: '/getting-started/installation' },
+        ]
+      },
+      {
+        text: 'Core',
+        collapsed: false,
+        items: [
+          { text: 'Client', link: '/core/client' },
+          { text: 'Keys', link: '/core/keys' },
+          { text: 'User', link: '/core/user' },
+        ]
+      },
+      {
+        text: 'Relays',
+        items: [
+          { text: 'Connecting to a relay', link: '/relays/connecting-to-a-relay' },
+          { text: 'Publishing events', link: '/relays/publishing-events' },
+          { text: 'Receiving events', link: '/relays/receiving-events' },
+        ]
+      },
+      {
+        text: 'Subscriptions',
+        collapsed: false,
+        items: [
+          { text: 'Creating a subscription', link: '/subscriptions/creating-a-subscription' },
+          { text: 'Filtering subscription events', link: '/subscriptions/filtering-subscription-events' },
+          { text: 'Updating a subscription', link: '/subscriptions/updating-a-subscription' },
+          { text: 'Deleting a subscription', link: '/subscriptions/deleting-a-subscription' },
+        ]
+      },
+      {
+        text: 'Events',
+        link: '/events',
+        collapsed: false,
+        items: [
+          { text: 'Set Metadata', link: '/events/set-metadata' },
+          { text: 'Text Note', link: '/events/text-note' },
+          { text: 'Recommend Server', link: '/events/recommend-server' },
+          { text: 'Contact List', link: '/events/contact-list' },
+          { text: 'Encrypted Direct Message', link: '/events/encrypted-direct-message' },
+        ]
+      },
+      {
+        text: 'Common use cases',
+        collapsed: false,
+        items: [
+          { text: 'Bech32 enc/decoding (NIP-19)', link: '/common-use-cases/bech32-encoding-and-decoding-(NIP-19)' },
+          { text: 'Signing/verifying messages', link: '/common-use-cases/signing-and-verifying-messages' },
+          { text: 'Signing/verifying events', link: '/common-use-cases/signing-and-verifying-events' },
+        ]
+      },
+      {
+        text: 'Implemented NIPs',
+        link: '/implemented-nips',
+      },
+    ],
+
+    // https://vitepress.dev/reference/default-theme-config#sociallinks
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/wilsonsilva/nostr' }
+    ],
+
+    // https://vitepress.dev/reference/default-theme-edit-link
+    editLink: {
+      pattern: 'https://github.com/wilsonsilva/nostr/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    },
+
+    // https://vitepress.dev/reference/default-theme-footer
+    footer: {
+      message: 'Released under the <a href="https://github.com/wilsonsilva/nostr/blob/main/LICENSE.txt">MIT License</a>.',
+      copyright: 'Copyright © 2023-present <a href="https://github.com/wilsonsilva">Wilson Silva</a>'
+    }
+  },
+
+  // https://vitepress.dev/reference/site-config#ignoredeadlinks
+  ignoreDeadLinks: [
+    /^https?:\/\/localhost/
+  ],
+}))

data/docs/README.md

@@ -0,0 +1,44 @@
+# Nostr Docs
+
+VitePress-powered documentation for the Nostr Ruby gem.
+
+## Live Demo
+
+https://nostr-ruby.com/
+
+## Development
+
+### Requirements
+
+- [Bun](https://bun.sh/)
+
+### Installation
+
+```shell
+bun install
+```
+
+### Tasks
+
+The `docs:dev` script will start a local dev server with instant hot updates. Run it with the following command:
+
+```shell
+bun run docs:dev
+```
+
+Run this command to build the docs:
+
+```shell
+bun run docs:build
+```
+
+Once built, preview it locally by running:
+
+```shell
+bun run docs:preview
+```
+
+The preview command will boot up a local static web server that will serve the output directory .`vitepress/dist` at
+http://localhost:4173. You can use this to make sure everything looks good before pushing to production.
+
+

data/docs/api-examples.md

@@ -0,0 +1,49 @@
+---
+outline: deep
+---
+
+# Runtime API Examples
+
+This page demonstrates usage of some of the runtime APIs provided by VitePress.
+
+The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
+
+```md
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+```
+
+<script setup>
+import { useData } from 'vitepress'
+
+const { site, theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+
+## More
+
+Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).

data/docs/common-use-cases/bech32-encoding-and-decoding-(NIP-19).md

@@ -0,0 +1,190 @@
+# Encoding/decoding bech-32 strings (NIP-19)
+
+[NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md) standardizes bech32-formatted strings that can be
+used to display keys, ids and other information in clients. These formats are not meant to be used anywhere in the core
+protocol, they are only meant for displaying to users, copy-pasting, sharing, rendering QR codes and inputting data.
+
+
+In order to guarantee the deterministic nature of the documentation, the examples below assume that there is a `keypair`
+variable with the following values:
+
+```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'
+```
+
+## Public key (npub)
+
+### Encoding
+
+```ruby
+npub = Nostr::Bech32.npub_encode('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e')
+npub # => 'npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg'
+```
+
+### Decoding
+
+```ruby
+type, public_key = Nostr::Bech32.decode('npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg')
+type # => 'npub'
+public_key # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+```
+
+## Private key (nsec)
+
+### Encoding
+
+```ruby
+nsec = Nostr::Bech32.nsec_encode('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa')
+nsec # => 'nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5'
+```
+
+### Decoding
+
+```ruby
+type, private_key = Nostr::Bech32.decode('nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5')
+type # => 'npub'
+private_key # => '67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'
+```
+
+## Relay (nrelay)
+
+### Encoding
+
+```ruby
+nrelay = Nostr::Bech32.nrelay_encode('wss://relay.damus.io')
+nrelay # => 'nrelay1qq28wumn8ghj7un9d3shjtnyv9kh2uewd9hsc5zt2x'
+```
+
+### Decoding
+
+```ruby
+type, data = Nostr::Bech32.decode('nrelay1qq28wumn8ghj7un9d3shjtnyv9kh2uewd9hsc5zt2x')
+
+type # => 'nrelay'
+data.entries.first.label # => 'relay'
+data.entries.first.value # => 'wss://relay.damus.io'
+```
+
+## Event (nevent)
+
+### Encoding
+
+```ruby{8-12}
+user = Nostr::User.new(keypair: keypair)
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  created_at: 1700467997,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+nevent = Nostr::Bech32.nevent_encode(
+  id: text_note_event.id,
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+  kind: Nostr::EventKind::TEXT_NOTE,
+)
+
+nevent # => 'nevent1qgsqlkuslr3rf56qpmd0m5ndfyl39m7q6l0zcmuly8ue0praxwkjagcpz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dspsgqqqqqqs03k8v3'
+```
+
+### Decoding
+
+```ruby
+type, event = Nostr::Bech32.decode('nevent1qgsqlkuslr3rf56qpmd0m5ndfyl39m7q6l0zcmuly8ue0praxwkjagcpz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dspsgqqqqqqs03k8v3')
+
+type # => 'nevent'
+event.entries[0].label # => 'author'
+event.entries[0].value # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+event.entries[1].relay # => 'relay'
+event.entries[1].value # => 'wss://relay.damus.io'
+event.entries[2].label # => 'relay'
+event.entries[2].value # => 'wss://nos.lol'
+event.entries[3].label # => 'kind'
+event.entries[3].value # => 1
+```
+
+## Address (naddr)
+
+### Encoding
+
+```ruby
+naddr = Nostr::Bech32.naddr_encode(
+  pubkey: keypair.public_key,
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+  kind: Nostr::EventKind::TEXT_NOTE,
+  identifier: 'damus',
+)
+
+naddr # => 'naddr1qgs8ul5ug253hlh3n75jne0a5xmjur4urfxpzst88cnegg6ds6ka7nspz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dspsgqqqqqqsqptyv9kh2uc3qfs2p'
+```
+
+### Decoding
+
+```ruby
+type, addr = Nostr::Bech32.decode('naddr1qgs8ul5ug253hlh3n75jne0a5xmjur4urfxpzst88cnegg6ds6ka7nspz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dspsgqqqqqqsqptyv9kh2uc3qfs2p')
+
+type # => 'naddr'
+addr.entries[0].label # => 'author'
+addr.entries[0].value # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+addr.entries[1].label # => 'relay'
+addr.entries[1].value # => 'wss://relay.damus.io'
+addr.entries[2].label # => 'relay'
+addr.entries[2].value # => 'wss://nos.lol'
+addr.entries[3].label # => 'kind'
+addr.entries[3].value # => 1
+addr.entries[4].label # => 'identifier'
+addr.entries[4].value # => 'damus'
+```
+
+## Profile (nprofile)
+
+### Encoding
+```ruby
+relay_urls = %w[wss://relay.damus.io wss://nos.lol]
+nprofile = Nostr::Bech32.nprofile_encode(pubkey: keypair.public_key, relays: relay_urls)
+
+nprofile # => nprofile1qqs8ul5ug253hlh3n75jne0a5xmjur4urfxpzst88cnegg6ds6ka7nspz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dsxe58m5
+```
+
+### Decoding
+
+```ruby
+type, profile = Nostr::Bech32.decode('nprofile1qqs8ul5ug253hlh3n75jne0a5xmjur4urfxpzst88cnegg6ds6ka7nspz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0dsxe58m5')
+
+type # => 'nprofile'
+profile.entries[0].label # => 'pubkey'
+profile.entries[0].value # => '7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'
+profile.entries[1].label # => 'relay'
+profile.entries[1].value # => 'wss://relay.damus.io'
+profile.entries[2].label # => 'relay'
+profile.entries[2].value # => 'wss://nos.lol'
+```
+
+## Other simple types (note)
+
+### Encoding
+
+```ruby{8-9}
+user = Nostr::User.new(keypair: keypair)
+text_note_event = user.create_event(
+  kind: Nostr::EventKind::TEXT_NOTE,
+  created_at: 1700467997,
+  content: 'Your feedback is appreciated, now pay $8'
+)
+
+note = Nostr::Bech32.encode(hrp: 'note', data: text_note_event.id)
+note # => 'note10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qnx3ujq'
+```
+
+### Decoding
+
+```ruby
+type, note = Nostr::Bech32.decode('note1pldep78zxnf5qrk6lhfx6jflzthup47793he7g0ej7z86vad963s42v0rr')
+type # => 'note'
+note # => '0fdb90f8e234d3400edafdd26d493f12efc0d7de2c6f9f21f997847d33ad2ea3'
+```

data/docs/common-use-cases/signing-and-verifying-events.md

@@ -0,0 +1,50 @@
+# Signing and verifying events
+
+Signing an event in Nostr proves it was sent by the owner of a specific private key.
+
+## Signing an event
+
+To sign an event, use the private key associated with the event's creator. Here's how to sign a message using a
+predefined keypair:
+
+```ruby{14}
+require 'nostr'
+
+private_key = Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+public_key = Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+
+event = Nostr::Event.new(
+  pubkey: public_key.to_s,
+  kind: Nostr::EventKind::TEXT_NOTE,
+  content: 'We did it with security, now we’re going to do it with the economy.',
+  created_at: Time.now.to_i,
+)
+
+# Sign the event with the private key
+event.sign(private_key)
+
+puts "Event ID: #{event.id}"
+puts "Event Signature: #{event.sig}"
+```
+
+## Verifying an event's signature
+
+To verify an event, you must ensure the event's signature is valid. This indicates the event was created by the owner
+of the corresponding public key.
+
+When the event was signed with the private key corresponding to the public key, the `verify_signature` method will
+return `true`.
+
+```ruby
+event.verify_signature # => true
+```
+
+And when the event was not signed with the private key corresponding to the public key, the `verify_signature` method
+will return `false`.
+
+An event without an `id`, `pubkey`, `sig` is considered invalid and will return `false` when calling `verify_signature`.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+event.verify_signature # => false
+```

data/docs/common-use-cases/signing-and-verifying-messages.md

@@ -0,0 +1,43 @@
+# Signing and verifying messages
+
+Signing a message in Nostr proves it was sent by the owner of a specific private key.
+
+## Signing a message
+
+To sign a message, you'll need a private key. Here's how to sign a message using a predefined keypair:
+
+```ruby{9}
+require 'nostr'
+
+private_key = Nostr::PrivateKey.new('67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa'),
+public_key = Nostr::PublicKey.new('7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e'),
+
+message = 'We did it with security, now we’re going to do it with the economy.' # The message you want to sign
+
+crypto = Nostr::Crypto.new
+signature = crypto.sign_message(message, private_key)
+signature # => "d7a0aac1fadcddf1aa2949bedfcdf25ce0c1604e648e55d31431fdacbff8e8256f7c2166d98292f80bc5f79105a0b6e8a89236a47d97cf5d0e7cc1ebf34dea5c"
+```
+
+## Verifying a signature
+
+To verify a signature, you need the original message, the public key of the signer, and the signature.
+
+```ruby
+crypto.valid_sig?(message, public_key, signature) # => true
+crypto.check_sig!(message, public_key, signature) # => true
+```
+
+When the message was not signed with the private key corresponding to the public key, the `valid_sig?` method will return `false`.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+crypto.valid_sig?(message, public_key, signature) # => false
+```
+
+And when the message was not signed with the private key corresponding to the public key, the `check_sig!` method will raise an error.
+
+```ruby
+other_public_key = Nostr::PublicKey.new('10be96d345ed58d923a734560680f1adfd2b1006c28ac93b8e1b032a9a32c6e9')
+crypto.check_sig!(message, other_public_key, signature) # => Schnorr::InvalidSignatureError: signature verification failed
+```

data/docs/core/client.md

@@ -0,0 +1,108 @@
+# Client
+
+Clients establish a WebSocket connection to [relays](../relays/connecting-to-a-relay). Through this connection, clients
+communicate and subscribe to a range of [Nostr events](../events) based on specified subscription filters. These filters
+define the Nostr events a client wishes to receive updates about.
+
+::: info
+Clients do not need to sign up or create an account to use Nostr. Upon connecting to a relay, a client provides
+its subscription filters. The relay then streams events that match these filters to the client for the duration of the
+connection.
+:::
+
+## WebSocket events
+
+Communication between clients and relays happen via WebSockets. The client will emit WebSocket events when the
+connection is __opened__, __closed__, when a __message__ is received or when there's an __error__.
+
+::: info
+WebSocket events are not [Nostr events](https://nostr.com/the-protocol/events). They are events emitted by the
+WebSocket connection. The WebSocket `:message` event, however, contains a Nostr event in its payload.
+:::
+
+### connect
+
+The `:connect` event is fired when a connection with a WebSocket is opened. You must call `Nostr::Client#connect` first.
+
+```ruby
+client = Nostr::Client.new
+relay = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')
+
+client.on :connect do
+  # When this block executes, you're connected to the relay
+end
+
+# Connect to a relay asynchronously
+client.connect(relay)
+```
+
+Once the connection is open, you can send events to the relay, manage subscriptions, etc.
+
+::: tip
+Define the connection event handler before calling
+[`Nostr::Client#connect`](https://www.rubydoc.info/gems/nostr/Nostr/Client#connect-instance_method). Otherwise,
+you may miss the event.
+:::
+
+### error
+
+The `:error` event is fired when a connection with a WebSocket has been closed because of an error.
+
+```ruby
+client.on :error do |error_message|
+  puts error_message
+end
+
+# > Network error: wss://rsslay.fiatjaf.com: Unable to verify the
+# server certificate for 'rsslay.fiatjaf.com'
+```
+
+### message
+
+The `:message` event is fired when data is received through a WebSocket.
+
+```ruby
+client.on :message do |message|
+  puts message
+end
+```
+
+The message will be one of these 4 types, which must also be JSON arrays, according to the following patterns:
+- `["EVENT", <subscription_id>, <event JSON>]`
+- `["OK", <event_id>, <true|false>, <message>]`
+- `["EOSE", <subscription_id>]`
+- `["NOTICE", <message>]`
+
+::: details Click me to see how a WebSocket message looks like
+```ruby
+[
+  "EVENT",
+  "d34107357089bfc9882146d3bfab0386",
+  {
+    "content": "",
+    "created_at": 1676456512,
+    "id": "18f63550da74454c5df7caa2a349edc5b2a6175ea4c5367fa4b4212781e5b310",
+    "kind": 3,
+    "pubkey": "117a121fa41dc2caa0b3d6c5b9f42f90d114f1301d39f9ee96b646ebfee75e36",
+    "sig": "d171420bd62cf981e8f86f2dd8f8f86737ea2bbe2d98da88db092991d125535860d982139a3c4be39886188613a9912ef380be017686a0a8b74231dc6e0b03cb",
+    "tags":[
+      ["p", "1cc821cc2d47191b15fcfc0f73afed39a86ac6fb34fbfa7993ee3e0f0186ef7c"]
+    ]
+  }
+]
+```
+:::
+
+### close
+
+The `:close` event is fired when a connection with a WebSocket is closed.
+
+```ruby
+client.on :close do |code, reason|
+  puts "Error: #{code} - #{reason}"
+end
+```
+
+::: tip
+This handler is useful to attempt to reconnect to the relay.
+:::