Merge pull request #376 from bsv-blockchain/overlay-reputation

Overlay reputation

Author: ty-everett

CHANGELOG.md

@@ -1,10 +1,12 @@
 # CHANGELOG for `@bsv/sdk`
 
-All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec2.0.0.html).
 
 ## Table of Contents
 
 - [Unreleased](#unreleased)
+- [1.8.13 - 2025-11-06](#1813---2025-11-06)
+- [1.8.12 - 2025-11-06](#1812---2025-11-06)
 - [1.8.11 - 2025-10-30](#1811---2025-10-30)
 - [1.8.10 - 2025-10-28](#1810---2025-10-28)
 - [1.8.9 - 2025-10-27](#189---2025-10-27)
@@ -171,6 +173,14 @@ All notable changes to this project will be documented in this file. The format
 
 ---
 
+### [1.8.13] - 2025-11-06
+
+### Added
+
+- LookupResolver: Support for custom overlay ranking to allow for expedited lookups and reputation tracking.
+
+---
+
 ### [1.8.12] - 2025-11-06
 
 ### Fixed

docs/reference/overlay-tools.md

@@ -11,6 +11,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [LookupResolverConfig](#interface-lookupresolverconfig) |
 | [OverlayBroadcastFacilitator](#interface-overlaybroadcastfacilitator) |
 | [OverlayLookupFacilitator](#interface-overlaylookupfacilitator) |
+| [RankedHost](#interface-rankedhost) |
 | [SHIPBroadcasterConfig](#interface-shipbroadcasterconfig) |
 | [TaggedBEEF](#interface-taggedbeef) |
 
@@ -101,6 +102,10 @@ export interface LookupResolverConfig {
     hostOverrides?: Record<string, string[]>;
     additionalHosts?: Record<string, string[]>;
     cache?: CacheOptions;
+    reputationStorage?: "localStorage" | {
+        get: (key: string) => string | null | undefined;
+        set: (key: string, value: string) => void;
+    };
 }
 ```
 
@@ -150,6 +155,17 @@ The network preset to use, unless other options override it.
 networkPreset?: "mainnet" | "testnet" | "local"
 ```
 
+#### Property reputationStorage
+
+Optional storage for host reputation data.
+
+```ts
+reputationStorage?: "localStorage" | {
+    get: (key: string) => string | null | undefined;
+    set: (key: string, value: string) => void;
+}
+```
+
 #### Property slapTrackers
 
 The list of SLAP trackers queried to resolve Overlay Services hosts for a given lookup service.
@@ -199,6 +215,17 @@ See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion]
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Interface: RankedHost
+
+```ts
+export interface RankedHost extends HostReputationEntry {
+    score: number;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Interface: SHIPBroadcasterConfig
 
@@ -294,6 +321,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | --- |
 | [HTTPSOverlayBroadcastFacilitator](#class-httpsoverlaybroadcastfacilitator) |
 | [HTTPSOverlayLookupFacilitator](#class-httpsoverlaylookupfacilitator) |
+| [HostReputationTracker](#class-hostreputationtracker) |
 | [LookupResolver](#class-lookupresolver) |
 | [OverlayAdminTokenTemplate](#class-overlayadmintokentemplate) |
 | [TopicBroadcaster](#class-topicbroadcaster) |
@@ -333,6 +361,24 @@ See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion]
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Class: HostReputationTracker
+
+```ts
+export class HostReputationTracker {
+    constructor(store?: KeyValueStore) 
+    reset(): void 
+    recordSuccess(host: string, latencyMs: number): void 
+    recordFailure(host: string, reason?: unknown): void 
+    rankHosts(hosts: string[], now: number = Date.now()): RankedHost[] 
+    snapshot(host: string): HostReputationEntry | undefined 
+}
+```
+
+See also: [RankedHost](./overlay-tools.md#interface-rankedhost)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Class: LookupResolver
 
@@ -569,6 +615,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | --- |
 | [DEFAULT_SLAP_TRACKERS](#variable-default_slap_trackers) |
 | [DEFAULT_TESTNET_SLAP_TRACKERS](#variable-default_testnet_slap_trackers) |
+| [getOverlayHostReputationTracker](#variable-getoverlayhostreputationtracker) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -599,3 +646,14 @@ DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
+### Variable: getOverlayHostReputationTracker
+
+```ts
+getOverlayHostReputationTracker = (): HostReputationTracker => globalTracker
+```
+
+See also: [HostReputationTracker](./overlay-tools.md#class-hostreputationtracker)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---

docs/reference/primitives.md

@@ -4764,6 +4764,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [red](#function-red) |
 | [toArray](#function-toarray) |
 | [toBase64](#function-tobase64) |
+| [verifyNotNull](#function-verifynotnull) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -4889,6 +4890,38 @@ Argument Details
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Function: verifyNotNull
+
+Verifies that a value is not null or undefined, throwing an error if it is.
+
+Example
+
+```ts
+const myValue = verifyNotNull(someValue, 'someValue must be defined')
+```
+
+```ts
+export function verifyNotNull<T>(value: T | undefined | null, errorMessage: string = "Expected a valid value, but got undefined or null."): T 
+```
+
+Returns
+
+- The verified value
+
+Argument Details
+
++ **value**
+  + The value to verify
++ **errorMessage**
+  + The error message to throw if the value is null or undefined
+
+Throws
+
+- If the value is null or undefined
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ## Types
 

package-lock.json

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