@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
• GLO protocol access through @bitos/bnos-core/glo

GLO protocol documentation: model and wire format, architecture, kind audit, and security contract.

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 {
  NOSTR_KINDS,
  createBnosRecord,
  normalizeSyncStatus,
  type BnosRecord,
} from "@bitos/bnos-core";

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

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

Global Object Model

import {
  createGloEventTemplate,
  createGloObject,
  type GloProduct,
} from "@bitos/bnos-core/glo";

const product = createGloObject<GloProduct, "catalog.product">({
  type: "catalog.product",
  id: "coffee-001",
  scope: { organizationId: "org-001" },
  visibility: "organization",
  data: {
    name: "Coffee",
    price: 35_000,
    currency: "LAK",
  },
});

const template = createGloEventTemplate(product);
// template.kind === NOSTR_KINDS.PRODUCT (30100)

Known GLO types use their central domain kind. Unknown extension types fall back to NIP-78 application data kind 30078.

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/glo
• @bitos/bnos-core/glo/adapters
• @bitos/bnos-core/glo/kinds
• @bitos/bnos-core/glo/legacy
• @bitos/bnos-core/glo/model
• @bitos/bnos-core/glo/nostr
• @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.