@bsv/sdk 1.7.7 → 1.8.1

package/src/script/templates/PushDrop.ts

@@ -6,8 +6,9 @@ import {
   Signature,
   PublicKey
 } from '../../primitives/index.js'
-import { WalletInterface, SecurityLevel } from '../../wallet/Wallet.interfaces.js'
+import { WalletInterface } from '../../wallet/Wallet.interfaces.js'
 import { Transaction } from '../../transaction/index.js'
+import { WalletProtocol } from '../../wallet/Wallet.interfaces.js'
 
 function verifyTruthy<T>(v: T | undefined): T {
   if (v == null) throw new Error('must have value')
@@ -117,7 +118,7 @@ export default class PushDrop implements ScriptTemplate {
    * Creates a PushDrop locking script with arbitrary data fields and a public key lock.
    *
    * @param {number[][]} fields - The token fields to include in the locking script.
-   * @param {[SecurityLevel, string]} protocolID - The protocol ID to use.
+   * @param {WalletProtocol} protocolID - The protocol ID to use.
    * @param {string} keyID - The key ID to use.
    * @param {string} counterparty - The counterparty involved in the transaction, "self" or "anyone".
    * @param {boolean} [forSelf=false] - Flag indicating if the lock is for the creator (default no).
@@ -126,7 +127,7 @@ export default class PushDrop implements ScriptTemplate {
    */
   async lock(
     fields: number[][],
-    protocolID: [SecurityLevel, string],
+    protocolID: WalletProtocol,
     keyID: string,
     counterparty: string,
     forSelf = false,
@@ -177,7 +178,7 @@ export default class PushDrop implements ScriptTemplate {
   /**
    * Creates an unlocking script for spending a PushDrop token output.
    *
-   * @param {[SecurityLevel, string]} protocolID - The protocol ID to use.
+   * @param {WalletProtocol} protocolID - The protocol ID to use.
    * @param {string} keyID - The key ID to use.
    * @param {string} counterparty - The counterparty involved in the transaction, "self" or "anyone".
    * @param {string} [sourceTXID] - The TXID of the source transaction.
@@ -188,7 +189,7 @@ export default class PushDrop implements ScriptTemplate {
    * @returns {Object} An object containing functions to sign the transaction and estimate the script length.
    */
   unlock(
-    protocolID: [SecurityLevel, string],
+    protocolID: WalletProtocol,
     keyID: string,
     counterparty: string,
     signOutputs: 'all' | 'none' | 'single' = 'all',

package/src/transaction/Transaction.ts

@@ -6,7 +6,7 @@ import LockingScript from '../script/LockingScript.js'
 import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
 import { hash256 } from '../primitives/Hash.js'
 import FeeModel from './FeeModel.js'
-import SatoshisPerKilobyte from './fee-models/SatoshisPerKilobyte.js'
+import LivePolicy from './fee-models/LivePolicy.js'
 import { Broadcaster, BroadcastResponse, BroadcastFailure } from './Broadcaster.js'
 import MerklePath from './MerklePath.js'
 import Spend from '../script/Spend.js'
@@ -411,7 +411,7 @@ export default class Transaction {
 
   /**
    * Computes fees prior to signing.
-   * If no fee model is provided, uses a SatoshisPerKilobyte fee model that pays 1 sat/kb.
+   * If no fee model is provided, uses a LivePolicy fee model that fetches current rates from ARC.
    * If fee is a number, the transaction uses that value as fee.
    *
    * @param modelOrFee - The initialized fee model to use or fixed fee for the transaction
@@ -420,7 +420,7 @@ export default class Transaction {
    *
    */
   async fee (
-    modelOrFee: FeeModel | number = new SatoshisPerKilobyte(1),
+    modelOrFee: FeeModel | number = LivePolicy.getInstance(),
     changeDistribution: 'equal' | 'random' = 'equal'
   ): Promise<void> {
     this.cachedHash = undefined
@@ -774,7 +774,7 @@ export default class Transaction {
    *
    * @returns Whether the transaction is valid according to the rules of SPV.
    *
-   * @example tx.verify(new WhatsOnChain(), new SatoshisPerKilobyte(1))
+   * @example tx.verify(new WhatsOnChain(), LivePolicy.getInstance())
    */
   async verify (
     chainTracker: ChainTracker | 'scripts only' = defaultChainTracker(),

package/src/transaction/fee-models/LivePolicy.ts

@@ -0,0 +1,97 @@
+import SatoshisPerKilobyte from './SatoshisPerKilobyte.js'
+import Transaction from '../Transaction.js'
+
+/**
+ * Represents a live fee policy that fetches current rates from ARC GorillaPool.
+ * Extends SatoshisPerKilobyte to reuse transaction size calculation logic.
+ */
+export default class LivePolicy extends SatoshisPerKilobyte {
+  private static readonly ARC_POLICY_URL = 'https://arc.gorillapool.io/v1/policy'
+  private static instance: LivePolicy | null = null
+  private cachedRate: number | null = null
+  private cacheTimestamp: number = 0
+  private readonly cacheValidityMs: number
+
+  /**
+   * Constructs an instance of the live policy fee model.
+   *
+   * @param {number} cacheValidityMs - How long to cache the fee rate in milliseconds (default: 5 minutes)
+   */
+  constructor(cacheValidityMs: number = 5 * 60 * 1000) {
+    super(100) // Initialize with dummy value, will be overridden by fetchFeeRate
+    this.cacheValidityMs = cacheValidityMs
+  }
+
+  /**
+   * Gets the singleton instance of LivePolicy to ensure cache sharing across the application.
+   *
+   * @param {number} cacheValidityMs - How long to cache the fee rate in milliseconds (default: 5 minutes)
+   * @returns The singleton LivePolicy instance
+   */
+  static getInstance(cacheValidityMs: number = 5 * 60 * 1000): LivePolicy {
+    if (!LivePolicy.instance) {
+      LivePolicy.instance = new LivePolicy(cacheValidityMs)
+    }
+    return LivePolicy.instance
+  }
+
+  /**
+   * Fetches the current fee rate from ARC GorillaPool API.
+   * 
+   * @returns The current satoshis per kilobyte rate
+   */
+  private async fetchFeeRate(): Promise<number> {
+    const now = Date.now()
+    
+    // Return cached rate if still valid
+    if (this.cachedRate !== null && (now - this.cacheTimestamp) < this.cacheValidityMs) {
+      return this.cachedRate
+    }
+
+    try {
+      const response = await fetch(LivePolicy.ARC_POLICY_URL)
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      }
+      
+      const response_data = await response.json()
+      
+      if (!response_data.policy?.miningFee || typeof response_data.policy.miningFee.satoshis !== 'number' || typeof response_data.policy.miningFee.bytes !== 'number') {
+        throw new Error('Invalid policy response format')
+      }
+      
+      // Convert to satoshis per kilobyte
+      const rate = (response_data.policy.miningFee.satoshis / response_data.policy.miningFee.bytes) * 1000
+      
+      // Cache the result
+      this.cachedRate = rate
+      this.cacheTimestamp = now
+      
+      return rate
+    } catch (error) {
+      // If we have a cached rate, use it as fallback
+      if (this.cachedRate !== null) {
+        console.warn('Failed to fetch live fee rate, using cached value:', error)
+        return this.cachedRate
+      }
+      
+      // Otherwise, use a reasonable default (100 sat/kb)
+      console.warn('Failed to fetch live fee rate, using default 100 sat/kb:', error)
+      return 100
+    }
+  }
+
+  /**
+   * Computes the fee for a given transaction using the current live rate.
+   * Overrides the parent method to use dynamic rate fetching.
+   *
+   * @param tx The transaction for which a fee is to be computed.
+   * @returns The fee in satoshis for the transaction.
+   */
+  async computeFee(tx: Transaction): Promise<number> {
+    const rate = await this.fetchFeeRate()
+    // Update the value property so parent's computeFee uses the live rate
+    this.value = rate
+    return super.computeFee(tx)
+  }
+}

package/src/transaction/fee-models/__tests/LivePolicy.test.ts

@@ -0,0 +1,148 @@
+import LivePolicy from '../LivePolicy.js'
+
+describe('LivePolicy', () => {
+  let consoleSpy: jest.SpyInstance
+
+  const createMockTransaction = () => ({
+    inputs: [],
+    outputs: []
+  } as any)
+
+  const createSuccessfulFetchMock = (satoshis: number, bytes: number = 1000) => 
+    jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        policy: {
+          miningFee: { satoshis, bytes }
+        }
+      })
+    })
+
+  const createErrorFetchMock = (status = 500, statusText = 'Internal Server Error') =>
+    jest.fn().mockResolvedValue({
+      ok: false,
+      status,
+      statusText
+    })
+
+  const createInvalidResponseMock = () =>
+    jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ invalid: 'response' })
+    })
+
+  const createNetworkErrorMock = () =>
+    jest.fn().mockRejectedValue(new Error('Network error'))
+
+  const expectDefaultFallback = (consoleSpy: jest.SpyInstance) => {
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Failed to fetch live fee rate, using default 100 sat/kb:',
+      expect.any(Error)
+    )
+  }
+
+  const expectCachedFallback = (consoleSpy: jest.SpyInstance) => {
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Failed to fetch live fee rate, using cached value:',
+      expect.any(Error)
+    )
+  }
+
+  beforeEach(() => {
+    ;(LivePolicy as any).instance = null
+    jest.clearAllMocks()
+    consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+  })
+
+  afterEach(() => {
+    consoleSpy.mockRestore()
+  })
+
+  it('should return the same instance when getInstance is called multiple times', () => {
+    const instance1 = LivePolicy.getInstance()
+    const instance2 = LivePolicy.getInstance()
+    
+    expect(instance1).toBe(instance2)
+    expect(instance1).toBeInstanceOf(LivePolicy)
+  })
+
+  it('should share cache between singleton instances', async () => {
+    const instance1 = LivePolicy.getInstance()
+    const instance2 = LivePolicy.getInstance()
+    
+    global.fetch = createSuccessfulFetchMock(5)
+    const mockTx = createMockTransaction()
+
+    const fee1 = await instance1.computeFee(mockTx)
+    const fee2 = await instance2.computeFee(mockTx)
+    
+    expect(fee1).toBe(fee2)
+    expect(fee1).toBe(1) // 5 sat/kb rate, minimum tx size gets 1 sat
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('should allow different cache validity when creating singleton', () => {
+    const instance1 = LivePolicy.getInstance(10000)
+    const instance2 = LivePolicy.getInstance(20000)
+    
+    expect(instance1).toBe(instance2)
+    expect((instance1 as any).cacheValidityMs).toBe(10000)
+  })
+
+  it('should create instance with custom cache validity', () => {
+    const instance = new LivePolicy(30000)
+    expect((instance as any).cacheValidityMs).toBe(30000)
+  })
+
+  it('should handle HTTP error responses', async () => {
+    const instance = LivePolicy.getInstance()
+    global.fetch = createErrorFetchMock()
+    const mockTx = createMockTransaction()
+
+    const fee = await instance.computeFee(mockTx)
+    
+    expect(fee).toBe(1)
+    expectDefaultFallback(consoleSpy)
+  })
+
+  it('should handle invalid API response format', async () => {
+    const instance = LivePolicy.getInstance()
+    global.fetch = createInvalidResponseMock()
+    const mockTx = createMockTransaction()
+
+    const fee = await instance.computeFee(mockTx)
+    
+    expect(fee).toBe(1)
+    expectDefaultFallback(consoleSpy)
+  })
+
+  it('should use cached value when API fails after successful fetch', async () => {
+    const instance = LivePolicy.getInstance()
+    const mockTx = createMockTransaction()
+    
+    // First call - successful fetch
+    global.fetch = createSuccessfulFetchMock(10)
+    const fee1 = await instance.computeFee(mockTx)
+    expect(fee1).toBe(1)
+
+    // Expire cache and simulate API failure
+    ;(instance as any).cacheTimestamp = Date.now() - (6 * 60 * 1000)
+    global.fetch = createNetworkErrorMock()
+    
+    const fee2 = await instance.computeFee(mockTx)
+    
+    expect(fee2).toBe(1)
+    expectCachedFallback(consoleSpy)
+  })
+
+  it('should handle network errors with no cached value', async () => {
+    const instance = LivePolicy.getInstance()
+    global.fetch = createNetworkErrorMock()
+    const mockTx = createMockTransaction()
+
+    const fee = await instance.computeFee(mockTx)
+    
+    expect(fee).toBe(1)
+    expectDefaultFallback(consoleSpy)
+  })
+})

package/src/transaction/fee-models/index.ts

@@ -1 +1,2 @@
 export { default as SatoshisPerKilobyte } from './SatoshisPerKilobyte.js'
+export { default as LivePolicy } from './LivePolicy.js'

package/src/wallet/WalletClient.ts

@@ -58,6 +58,7 @@ export default class WalletClient implements WalletInterface {
     | 'window.CWI'
     | 'json-api'
     | 'react-native'
+    | 'secure-json-api'
     | WalletInterface = 'auto',
     originator?: OriginatorDomainNameStringUnder250Bytes
   ) {
@@ -68,6 +69,7 @@ export default class WalletClient implements WalletInterface {
     if (substrate === 'XDM') substrate = new XDMSubstrate()
     if (substrate === 'json-api') substrate = new HTTPWalletJSON(originator)
     if (substrate === 'react-native') substrate = new ReactNativeWebView(originator)
+    if (substrate === 'secure-json-api') substrate = new HTTPWalletJSON(originator, 'https://localhost:2121')
     this.substrate = substrate
     this.originator = originator
   }
@@ -76,61 +78,58 @@ export default class WalletClient implements WalletInterface {
     if (typeof this.substrate === 'object') {
       return // substrate is already connected
     }
-    let sub: WalletInterface
-    const checkSub = async (timeout?: number): Promise<void> => {
-      let result
-      if (typeof timeout === 'number') {
-        result = await Promise.race([
-          sub.getVersion({}),
-          new Promise<never>((_resolve, reject) =>
-            setTimeout(() => reject(new Error('Timed out.')), timeout)
-          )
-        ])
-      } else {
-        result = await sub.getVersion({})
-      }
-      if (typeof result !== 'object' || typeof result.version !== 'string') {
-        throw new Error('Failed to use substrate.')
-      }
-    }
-    try {
-      sub = new WindowCWISubstrate()
-      await checkSub()
-      this.substrate = sub
-    } catch (e) {
-      // XDM failed, try the next one...
+
+    const attemptSubstrate = async (factory: () => WalletInterface, timeout?: number): Promise<{ success: boolean, sub?: WalletInterface }> => {
       try {
-        sub = new XDMSubstrate()
-        await checkSub(MAX_XDM_RESPONSE_WAIT)
-        this.substrate = sub
-      } catch (e) {
-        // HTTP wire failed, move on...
-        try {
-          sub = new WalletWireTransceiver(new HTTPWalletWire(this.originator))
-          await checkSub()
-          this.substrate = sub
-        } catch (e) {
-          // HTTP Wire failed, attempt the next...
-          try {
-            sub = new HTTPWalletJSON(this.originator)
-            await checkSub()
-            this.substrate = sub
-          } catch (e) {
-            // HTTP JSON failed, attempt the next...
-            try {
-              sub = new ReactNativeWebView(this.originator)
-              await checkSub()
-              this.substrate = sub
-            } catch (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!'
-              )
-            }
-          }
+        const sub = factory()
+        let result
+        if (typeof timeout === 'number') {
+          result = await Promise.race([
+            sub.getVersion({}),
+            new Promise<never>((_resolve, reject) =>
+              setTimeout(() => reject(new Error('Timed out.')), timeout)
+            )
+          ])
+        } else {
+          result = await sub.getVersion({})
+        }
+        if (typeof result !== 'object' || typeof result.version !== 'string') {
+          return { success: false }
         }
+        return { success: true, sub }
+      } catch {
+        return { success: false }
       }
     }
+
+    // Try fast substrates first
+    const fastAttempts = [
+      attemptSubstrate(() => new WindowCWISubstrate()),
+      attemptSubstrate(() => new HTTPWalletJSON(this.originator, 'https://localhost:2121')),
+      attemptSubstrate(() => new HTTPWalletJSON(this.originator)),
+      attemptSubstrate(() => new ReactNativeWebView(this.originator)),
+      attemptSubstrate(() => new WalletWireTransceiver(new HTTPWalletWire(this.originator)))
+    ]
+
+    const fastResults = await Promise.allSettled(fastAttempts)
+    const fastSuccessful = fastResults
+      .filter((r): r is PromiseFulfilledResult<{ success: boolean, sub?: WalletInterface }> => r.status === 'fulfilled' && r.value.success && r.value.sub !== undefined)
+      .map(r => r.value.sub as WalletInterface)
+
+    if (fastSuccessful.length > 0) {
+      this.substrate = fastSuccessful[0]
+      return
+    }
+
+    // Fall back to slower XDM substrate
+    const xdmResult = await attemptSubstrate(() => new XDMSubstrate(), MAX_XDM_RESPONSE_WAIT)
+    if (xdmResult.success && xdmResult.sub !== undefined) {
+      this.substrate = xdmResult.sub
+    } else {
+      throw new Error(
+        'No wallet available over any communication substrate. Install a BSV wallet today!'
+      )
+    }
   }
 
   async createAction (args: CreateActionArgs): Promise<CreateActionResult> {

package/src/wallet/substrates/WalletWireProcessor.ts

@@ -1782,6 +1782,27 @@ export default class WalletWireProcessor implements WalletWire {
             // Write certificate binary length and data
             resultWriter.writeVarIntNum(certBin.length)
             resultWriter.write(certBin)
+
+            if (cert.keyring && Object.keys(cert.keyring).length > 0) {
+              resultWriter.writeInt8(1) // Flag indicating keyring is present
+              const keyringEntries = Object.entries(cert.keyring)
+              resultWriter.writeVarIntNum(keyringEntries.length)
+              for (const [fieldName, fieldValue] of keyringEntries) {
+                const fieldNameBytes = Utils.toArray(fieldName, 'utf8')
+                resultWriter.writeVarIntNum(fieldNameBytes.length)
+                resultWriter.write(fieldNameBytes)
+
+                const fieldValueBytes = Utils.toArray(fieldValue, 'base64')
+                resultWriter.writeVarIntNum(fieldValueBytes.length)
+                resultWriter.write(fieldValueBytes)
+              }
+            } else {
+              resultWriter.writeInt8(0) // Flag indicating no keyring
+            }
+
+            const verifierBytes = Utils.toArray(cert.verifier, 'hex')
+            resultWriter.writeVarIntNum(verifierBytes.length)
+            resultWriter.write(verifierBytes)
           }
 
           // Return the response

package/src/wallet/substrates/WalletWireTransceiver.ts

@@ -11,6 +11,7 @@ import {
   BooleanDefaultTrue,
   Byte,
   CertificateFieldNameUnder50Bytes,
+  CertificateResult,
   CreateActionArgs,
   CreateActionResult,
   DescriptionString5to50Bytes,
@@ -1672,22 +1673,33 @@ export default class WalletWireTransceiver implements WalletInterface {
     )
     const resultReader = new Utils.Reader(result)
     const totalCertificates = resultReader.readVarIntNum()
-    const certificates: Array<{
-      type: Base64String
-      subject: PubKeyHex
-      serialNumber: Base64String
-      certifier: PubKeyHex
-      revocationOutpoint: OutpointString
-      signature: HexString
-      fields: Record<CertificateFieldNameUnder50Bytes, Base64String>
-    }> = []
+    const certificates: Array<CertificateResult> = []
     for (let i = 0; i < totalCertificates; i++) {
       const certificateLength = resultReader.readVarIntNum()
       const certificateBin = resultReader.read(certificateLength)
       const cert = Certificate.fromBinary(certificateBin)
+      const keyringForVerifier: Record<string, string> = {}
+      if (resultReader.readInt8() === 1) {
+        const numFields = resultReader.readVarIntNum()
+        for (let i = 0; i < numFields; i++) {
+          const fieldKeyLength = resultReader.readVarIntNum()
+          const fieldKey = Utils.toUTF8(resultReader.read(fieldKeyLength))
+          const fieldValueLength = resultReader.readVarIntNum()
+          keyringForVerifier[fieldKey] = Utils.toBase64(
+              resultReader.read(fieldValueLength)
+          )
+        }
+      }
+      const verifierLength = resultReader.readVarIntNum()
+      let verifier: string | undefined = undefined
+      if (verifierLength > 0) {
+        verifier = Utils.toUTF8(resultReader.read(verifierLength))
+      }
       certificates.push({
         ...cert,
-        signature: cert.signature as string
+        signature: cert.signature as string,
+        keyring: keyringForVerifier,
+        verifier,
       })
     }
     return {