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.

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_keypair

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 whenwhen data is received through a WebSocket.

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

# > Network error: wss://rsslay.fiatjaf.com: Unable to verify the server certificate for 'rsslay.fiatjaf.com'

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.

# Set up the private key
private_key = 'a630b06e2f883378d0aa335b9adaf7734603e00433350b684fe53e184f08c58f'
user = Nostr::User.new(private_key)

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

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 bundle:audit          # Checks for vulnerable versions of gems
rake qa                    # Test, lint and perform security and documentation audits
rake rubocop               # Lint the codebase with RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
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

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.