@bitos/bnos-core

Core TypeScript utilities for the Bitcoin Network Operations System (BNOS).

@bitos/bnos-core provides shared Nostr helpers, BNOS record types, sync utilities, relay helpers, and migration tools used across BNOS applications.

Installation

npm install @bitos/bnos-core

yarn add @bitos/bnos-core

pnpm add @bitos/bnos-core

Features

Nostr key normalization for nsec, npub, and hex keys
Auth snapshot helpers for BNOS login state
Nostr event kind constants and helpers
Event signing with nsec keys or browser extension signers
Browser relay query, publish, preconnect, and connection management helpers
BNOS record types and record ID utilities
Sync cursor, query window, access, and bootstrap helpers
BNOS Space migration utilities

Usage

Authentication

import {
  createAuthSnapshotFromPrivateKey,
  normalizePrivateKey,
  publicKeyToNpub,
} from "@bitos/bnos-core";

const normalized = normalizePrivateKey("nsec1...");

console.log(normalized.pubkey);
console.log(normalized.npub);

const npub = publicKeyToNpub(normalized.pubkey);
const snapshot = createAuthSnapshotFromPrivateKey(normalized.nsec);

Event Kinds

import {
  NOSTR_KINDS,
  getKindName,
  isReplaceableKind,
} from "@bitos/bnos-core";

console.log(NOSTR_KINDS.TEXT_NOTE);
console.log(getKindName(NOSTR_KINDS.TEXT_NOTE));

if (isReplaceableKind(10002)) {
  // Handle replaceable Nostr metadata.
}

Signing Events

import { signNostrEvent } from "@bitos/bnos-core";

const event = await signNostrEvent({
  loginMethod: "nsec",
  nsec: "nsec1...",
  fallbackPubkey: "hex_public_key",
  template: {
    kind: 1,
    content: "Hello from BNOS",
    tags: [],
    created_at: Math.floor(Date.now() / 1000),
  },
});

BNOS Records

import {
  createBnosRecord,
  normalizeSyncStatus,
  type BnosRecord,
} from "@bitos/bnos-core";

type ProductData = {
  name: string;
  price: number;
};

const record: BnosRecord<ProductData> = createBnosRecord("products", {
  kind: 30078,
  pubkey: "hex_public_key",
  dTag: "product-001",
  data: {
    name: "Coffee",
    price: 120,
  },
  raw: {
    id: "event_id",
    kind: 30078,
    pubkey: "hex_public_key",
    created_at: Math.floor(Date.now() / 1000),
    tags: [["d", "product-001"]],
    content: "{}",
    sig: "event_signature",
  },
  syncStatus: normalizeSyncStatus("new"),
});

Relays

Relay helpers are designed for browser runtimes because they use browser WebSocket APIs through nostr-tools.

import {
  normalizeRelayUrls,
  preconnectRelays,
  publishToRelays,
  queryRelays,
} from "@bitos/bnos-core";

const relays = normalizeRelayUrls([
  "wss://relay.damus.io",
  "wss://nos.lol",
]);

await preconnectRelays(relays);

const events = await queryRelays(relays, {
  kinds: [1],
  limit: 10,
});

await publishToRelays(events[0], relays);

Import Paths

The package exposes both a top-level entry point and focused subpath exports.

import { normalizePrivateKey } from "@bitos/bnos-core";
import { normalizePrivateKey } from "@bitos/bnos-core/auth";
import { NOSTR_KINDS } from "@bitos/bnos-core/events/kinds";
import { queryRelays } from "@bitos/bnos-core/relays";
import type { BnosRecord } from "@bitos/bnos-core/types";

Available subpaths:

@bitos/bnos-core/auth
@bitos/bnos-core/events
@bitos/bnos-core/events/kinds
@bitos/bnos-core/migration
@bitos/bnos-core/relays
@bitos/bnos-core/sync
@bitos/bnos-core/types

Development

npm install
npm run build

The package is written in TypeScript and publishes compiled files from dist.

Publishing

The package is configured for public npm publishing.

npm publish --access public

If your npm account requires two-factor authentication, include the current OTP code:

npm publish --access public --otp 123456

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

Acknowledgments

Special thanks to BitDigo for contributions, sponsorship, and support in building the foundational architecture of the Bitcoin Network Operations System.

License

MIT. See LICENSE for details.