@bopen-io/wallet-toolbox 1.7.18

package/src/services/providers/ARC.ts

@@ -0,0 +1,350 @@
+import {
+  Beef,
+  BEEF_V1,
+  BEEF_V2,
+  defaultHttpClient,
+  HexString,
+  HttpClient,
+  HttpClientRequestOptions,
+  Random,
+  Utils
+} from '@bsv/sdk'
+import { PostBeefResult, PostTxResultForTxid, PostTxResultForTxidError } from '../../sdk/WalletServices.interfaces'
+import { doubleSha256BE } from '../../utility/utilityHelpers'
+import { ReqHistoryNote } from '../../sdk/types'
+import { WalletError } from '../../sdk/WalletError'
+
+/** Configuration options for the ARC broadcaster. */
+export interface ArcConfig {
+  /** Authentication token for the ARC API */
+  apiKey?: string
+  /** The HTTP client used to make requests to the ARC API. */
+  httpClient?: HttpClient
+  /** Deployment id used annotating api calls in XDeployment-ID header - this value will be randomly generated if not set */
+  deploymentId?: string
+  /** notification callback endpoint for proofs and double spend notification */
+  callbackUrl?: string
+  /** default access token for notification callback endpoint. It will be used as a Authorization header for the http callback */
+  callbackToken?: string
+  /** additional headers to be attached to all tx submissions. */
+  headers?: Record<string, string>
+}
+
+function defaultDeploymentId(): string {
+  return `ts-sdk-${Utils.toHex(Random(16))}`
+}
+
+/**
+ * Represents an ARC transaction broadcaster.
+ */
+export class ARC {
+  readonly name: string
+  readonly URL: string
+  readonly apiKey: string | undefined
+  readonly deploymentId: string
+  readonly callbackUrl: string | undefined
+  readonly callbackToken: string | undefined
+  readonly headers: Record<string, string> | undefined
+  private readonly httpClient: HttpClient
+
+  /**
+   * Constructs an instance of the ARC broadcaster.
+   *
+   * @param {string} URL - The URL endpoint for the ARC API.
+   * @param {ArcConfig} config - Configuration options for the ARC broadcaster.
+   */
+  constructor(URL: string, config?: ArcConfig, name?: string)
+  /**
+   * Constructs an instance of the ARC broadcaster.
+   *
+   * @param {string} URL - The URL endpoint for the ARC API.
+   * @param {string} apiKey - The API key used for authorization with the ARC API.
+   */
+  constructor(URL: string, apiKey?: string, name?: string)
+
+  constructor(URL: string, config?: string | ArcConfig, name?: string) {
+    this.name = name ?? 'ARC'
+    this.URL = URL
+    if (typeof config === 'string') {
+      this.apiKey = config
+      this.httpClient = defaultHttpClient()
+      this.deploymentId = defaultDeploymentId()
+      this.callbackToken = undefined
+      this.callbackUrl = undefined
+    } else {
+      const configObj: ArcConfig = config ?? {}
+      const { apiKey, deploymentId, httpClient, callbackToken, callbackUrl, headers } = configObj
+      this.apiKey = apiKey
+      this.httpClient = httpClient ?? defaultHttpClient()
+      this.deploymentId = deploymentId ?? defaultDeploymentId()
+      this.callbackToken = callbackToken
+      this.callbackUrl = callbackUrl
+      this.headers = headers
+    }
+  }
+
+  /**
+   * Constructs a dictionary of the default & supplied request headers.
+   */
+  private requestHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'XDeployment-ID': this.deploymentId
+    }
+
+    if (this.apiKey != null && this.apiKey !== '') {
+      headers.Authorization = `Bearer ${this.apiKey}`
+    }
+
+    if (this.callbackUrl != null && this.callbackUrl !== '') {
+      headers['X-CallbackUrl'] = this.callbackUrl
+    }
+
+    if (this.callbackToken != null && this.callbackToken !== '') {
+      headers['X-CallbackToken'] = this.callbackToken
+    }
+
+    if (this.headers != null) {
+      for (const key in this.headers) {
+        headers[key] = this.headers[key]
+      }
+    }
+
+    return headers
+  }
+
+  /**
+   * The ARC '/v1/tx' endpoint, as of 2025-02-17 supports all of the following hex string formats:
+   *   1. Single serialized raw transaction.
+   *   2. Single EF serialized raw transaction (untested).
+   *   3. V1 serialized Beef (results returned reflect only the last transaction in the beef)
+   *
+   * The ARC '/v1/tx' endpoint, as of 2025-02-17 DOES NOT support the following hex string formats:
+   *   1. V2 serialized Beef
+   *
+   * @param rawTx
+   * @param txids
+   * @returns
+   */
+  async postRawTx(rawTx: HexString, txids?: string[]): Promise<PostTxResultForTxid> {
+    let txid = Utils.toHex(doubleSha256BE(Utils.toArray(rawTx, 'hex')))
+    if (txids) {
+      txid = txids.slice(-1)[0]
+    } else {
+      txids = [txid]
+    }
+
+    const requestOptions: HttpClientRequestOptions = {
+      method: 'POST',
+      headers: this.requestHeaders(),
+      data: { rawTx },
+      signal: AbortSignal.timeout(1000 * 30) // 30 seconds timeout, error.code will be 'ABORT_ERR'
+    }
+
+    const r: PostTxResultForTxid = {
+      txid,
+      status: 'success',
+      notes: []
+    }
+
+    const url = `${this.URL}/v1/tx`
+    const nn = () => ({ name: this.name, when: new Date().toISOString() })
+    const nne = () => ({ ...nn(), rawTx, txids: txids.join(','), url })
+
+    try {
+      const response = await this.httpClient.request<ArcResponse>(url, requestOptions)
+
+      const { txid, extraInfo, txStatus, competingTxs } = response.data
+      const nnr = () => ({
+        txid,
+        extraInfo,
+        txStatus,
+        competingTxs: competingTxs?.join(',')
+      })
+
+      if (response.ok) {
+        r.data = `${txStatus} ${extraInfo}`
+        if (r.txid !== txid) r.data += ` txid altered from ${r.txid} to ${txid}`
+        r.txid = txid
+        if (txStatus === 'DOUBLE_SPEND_ATTEMPTED' || txStatus === 'SEEN_IN_ORPHAN_MEMPOOL') {
+          r.status = 'error'
+          r.doubleSpend = true
+          r.competingTxs = competingTxs
+          r.notes!.push({ ...nne(), ...nnr(), what: 'postRawTxDoubleSpend' })
+        } else {
+          r.notes!.push({ ...nn(), ...nnr(), what: 'postRawTxSuccess' })
+        }
+      } else if (typeof response === 'string') {
+        r.notes!.push({ ...nne(), what: 'postRawTxString', response })
+        r.status = 'error'
+        // response is not normally a string
+        r.serviceError = true
+      } else {
+        r.status = 'error'
+        // Treat unknown errors as service errors
+        r.serviceError = true
+        const n: ReqHistoryNote = {
+          ...nn(),
+          ...nne(),
+          ...nnr(),
+          what: 'postRawTxError'
+        }
+        const ed: PostTxResultForTxidError = {}
+        r.data = ed
+        const st = typeof response.status
+        if (st === 'number' || st === 'string') {
+          n.status = response.status
+          ed.status = response.status.toString()
+        } else {
+          n.status = st
+          ed.status = 'ERR_UNKNOWN'
+        }
+
+        let d = response.data
+        if (d && typeof d === 'string') {
+          n.data = response.data.slice(0, 128)
+          try {
+            d = JSON.parse(d)
+          } catch {
+            // Intentionally left empty
+          }
+        } else if (d && typeof d === 'object') {
+          ed.more = d
+          ed.detail = d['detail']
+          if (typeof ed.detail !== 'string') ed.detail = undefined
+          if (ed.detail) {
+            n.detail = ed.detail
+          }
+        }
+        r.notes!.push(n)
+      }
+    } catch (eu: unknown) {
+      const e = WalletError.fromUnknown(eu)
+      r.status = 'error'
+      r.serviceError = true
+      r.data = `${e.code} ${e.message}`
+      r.notes!.push({
+        ...nne(),
+        what: 'postRawTxCatch',
+        code: e.code,
+        description: e.description
+      })
+    }
+
+    return r
+  }
+
+  /**
+   * ARC does not natively support a postBeef end-point aware of multiple txids of interest in the Beef.
+   *
+   * It does process multiple new transactions, however, which allows results for all txids of interest
+   * to be collected by the `/v1/tx/${txid}` endpoint.
+   *
+   * @param beef
+   * @param txids
+   * @returns
+   */
+  async postBeef(beef: Beef, txids: string[]): Promise<PostBeefResult> {
+    const r: PostBeefResult = {
+      name: this.name,
+      status: 'success',
+      txidResults: [],
+      notes: []
+    }
+
+    const nn = () => ({ name: this.name, when: new Date().toISOString() })
+
+    if (beef.version === BEEF_V2 && beef.txs.every(btx => !btx.isTxidOnly)) {
+      beef.version = BEEF_V1
+      r.notes!.push({ ...nn(), what: 'postBeefV2ToV1' })
+    }
+
+    const beefHex = beef.toHex()
+
+    const prtr = await this.postRawTx(beefHex, txids)
+
+    r.status = prtr.status
+    r.txidResults = [prtr]
+
+    // Since postRawTx only returns results for a single txid,
+    // replicate the basic results any additional txids.
+    // TODO: Temporary hack...
+    for (const txid of txids) {
+      if (prtr.txid === txid) continue
+      const tr: PostTxResultForTxid = {
+        txid,
+        status: 'success',
+        notes: []
+      }
+      // For the extra txids, go back to the service for confirmation...
+      const dr = await this.getTxData(txid)
+      if (dr.txid !== txid) {
+        tr.status = 'error'
+        tr.data = 'internal error'
+        tr.notes!.push({
+          ...nn(),
+          what: 'postBeefGetTxDataInternal',
+          txid,
+          returnedTxid: dr.txid
+        })
+      } else if (dr.txStatus === 'SEEN_ON_NETWORK' || dr.txStatus === 'STORED') {
+        tr.data = dr.txStatus
+        tr.notes!.push({
+          ...nn(),
+          what: 'postBeefGetTxDataSuccess',
+          txid,
+          txStatus: dr.txStatus
+        })
+      } else {
+        tr.status = 'error'
+        tr.data = dr
+        tr.notes!.push({
+          ...nn(),
+          what: 'postBeefGetTxDataError',
+          txid,
+          txStatus: dr.txStatus
+        })
+      }
+      r.txidResults.push(tr)
+      if (r.status === 'success' && tr.status === 'error') r.status = 'error'
+    }
+
+    return r
+  }
+
+  /**
+   * This seems to only work for recently submitted txids...but that's all we need to complete postBeef!
+   * @param txid
+   * @returns
+   */
+  async getTxData(txid: string): Promise<ArcMinerGetTxData> {
+    const requestOptions: HttpClientRequestOptions = {
+      method: 'GET',
+      headers: this.requestHeaders()
+    }
+
+    const response = await this.httpClient.request<ArcMinerGetTxData>(`${this.URL}/v1/tx/${txid}`, requestOptions)
+
+    return response.data
+  }
+}
+
+interface ArcResponse {
+  txid: string
+  extraInfo: string
+  txStatus: string
+  competingTxs?: string[]
+}
+
+export interface ArcMinerGetTxData {
+  status: number // 200
+  title: string // OK
+  blockHash: string
+  blockHeight: number
+  competingTxs: null | string[]
+  extraInfo: string
+  merklePath: string
+  timestamp: string // ISO Z
+  txid: string
+  txStatus: string // 'SEEN_IN_ORPHAN_MEMPOOL'
+}

