@bsv/sdk 1.3.35 → 1.4.0

package/src/storage/StorageUploader.ts

@@ -0,0 +1,108 @@
+import { AuthFetch } from '../auth/clients/AuthFetch.js'
+import { WalletInterface } from '../wallet/Wallet.interfaces.js'
+import * as StorageUtils from './StorageUtils.js'
+
+export interface UploaderConfig {
+  storageURL: string
+  wallet: WalletInterface
+}
+
+export interface UploadableFile {
+  data: number[]
+  type: string
+}
+
+export interface UploadFileResult {
+  published: boolean
+  uhrpURL: string
+}
+
+export class StorageUploader {
+  private readonly authFetch: AuthFetch
+  private readonly baseURL: string
+
+  constructor (config: UploaderConfig) {
+    this.baseURL = config.storageURL
+    this.authFetch = new AuthFetch(config.wallet)
+  }
+
+  private async getUploadInfo (
+    fileSize: number,
+    retentionPeriod: number
+  ): Promise<{
+      uploadURL: string
+      amount?: number
+    }> {
+    const url = `${this.baseURL}/upload`
+    const body = { fileSize, retentionPeriod }
+
+    const response = await this.authFetch.fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    })
+    if (!response.ok) {
+      throw new Error(`Upload info request failed: HTTP ${response.status}`)
+    }
+    const data = await response.json() as {
+      status: string
+      uploadURL: string
+      amount?: number
+    }
+    if (data.status === 'error') {
+      throw new Error('Upload route returned an error.')
+    }
+    return {
+      uploadURL: data.uploadURL,
+      amount: data.amount
+    }
+  }
+
+  private async uploadFile (
+    uploadURL: string,
+    file: UploadableFile
+  ): Promise<UploadFileResult> {
+    const body = Uint8Array.from(file.data)
+
+    const response = await fetch(uploadURL, {
+      method: 'PUT',
+      body,
+      headers: { 'Content-Type': file.type }
+    })
+    if (!response.ok) {
+      throw new Error(`File upload failed: HTTP ${response.status}`)
+    }
+
+    const uhrpURL = await StorageUtils.getURLForFile(file.data)
+    return {
+      published: true,
+      uhrpURL
+    }
+  }
+
+  /**
+     * Publishes a file to the storage server with the specified retention period.
+     *
+     * This will:
+     * 1. Request an upload URL from the server.
+     * 2. Perform an HTTP PUT to upload the file’s raw bytes.
+     * 3. Return a UHRP URL referencing the file once published.
+     *
+     * @param params.file - An object describing the file’s data (number[] array of bytes) and mime type.
+     * @param params.retentionPeriod - Number of minutes to keep the file hosted.
+     *
+     * @returns An object indicating whether the file was published successfully and the resulting UHRP URL.
+     *
+     * @throws If either the upload info request or the subsequent file upload request fails (non-OK HTTP status).
+     */
+  public async publishFile (params: {
+    file: UploadableFile
+    retentionPeriod: number
+  }): Promise<UploadFileResult> {
+    const { file, retentionPeriod } = params
+    const fileSize = file.data.length
+
+    const { uploadURL } = await this.getUploadInfo(fileSize, retentionPeriod)
+    return await this.uploadFile(uploadURL, file)
+  }
+}

package/src/storage/StorageUtils.ts

