dart_nostr

dart_nostr is a Dart and Flutter SDK for building Nostr applications. It handles relay connections, event signing and publishing, typed subscription management, key tooling, and NIP utilities — so you can focus on your product instead of the protocol.

Documentation

Full API guides, per-feature references, and advanced configuration are in the documentation site:

Source documentation is also available on pub.dev.

Getting Started

Install

dependencies:
  dart_nostr: ^10.0.0

dart pub add dart_nostr
# or
flutter pub add dart_nostr

Import

import 'package:dart_nostr/dart_nostr.dart';

Connect, publish, and subscribe

Future<void> main() async {
  final nostr = Nostr.instance;

  // Connect to relays
  final connectResult = await nostr.connect([
    'wss://relay.damus.io',
    'wss://nos.lol',
  ]);

  if (connectResult.isFailure) {
    print(connectResult.failureOrNull);
    return;
  }

  // Generate a key pair
  final keyPair = nostr.keys.generateKeyPair();

  // Publish a note
  final event = NostrEvent.fromPartialData(
    kind: 1,
    content: 'Hello from dart_nostr',
    keyPairs: keyPair,
  );

  final publishResult = await nostr.publish(event);
  publishResult.fold(
    (ok) => print('published: ${ok.isEventAccepted}'),
    (failure) => print('failed: ${failure.message}'),
  );

  // Subscribe to recent notes
  final subResult = nostr.subscribeRequest(
    NostrRequest(
      filters: [
        NostrFilter(
          kinds: [1],
          limit: 20,
          since: DateTime.now().subtract(const Duration(hours: 1)),
        ),
      ],
    ),
  );

  subResult.fold(
    (stream) {
      stream.stream.listen((event) => print(event.content));
    },
    (failure) => print('subscribe failed: ${failure.message}'),
  );
}

Error handling pattern

Every operation that can fail returns NostrResult<T>:

result.fold(
  (value) { /* success */ },
  (failure) {
    print(failure.message);
    print(failure.code);
    print(failure.isRetryable);
  },
);

Key operations

final keyPair = nostr.keys.generateKeyPair();
print(keyPair.public);   // hex pubkey
print(keyPair.private);  // hex privkey

// Reconstruct from private key
final same = nostr.keys.generateKeyPairFromExistingPrivateKey(keyPair.private);

// NIP-19 bech32 encoding
final npub = nostr.bech32.encodePublicKeyToNpub(keyPair.public);
final nsec = nostr.bech32.encodePrivateKeyToNsec(keyPair.private);

// Sign and verify
final sig = nostr.keys.sign(privateKey: keyPair.private, message: 'hello');
final ok  = nostr.keys.verify(publicKey: keyPair.public, message: 'hello', signature: sig);

NIP-05 identity verification

final pubKey = await nostr.utils.pubKeyFromIdentifierNip05(
  internetIdentifier: 'user@domain.com',
);

final verified = await nostr.utils.verifyNip05(
  internetIdentifier: 'user@domain.com',
  pubKey: pubKey ?? '',
);

What the package provides

  • Nostr.instance — singleton; Nostr() — isolated instance with independent relay pool
  • nostr.connect() / nostr.disconnect() — connection lifecycle with typed results
  • nostr.publish() — signed event submission with relay OK response
  • nostr.subscribeRequest() / nostr.subscribeFilters() — typed stream subscriptions
  • nostr.count() — NIP-45 event count requests
  • nostr.keys — key generation, derivation, signing, verification
  • nostr.bech32 — NIP-19 encode/decode (npub, nsec, nprofile, nevent)
  • nostr.utils — NIP-05 resolution and verification
  • nostr.relays — low-level relay pool for protocol work
  • NostrResult<T> / NostrFailure — typed error model throughout
  • NostrClientOptions / NostrRetryPolicy — configurable timeouts and retry

API surfaces

Surface Use when
Top-level facade (nostr.connect, nostr.publish, ...) Building app features, need typed results and lifecycle management
nostr.relays Raw relay operations, protocol research, custom orchestration
nostr.services Direct access to internal components, building abstractions

Example files

The example directory contains runnable samples:

Tests

dart test

Contributing

Fork the repository, make changes, and open a pull request. Include tests where appropriate.

License

MIT. See LICENSE.

Libraries

dart_nostr
nostr/builder/config
nostr/builder/defaults
nostr/builder/extensions
nostr/builder/filter_builder
nostr/builder/retry_policy
nostr/core/constants
nostr/core/crypto_utils
nostr/core/exceptions
nostr/core/extensions
nostr/core/failures
nostr/core/key_pairs
nostr/core/result
nostr/core/utils
nostr/dart_nostr
nostr/instance/bech32/bech32
nostr/instance/connection_pool
nostr/instance/error_recovery
nostr/instance/keys/keys
nostr/instance/registry
nostr/instance/relay_pool
nostr/instance/relays/base/relays
nostr/instance/relays/relays
nostr/instance/streams
nostr/instance/subscription_manager
nostr/instance/tlv/base/base
nostr/instance/tlv/tlv_utils
nostr/instance/utils/utils
nostr/instance/web_sockets
nostr/model/base
nostr/model/count
nostr/model/debug_options
nostr/model/ease
nostr/model/event/event
nostr/model/export
nostr/model/nostr_event_key
nostr/model/nostr_events_stream
nostr/model/notice
nostr/model/ok
nostr/model/relay
nostr/model/relay_informations
nostr/model/request/close
nostr/model/request/eose
nostr/model/request/filter
nostr/model/request/request
nostr/model/tlv
nostr/service/client
nostr/service/client_options
nostr/service/relay_transport
nostr/service/services