package/src/services/providers/Bitails.ts

@@ -0,0 +1,256 @@
+import { Beef, defaultHttpClient, HexString, HttpClient, Utils } from '@bsv/sdk'
+import { Chain, ReqHistoryNote } from '../../sdk/types'
+import { GetMerklePathResult, PostBeefResult, WalletServices } from '../../sdk/WalletServices.interfaces'
+import { doubleSha256BE } from '../../utility/utilityHelpers'
+import { WalletError } from '../../sdk/WalletError'
+import { convertProofToMerklePath } from '../../utility/tscProofToMerklePath'
+
+export interface BitailsConfig {
+  /** Authentication token for BitTails API */
+  apiKey?: string
+  /** The HTTP client used to make requests to the API. */
+  httpClient?: HttpClient
+}
+
+/**
+ *
+ */
+export class Bitails {
+  readonly chain: Chain
+  readonly apiKey: string
+  readonly URL: string
+  readonly httpClient: HttpClient
+
+  constructor(chain: Chain = 'main', config: BitailsConfig = {}) {
+    const { apiKey, httpClient } = config
+    this.chain = chain
+    this.URL = chain === 'main' ? `https://api.bitails.io/` : `https://test-api.bitails.io/`
+    this.httpClient = httpClient ?? defaultHttpClient()
+    this.apiKey = apiKey ?? ''
+  }
+
+  getHttpHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json'
+    }
+
+    if (typeof this.apiKey === 'string' && this.apiKey.trim() !== '') {
+      headers.Authorization = this.apiKey
+    }
+
+    return headers
+  }
+
+  /**
+   * Bitails does not natively support a postBeef end-point aware of multiple txids of interest in the Beef.
+   *
+   * Send rawTx in `txids` order from beef.
+   *
+   * @param beef
+   * @param txids
+   * @returns
+   */
+  async postBeef(beef: Beef, txids: string[]): Promise<PostBeefResult> {
+    const nn = () => ({
+      name: 'BitailsPostBeef',
+      when: new Date().toISOString()
+    })
+    const nne = () => ({ ...nn(), beef: beef.toHex(), txids: txids.join(',') })
+
+    const note: ReqHistoryNote = { ...nn(), what: 'postBeef' }
+
+    const raws: string[] = []
+    for (const txid of txids) {
+      const rawTx = Utils.toHex(beef.findTxid(txid)!.rawTx!)
+      raws.push(rawTx)
+    }
+
+    const r = await this.postRaws(raws, txids)
+
+    r.notes!.unshift(note)
+    if (r.status !== 'success') r.notes!.push({ ...nne(), what: 'postBeefError' })
+    else r.notes!.push({ ...nn(), what: 'postBeefSuccess' })
+
+    return r
+  }
+
+  /**
+   * @param raws Array of raw transactions to broadcast as hex strings
+   * @param txids Array of txids for transactions in raws for which results are requested, remaining raws are supporting only.
+   * @returns
+   */
+  async postRaws(raws: HexString[], txids?: string[]): Promise<PostBeefResult> {
+    const r: PostBeefResult = {
+      name: 'BitailsPostRaws',
+      status: 'success',
+      txidResults: [],
+      notes: []
+    }
+
+    const rawTxids: string[] = []
+
+    for (const raw of raws) {
+      const txid = Utils.toHex(doubleSha256BE(Utils.toArray(raw, 'hex')))
+      // Results aren't always identified by txid.
+      rawTxids.push(txid)
+      if (!txids || txids.indexOf(txid) >= 0) {
+        r.txidResults.push({
+          txid,
+          status: 'success',
+          notes: []
+        })
+      }
+    }
+
+    const headers = this.getHttpHeaders()
+    headers['Content-Type'] = 'application/json'
+    //headers['Accept'] = 'text/json'
+
+    const data = { raws: raws }
+    const requestOptions = {
+      method: 'POST',
+      headers,
+      data
+    }
+
+    const url = `${this.URL}tx/broadcast/multi`
+    const nn = () => ({
+      name: 'BitailsPostRawTx',
+      when: new Date().toISOString()
+    })
+    const nne = () => ({
+      ...nn(),
+      raws: raws.join(','),
+      txids: r.txidResults.map(r => r.txid).join(','),
+      url
+    })
+
+    try {
+      const response = await this.httpClient.request<BitailsPostRawsResult[]>(url, requestOptions)
+      if (response.ok) {
+        // status: 201, statusText: 'Created'
+        const btrs: BitailsPostRawsResult[] = response.data
+        if (btrs.length !== raws.length) {
+          r.status = 'error'
+          r.notes!.push({ ...nne(), what: 'postRawsErrorResultsCount' })
+        } else {
+          // Check that each response result has a txid that matches corresponding rawTxids
+          let i = -1
+          for (const btr of btrs) {
+            i++
+            if (!btr.txid) {
+              btr.txid = rawTxids[i]
+              r.notes!.push({ ...nn(), what: 'postRawsResultMissingTxids', i, rawsTxid: rawTxids[i] })
+            } else if (btr.txid !== rawTxids[i]) {
+              r.status = 'error'
+              r.notes!.push({ ...nn(), what: 'postRawsResultTxids', i, txid: btr.txid, rawsTxid: rawTxids[i] })
+            }
+          }
+          if (r.status === 'success') {
+            // btrs has correct number of results and each one has expected txid.
+            // focus on results for requested txids
+            for (const rt of r.txidResults) {
+              const btr = btrs.find(btr => btr.txid! === rt.txid)!
+              const txid = rt.txid
+              if (btr.error) {
+                // code: -25, message: 'missing-inputs'
+                // code: -27, message: 'already-in-mempool'
+                const { code, message } = btr.error
+                if (code === -27) {
+                  rt.notes!.push({ ...nne(), what: 'postRawsSuccessAlreadyInMempool' })
+                } else {
+                  rt.status = 'error'
+                  if (code === -25) {
+                    rt.doubleSpend = true // this is a possible double spend attempt
+                    rt.competingTxs = undefined // not provided with any data for this.
+                    rt.notes!.push({ ...nne(), what: 'postRawsErrorMissingInputs' })
+                  } else if ((btr['code'] as string) === 'ECONNRESET') {
+                    rt.notes!.push({ ...nne(), what: 'postRawsErrorECONNRESET', txid, message })
+                  } else {
+                    rt.notes!.push({ ...nne(), what: 'postRawsError', txid, code, message })
+                  }
+                }
+              } else {
+                rt.notes!.push({ ...nn(), what: 'postRawsSuccess' })
+              }
+              if (rt.status !== 'success' && r.status === 'success') r.status = 'error'
+            }
+          }
+        }
+      } else {
+        r.status = 'error'
+        const n: ReqHistoryNote = { ...nne(), what: 'postRawsError' }
+        r.notes!.push(n)
+      }
+    } catch (eu: unknown) {
+      r.status = 'error'
+      const e = WalletError.fromUnknown(eu)
+      const { code, description } = e
+      r.notes!.push({ ...nne(), what: 'postRawsCatch', code, description })
+    }
+    return r
+  }
+
+  /**
+   *
+   * @param txid
+   * @param services
+   * @returns
+   */
+  async getMerklePath(txid: string, services: WalletServices): Promise<GetMerklePathResult> {
+    const r: GetMerklePathResult = { name: 'BitailsTsc', notes: [] }
+
+    const url = `${this.URL}tx/${txid}/proof/tsc`
+
+    const nn = () => ({ name: 'BitailsProofTsc', when: new Date().toISOString(), txid, url })
+
+    const headers = this.getHttpHeaders()
+    const requestOptions = { method: 'GET', headers }
+
+    try {
+      const response = await this.httpClient.request<BitailsMerkleProof>(url, requestOptions)
+
+      const nne = () => ({ ...nn(), txid, url, status: response.status, statusText: response.statusText })
+
+      if (response.status === 404 && response.statusText === 'Not Found') {
+        r.notes!.push({ ...nn(), what: 'getMerklePathNotFound' })
+      } else if (!response.ok || response.status !== 200 || response.statusText !== 'OK') {
+        r.notes!.push({ ...nne(), what: 'getMerklePathBadStatus' })
+      } else if (!response.data) {
+        r.notes!.push({ ...nne(), what: 'getMerklePathNoData' })
+      } else {
+        const p = response.data
+        const header = await services.hashToHeader(p.target)
+        if (header) {
+          const proof = { index: p.index, nodes: p.nodes, height: header.height }
+          r.merklePath = convertProofToMerklePath(txid, proof)
+          r.header = header
+          r.notes!.push({ ...nne(), what: 'getMerklePathSuccess' })
+        } else {
+          r.notes!.push({ ...nne(), what: 'getMerklePathNoHeader', target: p.target })
+        }
+      }
+    } catch (eu: unknown) {
+      const e = WalletError.fromUnknown(eu)
+      const { code, description } = e
+      r.notes!.push({ ...nn(), what: 'getMerklePathCatch', code, description })
+      r.error = e
+    }
+    return r
+  }
+}
+
+interface BitailsPostRawsResult {
+  txid?: string
+  error?: {
+    code: number
+    message: string
+  }
+}
+
+export interface BitailsMerkleProof {
+  index: number
+  txOrId: string
+  target: string
+  nodes: string[]
+}