@@ -0,0 +1,66 @@
+import { sha256 } from '../primitives/Hash.js'
+import { toHex, fromBase58Check, toBase58Check, toArray } from '../primitives/utils.js'
+
+/**
+ * Takes a UHRP URL and removes any prefixes.
+ * @param {string} URL - The UHRP URL.
+ * @returns {string} - Normalized URL.
+ */
+export const normalizeURL = (URL: string): string => {
+  if (URL.toLowerCase().startsWith('uhrp:')) URL = URL.slice(5)
+  if (URL.startsWith('//')) URL = URL.slice(2)
+  return URL
+}
+
+/**
+ * Generates a UHRP URL from a given SHA-256 hash.
+ * @param {number[]} hash - 32-byte SHA-256 hash.
+ * @returns {string} - Base58Check encoded URL.
+ */
+export const getURLForHash = (hash: number[]): string => {
+  if (hash.length !== 32) {
+    throw new Error('Hash length must be 32 bytes (sha256)')
+  }
+  return toBase58Check(hash, toArray('ce00', 'hex'))
+}
+
+/**
+ * Generates a UHRP URL for a given file.
+ * @param {number[] | string} file - File content as number array or string.
+ * @returns {string} - Base58Check encoded URL.
+ */
+export const getURLForFile = (file: number[]): string => {
+  const hash = sha256(file)
+  return getURLForHash(hash)
+}
+
+/**
+ * Extracts the hash from a UHRP URL.
+ * @param {string} URL - UHRP URL.
+ * @returns {number[]} - Extracted SHA-256 hash.
+ */
+export const getHashFromURL = (URL: string): number[] => {
+  URL = normalizeURL(URL)
+  const { data, prefix } = fromBase58Check(URL, undefined, 2)
+  if (data.length !== 32) {
+    throw new Error('Invalid length!')
+  }
+  if (toHex(prefix as number[]) !== 'ce00') {
+    throw new Error('Bad prefix')
+  }
+  return data as number[]
+}
+
+/**
+ * Checks if a URL is a valid UHRP URL.
+ * @param {string} URL - The URL to validate.
+ * @returns {boolean} - True if valid, false otherwise.
+ */
+export const isValidURL = (URL: string): boolean => {
+  try {
+    getHashFromURL(URL)
+    return true
+  } catch (e) {
+    return false
+  }
+}

package/src/storage/__test/StorageUploader.test.ts

