@bsv/sdk 1.2.2 → 1.2.4

package/docs/overlay-tools.md

@@ -169,12 +169,27 @@ Facilitates lookups to URLs that return answers.
 
 ```ts
 export interface OverlayLookupFacilitator {
-    lookup: (url: string, question: LookupQuestion) => Promise<LookupAnswer>;
+    lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>;
 }
 ```
 
 See also: [LookupAnswer](#type-lookupanswer), [LookupQuestion](#interface-lookupquestion)
 
+<details>
+
+<summary>Interface OverlayLookupFacilitator Details</summary>
+
+#### Property lookup
+
+Returns a lookup answer for a lookup question
+
+```ts
+lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>
+```
+See also: [LookupAnswer](#type-lookupanswer), [LookupQuestion](#interface-lookupquestion)
+
+</details>
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -294,7 +309,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
     fetchClient: typeof fetch;
     constructor(httpClient = fetch) 
-    async lookup(url: string, question: LookupQuestion): Promise<LookupAnswer> 
+    async lookup(url: string, question: LookupQuestion, timeout: number = 5000): Promise<LookupAnswer> 
 }
 ```
 
@@ -310,7 +325,7 @@ Represents an SHIP transaction broadcaster.
 ```ts
 export default class LookupResolver {
     constructor(config?: LookupResolverConfig) 
-    async query(question: LookupQuestion): Promise<LookupAnswer> 
+    async query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer> 
 }
 ```
 
@@ -325,7 +340,7 @@ See also: [LookupAnswer](#type-lookupanswer), [LookupQuestion](#interface-lookup
 Given a LookupQuestion, returns a LookupAnswer. Aggregates across multiple services and supports resiliency.
 
 ```ts
-async query(question: LookupQuestion): Promise<LookupAnswer> 
+async query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer> 
 ```
 See also: [LookupAnswer](#type-lookupanswer), [LookupQuestion](#interface-lookupquestion)
 

package/package.json

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

package/src/auth/Certificate.ts

@@ -54,14 +54,14 @@ export default class Certificate {
    * @param {Record<CertificateFieldNameUnder50Bytes, string>} fields - All the fields present in the certificate.
    * @param {HexString} signature - Certificate signature by the certifier's private key, DER encoded hex string.
    */
-  constructor(
+  constructor (
     type: Base64String,
     serialNumber: Base64String,
     subject: PubKeyHex,
     certifier: PubKeyHex,
     revocationOutpoint: OutpointString,
     fields: Record<CertificateFieldNameUnder50Bytes, string>,
-    signature?: HexString,
+    signature?: HexString
   ) {
     this.type = type
     this.serialNumber = serialNumber
@@ -78,7 +78,7 @@ export default class Certificate {
    * @param {boolean} [includeSignature=true] - Whether to include the signature in the serialization.
    * @returns {number[]} - The serialized certificate in binary format.
    */
-  toBin(includeSignature: boolean = true): number[] {
+  toBin (includeSignature: boolean = true): number[] {
     const writer = new Utils.Writer()
 
     // Write type (Base64String, 32 bytes)
@@ -134,7 +134,7 @@ export default class Certificate {
    * @param {number[]} bin - The binary data representing the certificate.
    * @returns {Certificate} - The deserialized Certificate object.
    */
-  static fromBin(bin: number[]): Certificate {
+  static fromBin (bin: number[]): Certificate {
     const reader = new Utils.Reader(bin)
 
     // Read type
@@ -166,7 +166,7 @@ export default class Certificate {
       // Field name
       const fieldNameLength = reader.readVarIntNum()
       const fieldNameBytes = reader.read(fieldNameLength)
-      const fieldName = Utils.toUTF8(fieldNameBytes) as CertificateFieldNameUnder50Bytes
+      const fieldName = Utils.toUTF8(fieldNameBytes)
 
       // Field value
       const fieldValueLength = reader.readVarIntNum()
@@ -177,7 +177,7 @@ export default class Certificate {
     }
 
     // Read signature if present
-    let signature: string | undefined = undefined
+    let signature: string | undefined
     if (!reader.eof()) {
       const signatureLength = reader.readVarIntNum()
       const signatureBytes = reader.read(signatureLength)
@@ -200,7 +200,7 @@ export default class Certificate {
    *
    * @returns {Promise<boolean>} - A promise that resolves to true if the signature is valid.
    */
-  async verify(): Promise<boolean> {
+  async verify (): Promise<boolean> {
     // A verifier can be any wallet capable of verifying signatures
     const verifier = new ProtoWallet('anyone')
     const verificationData = this.toBin(false) // Exclude the signature from the verification data
@@ -221,7 +221,7 @@ export default class Certificate {
    * @param {Wallet} certifier - The wallet representing the certifier.
    * @returns {Promise<void>}
    */
-  async sign(certifier: Wallet): Promise<void> {
+  async sign (certifier: Wallet): Promise<void> {
     const preimage = this.toBin(false) // Exclude the signature when signing
     const { signature } = await certifier.createSignature({
       data: preimage,
@@ -230,4 +230,4 @@ export default class Certificate {
     })
     this.signature = Utils.toHex(signature)
   }
-}
+}

package/src/auth/index.ts

@@ -1 +1 @@
-export { default as Certificate } from './Certificate.js'
+export { default as Certificate } from './Certificate.js'

package/src/overlay-tools/LookupResolver.ts

@@ -49,6 +49,8 @@ export const DEFAULT_SLAP_TRACKERS: string[] = [
   // Trackers known to host invalid or illegal records will be removed at the discretion of the BSV Association.
 ]
 
+const MAX_TRACKER_WAIT_TIME = 1000
+
 /** Configuration options for the Lookup resolver. */
 export interface LookupResolverConfig {
   /** The facilitator used to make requests to Overlay Services hosts. */
@@ -63,27 +65,41 @@ export interface LookupResolverConfig {
 
 /** Facilitates lookups to URLs that return answers. */
 export interface OverlayLookupFacilitator {
-  lookup: (url: string, question: LookupQuestion) => Promise<LookupAnswer>
+  /**
+   * Returns a lookup answer for a lookup question
+   * @param url - Overlay Service URL to send the lookup question to.
+   * @param question - Lookup question to find an answer to.
+   * @param timeout - Specifics how long to wait for a lookup answer in milliseconds.
+   * @returns
+   */
+  lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>
 }
 
 export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
   fetchClient: typeof fetch
 
-  constructor(httpClient = fetch) {
+  constructor (httpClient = fetch) {
     this.fetchClient = httpClient
   }
 
-  async lookup(url: string, question: LookupQuestion): Promise<LookupAnswer> {
+  async lookup (url: string, question: LookupQuestion, timeout: number = 5000): Promise<LookupAnswer> {
     if (!url.startsWith('https:')) {
       throw new Error('HTTPS facilitator can only use URLs that start with "https:"')
     }
-    const response = await fetch(`${url}/lookup`, {
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Request timed out')), timeout)
+    )
+
+    const fetchPromise = fetch(`${url}/lookup`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json'
       },
       body: JSON.stringify({ service: question.service, query: question.query })
     })
+
+    const response: Response = await Promise.race([fetchPromise, timeoutPromise]) as Response
+
     if (response.ok) {
       return await response.json()
     } else {
@@ -101,7 +117,7 @@ export default class LookupResolver {
   private readonly hostOverrides: Record<string, string[]>
   private readonly additionalHosts: Record<string, string[]>
 
-  constructor(config?: LookupResolverConfig) {
+  constructor (config?: LookupResolverConfig) {
     const { facilitator, slapTrackers, hostOverrides, additionalHosts } = config ?? {} as LookupResolverConfig
     this.facilitator = facilitator ?? new HTTPSOverlayLookupFacilitator()
     this.slapTrackers = slapTrackers ?? DEFAULT_SLAP_TRACKERS
@@ -112,7 +128,7 @@ export default class LookupResolver {
   /**
    * Given a LookupQuestion, returns a LookupAnswer. Aggregates across multiple services and supports resiliency.
    */
-  async query(question: LookupQuestion): Promise<LookupAnswer> {
+  async query (question: LookupQuestion, timeout?: number): Promise<LookupAnswer> {
     let competentHosts: string[] = []
     if (question.service === 'ls_slap') {
       competentHosts = this.slapTrackers
@@ -133,7 +149,7 @@ export default class LookupResolver {
 
     // Use Promise.allSettled to handle individual host failures
     const hostResponses = await Promise.allSettled(
-      competentHosts.map(async host => await this.facilitator.lookup(host, question))
+      competentHosts.map(async host => await this.facilitator.lookup(host, question, timeout))
     )
 
     const successfulResponses = hostResponses
@@ -180,7 +196,7 @@ export default class LookupResolver {
      * @param service Service for which competent hosts are to be returned
      * @returns Array of hosts competent for resolving queries
      */
-  private async findCompetentHosts(service: string): Promise<string[]> {
+  private async findCompetentHosts (service: string): Promise<string[]> {
     const query: LookupQuestion = {
       service: 'ls_slap',
       query: {
@@ -190,7 +206,7 @@ export default class LookupResolver {
 
     // Use Promise.allSettled to handle individual SLAP tracker failures
     const trackerResponses = await Promise.allSettled(
-      this.slapTrackers.map(async tracker => await this.facilitator.lookup(tracker, query))
+      this.slapTrackers.map(async tracker => await this.facilitator.lookup(tracker, query, MAX_TRACKER_WAIT_TIME))
     )
 
     const hosts = new Set<string>()

package/src/overlay-tools/OverlayAdminTokenTemplate.ts

@@ -15,7 +15,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param script Locking script comprising a SHIP or SLAP token to decode
      * @returns Decoded SHIP or SLAP advertisement
      */
-  static decode(script: LockingScript): { protocol: 'SHIP' | 'SLAP', identityKey: string, domain: string, topicOrService: string } {
+  static decode (script: LockingScript): { protocol: 'SHIP' | 'SLAP', identityKey: string, domain: string, topicOrService: string } {
     const result = PushDrop.decode(script)
     if (result.fields.length < 4) {
       throw new Error('Invalid SHIP/SLAP advertisement!')
@@ -39,7 +39,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * Constructs a new Overlay Admin template instance
      * @param wallet Wallet to use for locking and unlocking
      */
-  constructor(wallet: Wallet) {
+  constructor (wallet: Wallet) {
     this.pushDrop = new PushDrop(wallet)
   }
 
@@ -50,7 +50,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param topicOrService Topic or service to advertise
      * @returns Locking script comprising the advertisement token
      */
-  async lock(protocol: 'SHIP' | 'SLAP', domain: string, topicOrService: string): Promise<LockingScript> {
+  async lock (protocol: 'SHIP' | 'SLAP', domain: string, topicOrService: string): Promise<LockingScript> {
     const { publicKey: identityKey } = await this.pushDrop.wallet.getPublicKey({ identityKey: true })
     return await this.pushDrop.lock(
       [
@@ -70,7 +70,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param protocol SHIP or SLAP, depending on the token to unlock
      * @returns Script unlocker capable of unlocking the advertisement token
      */
-  unlock(protocol: 'SHIP' | 'SLAP'): {
+  unlock (protocol: 'SHIP' | 'SLAP'): {
     sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
     estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
   } {

package/src/overlay-tools/SHIPBroadcaster.ts

@@ -56,14 +56,16 @@ export interface OverlayBroadcastFacilitator {
   send: (url: string, taggedBEEF: TaggedBEEF) => Promise<STEAK>
 }
 
+const MAX_SHIP_QUERY_TIMEOUT = 1000
+
 export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilitator {
   httpClient: typeof fetch
 
-  constructor(httpClient = fetch) {
+  constructor (httpClient = fetch) {
     this.httpClient = httpClient
   }
 
-  async send(url: string, taggedBEEF: TaggedBEEF): Promise<STEAK> {
+  async send (url: string, taggedBEEF: TaggedBEEF): Promise<STEAK> {
     if (!url.startsWith('https:')) {
       throw new Error('HTTPS facilitator can only use URLs that start with "https:"')
     }
@@ -100,7 +102,7 @@ export default class SHIPCast 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.')
     }
@@ -127,7 +129,7 @@ export default class SHIPCast implements Broadcaster {
      * @param {Transaction} tx - The transaction to be sent.
      * @returns {Promise<BroadcastResponse | BroadcastFailure>} A promise that resolves to either a success or failure response.
      */
-  async broadcast(tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
+  async broadcast (tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
     let beef: number[]
     try {
       beef = tx.toBEEF()
@@ -269,7 +271,7 @@ export default class SHIPCast implements Broadcaster {
     }
   }
 
-  private checkAcknowledgmentFromAllHosts(hostAcknowledgments: Record<string, Set<string>>, requiredTopics: string[], require: 'all' | 'any'): boolean {
+  private checkAcknowledgmentFromAllHosts (hostAcknowledgments: Record<string, Set<string>>, requiredTopics: string[], require: 'all' | 'any'): boolean {
     for (const acknowledgedTopics of Object.values(hostAcknowledgments)) {
       if (require === 'all') {
         for (const topic of requiredTopics) {
@@ -293,7 +295,7 @@ export default class SHIPCast implements Broadcaster {
     return true
   }
 
-  private checkAcknowledgmentFromAnyHost(hostAcknowledgments: Record<string, Set<string>>, requiredTopics: string[], require: 'all' | 'any'): boolean {
+  private checkAcknowledgmentFromAnyHost (hostAcknowledgments: Record<string, Set<string>>, requiredTopics: string[], require: 'all' | 'any'): boolean {
     if (require === 'all') {
       // All required topics must be acknowledged by at least one host
       for (const acknowledgedTopics of Object.values(hostAcknowledgments)) {
@@ -322,7 +324,7 @@ export default class SHIPCast implements Broadcaster {
     }
   }
 
-  private checkAcknowledgmentFromSpecificHosts(hostAcknowledgments: Record<string, Set<string>>, requirements: Record<string, 'all' | 'any' | string[]>): boolean {
+  private checkAcknowledgmentFromSpecificHosts (hostAcknowledgments: Record<string, Set<string>>, requirements: Record<string, 'all' | 'any' | string[]>): boolean {
     for (const [host, requiredTopicsOrAllAny] of Object.entries(requirements)) {
       const acknowledgedTopics = hostAcknowledgments[host]
       if (!acknowledgedTopics) {
@@ -368,7 +370,7 @@ export default class SHIPCast implements Broadcaster {
      *
      * @returns A mapping of URLs for hosts interested in this transaction. Keys are URLs, values are which of our topics the specific host cares about.
      */
-  private async findInterestedHosts(): Promise<Record<string, Set<string>>> {
+  private async findInterestedHosts (): Promise<Record<string, Set<string>>> {
     // TODO: cache the list of interested hosts to avoid spamming SHIP trackers.
     // TODO: Monetize the operation of the SHIP tracker system.
     // TODO: Cache ship/slap lookup with expiry (every 5min)
@@ -380,7 +382,7 @@ export default class SHIPCast implements Broadcaster {
       query: {
         topics: this.topics
       }
-    })
+    }, MAX_SHIP_QUERY_TIMEOUT)
     if (answer.type !== 'output-list') {
       throw new Error('SHIP answer is not an output list.')
     }