package/src/services/providers/SdkWhatsOnChain.ts

@@ -0,0 +1,83 @@
+import { ChainTracker, defaultHttpClient, HttpClient, WhatsOnChainConfig } from '@bsv/sdk'
+
+interface WhatsOnChainBlockHeader {
+  merkleroot: string
+}
+
+/**
+ * Represents a chain tracker based on What's On Chain .
+ */
+export default class SdkWhatsOnChain implements ChainTracker {
+  readonly network: string
+  readonly apiKey: string
+  protected readonly URL: string
+  protected readonly httpClient: HttpClient
+
+  /**
+   * Constructs an instance of the WhatsOnChain ChainTracker.
+   *
+   * @param {'main' | 'test' | 'stn'} network - The BSV network to use when calling the WhatsOnChain API.
+   * @param {WhatsOnChainConfig} config - Configuration options for the WhatsOnChain ChainTracker.
+   */
+  constructor(network: 'main' | 'test' | 'stn' = 'main', config: WhatsOnChainConfig = {}) {
+    const { apiKey, httpClient } = config
+    this.network = network
+    this.URL = `https://api.whatsonchain.com/v1/bsv/${network}`
+    this.httpClient = httpClient ?? defaultHttpClient()
+    this.apiKey = apiKey ?? ''
+  }
+
+  async isValidRootForHeight(root: string, height: number): Promise<boolean> {
+    const requestOptions = {
+      method: 'GET',
+      headers: this.getHttpHeaders()
+    }
+
+    const response = await this.httpClient.request<WhatsOnChainBlockHeader>(
+      `${this.URL}/block/${height}/header`,
+      requestOptions
+    )
+    if (response.ok) {
+      const { merkleroot } = response.data
+      return merkleroot === root
+    } else if (response.status === 404) {
+      return false
+    } else {
+      throw new Error(
+        `Failed to verify merkleroot for height ${height} because of an error: ${JSON.stringify(response.data)} `
+      )
+    }
+  }
+
+  async currentHeight(): Promise<number> {
+    try {
+      const requestOptions = {
+        method: 'GET',
+        headers: this.getHttpHeaders()
+      }
+
+      const response = await this.httpClient.request<{ height: number }>(`${this.URL}/block/headers`, requestOptions)
+      if (response.ok) {
+        return response.data[0].height
+      } else {
+        throw new Error(`Failed to get current height because of an error: ${JSON.stringify(response.data)} `)
+      }
+    } catch (error) {
+      throw new Error(
+        `Failed to get current height because of an error: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  protected getHttpHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json'
+    }
+
+    if (typeof this.apiKey === 'string' && this.apiKey.trim() !== '') {
+      headers.Authorization = this.apiKey
+    }
+
+    return headers
+  }
+}