@@ -0,0 +1,80 @@
+import { StorageUploader } from '../StorageUploader.js'
+import * as StorageUtils from '../StorageUtils.js'
+import WalletClient from '../../wallet/WalletClient.js'
+
+// A helper for converting a string to a number[] of UTF-8 bytes
+function stringToUtf8Array(str: string): number[] {
+  return Array.from(new TextEncoder().encode(str))
+}
+
+describe('StorageUploader Tests', () => {
+  let uploader: StorageUploader
+  let walletClient: WalletClient
+  let globalFetchSpy: jest.SpiedFunction<typeof global.fetch>
+
+  beforeEach(() => {
+    walletClient = new WalletClient('json-api', 'non-admin.com')
+
+    uploader = new StorageUploader({
+      storageURL: 'https://example.test.system',
+      wallet: walletClient
+    })
+
+    globalFetchSpy = jest
+      .spyOn(global, 'fetch')
+      .mockResolvedValue(new Response(null, { status: 200 }))
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('should upload a file, produce a valid UHRP URL, and decode it to the known SHA-256', async () => {
+    const data = stringToUtf8Array('Hello, world!')
+
+    // Mock out getUploadInfo so we can control the returned upload/public URLs
+    jest.spyOn(uploader as any, 'getUploadInfo').mockResolvedValue({
+      uploadURL: 'https://example-upload.com/put',
+    })
+
+    const result = await uploader.publishFile({
+      file: {
+        data,
+        type: 'text/plain'
+      },
+      retentionPeriod: 7
+    })
+
+    // We expect exactly one PUT request
+    expect(globalFetchSpy).toHaveBeenCalledTimes(1)
+    // Check the result
+    expect(StorageUtils.isValidURL(result.uhrpURL)).toBe(true)
+    expect(result.published).toBe(true)
+
+    const url = StorageUtils.getHashFromURL(result.uhrpURL)
+    const firstFour = url.slice(0, 4).map(b => b.toString(16).padStart(2, '0')).join('')
+    expect(firstFour).toHaveLength(8)
+  })
+
+  it('should throw if the upload fails with HTTP 500', async () => {
+    // Force the fetch to fail
+    globalFetchSpy.mockResolvedValueOnce(new Response(null, { status: 500 }))
+
+    // Also mock getUploadInfo
+    jest.spyOn(uploader as any, 'getUploadInfo').mockResolvedValue({
+      uploadURL: 'https://example-upload.com/put',
+    })
+
+    const failingData = stringToUtf8Array('failing data')
+
+    await expect(
+      uploader.publishFile({
+        file: {
+          data: failingData,
+          type: 'text/plain'
+        },
+        retentionPeriod: 30
+      })
+    ).rejects.toThrow('File upload failed: HTTP 500')
+  })
+})

package/src/storage/__test/StorageUtils.test.ts

@@ -0,0 +1,86 @@
+import { StorageUtils } from '../index.js'
+import * as Utils from '../../primitives/utils.js'
+import * as Hash from '../..//primitives/Hash.js'
+
+// Example data
+const exampleHashHex = '1a5ec49a3f32cd56d19732e89bde5d81755ddc0fd8515dc8b226d47654139dca'
+const exampleHash = Utils.toArray(exampleHashHex, 'hex')
+const exampleFileHex = '687da27f04a112aa48f1cab2e7949f1eea4f7ba28319c1e999910cd561a634a05a3516e6db'
+const exampleFile = Utils.toArray(exampleFileHex, 'hex')
+const exampleURL = 'XUT6PqWb3GP3LR7dmBMCJwZ3oo5g1iGCF3CrpzyuJCemkGu1WGoq'
+
+describe('StorageUtils', () => {
+  describe('getURLForHash', () => {
+    it('Creates the correct URL for the hash', () => {
+      const url = StorageUtils.getURLForHash(exampleHash)
+      expect(url).toBe(exampleURL)
+    })
+
+    it('Throws an error if hash length is invalid', () => {
+      // Get the length of a FILE (not a hash — wrong length!)
+      expect(() => StorageUtils.getURLForHash(exampleFile)).toThrow(
+        new Error('Hash length must be 32 bytes (sha256)')
+      )
+    })
+  })
+
+  describe('getURLForFile', () => {
+    it('Creates the correct URL for the file', () => {
+      const url = StorageUtils.getURLForFile(exampleFile)
+      expect(url).toEqual(exampleURL)
+    })
+  })
+
+  describe('getHashFromURL', () => {
+    it('Decodes the URL to the correct hash', () => {
+      const hash = StorageUtils.getHashFromURL(exampleURL)
+      expect(Utils.toHex(hash)).toEqual(exampleHashHex)
+    })
+
+    it('Gets the same hash as getting one directly from the file', () => {
+      const hashA = StorageUtils.getHashFromURL(exampleURL)
+      const hashB = Hash.sha256(exampleFile)
+      expect(hashA).toEqual(hashB)
+    })
+
+    it('Throws an error if checksum is invalid', () => {
+      const badURL = 'XUU7cTfy6fA6q2neLDmzPqJnGB6o18PXKoGaWLPrH1SeWLKgdCKq'
+      expect(() => StorageUtils.getHashFromURL(badURL)).toThrow(new Error('Invalid checksum'))
+    })
+
+    it('Throws an error if URL length is invalid', () => {
+      const badURL = 'SomeBase58CheckTooShortOrTooLong'
+      expect(() => StorageUtils.getHashFromURL(badURL)).toThrow()
+    })
+
+    it('Throws an error if prefix is invalid', () => {
+      const invalidPrefixURL1 = 'AInvalidPrefixTestString1'
+      const invalidPrefixURL2 = 'AInvalidPrefixTestString2'
+      expect(() => StorageUtils.getHashFromURL(invalidPrefixURL1)).toThrow()
+      expect(() => StorageUtils.getHashFromURL(invalidPrefixURL2)).toThrow()
+    })
+  })
+
+  describe('isValidURL', () => {
+    it('Returns true when URL is valid', () => {
+      expect(StorageUtils.isValidURL(exampleURL)).toBe(true)
+    })
+
+    it('Returns false if checksum is invalid', () => {
+      const badURL = 'XUU7cTfy6fA6q2neLDmzPqJnGB6o18PXKoGaWLPrH1SeWLKgdCKq'
+      expect(StorageUtils.isValidURL(badURL)).toBe(false)
+    })
+
+    it('Returns false if URL length is invalid', () => {
+      const badURL = 'SomeBase58CheckTooShortOrTooLong'
+      expect(StorageUtils.isValidURL(badURL)).toBe(false)
+    })
+
+    it('Returns false if prefix is invalid', () => {
+      const badURL1 = 'AnotherInvalidPrefixTestString'
+      const badURL2 = 'YetAnotherInvalidPrefixTestString'
+      expect(StorageUtils.isValidURL(badURL1)).toBe(false)
+      expect(StorageUtils.isValidURL(badURL2)).toBe(false)
+    })
+  })
+})

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export * as StorageUtils from './StorageUtils.js'
+export { StorageUploader } from './StorageUploader.js'

package/src/transaction/__tests/Transaction.benchmarks.test.ts

@@ -9,7 +9,7 @@ import MerklePath from '../MerklePath'
 jest.setTimeout(60000) // Increase timeout for benchmarking tests if necessary
 
 // Helper function to measure execution time
-async function measureTime (fn: () => Promise<void>): Promise<number> {
+async function measureTime(fn: () => Promise<void>): Promise<number> {
   const start = process.hrtime()
   await fn()
   const diff = process.hrtime(start)
@@ -113,11 +113,6 @@ describe('Transaction Verification Benchmark', () => {
       const verified = await tx.verify('scripts only')
       expect(verified).toBe(true)
     })
-    console.log(
-      `Verification time for wide transaction with ${inputCount} inputs: ${timeTaken.toFixed(
-        2
-      )} ms`
-    )
   })
 
   it('verifies a large transaction with many inputs and outputs', async () => {
@@ -172,11 +167,6 @@ describe('Transaction Verification Benchmark', () => {
       const verified = await tx.verify('scripts only')
       expect(verified).toBe(true)
     })
-    console.log(
-      `Verification time for large transaction with ${inputCount} inputs and ${outputCount} outputs: ${timeTaken.toFixed(
-        2
-      )} ms`
-    )
   })
 
   it('verifies a transaction with nested inputs (complex graph)', async () => {
@@ -243,10 +233,5 @@ describe('Transaction Verification Benchmark', () => {
       const verified = await finalTx.verify('scripts only')
       expect(verified).toBe(true)
     })
-    console.log(
-      `Verification time for nested inputs with depth ${depth} and fan-out ${fanOut}: ${timeTaken.toFixed(
-        2
-      )} ms`
-    )
   })
 })

