@bsv/sdk 1.8.11 → 1.8.13

package/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)
+
+---

package/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/docs/tutorials/advanced-transaction.md

@@ -17,7 +17,7 @@ This tutorial builds on your knowledge of basic `WalletClient` usage to explore
 ## Prerequisites
 
 - Complete the [Transaction Types and Data](./transaction-types.md) tutorial
-- Have a BRC-100 compliant wallet (such as the [MetaNet Desktop Wallet](https://metanet.bsvb.tech/)) installed and configured
+- Have a BRC-100 compliant wallet (such as the [MetaNet Desktop Wallet](https://desktop.bsvb.tech/)) installed and configured
 - Some BSV in your wallet
 - Understanding of Bitcoin transaction fundamentals
 
@@ -569,4 +569,4 @@ These techniques enable you to build production-ready applications that efficien
 
 - [Wallet Reference](../reference/wallet.md)
 - [BSV Blockchain Documentation](https://docs.bsvblockchain.org/)
-- [MetaNet Desktop Wallet](https://metanet.bsvb.tech/)
+- [MetaNet Desktop Wallet](https://desktop.bsvb.tech/)

package/docs/tutorials/first-transaction.md

@@ -18,7 +18,7 @@ In this tutorial, you'll learn how to create your first Bitcoin SV transactions
 
 ## Precondition
 
-Install a BRC-100 compliant wallet such as the [MetaNet Desktop Wallet](https://metanet.bsvb.tech/). When you install it, you'll receive a small amount of funds to play with.
+Install a BRC-100 compliant wallet such as the [MetaNet Desktop Wallet](https://desktop.bsvb.tech/). When you install it, you'll receive a small amount of funds to play with.
 
 ## Step 1: Setting Up Your Environment
 

package/docs/tutorials/transaction-types.md

@@ -17,7 +17,7 @@ In the previous tutorial, you created a simple transaction that sent BSV to a si
 ## Prerequisites
 
 - Complete the [Your First BSV Transaction](./first-transaction.md) tutorial
-- Have a BRC-100 compliant wallet (such as [MetaNet Desktop Wallet](https://metanet.bsvb.tech/)) installed and configured
+- Have a BRC-100 compliant wallet (such as [MetaNet Desktop Wallet](https://desktop.bsvb.tech/)) installed and configured
 - Some BSV in your wallet
 
 ## Transaction with Multiple Outputs

package/package.json

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

package/src/overlay-tools/HostReputationTracker.ts

@@ -0,0 +1,232 @@
+interface HostReputationEntry {
+  host: string
+  totalSuccesses: number
+  totalFailures: number
+  consecutiveFailures: number
+  avgLatencyMs: number | null
+  lastLatencyMs: number | null
+  backoffUntil: number
+  lastUpdatedAt: number
+  lastError?: string
+}
+
+export interface RankedHost extends HostReputationEntry {
+  score: number
+}
+
+const DEFAULT_LATENCY_MS = 1500
+const LATENCY_SMOOTHING_FACTOR = 0.25
+const BASE_BACKOFF_MS = 1000
+const MAX_BACKOFF_MS = 60_000
+const FAILURE_PENALTY_MS = 400
+const SUCCESS_BONUS_MS = 30
+const FAILURE_BACKOFF_GRACE = 2
+const STORAGE_KEY = 'bsvsdk_overlay_host_reputation_v1'
+
+interface KeyValueStore {
+  get: (key: string) => string | null | undefined
+  set: (key: string, value: string) => void
+}
+
+export class HostReputationTracker {
+  private readonly stats: Map<string, HostReputationEntry>
+  private readonly store: KeyValueStore | undefined
+
+  constructor (store?: KeyValueStore) {
+    this.stats = new Map()
+    this.store = store ?? this.getLocalStorageAdapter()
+    this.loadFromStorage()
+  }
+
+  reset (): void {
+    this.stats.clear()
+  }
+
+  recordSuccess (host: string, latencyMs: number): void {
+    const entry = this.getOrCreate(host)
+    const now = Date.now()
+    const safeLatency = Number.isFinite(latencyMs) && latencyMs >= 0 ? latencyMs : DEFAULT_LATENCY_MS
+    if (entry.avgLatencyMs === null) {
+      entry.avgLatencyMs = safeLatency
+    } else {
+      entry.avgLatencyMs =
+        (1 - LATENCY_SMOOTHING_FACTOR) * entry.avgLatencyMs +
+        LATENCY_SMOOTHING_FACTOR * safeLatency
+    }
+    entry.lastLatencyMs = safeLatency
+    entry.totalSuccesses += 1
+    entry.consecutiveFailures = 0
+    entry.backoffUntil = 0
+    entry.lastUpdatedAt = now
+    entry.lastError = undefined
+    this.saveToStorage()
+  }
+
+  recordFailure (host: string, reason?: unknown): void {
+    const entry = this.getOrCreate(host)
+    const now = Date.now()
+    entry.totalFailures += 1
+    entry.consecutiveFailures += 1
+    const msg =
+      typeof reason === 'string'
+        ? reason
+        : reason instanceof Error
+          ? reason.message
+          : undefined
+    const immediate =
+      typeof msg === 'string' &&
+      (msg.includes('ERR_NAME_NOT_RESOLVED') ||
+        msg.includes('ENOTFOUND') ||
+        msg.includes('getaddrinfo') ||
+        msg.includes('Failed to fetch'))
+    if (immediate && entry.consecutiveFailures < FAILURE_BACKOFF_GRACE + 1) {
+      entry.consecutiveFailures = FAILURE_BACKOFF_GRACE + 1
+    }
+    const penaltyLevel = Math.max(entry.consecutiveFailures - FAILURE_BACKOFF_GRACE, 0)
+    if (penaltyLevel === 0) {
+      entry.backoffUntil = 0
+    } else {
+      const backoffDuration = Math.min(
+        MAX_BACKOFF_MS,
+        BASE_BACKOFF_MS * Math.pow(2, penaltyLevel - 1)
+      )
+      entry.backoffUntil = now + backoffDuration
+    }
+    entry.lastUpdatedAt = now
+    entry.lastError =
+      typeof reason === 'string'
+        ? reason
+        : reason instanceof Error
+          ? reason.message
+          : undefined
+    this.saveToStorage()
+  }
+
+  rankHosts (hosts: string[], now: number = Date.now()): RankedHost[] {
+    const seen = new Map<string, number>()
+    hosts.forEach((host, idx) => {
+      if (typeof host !== 'string' || host.length === 0) return
+      if (!seen.has(host)) seen.set(host, idx)
+    })
+
+    const orderedHosts = Array.from(seen.keys())
+    const ranked = orderedHosts.map((host) => {
+      const entry = this.getOrCreate(host)
+      return {
+        ...entry,
+        score: this.computeScore(entry, now),
+        originalOrder: seen.get(host) ?? 0
+      }
+    })
+
+    ranked.sort((a, b) => {
+      const aInBackoff = a.backoffUntil > now
+      const bInBackoff = b.backoffUntil > now
+      if (aInBackoff !== bInBackoff) return aInBackoff ? 1 : -1
+      if (a.score !== b.score) return a.score - b.score
+      if (a.totalSuccesses !== b.totalSuccesses) return b.totalSuccesses - a.totalSuccesses
+      return (a as any).originalOrder - (b as any).originalOrder
+    })
+
+    return ranked.map(({ originalOrder, ...rest }) => rest)
+  }
+
+  snapshot (host: string): HostReputationEntry | undefined {
+    const entry = this.stats.get(host)
+    return entry != null ? { ...entry } : undefined
+  }
+
+  private getStorage (): any {
+    try {
+      const g: any = typeof globalThis === 'object' ? globalThis : undefined
+      if (g == null || g.localStorage == null) return undefined
+      return g.localStorage
+    } catch {
+      return undefined
+    }
+  }
+
+  private getLocalStorageAdapter (): KeyValueStore | undefined {
+    const s = this.getStorage()
+    if (s == null) return undefined
+    return {
+      get: (key: string) => {
+        try { return s.getItem(key) } catch { return null }
+      },
+      set: (key: string, value: string) => {
+        try { s.setItem(key, value) } catch { }
+      }
+    }
+  }
+
+  private loadFromStorage (): void {
+    const s = this.store
+    if (s == null) return
+    try {
+      const raw = s.get(STORAGE_KEY)
+      if (typeof raw !== 'string' || raw.length === 0) return
+      const data = JSON.parse(raw)
+      if (typeof data !== 'object' || data === null) return
+      this.stats.clear()
+      for (const k of Object.keys(data)) {
+        const v: any = (data)[k]
+        if (v != null && typeof v === 'object') {
+          const entry: HostReputationEntry = {
+            host: String(v.host ?? k),
+            totalSuccesses: Number(v.totalSuccesses ?? 0),
+            totalFailures: Number(v.totalFailures ?? 0),
+            consecutiveFailures: Number(v.consecutiveFailures ?? 0),
+            avgLatencyMs: v.avgLatencyMs == null ? null : Number(v.avgLatencyMs),
+            lastLatencyMs: v.lastLatencyMs == null ? null : Number(v.lastLatencyMs),
+            backoffUntil: Number(v.backoffUntil ?? 0),
+            lastUpdatedAt: Number(v.lastUpdatedAt ?? 0),
+            lastError: typeof v.lastError === 'string' ? v.lastError : undefined
+          }
+          this.stats.set(entry.host, entry)
+        }
+      }
+    } catch {}
+  }
+
+  private saveToStorage (): void {
+    const s = this.store
+    if (s == null) return
+    try {
+      const obj: Record<string, any> = {}
+      for (const [host, entry] of this.stats.entries()) {
+        obj[host] = entry
+      }
+      s.set(STORAGE_KEY, JSON.stringify(obj))
+    } catch {}
+  }
+
+  private computeScore (entry: HostReputationEntry, now: number): number {
+    const latency = entry.avgLatencyMs ?? DEFAULT_LATENCY_MS
+    const failurePenalty = entry.consecutiveFailures * FAILURE_PENALTY_MS
+    const successBonus = Math.min(entry.totalSuccesses * SUCCESS_BONUS_MS, latency / 2)
+    const backoffPenalty = entry.backoffUntil > now ? entry.backoffUntil - now : 0
+    return latency + failurePenalty + backoffPenalty - successBonus
+  }
+
+  private getOrCreate (host: string): HostReputationEntry {
+    let entry = this.stats.get(host)
+    if (entry == null) {
+      entry = {
+        host,
+        totalSuccesses: 0,
+        totalFailures: 0,
+        consecutiveFailures: 0,
+        avgLatencyMs: null,
+        lastLatencyMs: null,
+        backoffUntil: 0,
+        lastUpdatedAt: 0
+      }
+      this.stats.set(host, entry)
+    }
+    return entry
+  }
+}
+
+const globalTracker = new HostReputationTracker()
+
+export const getOverlayHostReputationTracker = (): HostReputationTracker => globalTracker

package/src/overlay-tools/LookupResolver.ts

@@ -1,6 +1,7 @@
 import { Transaction } from '../transaction/index.js'
 import OverlayAdminTokenTemplate from './OverlayAdminTokenTemplate.js'
 import * as Utils from '../primitives/utils.js'
+import { getOverlayHostReputationTracker, HostReputationTracker } from './HostReputationTracker.js'
 
 const defaultFetch: typeof fetch =
   typeof globalThis !== 'undefined' && typeof globalThis.fetch === 'function'
@@ -92,6 +93,8 @@ export interface LookupResolverConfig {
   additionalHosts?: Record<string, string[]>
   /** Optional cache tuning. */
   cache?: CacheOptions
+  /** Optional storage for host reputation data. */
+  reputationStorage?: 'localStorage' | { get: (key: string) => string | null | undefined, set: (key: string, value: string) => void }
 }
 
 /** Facilitates lookups to URLs that return answers. */
@@ -204,6 +207,7 @@ export default class LookupResolver {
   private readonly hostOverrides: Record<string, string[]>
   private readonly additionalHosts: Record<string, string[]>
   private readonly networkPreset: 'mainnet' | 'testnet' | 'local'
+  private readonly hostReputation: HostReputationTracker
 
   // ---- Caches / memoization ----
   private readonly hostsCache: Map<string, { hosts: string[], expiresAt: number }>
@@ -223,6 +227,15 @@ export default class LookupResolver {
     this.hostOverrides = hostOverrides
     this.additionalHosts = config.additionalHosts ?? {}
 
+    const rs = config.reputationStorage
+    if (rs === 'localStorage') {
+      this.hostReputation = new HostReputationTracker()
+    } else if (typeof rs === 'object' && rs !== null && typeof rs.get === 'function' && typeof rs.set === 'function') {
+      this.hostReputation = new HostReputationTracker(rs)
+    } else {
+      this.hostReputation = getOverlayHostReputationTracker()
+    }
+
     // cache tuning
     this.hostsTtlMs = config.cache?.hostsTtlMs ?? 5 * 60 * 1000 // 5 min
     this.hostsMaxEntries = config.cache?.hostsMaxEntries ?? 128
@@ -262,10 +275,18 @@ export default class LookupResolver {
       )
     }
 
+    const rankedHosts = this.prepareHostsForQuery(
+      competentHosts,
+      `lookup service ${question.service}`
+    )
+    if (rankedHosts.length < 1) {
+      throw new Error(`All competent hosts for ${question.service} are temporarily unavailable due to backoff.`)
+    }
+
     // Fire all hosts with per-host timeout, harvest successful output-list responses
     const hostResponses = await Promise.allSettled(
-      competentHosts.map(async (host) => {
-        return await this.facilitator.lookup(host, question, timeout)
+      rankedHosts.map(async (host) => {
+        return await this.lookupHostWithTracking(host, question, timeout)
       })
     )
 
@@ -382,9 +403,15 @@ export default class LookupResolver {
     }
 
     // Query all SLAP trackers; tolerate failures.
+    const trackerHosts = this.prepareHostsForQuery(
+      this.slapTrackers,
+      'SLAP trackers'
+    )
+    if (trackerHosts.length === 0) return []
+
     const trackerResponses = await Promise.allSettled(
-      this.slapTrackers.map(async (tracker) =>
-        await this.facilitator.lookup(tracker, query, MAX_TRACKER_WAIT_TIME)
+      trackerHosts.map(async (tracker) =>
+        await this.lookupHostWithTracking(tracker, query, MAX_TRACKER_WAIT_TIME)
       )
     )
 
@@ -427,4 +454,46 @@ export default class LookupResolver {
       }
     }
   }
+
+  private prepareHostsForQuery (hosts: string[], context: string): string[] {
+    if (hosts.length === 0) return []
+    const now = Date.now()
+    const ranked = this.hostReputation.rankHosts(hosts, now)
+    const available = ranked.filter((h) => h.backoffUntil <= now).map((h) => h.host)
+    if (available.length > 0) return available
+
+    const soonest = Math.min(...ranked.map((h) => h.backoffUntil))
+    const waitMs = Math.max(soonest - now, 0)
+    throw new Error(
+      `All ${context} hosts are backing off for approximately ${waitMs}ms due to repeated failures.`
+    )
+  }
+
+  private async lookupHostWithTracking (
+    host: string,
+    question: LookupQuestion,
+    timeout?: number
+  ): Promise<LookupAnswer> {
+    const startedAt = Date.now()
+    try {
+      const answer = await this.facilitator.lookup(host, question, timeout)
+      const latency = Date.now() - startedAt
+      const isValid =
+        typeof answer === 'object' &&
+        answer !== null &&
+        answer.type === 'output-list' &&
+        Array.isArray((answer).outputs)
+
+      if (isValid) {
+        this.hostReputation.recordSuccess(host, latency)
+      } else {
+        this.hostReputation.recordFailure(host, 'Invalid lookup response')
+      }
+
+      return answer
+    } catch (err) {
+      this.hostReputation.recordFailure(host, err)
+      throw err
+    }
+  }
 }

package/src/overlay-tools/__tests/LookupResolver.test.ts

@@ -1,6 +1,7 @@
 import LookupResolver, {
   HTTPSOverlayLookupFacilitator
 } from '../LookupResolver'
+import { getOverlayHostReputationTracker } from '../HostReputationTracker'
 import OverlayAdminTokenTemplate from '../../overlay-tools/OverlayAdminTokenTemplate'
 import { CompletedProtoWallet } from '../../auth/certificates/__tests/CompletedProtoWallet'
 import { PrivateKey } from '../../primitives/index'
@@ -37,8 +38,10 @@ const sampleBeef4 = new Transaction(
 ).toBEEF()
 
 describe('LookupResolver', () => {
+  const hostTracker = getOverlayHostReputationTracker()
   beforeEach(() => {
     mockFacilitator.lookup.mockReset()
+    hostTracker.reset()
   })
 
   it('should query the host and return the response when a single host is found via SLAP', async () => {
@@ -967,6 +970,123 @@ describe('LookupResolver', () => {
       'HTTPS facilitator can only use URLs that start with "https:"'
     )
   })
+
+  describe('Host reputation tracking', () => {
+    it('shares performance learnings across resolver instances and prefers low latency hosts', async () => {
+      const fastHost = 'https://fast.host'
+      const slowHost = 'https://slow.host'
+      const hosts = [slowHost, fastHost]
+      let fakeNow = 0
+      const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => fakeNow)
+
+      try {
+        mockFacilitator.lookup.mockImplementation(async (url: string) => {
+          if (url === slowHost) {
+            fakeNow += 80
+          } else if (url === fastHost) {
+            fakeNow += 5
+          }
+          return {
+            type: 'output-list',
+            outputs: [
+              {
+                beef: url === fastHost ? sampleBeef2 : sampleBeef1,
+                outputIndex: url === fastHost ? 2 : 1
+              }
+            ]
+          }
+        })
+
+        const resolverA = new LookupResolver({
+          facilitator: mockFacilitator,
+          hostOverrides: {
+            ls_latency: hosts
+          }
+        })
+        await resolverA.query({
+          service: 'ls_latency',
+          query: { attempt: 1 }
+        })
+
+        mockFacilitator.lookup.mockClear()
+
+        const resolverB = new LookupResolver({
+          facilitator: mockFacilitator,
+          hostOverrides: {
+            ls_latency: hosts
+          }
+        })
+        await resolverB.query({
+          service: 'ls_latency',
+          query: { attempt: 2 }
+        })
+
+        const orderedHosts = mockFacilitator.lookup.mock.calls.map((call) => call[0])
+        expect(orderedHosts).toEqual([fastHost, slowHost])
+      } finally {
+        nowSpy.mockRestore()
+      }
+    })
+
+    it('exponentially backs off consistently failing hosts to avoid repeated work', async () => {
+      const failingHost = 'https://offline.host'
+      const healthyHost = 'https://healthy.host'
+      let fakeNow = 0
+      const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => fakeNow)
+      const callLog: string[] = []
+      let failingCalls = 0
+
+      try {
+        mockFacilitator.lookup.mockImplementation(async (url: string) => {
+          callLog.push(url)
+          fakeNow += 5
+          if (url === failingHost) {
+            failingCalls += 1
+            throw new Error('offline')
+          }
+          return {
+            type: 'output-list',
+            outputs: [
+              {
+                beef: sampleBeef3,
+                outputIndex: 0
+              }
+            ]
+          }
+        })
+
+        const resolver = new LookupResolver({
+          facilitator: mockFacilitator,
+          hostOverrides: {
+            ls_backoff: [failingHost, healthyHost]
+          }
+        })
+
+        // First three attempts should contact both hosts (grace period)
+        await resolver.query({ service: 'ls_backoff', query: { attempt: 1 } })
+        fakeNow += 20
+        await resolver.query({ service: 'ls_backoff', query: { attempt: 2 } })
+        fakeNow += 20
+        await resolver.query({ service: 'ls_backoff', query: { attempt: 3 } })
+
+        expect(failingCalls).toBe(3)
+
+        // Immediately try again; failing host should now be in backoff and skipped
+        fakeNow += 20
+        await resolver.query({ service: 'ls_backoff', query: { attempt: 4 } })
+        expect(failingCalls).toBe(3)
+        const lastCall = callLog[callLog.length - 1]
+        expect(lastCall).toBe(healthyHost)
+
+        // Advance beyond the backoff window so the failing host is retried
+        fakeNow = 2000
+        await resolver.query({ service: 'ls_backoff', query: { attempt: 5 } })
+        expect(failingCalls).toBe(4)
+      } finally {
+        nowSpy.mockRestore()
+      }
+    })
+  })
   describe('LookupResolver Resiliency', () => {
     beforeEach(() => {
       mockFacilitator.lookup.mockReset()