@bsv/sdk 1.8.1 → 1.8.3

package/docs/reference/kvstore.md

@@ -4,8 +4,434 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ## Interfaces
 
+| |
+| --- |
+| [KVContext](#interface-kvcontext) |
+| [KVStoreConfig](#interface-kvstoreconfig) |
+| [KVStoreEntry](#interface-kvstoreentry) |
+| [KVStoreGetOptions](#interface-kvstoregetoptions) |
+| [KVStoreLookupResult](#interface-kvstorelookupresult) |
+| [KVStoreQuery](#interface-kvstorequery) |
+| [KVStoreRemoveOptions](#interface-kvstoreremoveoptions) |
+| [KVStoreSetOptions](#interface-kvstoresetoptions) |
+| [KVStoreToken](#interface-kvstoretoken) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Interface: KVContext
+
+```ts
+export interface KVContext {
+    key: string;
+    protocolID: WalletProtocol;
+}
+```
+
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreConfig
+
+Configuration interface for GlobalKVStore operations.
+Defines all options for connecting to overlay services and managing KVStore behavior.
+
+```ts
+export interface KVStoreConfig {
+    overlayHost?: string;
+    protocolID?: WalletProtocol;
+    serviceName?: string;
+    tokenAmount?: number;
+    topics?: string[];
+    originator?: string;
+    wallet?: WalletInterface;
+    networkPreset?: "mainnet" | "testnet" | "local";
+    acceptDelayedBroadcast?: boolean;
+    tokenSetDescription?: string;
+    tokenUpdateDescription?: string;
+    tokenRemovalDescription?: string;
+}
+```
+
+See also: [WalletInterface](./wallet.md#interface-walletinterface), [WalletProtocol](./wallet.md#type-walletprotocol)
+
+#### Property acceptDelayedBroadcast
+
+Whether to accept delayed broadcast
+
+```ts
+acceptDelayedBroadcast?: boolean
+```
+
+#### Property networkPreset
+
+Network preset for overlay services
+
+```ts
+networkPreset?: "mainnet" | "testnet" | "local"
+```
+
+#### Property originator
+
+Originator
+
+```ts
+originator?: string
+```
+
+#### Property overlayHost
+
+The overlay service host URL
+
+```ts
+overlayHost?: string
+```
+
+#### Property protocolID
+
+Protocol ID for the KVStore protocol
+
+```ts
+protocolID?: WalletProtocol
+```
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+#### Property serviceName
+
+Service name for overlay submission
+
+```ts
+serviceName?: string
+```
+
+#### Property tokenAmount
+
+Amount of satoshis for each token
+
+```ts
+tokenAmount?: number
+```
+
+#### Property tokenRemovalDescription
+
+Description for token removal
+
+```ts
+tokenRemovalDescription?: string
+```
+
+#### Property tokenSetDescription
+
+Description for token set
+
+```ts
+tokenSetDescription?: string
+```
+
+#### Property tokenUpdateDescription
+
+Description for token update
+
+```ts
+tokenUpdateDescription?: string
+```
+
+#### Property topics
+
+Topics for overlay submission
+
+```ts
+topics?: string[]
+```
+
+#### Property wallet
+
+Wallet interface for operations
+
+```ts
+wallet?: WalletInterface
+```
+See also: [WalletInterface](./wallet.md#interface-walletinterface)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreEntry
+
+KVStore entry returned from queries
+
+```ts
+export interface KVStoreEntry {
+    key: string;
+    value: string;
+    controller: PubKeyHex;
+    protocolID: WalletProtocol;
+    token?: KVStoreToken;
+    history?: string[];
+}
+```
+
+See also: [KVStoreToken](./kvstore.md#interface-kvstoretoken), [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreGetOptions
+
+Options for configuring KVStore get operations (local processing)
+
+```ts
+export interface KVStoreGetOptions {
+    history?: boolean;
+    includeToken?: boolean;
+    serviceName?: string;
+}
+```
+
+#### Property history
+
+Whether to build and include history for each entry
+
+```ts
+history?: boolean
+```
+
+#### Property includeToken
+
+Whether to include token transaction data in results
+
+```ts
+includeToken?: boolean
+```
+
+#### Property serviceName
+
+Service name for overlay retrieval
+
+```ts
+serviceName?: string
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreLookupResult
+
+Result structure for KVStore lookups from overlay services.
+Contains the transaction output information for a found key-value pair.
+
+```ts
+export interface KVStoreLookupResult {
+    txid: string;
+    outputIndex: number;
+    outputScript: string;
+    satoshis: number;
+    history?: (output: any, currentDepth: number) => Promise<boolean>;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreQuery
+
+Query parameters for KVStore lookups from overlay services.
+Used when searching for existing key-value pairs in the network.
+
+```ts
+export interface KVStoreQuery {
+    key?: string;
+    controller?: PubKeyHex;
+    protocolID?: WalletProtocol;
+    limit?: number;
+    skip?: number;
+    sortOrder?: "asc" | "desc";
+}
+```
+
+See also: [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreRemoveOptions
+
+```ts
+export interface KVStoreRemoveOptions {
+    protocolID?: WalletProtocol;
+    tokenRemovalDescription?: string;
+}
+```
+
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreSetOptions
+
+```ts
+export interface KVStoreSetOptions {
+    protocolID?: WalletProtocol;
+    tokenSetDescription?: string;
+    tokenUpdateDescription?: string;
+    tokenAmount?: number;
+}
+```
+
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: KVStoreToken
+
+Token structure containing a KVStore token from overlay services.
+Wraps the transaction data and metadata for a key-value pair.
+
+```ts
+export interface KVStoreToken {
+    txid: string;
+    outputIndex: number;
+    satoshis: number;
+    beef: Beef;
+}
+```
+
+See also: [Beef](./transaction.md#class-beef)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ## Classes
 
+| |
+| --- |
+| [GlobalKVStore](#class-globalkvstore) |
+| [LocalKVStore](#class-localkvstore) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Class: GlobalKVStore
+
+Implements a global key-value storage system which uses an overlay service to track key-value pairs.
+Each key-value pair is represented by a PushDrop token output.
+Allows getting, setting, and removing key-value pairs with optional fetching by protocolID and history tracking.
+
+```ts
+export class GlobalKVStore {
+    constructor(config: KVStoreConfig = {}) 
+    async get(query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> 
+    async set(key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> 
+    async remove(key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> 
+}
+```
+
+See also: [CreateActionOutput](./wallet.md#interface-createactionoutput), [HexString](./wallet.md#type-hexstring), [KVStoreConfig](./kvstore.md#interface-kvstoreconfig), [KVStoreEntry](./kvstore.md#interface-kvstoreentry), [KVStoreGetOptions](./kvstore.md#interface-kvstoregetoptions), [KVStoreQuery](./kvstore.md#interface-kvstorequery), [KVStoreRemoveOptions](./kvstore.md#interface-kvstoreremoveoptions), [KVStoreSetOptions](./kvstore.md#interface-kvstoresetoptions), [OutpointString](./wallet.md#type-outpointstring)
+
+#### Constructor
+
+Creates an instance of the GlobalKVStore.
+
+```ts
+constructor(config: KVStoreConfig = {}) 
+```
+See also: [KVStoreConfig](./kvstore.md#interface-kvstoreconfig)
+
+Argument Details
+
++ **config**
+  + Configuration options for the KVStore. Defaults to empty object.
++ **config.wallet**
+  + Wallet to use for operations. Defaults to WalletClient.
+
+Throws
+
+If the configuration contains invalid parameters.
+
+#### Method get
+
+Retrieves data from the KVStore.
+Can query by key+controller (single result), protocolID, controller, or key (multiple results).
+
+```ts
+async get(query: KVStoreQuery, options: KVStoreGetOptions = {}): Promise<KVStoreEntry | KVStoreEntry[] | undefined> 
+```
+See also: [KVStoreEntry](./kvstore.md#interface-kvstoreentry), [KVStoreGetOptions](./kvstore.md#interface-kvstoregetoptions), [KVStoreQuery](./kvstore.md#interface-kvstorequery)
+
+Returns
+
+Single entry for key+controller queries, array for all other queries
+
+Argument Details
+
++ **query**
+  + Query parameters sent to overlay
++ **options**
+  + Configuration options for the get operation
+
+#### Method remove
+
+Removes the key-value pair associated with the given key from the overlay service.
+
+```ts
+async remove(key: string, outputs?: CreateActionOutput[], options: KVStoreRemoveOptions = {}): Promise<HexString> 
+```
+See also: [CreateActionOutput](./wallet.md#interface-createactionoutput), [HexString](./wallet.md#type-hexstring), [KVStoreRemoveOptions](./kvstore.md#interface-kvstoreremoveoptions)
+
+Returns
+
+A promise that resolves to the txid of the removal transaction if successful.
+
+Argument Details
+
++ **key**
+  + The key to remove.
++ **outputs**
+  + Additional outputs to include in the removal transaction.
++ **options**
+  + Optional parameters for the removal operation.
+
+Throws
+
+If the key is invalid.
+
+If the key does not exist in the store.
+
+If the overlay service is unreachable or the transaction fails.
+
+If there are existing tokens that cannot be unlocked.
+
+#### Method set
+
+Sets a key-value pair. The current user (wallet identity) becomes the controller.
+
+```ts
+async set(key: string, value: string, options: KVStoreSetOptions = {}): Promise<OutpointString> 
+```
+See also: [KVStoreSetOptions](./kvstore.md#interface-kvstoresetoptions), [OutpointString](./wallet.md#type-outpointstring)
+
+Returns
+
+The outpoint of the created token
+
+Argument Details
+
++ **key**
+  + The key to set (user computes this however they want)
++ **value**
+  + The value to store
++ **options**
+  + Configuration options for the set operation
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Class: LocalKVStore
 
 Implements a key-value storage system backed by transaction outputs managed by a wallet.
@@ -134,3 +560,62 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ## Variables
 
+| |
+| --- |
+| [kvProtocol](#variable-kvprotocol) |
+| [kvStoreInterpreter](#variable-kvstoreinterpreter) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Variable: kvProtocol
+
+```ts
+kvProtocol = {
+    protocolID: 0,
+    key: 1,
+    value: 2,
+    controller: 3,
+    signature: 4
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Variable: kvStoreInterpreter
+
+```ts
+kvStoreInterpreter: InterpreterFunction<string, KVContext> = async (transaction: Transaction, outputIndex: number, ctx?: KVContext): Promise<string | undefined> => {
+    try {
+        const output = transaction.outputs[outputIndex];
+        if (output == null || output.lockingScript == null)
+            return undefined;
+        if (ctx == null || ctx.key == null)
+            return undefined;
+        const decoded = PushDrop.decode(output.lockingScript);
+        if (decoded.fields.length !== Object.keys(kvProtocol).length)
+            return undefined;
+        const key = Utils.toUTF8(decoded.fields[kvProtocol.key]);
+        const protocolID = Utils.toUTF8(decoded.fields[kvProtocol.protocolID]);
+        if (key !== ctx.key || protocolID !== JSON.stringify(ctx.protocolID))
+            return undefined;
+        try {
+            return Utils.toUTF8(decoded.fields[kvProtocol.value]);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+```
+
+See also: [KVContext](./kvstore.md#interface-kvcontext), [PushDrop](./script.md#class-pushdrop), [Transaction](./transaction.md#class-transaction), [kvProtocol](./kvstore.md#variable-kvprotocol), [toUTF8](./primitives.md#variable-toutf8)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/kvstore/index.ts

@@ -1 +1,2 @@
 export { default as LocalKVStore } from './LocalKVStore.js'
+export { default as GlobalKVStore } from './GlobalKVStore.js'

package/src/primitives/Random.ts

@@ -1,6 +1,25 @@
+/**
+ * Random number generator that works across modern JavaScript environments.
+ *
+ * This implementation uses the Web Crypto API which is available in:
+ * - Node.js 6+ via require('crypto').randomBytes()
+ * - Node.js 18+ via globalThis.crypto
+ * - Modern browsers via globalThis.crypto, self.crypto, or window.crypto
+ * - Web Workers and Service Workers via self.crypto
+ * - Deno and Bun via globalThis.crypto
+ * - React Native (requires react-native-get-random-values polyfill)
+ *
+ * @throws {Error} If no secure random number generator is available
+ */
 class Rand {
   _rand: (n: number) => number[] // ✅ Explicit function type
 
+  getRandomValues (obj: any, n: number): number[] {
+    const arr = new Uint8Array(n)
+    obj.crypto.getRandomValues(arr)
+    return Array.from(arr)
+  }
+
   constructor () {
     const noRand = (): never => {
       throw new Error(
@@ -10,29 +29,79 @@ class Rand {
 
     this._rand = noRand // Assign the function
 
-    if (typeof self === 'object') {
-      /* eslint-disable-next-line */
-      if (self.crypto?.getRandomValues) {
-        this._rand = (n) => {
-          const arr = new Uint8Array(n)
-          /* eslint-disable-next-line */
-          self.crypto.getRandomValues(arr);
-          return [...arr]
-        }
-      } /* if (typeof window === 'object') */ else {
-        this._rand = noRand
+    // Try globalThis.crypto (works in Node.js 18+, modern browsers, and Deno)
+    if (typeof globalThis !== 'undefined' && typeof (globalThis as any).crypto?.getRandomValues === 'function') {
+      this._rand = (n) => {
+        /* eslint-disable-next-line */
+        return this.getRandomValues(globalThis as any, n)
       }
-    } else {
+      return
+    }
+
+    // Node.js fallback for versions < 18
+    if (typeof process !== 'undefined' && process.release?.name === 'node') {
       try {
-        /* eslint-disable-next-line */
-        const crypto = require("crypto");
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const crypto = require('crypto')
         if (typeof crypto.randomBytes === 'function') {
-          this._rand = (n: number) => [...crypto.randomBytes(n)]
+          this._rand = (n) => {
+            return Array.from(crypto.randomBytes(n))
+          }
+          return
         }
-      } catch {
-        this._rand = noRand
+      } catch (e) {
+        // crypto module not available, continue to other checks
       }
     }
+
+    // Try self.crypto (Web Workers and Service Workers)
+    if (typeof self !== 'undefined' && typeof self.crypto?.getRandomValues === 'function') {
+      this._rand = (n) => {
+        /* eslint-disable-next-line */
+        return this.getRandomValues(self as any, n)
+      }
+      return
+    }
+
+    // Try window.crypto (browsers)
+    if (typeof window !== 'undefined' && typeof (window as any).crypto?.getRandomValues === 'function') {
+      this._rand = (n) => {
+        /* eslint-disable-next-line */
+        return this.getRandomValues(window as any, n)
+      }
+      return
+    }
+
+    // React Native support - try to load polyfill
+    if (typeof navigator !== 'undefined' && (navigator as any).product === 'ReactNative') {
+      try {
+        // Try to require the polyfill - this will populate globalThis.crypto
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        require('react-native-get-random-values')
+
+        if (typeof (globalThis as any).crypto?.getRandomValues === 'function') {
+          this._rand = (n) => {
+            /* eslint-disable-next-line */
+            return this.getRandomValues(globalThis as any, n)
+          }
+          return
+        }
+      } catch (e) {
+        // Polyfill not available - provide helpful error
+        this._rand = (): never => {
+          throw new Error(
+            'React Native detected but crypto is not available. ' +
+            'Please install and import "react-native-get-random-values" at the top of your entry file:\n' +
+            'npm install react-native-get-random-values\n' +
+            'Then add: import "react-native-get-random-values" to your index.js/App.js'
+          )
+        }
+        return
+      }
+    }
+
+    // No crypto available
+    this._rand = noRand
   }
 
   generate (len: number): number[] {

package/src/primitives/__tests/Random.test.ts

@@ -11,4 +11,25 @@ describe('Random', () => {
     // I haven't seen it fail yet. If you see it fail, please let me know.
     expect(Random(32)).not.toEqual(Random(32))
   })
+  it('Produces values in valid byte range (0-255)', () => {
+    const bytes = Random(100)
+    bytes.forEach(byte => {
+      expect(byte).toBeGreaterThanOrEqual(0)
+      expect(byte).toBeLessThanOrEqual(255)
+    })
+  })
+  it('Works with various lengths including edge cases', () => {
+    expect(Random(1).length).toBe(1)
+    expect(Random(16).length).toBe(16)
+    expect(Random(32).length).toBe(32)
+    expect(Random(64).length).toBe(64)
+    expect(Random(256).length).toBe(256)
+  })
+  it('Returns an array of numbers', () => {
+    const bytes = Random(10)
+    expect(Array.isArray(bytes)).toBe(true)
+    bytes.forEach(byte => {
+      expect(typeof byte).toBe('number')
+    })
+  })
 })