package/src/wallet/WalletClient.ts

@@ -95,25 +95,25 @@ export default class WalletClient implements WalletInterface {
       await checkSub()
       this.substrate = sub
     } catch (e) {
-      console.error('XDMSubstrate initialization failed:', e) // Log the error
+      // XDM failed, try the next one...
       try {
         sub = new XDMSubstrate()
         await checkSub(MAX_XDM_RESPONSE_WAIT)
         this.substrate = sub
       } catch (e) {
-        console.error('WalletWireTransceiver initialization failed:', e)
+        // HTTP wire failed, move on...
         try {
           sub = new WalletWireTransceiver(new HTTPWalletWire(this.originator))
           await checkSub()
           this.substrate = sub
         } catch (e) {
-          console.error('HTTPWalletJSON initialization failed:', e)
+          // HTTP JSON failed, attempt the next...
           try {
             sub = new HTTPWalletJSON(this.originator)
             await checkSub()
             this.substrate = sub
           } catch (e) {
-            console.error('No wallet available:', e)
+            // No comms. Tell the user to install a BSV wallet.
             throw new Error(
               'No wallet available over any communication substrate. Install a BSV wallet today!'
             )

package/src/wallet/substrates/HTTPWalletWire.ts

@@ -1,6 +1,6 @@
 import WalletWire from './WalletWire.js'
 import WalletWireCalls from './WalletWireCalls.js'
-import { Utils } from '../../primitives/index.js'
+import * as Utils from '../../primitives/utils.js'
 
 export default class HTTPWalletWire implements WalletWire {
   baseUrl: string

package/src/wallet/substrates/WalletWireProcessor.ts

@@ -1,6 +1,6 @@
 import { WalletInterface, SecurityLevel } from '../Wallet.interfaces.js'
 import WalletWire from './WalletWire.js'
-import { Utils } from '../../primitives/index.js'
+import * as Utils from '../../primitives/utils.js'
 import calls from './WalletWireCalls.js'
 import Certificate from '../../auth/certificates/Certificate.js'
 

package/src/wallet/substrates/WalletWireTransceiver.ts

@@ -46,8 +46,8 @@ import {
   WalletInterface
 } from '../Wallet.interfaces.js'
 import WalletWire from './WalletWire.js'
-import { Certificate } from '../../auth/index.js'
-import { Utils } from '../../primitives/index.js'
+import Certificate from '../../auth/certificates/Certificate.js'
+import * as Utils from '../../primitives/utils.js'
 import calls, { CallType } from './WalletWireCalls.js'
 import { WalletError } from '../WalletError.js'
 

package/src/wallet/substrates/XDM.ts

@@ -27,9 +27,10 @@ import {
   VersionString7To30Bytes,
   WalletInterface
 } from '../Wallet.interfaces.js'
-import { Utils, Random } from '../../primitives/index.js'
+import Random from '../../primitives/Random.js'
+import * as Utils from '../../primitives/utils.js'
 import { WalletError } from '../WalletError.js'
-import { CallType } from '../../../mod.js'
+import { CallType } from './WalletWireCalls.js'
 
 /**
  * Facilitates wallet operations over cross-document messaging.