@bsv/sdk 1.3.33 → 1.3.34

package/docs/overlay-tools.md

@@ -95,6 +95,7 @@ Configuration options for the Lookup resolver.
 
 ```ts
 export interface LookupResolverConfig {
+    networkPreset?: "mainnet" | "testnet" | "local";
     facilitator?: OverlayLookupFacilitator;
     slapTrackers?: string[];
     hostOverrides?: Record<string, string[]>;
@@ -129,6 +130,17 @@ Map of lookup service names to arrays of hosts to use in place of resolving via
 hostOverrides?: Record<string, string[]>
 ```
 
+#### Property networkPreset
+
+The network preset to use, unless other options override it.
+- mainnet: use mainnet SLAP trackers and HTTPS facilitator
+- testnet: use testnet SLAP trackers and HTTPS facilitator
+- local: directly query from localhost:8080 and a facilitator that permits plain HTTP
+
+```ts
+networkPreset?: "mainnet" | "testnet" | "local"
+```
+
 #### Property slapTrackers
 
 The list of SLAP trackers queried to resolve Overlay Services hosts for a given lookup service.
@@ -185,8 +197,9 @@ Configuration options for the SHIP broadcaster.
 
 ```ts
 export interface SHIPBroadcasterConfig {
+    networkPreset?: "mainnet" | "testnet" | "local";
     facilitator?: OverlayBroadcastFacilitator;
-    resolver: LookupResolver;
+    resolver?: LookupResolver;
     requireAcknowledgmentFromAllHostsForTopics?: "all" | "any" | string[];
     requireAcknowledgmentFromAnyHostForTopics?: "all" | "any" | string[];
     requireAcknowledgmentFromSpecificHostsForTopics?: Record<string, "all" | "any" | string[]>;
@@ -204,6 +217,17 @@ facilitator?: OverlayBroadcastFacilitator
 ```
 See also: [OverlayBroadcastFacilitator](./overlay-tools.md#interface-overlaybroadcastfacilitator)
 
+#### Property networkPreset
+
+The network preset to use, unless other options override it.
+- mainnet: use mainnet resolver and HTTPS facilitator
+- testnet: use testnet resolver and HTTPS facilitator
+- local: directly send to localhost:8080 and a facilitator that permits plain HTTP
+
+```ts
+networkPreset?: "mainnet" | "testnet" | "local"
+```
+
 #### Property requireAcknowledgmentFromAllHostsForTopics
 
 Determines which topics (all, any, or a specific list) must be present within all STEAKs received from every host for the broadcast to be considered a success. By default, all hosts must acknowledge all topics.
@@ -233,7 +257,7 @@ requireAcknowledgmentFromSpecificHostsForTopics?: Record<string, "all" | "any" |
 The resolver used to locate suitable hosts with SHIP
 
 ```ts
-resolver: LookupResolver
+resolver?: LookupResolver
 ```
 See also: [LookupResolver](./overlay-tools.md#class-lookupresolver)
 
@@ -262,7 +286,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [HTTPSOverlayLookupFacilitator](#class-httpsoverlaylookupfacilitator) |
 | [LookupResolver](#class-lookupresolver) |
 | [OverlayAdminTokenTemplate](#class-overlayadmintokentemplate) |
-| [SHIPBroadcaster](#class-shipbroadcaster) |
+| [TopicBroadcaster](#class-topicbroadcaster) |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
@@ -273,7 +297,8 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilitator {
     httpClient: typeof fetch;
-    constructor(httpClient = fetch) 
+    allowHTTP: boolean;
+    constructor(httpClient = fetch, allowHTTP: boolean = false) 
     async send(url: string, taggedBEEF: TaggedBEEF): Promise<STEAK> 
 }
 ```
@@ -288,7 +313,8 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ```ts
 export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
     fetchClient: typeof fetch;
-    constructor(httpClient = fetch) 
+    allowHTTP: boolean;
+    constructor(httpClient = fetch, allowHTTP: boolean = false) 
     async lookup(url: string, question: LookupQuestion, timeout: number = 5000): Promise<LookupAnswer> 
 }
 ```
@@ -304,7 +330,7 @@ Represents an SHIP transaction broadcaster.
 
 ```ts
 export default class LookupResolver {
-    constructor(config?: LookupResolverConfig) 
+    constructor(config: LookupResolverConfig = {}) 
     async query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer> 
 }
 ```
@@ -430,13 +456,13 @@ Argument Details
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
-### Class: SHIPBroadcaster
+### Class: TopicBroadcaster
 
-Represents a SHIP transaction broadcaster.
+Broadcasts transactions to one or more overlay topics.
 
 ```ts
-export default class SHIPBroadcaster implements Broadcaster {
-    constructor(topics: string[], config?: SHIPBroadcasterConfig) 
+export default class TopicBroadcaster implements Broadcaster {
+    constructor(topics: string[], config: SHIPBroadcasterConfig = {}) 
     async broadcast(tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> 
 }
 ```
@@ -448,7 +474,7 @@ See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [Broa
 Constructs an instance of the SHIP broadcaster.
 
 ```ts
-constructor(topics: string[], config?: SHIPBroadcasterConfig) 
+constructor(topics: string[], config: SHIPBroadcasterConfig = {}) 
 ```
 See also: [SHIPBroadcasterConfig](./overlay-tools.md#interface-shipbroadcasterconfig)
 
@@ -531,13 +557,31 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ## Variables
 
+| |
+| --- |
+| [DEFAULT_SLAP_TRACKERS](#variable-default_slap_trackers) |
+| [DEFAULT_TESTNET_SLAP_TRACKERS](#variable-default_testnet_slap_trackers) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
 ### Variable: DEFAULT_SLAP_TRACKERS
 
 ```ts
 DEFAULT_SLAP_TRACKERS: string[] = [
-    "https://overlay.babbage.systems",
-    "https://overlay-example.babbage.systems",
-    "https://office.babbage.systems"
+    "https://users.bapp.dev"
+]
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Variable: DEFAULT_TESTNET_SLAP_TRACKERS
+
+```ts
+DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
+    "https://testnet-users.bapp.dev"
 ]
 ```
 

package/package.json

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

package/src/overlay-tools/LookupResolver.ts

@@ -37,11 +37,7 @@ export type LookupAnswer =
 /** Default SLAP trackers */
 export const DEFAULT_SLAP_TRACKERS: string[] = [
   // Babbage primary overlay service
-  'https://overlay.babbage.systems',
-  // Babbage example overlay
-  'https://overlay-example.babbage.systems',
-  // The Babbage office building
-  'https://office.babbage.systems'
+  'https://users.bapp.dev'
 
   // NOTE: Other entities may submit pull requests to the library if they maintain SLAP overlay services.
   // Additional trackers run by different entities contribute to greater network resiliency.
@@ -51,10 +47,23 @@ export const DEFAULT_SLAP_TRACKERS: string[] = [
   // Trackers known to host invalid or illegal records will be removed at the discretion of the BSV Association.
 ]
 
+/** Default testnet SLAP trackers */
+export const DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
+  // Babbage primary testnet overlay service
+  'https://testnet-users.bapp.dev'
+]
+
 const MAX_TRACKER_WAIT_TIME = 1000
 
 /** Configuration options for the Lookup resolver. */
 export interface LookupResolverConfig {
+  /**
+   * The network preset to use, unless other options override it.
+   * - mainnet: use mainnet SLAP trackers and HTTPS facilitator
+   * - testnet: use testnet SLAP trackers and HTTPS facilitator
+   * - local: directly query from localhost:8080 and a facilitator that permits plain HTTP
+   */
+  networkPreset?: 'mainnet' | 'testnet' | 'local'
   /** The facilitator used to make requests to Overlay Services hosts. */
   facilitator?: OverlayLookupFacilitator
   /** The list of SLAP trackers queried to resolve Overlay Services hosts for a given lookup service. */
@@ -83,9 +92,11 @@ export interface OverlayLookupFacilitator {
 
 export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
   fetchClient: typeof fetch
+  allowHTTP: boolean
 
-  constructor (httpClient = fetch) {
+  constructor (httpClient = fetch, allowHTTP: boolean = false) {
     this.fetchClient = httpClient
+    this.allowHTTP = allowHTTP
   }
 
   async lookup (
@@ -93,7 +104,7 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
     question: LookupQuestion,
     timeout: number = 5000
   ): Promise<LookupAnswer> {
-    if (!url.startsWith('https:')) {
+    if (!url.startsWith('https:') && !this.allowHTTP) {
       throw new Error(
         'HTTPS facilitator can only use URLs that start with "https:"'
       )
@@ -134,26 +145,14 @@ export default class LookupResolver {
   private readonly slapTrackers: string[]
   private readonly hostOverrides: Record<string, string[]>
   private readonly additionalHosts: Record<string, string[]>
-
-  constructor (config?: LookupResolverConfig) {
-    const defaultConfig: LookupResolverConfig = {
-      facilitator: new HTTPSOverlayLookupFacilitator(),
-      slapTrackers: DEFAULT_SLAP_TRACKERS,
-      hostOverrides: {},
-      additionalHosts: {}
-    }
-
-    const {
-      facilitator = defaultConfig.facilitator,
-      slapTrackers = defaultConfig.slapTrackers,
-      hostOverrides = defaultConfig.hostOverrides,
-      additionalHosts = defaultConfig.additionalHosts
-    } = config ?? defaultConfig // ✅ Use a default object directly
-
-    this.facilitator = facilitator ?? new HTTPSOverlayLookupFacilitator()
-    this.slapTrackers = slapTrackers ?? []
-    this.hostOverrides = hostOverrides ?? {}
-    this.additionalHosts = additionalHosts ?? {}
+  private readonly networkPreset: 'mainnet' | 'testnet' | 'local'
+
+  constructor (config: LookupResolverConfig = {}) {
+    this.networkPreset = config.networkPreset ?? 'mainnet'
+    this.facilitator = config.facilitator ?? new HTTPSOverlayLookupFacilitator(undefined, this.networkPreset === 'local')
+    this.slapTrackers = config.slapTrackers ?? (this.networkPreset === 'mainnet' ? DEFAULT_SLAP_TRACKERS : DEFAULT_TESTNET_SLAP_TRACKERS)
+    this.hostOverrides = config.hostOverrides ?? {}
+    this.additionalHosts = config.additionalHosts ?? {}
   }
 
   /**
@@ -165,9 +164,11 @@ export default class LookupResolver {
   ): Promise<LookupAnswer> {
     let competentHosts: string[] = []
     if (question.service === 'ls_slap') {
-      competentHosts = this.slapTrackers
+      competentHosts = this.networkPreset === 'local' ? ['http://localhost:8080'] : this.slapTrackers
     } else if (this.hostOverrides[question.service] != null) {
       competentHosts = this.hostOverrides[question.service]
+    } else if (this.networkPreset === 'local') {
+      competentHosts = ['http://localhost:8080']
     } else {
       competentHosts = await this.findCompetentHosts(question.service)
     }
@@ -179,7 +180,7 @@ export default class LookupResolver {
     }
     if (competentHosts.length < 1) {
       throw new Error(
-        `No competent hosts found by the SLAP trackers for lookup service: ${question.service}`
+        `No competent ${this.networkPreset} hosts found by the SLAP trackers for lookup service: ${question.service}`
       )
     }
 
@@ -230,7 +231,6 @@ export default class LookupResolver {
         console.error('Error processing response outputs:', error)
       }
     }
-    // ✅ Ensure function always returns a value
     return {
       type: 'output-list',
       outputs: Array.from(outputs.values())

package/src/overlay-tools/SHIPBroadcaster.ts

@@ -50,10 +50,17 @@ export type STEAK = Record<string, AdmittanceInstructions>
 
 /** Configuration options for the SHIP broadcaster. */
 export interface SHIPBroadcasterConfig {
+  /**
+   * The network preset to use, unless other options override it.
+   * - mainnet: use mainnet resolver and HTTPS facilitator
+   * - testnet: use testnet resolver and HTTPS facilitator
+   * - local: directly send to localhost:8080 and a facilitator that permits plain HTTP
+   */
+  networkPreset?: 'mainnet' | 'testnet' | 'local'
   /** The facilitator used to make requests to Overlay Services hosts. */
   facilitator?: OverlayBroadcastFacilitator
   /** The resolver used to locate suitable hosts with SHIP */
-  resolver: LookupResolver
+  resolver?: LookupResolver
   /** Determines which topics (all, any, or a specific list) must be present within all STEAKs received from every host for the broadcast to be considered a success. By default, all hosts must acknowledge all topics. */
   requireAcknowledgmentFromAllHostsForTopics?: 'all' | 'any' | string[]
   /** Determines which topics (all, any, or a specific list) must be present within STEAK received from at least one host for the broadcast to be considered a success. */
@@ -71,13 +78,15 @@ const MAX_SHIP_QUERY_TIMEOUT = 1000
 
 export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilitator {
   httpClient: typeof fetch
+  allowHTTP: boolean
 
-  constructor (httpClient = fetch) {
+  constructor (httpClient = fetch, allowHTTP: boolean = false) {
     this.httpClient = httpClient
+    this.allowHTTP = false
   }
 
   async send (url: string, taggedBEEF: TaggedBEEF): Promise<STEAK> {
-    if (!url.startsWith('https:')) {
+    if (!url.startsWith('https:') && !this.allowHTTP) {
       throw new Error(
         'HTTPS facilitator can only use URLs that start with "https:"'
       )
@@ -99,15 +108,16 @@ export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilit
 }
 
 /**
- * Represents a SHIP transaction broadcaster.
+ * Broadcasts transactions to one or more overlay topics.
  */
-export default class SHIPBroadcaster implements Broadcaster {
+export default class TopicBroadcaster implements Broadcaster {
   private readonly topics: string[]
   private readonly facilitator: OverlayBroadcastFacilitator
   private readonly resolver: LookupResolver
   private readonly requireAcknowledgmentFromAllHostsForTopics: | 'all' | 'any' | string[]
   private readonly requireAcknowledgmentFromAnyHostForTopics: | 'all' | 'any' | string[]
   private readonly requireAcknowledgmentFromSpecificHostsForTopics: Record<string, 'all' | 'any' | string[]>
+  private readonly networkPreset: 'mainnet' | 'testnet' | 'local'
 
   /**
    * Constructs an instance of the SHIP broadcaster.
@@ -115,7 +125,7 @@ export default class SHIPBroadcaster implements Broadcaster {
    * @param {string[]} topics - The list of SHIP topic names where transactions are to be sent.
    * @param {SHIPBroadcasterConfig} config - Configuration options for the SHIP broadcaster.
    */
-  constructor (topics: string[], config?: SHIPBroadcasterConfig) {
+  constructor (topics: string[], config: SHIPBroadcasterConfig = {}) {
     if (topics.length === 0) {
       throw new Error('At least one topic is required for broadcast.')
     }
@@ -123,21 +133,15 @@ export default class SHIPBroadcaster implements Broadcaster {
       throw new Error('Every topic must start with "tm_".')
     }
     this.topics = topics
-    const {
-      facilitator,
-      resolver,
-      requireAcknowledgmentFromAllHostsForTopics,
-      requireAcknowledgmentFromAnyHostForTopics,
-      requireAcknowledgmentFromSpecificHostsForTopics
-    } = config ?? {}
-    this.facilitator = facilitator ?? new HTTPSOverlayBroadcastFacilitator()
-    this.resolver = resolver ?? new LookupResolver()
+    this.networkPreset = config.networkPreset ?? 'mainnet'
+    this.facilitator = config.facilitator ?? new HTTPSOverlayBroadcastFacilitator(undefined, this.networkPreset === 'local')
+    this.resolver = config.resolver ?? new LookupResolver({ networkPreset: this.networkPreset })
     this.requireAcknowledgmentFromAllHostsForTopics =
-      requireAcknowledgmentFromAllHostsForTopics ?? []
+      config.requireAcknowledgmentFromAllHostsForTopics ?? []
     this.requireAcknowledgmentFromAnyHostForTopics =
-      requireAcknowledgmentFromAnyHostForTopics ?? 'all'
+      config.requireAcknowledgmentFromAnyHostForTopics ?? 'all'
     this.requireAcknowledgmentFromSpecificHostsForTopics =
-      requireAcknowledgmentFromSpecificHostsForTopics ?? {}
+      config.requireAcknowledgmentFromSpecificHostsForTopics ?? {}
   }
 
   /**
@@ -157,12 +161,12 @@ export default class SHIPBroadcaster implements Broadcaster {
         'Transactions sent via SHIP to Overlay Services must be serializable to BEEF format.'
       )
     }
-    const interestedHosts = await this.findInterestedHosts()
+    const interestedHosts = this.networkPreset === 'local' ? ['http://localhost:8080'] : await this.findInterestedHosts()
     if (Object.keys(interestedHosts).length === 0) {
       return {
         status: 'error',
         code: 'ERR_NO_HOSTS_INTERESTED',
-        description: 'No hosts are interested in receiving this transaction.'
+        description: `No ${this.networkPreset} hosts are interested in receiving this transaction.`
       }
     }
     const hostPromises = Object.entries(interestedHosts).map(
@@ -190,7 +194,7 @@ export default class SHIPBroadcaster implements Broadcaster {
       return {
         status: 'error',
         code: 'ERR_ALL_HOSTS_REJECTED',
-        description: 'All SHIP hosts have rejected the transaction.'
+        description: `All ${this.networkPreset} topical hosts have rejected the transaction.`
       }
     }
 

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

@@ -861,7 +861,7 @@ describe('LookupResolver', () => {
         query: { test: 1 }
       })
     ).rejects.toThrow(
-      'No competent hosts found by the SLAP trackers for lookup service: ls_foo'
+      'No competent mainnet hosts found by the SLAP trackers for lookup service: ls_foo'
     )
 
     expect(mockFacilitator.lookup.mock.calls).toEqual([
@@ -1054,7 +1054,7 @@ describe('LookupResolver', () => {
         query: { test: 1 }
       })
     ).rejects.toThrow(
-      'No competent hosts found by the SLAP trackers for lookup service: ls_foo'
+      'No competent mainnet hosts found by the SLAP trackers for lookup service: ls_foo'
     )
 
     expect(mockFacilitator.lookup.mock.calls).toEqual([
@@ -1628,7 +1628,7 @@ describe('LookupResolver', () => {
           query: { test: 1 }
         })
       ).rejects.toThrow(
-        'No competent hosts found by the SLAP trackers for lookup service: ls_foo'
+        'No competent mainnet hosts found by the SLAP trackers for lookup service: ls_foo'
       )
 
       expect(mockFacilitator.lookup.mock.calls.length).toBe(2)

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

@@ -279,7 +279,7 @@ describe('SHIPCast', () => {
     expect(result).toEqual({
       status: 'error',
       code: 'ERR_NO_HOSTS_INTERESTED',
-      description: 'No hosts are interested in receiving this transaction.'
+      description: 'No mainnet hosts are interested in receiving this transaction.'
     })
 
     expect(mockResolver.query).toHaveBeenCalledWith(
@@ -343,7 +343,7 @@ describe('SHIPCast', () => {
     expect(result).toEqual({
       status: 'error',
       code: 'ERR_ALL_HOSTS_REJECTED',
-      description: 'All SHIP hosts have rejected the transaction.'
+      description: 'All mainnet topical hosts have rejected the transaction.'
     })
 
     expect(mockFacilitator.send).toHaveBeenCalled()
@@ -1081,7 +1081,7 @@ describe('SHIPCast', () => {
     expect(response).toEqual({
       status: 'error',
       code: 'ERR_ALL_HOSTS_REJECTED',
-      description: 'All SHIP hosts have rejected the transaction.'
+      description: 'All mainnet topical hosts have rejected the transaction.'
     })
   })
   describe('SHIPCast private methods', () => {

package/src/overlay-tools/index.ts

@@ -2,4 +2,9 @@ export * from './LookupResolver.js'
 export * from './SHIPBroadcaster.js'
 export { default as OverlayAdminTokenTemplate } from './OverlayAdminTokenTemplate.js'
 export { default as LookupResolver } from './LookupResolver.js'
+
+// For intuitive clarity, we name this the Topic Broadcaster.
+export { default as TopicBroadcaster } from './SHIPBroadcaster.js'
+// Historically, it was also known by two other names:
 export { default as SHIPBroadcaster } from './SHIPBroadcaster.js'
+export { default as SHIPCast } from './SHIPBroadcaster.js'