Nostr

Gem Version Maintainability Test Coverage

Asynchronous Nostr client. Please note that the API is likely to change as the gem is still in development and has not yet reached a stable release. Use with caution.

Table of contents

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add nostr

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install nostr

Usage

Requiring the gem

All examples below assume that the gem has been required.

require 'nostr'

Generating a keypair

keygen  = Nostr::Keygen.new
keypair = keygen.generate_key_pair

keypair.private_key
keypair.public_key

Generating a private key and a public key

keygen  = Nostr::Keygen.new

private_key = keygen.generate_private_key
public_key  = keygen.extract_public_key(private_key)

Connecting to a Relay

Clients can connect to multiple Relays. In this version, a Client can only connect to a single Relay at a time.

You may instantiate multiple Clients and multiple Relays.

client = Nostr::Client.new
relay  = Nostr::Relay.new(url: 'wss://relay.damus.io', name: 'Damus')

client.connect(relay)

WebSocket events

All communication between clients and relays happen in WebSockets.

The :connect event is fired when a connection with a WebSocket is opened. You must call Nostr::Client#connect first.

client.on :connect do
  # all the code goes here
end

The :close event is fired when a connection with a WebSocket has been closed because of an error.

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'

The :message event is fired when data is received through a WebSocket.

client.on :message do |message|
  puts message
end

# [
#   "EVENT",
#   "d34107357089bfc9882146d3bfab0386",
#   {
#     "content":"",
#     "created_at":1676456512,
#     "id":"18f63550da74454c5df7caa2a349edc5b2a6175ea4c5367fa4b4212781e5b310",
#     "kind":3,
#     "pubkey":"117a121fa41dc2caa0b3d6c5b9f42f90d114f1301d39f9ee96b646ebfee75e36",
#     "sig":"d171420bd62cf981e8f86f2dd8f8f86737ea2bbe2d98da88db092991d125535860d982139a3c4be39886188613a9912ef380be017686a0a8b74231dc6e0b03cb",
#     "tags":[
#       ["p","1cc821cc2d47191b15fcfc0f73afed39a86ac6fb34fbfa7993ee3e0f0186ef7c"]
#     ]
#   }
# ]

The :close event is fired when a connection with a WebSocket is closed.

client.on :close do |code, reason|
  # you may attempt to reconnect

  client.connect(relay)
end

Requesting for events / creating a subscription

A client can request events and subscribe to new updates after it has established a connection with the Relay.

You may use a Nostr::Filter instance with as many attributes as you wish:

client.on :connect do
  filter = Nostr::Filter.new(
    ids: ['8535d5e2d7b9dc07567f676fbe70428133c9884857e1915f5b1cc6514c2fdff8'],
    authors: ['ae00f88a885ce76afad5cbb2459ef0dcf0df0907adc6e4dac16e1bfbd7074577'],
    kinds: [Nostr::EventKind::TEXT_NOTE],
    e: ["f111593a72cc52a7f0978de5ecf29b4653d0cf539f1fa50d2168fc1dc8280e52"],
    p: ["f1f9b0996d4ff1bf75e79e4cc8577c89eb633e68415c7faf74cf17a07bf80bd8"],
    since: 1230981305,
    until: 1292190341,
    limit: 420,
  )

  subscription = client.subscribe('a_random_subscription_id', filter)
end

With just a few:

client.on :connect do
  filter = Nostr::Filter.new(kinds: [Nostr::EventKind::TEXT_NOTE])
  subscription = client.subscribe('a_random_subscription_id', filter)
end

Or omit the filter:

client.on :connect do
  subscription = client.subscribe('a_random_subscription_id')
end

Or even omit the subscription id:

client.on :connect do
  subscription = client.subscribe('a_random_subscription_id')
end

Stop previous subscriptions

You can stop receiving messages from a subscription by calling #unsubscribe:

client.unsubscribe('your_subscription_id')

Publishing an event

To publish an event you need a keypair.

# Create a keypair
keypair = Nostr::KeyPair.new(
  private_key: '893c4cc8088924796b41dc788f7e2f746734497010b1a9f005c1faad7074b900',
  public_key: '2d7661527d573cc8e84f665fa971dd969ba51e2526df00c149ff8e40a58f9558',
)

# Add the keypair to the user facade
user = Nostr::User.new(keypair: keypair)

# Create a signed event
event = user.create_event(
  created_at: 1667422587, # optional, defaults to the current time
  kind: Nostr::EventKind::TEXT_NOTE,
  tags: [], # optional, defaults to []
  content: 'Your feedback is appreciated, now pay $8'
)

# Send it to the Relay
client.publish(event)

Creating/updating your contact list

Every new contact list that gets published overwrites the past ones, so it should contain all entries.

# 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)

Sending an encrypted direct message

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)

Implemented NIPs

Development

After checking out the repo, run bin/setup to install dependencies.

To install this gem onto your local machine, run bundle exec rake install.

You can also run bin/console for an interactive prompt that will allow you to experiment.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

The health and maintainability of the codebase is ensured through a set of Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:

rake build                    # Build nostr.gem into the pkg directory
rake build:checksum           # Generate SHA512 checksum if nostr.gem into the checksums directory
rake bundle:audit:check       # Checks the Gemfile.lock for insecure dependencies
rake bundle:audit:update      # Updates the bundler-audit vulnerability database
rake clean                    # Remove any temporary products
rake clobber                  # Remove any generated files
rake coverage                 # Run spec with coverage
rake install                  # Build and install nostr.gem into system gems
rake install:local            # Build and install nostr.gem into system gems without network access
rake qa                       # Test, lint and perform security and documentation audits
rake release[remote]          # Create a tag, build and push nostr.gem to rubygems.org
rake rubocop                  # Run RuboCop
rake rubocop:autocorrect      # Autocorrect RuboCop offenses (only when it's safe)
rake rubocop:autocorrect_all  # Autocorrect RuboCop offenses (safe and unsafe)
rake spec                     # Run RSpec code examples
rake verify_measurements      # Verify that yardstick coverage is at least 100%
rake yard                     # Generate YARD Documentation
rake yard:junk                # Check the junk in your YARD Documentation
rake yardstick_measure        # Measure docs in lib/**/*.rb with yardstick

Type checking

This gem leverages RBS, a language to describe the structure of Ruby programs. It is used to provide type checking and autocompletion in your editor. Run bundle exec typeprof FILENAME to generate an RBS definition for the given Ruby file. And validate all definitions using Steep with the command bundle exec steep check.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/nostr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Nostr project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.