@bsv/sdk 1.1.33 → 1.2.0

package/src/overlay-tools/SHIPBroadcaster.ts

@@ -0,0 +1,405 @@
+import { Transaction, BroadcastResponse, BroadcastFailure, Broadcaster } from '../transaction/index.js'
+import LookupResolver from './LookupResolver.js'
+import OverlayAdminTokenTemplate from './OverlayAdminTokenTemplate.js'
+
+/**
+ * Tagged BEEF
+ *
+ * @description
+ * Tagged BEEF ([Background Evaluation Extended Format](https://brc.dev/62)) structure. Comprises a transaction, its SPV information, and the overlay topics where its inclusion is requested.
+ */
+export interface TaggedBEEF {
+  beef: number[]
+  topics: string[]
+}
+
+/**
+ * Instructs the Overlay Services Engine about which outputs to admit and which previous outputs to retain. Returned by a Topic Manager.
+ */
+export interface AdmittanceInstructions {
+  /**
+     * The indices of all admissable outputs into the managed topic from the provided transaction.
+     */
+  outputsToAdmit: number[]
+
+  /**
+     * The indices of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
+     */
+  coinsToRetain: number[]
+}
+
+/**
+ * Submitted Transaction Execution AcKnowledgment
+ *
+ * @description
+ * Comprises the topics where a transaction was submitted, and for each one, the output indices for the UTXOs newly admitted into the topics, and the coins retained.
+ * An object whose keys are topic names and whose values are topical admittance instructions denoting the state of the submitted transaction with respect to the associated topic.
+ */
+export type STEAK = Record<string, AdmittanceInstructions>
+
+/** Configuration options for the SHIP broadcaster. */
+export interface SHIPBroadcasterConfig {
+  /** The facilitator used to make requests to Overlay Services hosts. */
+  facilitator?: OverlayBroadcastFacilitator
+  /** The resolver used to locate suitable hosts with SHIP */
+  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. */
+  requireAcknowledgmentFromAnyHostForTopics?: 'all' | 'any' | string[]
+  /** Determines a mapping whose keys are specific hosts and whose values are the topics (all, any, or a specific list) that must be present within the STEAK received by the given hosts, in order for the broadcast to be considered a success. */
+  requireAcknowledgmentFromSpecificHostsForTopics?: Record<string, 'all' | 'any' | string[]>
+}
+
+/** Facilitates transaction broadcasts that return STEAK. */
+export interface OverlayBroadcastFacilitator {
+  send: (url: string, taggedBEEF: TaggedBEEF) => Promise<STEAK>
+}
+
+export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilitator {
+  httpClient: typeof fetch
+
+  constructor(httpClient = fetch) {
+    this.httpClient = httpClient
+  }
+
+  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:"')
+    }
+    const response = await fetch(`${url}/submit`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'X-Topics': JSON.stringify(taggedBEEF.topics)
+      },
+      body: new Uint8Array(taggedBEEF.beef)
+    })
+    if (response.ok) {
+      return await response.json()
+    } else {
+      throw new Error('Failed to facilitate broadcast')
+    }
+  }
+}
+
+/**
+ * Represents a SHIP transaction broadcaster.
+ */
+export default class SHIPCast 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[]>
+
+  /**
+     * Constructs an instance of the SHIP 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) {
+    if (topics.length === 0) {
+      throw new Error('At least one topic is required for broadcast.')
+    }
+    if (topics.some(x => !x.startsWith('tm_'))) {
+      throw new Error('Every topic must start with "tm_".')
+    }
+    this.topics = topics
+    const {
+      facilitator, resolver,
+      requireAcknowledgmentFromAllHostsForTopics,
+      requireAcknowledgmentFromAnyHostForTopics,
+      requireAcknowledgmentFromSpecificHostsForTopics
+    } = config ?? {} as SHIPBroadcasterConfig
+    this.facilitator = facilitator ?? new HTTPSOverlayBroadcastFacilitator()
+    this.resolver = resolver ?? new LookupResolver()
+    this.requireAcknowledgmentFromAllHostsForTopics = requireAcknowledgmentFromAllHostsForTopics ?? 'all'
+    this.requireAcknowledgmentFromAnyHostForTopics = requireAcknowledgmentFromAnyHostForTopics ?? []
+    this.requireAcknowledgmentFromSpecificHostsForTopics = requireAcknowledgmentFromSpecificHostsForTopics ?? {}
+  }
+
+  /**
+     * Broadcasts a transaction to Overlay Services via SHIP.
+     *
+     * @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> {
+    let beef: number[]
+    try {
+      beef = tx.toBEEF()
+    } catch (error) {
+      throw new Error('Transactions sent via SHIP to Overlay Services must be serializable to BEEF format.')
+    }
+    const interestedHosts = 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.'
+      }
+    }
+    const hostPromises = Object.entries(interestedHosts).map(async ([host, topics]) => {
+      try {
+        const steak = await this.facilitator.send(host, { beef, topics: [...topics] })
+        if (!steak || Object.keys(steak).length === 0) {
+          throw new Error('Steak has no topics.')
+        }
+        return { host, success: true, steak }
+      } catch (error) {
+        // Log error if needed
+        return { host, success: false, error }
+      }
+    })
+
+    const results = await Promise.all(hostPromises)
+    const successfulHosts = results.filter(result => result.success)
+
+    if (successfulHosts.length === 0) {
+      return {
+        status: 'error',
+        code: 'ERR_ALL_HOSTS_REJECTED',
+        description: 'All SHIP hosts have rejected the transaction.'
+      }
+    }
+
+    // Collect host acknowledgments
+    const hostAcknowledgments: Record<string, Set<string>> = {}
+
+    for (const result of successfulHosts) {
+      const host = result.host
+      const steak = result.steak
+
+      const acknowledgedTopics = new Set<string>()
+
+      for (const [topic, instructions] of Object.entries(steak)) {
+        const outputsToAdmit = instructions.outputsToAdmit
+        const coinsToRetain = instructions.coinsToRetain
+        if ((outputsToAdmit && outputsToAdmit.length > 0) || (coinsToRetain && coinsToRetain.length > 0)) {
+          acknowledgedTopics.add(topic)
+        }
+      }
+
+      hostAcknowledgments[host] = acknowledgedTopics
+    }
+
+    // Now, perform the checks
+
+    // Check requireAcknowledgmentFromAllHostsForTopics
+    let requiredTopicsAllHosts: string[]
+    let requireAllHosts: 'all' | 'any'
+
+    if (this.requireAcknowledgmentFromAllHostsForTopics === 'all') {
+      requiredTopicsAllHosts = this.topics
+      requireAllHosts = 'all'
+    } else if (this.requireAcknowledgmentFromAllHostsForTopics === 'any') {
+      requiredTopicsAllHosts = this.topics
+      requireAllHosts = 'any'
+    } else if (Array.isArray(this.requireAcknowledgmentFromAllHostsForTopics)) {
+      requiredTopicsAllHosts = this.requireAcknowledgmentFromAllHostsForTopics
+      requireAllHosts = 'all'
+    } else {
+      // Default to 'all' and 'all'
+      requiredTopicsAllHosts = this.topics
+      requireAllHosts = 'all'
+    }
+
+    if (requiredTopicsAllHosts.length > 0) {
+      const allHostsAcknowledged = this.checkAcknowledgmentFromAllHosts(hostAcknowledgments, requiredTopicsAllHosts, requireAllHosts)
+      if (!allHostsAcknowledged) {
+        return {
+          status: 'error',
+          code: 'ERR_REQUIRE_ACK_FROM_ALL_HOSTS_FAILED',
+          description: 'Not all hosts acknowledged the required topics.'
+        }
+      }
+    }
+
+    // Check requireAcknowledgmentFromAnyHostForTopics
+    let requiredTopicsAnyHost: string[]
+    let requireAnyHost: 'all' | 'any'
+
+    if (this.requireAcknowledgmentFromAnyHostForTopics === 'all') {
+      requiredTopicsAnyHost = this.topics
+      requireAnyHost = 'all'
+    } else if (this.requireAcknowledgmentFromAnyHostForTopics === 'any') {
+      requiredTopicsAnyHost = this.topics
+      requireAnyHost = 'any'
+    } else if (Array.isArray(this.requireAcknowledgmentFromAnyHostForTopics)) {
+      requiredTopicsAnyHost = this.requireAcknowledgmentFromAnyHostForTopics
+      requireAnyHost = 'all'
+    } else {
+      // No requirement
+      requiredTopicsAnyHost = []
+      requireAnyHost = 'all'
+    }
+
+    if (requiredTopicsAnyHost.length > 0) {
+      const anyHostAcknowledged = this.checkAcknowledgmentFromAnyHost(hostAcknowledgments, requiredTopicsAnyHost, requireAnyHost)
+      if (!anyHostAcknowledged) {
+        return {
+          status: 'error',
+          code: 'ERR_REQUIRE_ACK_FROM_ANY_HOST_FAILED',
+          description: 'No host acknowledged the required topics.'
+        }
+      }
+    }
+
+    // Check requireAcknowledgmentFromSpecificHostsForTopics
+    if (Object.keys(this.requireAcknowledgmentFromSpecificHostsForTopics).length > 0) {
+      const specificHostsAcknowledged = this.checkAcknowledgmentFromSpecificHosts(hostAcknowledgments, this.requireAcknowledgmentFromSpecificHostsForTopics)
+      if (!specificHostsAcknowledged) {
+        return {
+          status: 'error',
+          code: 'ERR_REQUIRE_ACK_FROM_SPECIFIC_HOSTS_FAILED',
+          description: 'Specific hosts did not acknowledge the required topics.'
+        }
+      }
+    }
+
+    // If all checks pass, return success
+    return {
+      status: 'success',
+      txid: tx.id('hex'),
+      message: `Sent to ${successfulHosts.length} Overlay Services ${successfulHosts.length === 1 ? 'host' : 'hosts'}.`
+    }
+  }
+
+  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) {
+          if (!acknowledgedTopics.has(topic)) {
+            return false
+          }
+        }
+      } else if (require === 'any') {
+        let anyAcknowledged = false
+        for (const topic of requiredTopics) {
+          if (acknowledgedTopics.has(topic)) {
+            anyAcknowledged = true
+            break
+          }
+        }
+        if (!anyAcknowledged) {
+          return false
+        }
+      }
+    }
+    return true
+  }
+
+  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)) {
+        let acknowledgesAllRequiredTopics = true
+        for (const topic of requiredTopics) {
+          if (!acknowledgedTopics.has(topic)) {
+            acknowledgesAllRequiredTopics = false
+            break
+          }
+        }
+        if (acknowledgesAllRequiredTopics) {
+          return true
+        }
+      }
+      return false
+    } else {
+      // At least one required topic must be acknowledged by at least one host
+      for (const acknowledgedTopics of Object.values(hostAcknowledgments)) {
+        for (const topic of requiredTopics) {
+          if (acknowledgedTopics.has(topic)) {
+            return true
+          }
+        }
+      }
+      return false
+    }
+  }
+
+  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) {
+        // Host did not respond successfully
+        return false
+      }
+      let requiredTopics: string[]
+      let require: 'all' | 'any'
+      if (requiredTopicsOrAllAny === 'all' || requiredTopicsOrAllAny === 'any') {
+        require = requiredTopicsOrAllAny
+        requiredTopics = this.topics
+      } else if (Array.isArray(requiredTopicsOrAllAny)) {
+        requiredTopics = requiredTopicsOrAllAny
+        require = 'all'
+      } else {
+        // Invalid configuration
+        continue
+      }
+      if (require === 'all') {
+        for (const topic of requiredTopics) {
+          if (!acknowledgedTopics.has(topic)) {
+            return false
+          }
+        }
+      } else if (require === 'any') {
+        let anyAcknowledged = false
+        for (const topic of requiredTopics) {
+          if (acknowledgedTopics.has(topic)) {
+            anyAcknowledged = true
+            break
+          }
+        }
+        if (!anyAcknowledged) {
+          return false
+        }
+      }
+    }
+    return true
+  }
+
+  /**
+     * Finds which hosts are interested in transactions tagged with the given set of topics.
+     *
+     * @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>>> {
+    // 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)
+
+    // Find all SHIP advertisements for the topics we care about
+    const results: Record<string, Set<string>> = {}
+    const answer = await this.resolver.query({
+      service: 'ls_ship',
+      query: {
+        topics: this.topics
+      }
+    })
+    if (answer.type !== 'output-list') {
+      throw new Error('SHIP answer is not an output list.')
+    }
+    for (const output of answer.outputs) {
+      try {
+        const tx = Transaction.fromBEEF(output.beef)
+        const script = tx.outputs[output.outputIndex].lockingScript
+        const parsed = OverlayAdminTokenTemplate.decode(script)
+        if (!this.topics.includes(parsed.topicOrService) || parsed.protocol !== 'SHIP') {
+          // This should make us think a LOT less highly of this SHIP tracker if it ever happens...
+          continue
+        }
+        if (!results[parsed.domain]) {
+          results[parsed.domain] = new Set()
+        }
+        results[parsed.domain].add(parsed.topicOrService)
+      } catch (e) {
+        continue
+      }
+    }
+    return results
+  }
+}