edge-currency-plugins 3.15.0 → 3.17.0

package/lib/common/utxobased/network/BlockbookElectrum.js

@@ -1,4 +1,5 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }var _altcoinjs = require('altcoin-js');
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }var _altcoinjs = require('altcoin-js');
+
 
 
 
@@ -22,6 +23,17 @@ var _Blockbook = require('./Blockbook');
 
 
 
+
+
+
+
+
+
+
+
+
+
+
 var _electrumApi = require('./electrumApi');
 
 
@@ -49,8 +61,9 @@ var _electrumApi = require('./electrumApi');
 
 
 
-const asResponseMessage = (raw) => {
-  const message = _cleaners.asJSON.call(void 0, 
+
+const asElectrumMessage = _cleaners.asJSON.call(void 0, 
+  _cleaners.asEither.call(void 0, 
     _cleaners.asObject.call(void 0, {
       id: _cleaners.asString,
       result: _cleaners.asUnknown,
@@ -60,8 +73,30 @@ const asResponseMessage = (raw) => {
           _cleaners.asObject.call(void 0, { connected: _cleaners.asString })
         )
       )
+    }),
+    // A subscription's notifications carry its method in place of an id:
+    _cleaners.asObject.call(void 0, {
+      method: _cleaners.asString,
+      params: _cleaners.asArray.call(void 0, _cleaners.asUnknown)
     })
-  )(raw)
+  )
+)
+
+const { method: headersSubscribeMethod } = _electrumApi.headersSubscribeMessage.call(void 0, )
+
+const asResponseMessage = (raw) => {
+  const message = asElectrumMessage(raw)
+
+  // The socket files each subscription under its method name:
+  if ('method' in message) {
+    return { id: message.method, data: message.params[0] }
+  }
+
+  // Electrum answers a subscription with the current header, not the
+  // acknowledgement the socket waits for. fetchInfo reports that height:
+  if (message.id === headersSubscribeMethod && message.error == null) {
+    return { id: message.id, data: { subscribed: true } }
+  }
 
   return {
     id: message.id,
@@ -70,11 +105,20 @@ const asResponseMessage = (raw) => {
   }
 }
 
-const asResponse = (raw) => {
+const makeAsResponse = (
+  isWatchingBlocks
+) => (raw) => {
   const payloadString = _cleaners.asString.call(void 0, raw).trimEnd()
   const messageStrings = payloadString.split('\n')
   const messages = messageStrings.map(asResponseMessage)
-  return messages
+
+  // fetchInfo's blockchain.headers.subscribe subscribes the connection to new
+  // blocks, so the server can announce one before watchBlocks files the
+  // subscription. The socket drops connections over messages it cannot route,
+  // so announcements until then are skipped. watchBlocks reports each block
+  // after it subscribes:
+  if (isWatchingBlocks()) return messages
+  return messages.filter(message => message.id !== headersSubscribeMethod)
 }
 
  function makeBlockbookElectrum(
@@ -98,14 +142,149 @@ const asResponse = (raw) => {
       address,
       coin: pluginInfo.coinInfo.name
     })
-    const scriptHashBuffer = _altcoinjs.crypto.sha256(Buffer.from(scriptPubkey, 'hex'))
-    const scriptHash = scriptHashBuffer.reverse().toString('hex')
-    return scriptHash
+    return toElectrumScriptHash(Buffer.from(scriptPubkey, 'hex'))
   }
 
+  // Makes the Electrum requests for a Blockbook task, and returns the
+  // Blockbook response built from their answers:
+  function* translateTask(
+    task
+  ) {
+    // Translate getAccountUtxo to blockchain.scripthash.listunspent:
+    if (task.method === 'getAccountUtxo') {
+      const params = task.params 
+      const address =
+        asAddress != null ? asAddress(params.descriptor) : params.descriptor
+      const scriptHash = addressToScriptHash(address)
+
+      // Safe because yielding WsTask<ListUnspentResponse> should get
+      // ListUnspentResponse next.
+      const electrumUtxos = (yield {
+        ..._electrumApi.listUnspentMessage.call(void 0, scriptHash)
+      }) 
+
+      const blockbookUtxos = electrumUtxos.map(
+        utxo => ({
+          txid: utxo.tx_hash,
+          vout: utxo.tx_pos,
+          value: utxo.value.toString(),
+          height: utxo.height
+        })
+      )
+      return blockbookUtxos
+    }
+
+    // Get Address Transactions:
+    if (task.method === 'getAccountInfo') {
+      const params = task.params 
+      const address =
+        asAddress != null ? asAddress(params.descriptor) : params.descriptor
+      const scriptHash = addressToScriptHash(address)
+
+      // Safe because yielding WsTask<AddressTransactionsResponse> should get
+      // AddressTransactionsResponse next.
+      const electrumUtxos = (yield {
+        ..._electrumApi.addressTransactionsMessage.call(void 0, scriptHash)
+      }) 
+
+      const blockbookUtxos = {
+        address, // unused
+        balance: '0', // unused
+        totalReceived: '0', // unused
+        totalSent: '0', // unused
+        txs: electrumUtxos.length,
+        unconfirmedBalance: '0', // unused
+        unconfirmedTxs: electrumUtxos.reduce(
+          // Electrum puts mempool transactions at height 0 or -1:
+          (sum, tx) => sum + (tx.height <= 0 ? 1 : 0),
+          0
+        ),
+        txids: [], // unused
+        transactions: [], // TODO: this requires an extra query per txid
+        page: 0, // unused
+        totalPages: 1,
+        itemsOnPage: 0 // unused
+      }
+      return blockbookUtxos
+    }
+
+    // Translate getTransaction to blockchain.transaction.get:
+    if (task.method === 'getTransaction') {
+      const params = task.params 
+      return yield* transactionTask(params.txid)
+    }
+
+    throw new Error(`${task.method} not supported for Electrum connections`)
+  }
+
+  function* transactionTask(
+    txid
+  ) {
+    // Safe because yielding WsTask<RawTransactionResponse> should get
+    // RawTransactionResponse next.
+    const hex = (yield {
+      ..._electrumApi.rawTransactionMessage.call(void 0, txid)
+    }) 
+    const transaction = _altcoinjs.Transaction.fromHex(hex)
+
+    // Electrum only reports a transaction's height in the history of a
+    // script it pays. Servers refuse the history of busy scripts, so each
+    // paid script is tried in turn. When none answers the task fails, so the
+    // engine retries it instead of taking the transaction as unconfirmed:
+    let blockHeight = 0
+    let historyError
+    for (const { script } of transaction.outs) {
+      if (script[0] === _altcoinjs.opcodes.OP_RETURN) continue
+      try {
+        // Safe because yielding WsTask<AddressTransactionsResponse> should get
+        // AddressTransactionsResponse next.
+        const history = (yield {
+          ..._electrumApi.addressTransactionsMessage.call(void 0, toElectrumScriptHash(script))
+        }) 
+        blockHeight = _nullishCoalesce(_optionalChain([history, 'access', _ => _.find, 'call', _2 => _2(item => item.tx_hash === txid), 'optionalAccess', _3 => _3.height]), () => ( 0))
+        historyError = undefined
+        break
+      } catch (error) {
+        log.warn(`failed to fetch the height of transaction ${txid}:`, error)
+        historyError = error
+      }
+    }
+    if (historyError != null) throw historyError
+
+    // The engine reads a fetched transaction's hex, height, outpoints, and
+    // outputs. It keeps the date, fee, and input amounts it already stored,
+    // which Electrum could only supply with a request per previous transaction:
+    const isCoinbase = transaction.isCoinbase()
+    return {
+      txid,
+      hex,
+      // Like Blockbook, Electrum puts mempool transactions at height 0 or -1:
+      blockHeight,
+      confirmations: 0,
+      blockTime: 0,
+      fees: '0',
+      vin: transaction.ins.map((input, n) => ({
+        addresses: [],
+        n,
+        sequence: input.sequence,
+        txid: Buffer.from(input.hash).reverse().toString('hex'),
+        value: '0',
+        vout: input.index,
+        coinbase: isCoinbase ? input.script.toString('hex') : undefined
+      })),
+      vout: transaction.outs.map((output, n) => ({
+        n,
+        value: output.value.toString(),
+        addresses: [], // unused, the engine reads the script in `hex`
+        hex: output.script.toString('hex')
+      }))
+    }
+  }
+
+  let isWatchingBlocks = false
   const instance = _Blockbook.makeBlockbook.call(void 0, {
     asAddress,
-    asResponse,
+    asResponse: makeAsResponse(() => isWatchingBlocks),
     connectionUri,
     engineEmitter,
     initOptions,
@@ -114,85 +293,47 @@ const asResponse = (raw) => {
       uri
     ) {
       const generator = taskGeneratorFn(uri)
-      let nextValue
+      let result = await generator.next()
 
       while (true) {
-        const result = await generator.next(nextValue)
-        const task = result.value
-
         // If the generator result is not a WsTask we will return it:
-        if (_optionalChain([result, 'optionalAccess', _ => _.done]) === true) return result.value
+        if (result.done === true) return result.value
+        const task = result.value
         if (typeof task === 'boolean') return task
 
-        // Translate getAccountUtxo to blockchain.scripthash.listunspent:
-        if (task.method === 'getAccountUtxo') {
-          const params = task.params 
-          const address =
-            asAddress != null ? asAddress(params.descriptor) : params.descriptor
-          const scriptHash = addressToScriptHash(address)
-
-          // Safe because yielding WsTask<ListUnspentResponse> should get
-          // ListUnspentResponse next.
-          const electrumUtxos = (yield {
-            ..._electrumApi.listUnspentMessage.call(void 0, scriptHash)
-          }) 
-
-          const blockbookUtxos = electrumUtxos.map(
-            utxo => ({
-              txid: utxo.tx_hash,
-              vout: utxo.tx_pos,
-              value: utxo.value.toString(),
-              height: utxo.height
-            })
-          )
-          nextValue = blockbookUtxos
-          continue
-        }
-
-        // Get Address Transactions:
-        if (task.method === 'getAccountInfo') {
-          const params = task.params 
-          const address =
-            asAddress != null ? asAddress(params.descriptor) : params.descriptor
-          const scriptHash = addressToScriptHash(address)
-
-          // Safe because yielding WsTask<AddressTransactionsResponse> should get
-          // AddressTransactionsResponse next.
-          const electrumUtxos = (yield {
-            ..._electrumApi.addressTransactionsMessage.call(void 0, scriptHash)
-          }) 
-
-          const blockbookUtxos = {
-            address, // unused
-            balance: '0', // unused
-            totalReceived: '0', // unused
-            totalSent: '0', // unused
-            txs: electrumUtxos.length,
-            unconfirmedBalance: '0', // unused
-            unconfirmedTxs: electrumUtxos.reduce(
-              (sum, tx) => (sum + tx.height >= 0 ? 1 : 0),
-              0
-            ),
-            txids: [], // unused
-            transactions: [], // TODO: this requires an extra query per txid
-            page: 0, // unused
-            totalPages: 1,
-            itemsOnPage: 0 // unused
-          }
-          nextValue = blockbookUtxos
+        let response
+        try {
+          response = yield* translateTask(task)
+        } catch (error) {
+          // Hand the failure to the task that made the request, as the socket
+          // does for the requests it sends unchanged:
+          result = await generator.throw(error)
           continue
         }
+        result = await generator.next(response)
       }
     },
     ping: async () => {
       return await instance.promisifyWsMessage(_electrumApi.pingMessage.call(void 0, ))
     },
+    subscribeNewBlockMessage: () => ({
+      ..._electrumApi.headersSubscribeMessage.call(void 0, ),
+      // Notifications hold the header itself, with no response envelope:
+      cleaner: (raw) => {
+        const header = _electrumApi.asHeadersSubscribeResponse.call(void 0, raw)
+        return { height: header.height, hash: headerToBlockHash(header.hex) }
+      }
+    }),
     socketEmitter,
     walletId
   })
 
-  instance.broadcastTx = async () => {
-    throw new Error('broadcastTx not supported for Electrum connections')
+  instance.broadcastTx = async transaction => {
+    const txid = await instance.promisifyWsMessage(
+      _electrumApi.broadcastTransactionMessage.call(void 0, transaction.signedTx)
+    )
+    // Blockbook reports the broadcast txid as `result`:
+    return { result: txid }
   }
   instance.fetchAddress = async () => {
     throw new Error('fetchAddress not supported for Electrum connections')
@@ -201,18 +342,43 @@ const asResponse = (raw) => {
     throw new Error('fetchAddressUtxos not supported for Electrum connections')
   }
   instance.fetchInfo = async () => {
-    throw new Error('fetchInfo not supported for Electrum connections')
+    const header = await instance.promisifyWsMessage(_electrumApi.headersSubscribeMessage.call(void 0, ))
+    return {
+      name: pluginInfo.currencyInfo.displayName, // unused
+      shortcut: pluginInfo.currencyInfo.currencyCode, // unused
+      decimals: 8, // unused
+      version: '', // unused
+      bestHeight: header.height,
+      bestHash: headerToBlockHash(header.hex),
+      block0Hash: '', // unused
+      testnet: false, // unused
+      backend: undefined // unused
+    }
   }
   instance.fetchTransaction = async () => {
     throw new Error('fetchTransaction not supported for Electrum connections')
   }
 
-  instance.watchAddresses = async () => {
-    return // Fail gracefully
+  const { watchBlocks } = instance
+  instance.watchBlocks = deferredBlockSub => {
+    isWatchingBlocks = true
+    watchBlocks(deferredBlockSub)
   }
-  instance.watchBlocks = async () => {
+  instance.watchAddresses = async () => {
     return // Fail gracefully
   }
 
   return instance
 } exports.makeBlockbookElectrum = makeBlockbookElectrum;
+
+/** True for the URIs of Electrum servers, as opposed to Blockbook servers. */
+ const isElectrumUri = (uri) =>
+  /^electrumwss?:/.test(uri); exports.isElectrumUri = isElectrumUri
+
+// Electrum indexes scripts by their SHA-256, in reverse byte order:
+const toElectrumScriptHash = (scriptPubkey) =>
+  _altcoinjs.crypto.sha256(scriptPubkey).reverse().toString('hex')
+
+// A block's hash is its header's double SHA-256, in reverse byte order:
+const headerToBlockHash = (headerHex) =>
+  _altcoinjs.crypto.hash256(Buffer.from(headerHex, 'hex')).reverse().toString('hex')

package/lib/common/utxobased/network/Socket.js

@@ -87,6 +87,10 @@ const WAKE_UP_MS = 5000 // interval at which we wakeUp and potentially onQueueSp
 
 
 
+
+
+
+
 
 
 
@@ -134,6 +138,8 @@ const asResponseDefault = (raw) => [
   let connected = false
   let cancelConnect = false
   const timeout = 1000 * (_nullishCoalesce(config.timeout, () => ( 30)))
+  const keepAliveMs = _nullishCoalesce(config.keepAliveMs, () => ( KEEP_ALIVE_MS))
+  const wakeUpMs = _nullishCoalesce(config.wakeUpMs, () => ( WAKE_UP_MS))
   let trackedError
   let timer
 
@@ -261,10 +267,27 @@ const asResponseDefault = (raw) => [
     }
   }
 
+  // A task resumes with each response or failure, and then makes its next
+  // request or reports with a boolean that it is done:
+  const submitNextTask = (
+    generator,
+    resumed
+  ) => {
+    resumed
+      .then(result => {
+        const task = result.value
+        if (typeof task === 'boolean') return
+        instance.submitTask(task, generator)
+      })
+      .catch(e => {
+        log.error(e.message)
+      })
+  }
+
   const onTimer = () => {
     log(`socket timer with server ${uri} expired, check if healthCheck needed`)
     const now = Date.now() - TIMER_SLACK
-    if (lastKeepAlive + KEEP_ALIVE_MS < now) {
+    if (lastKeepAlive + keepAliveMs < now) {
       log(`submitting healthCheck to server ${uri}`)
       lastKeepAlive = now
       config
@@ -277,11 +300,10 @@ const asResponseDefault = (raw) => [
 
     for (const [id, request] of Object.entries(pendingRequests)) {
       if (request.startTime + timeout < now) {
-        request.generator
-          .throw(new Error(`Timeout for request ${id}`))
-          .catch(e => {
-            log.error(e.message)
-          })
+        submitNextTask(
+          request.generator,
+          request.generator.throw(new Error(`Timeout for request ${id}`))
+        )
         _utils.removeItem.call(void 0, pendingRequests, id)
       }
     }
@@ -291,7 +313,7 @@ const asResponseDefault = (raw) => [
 
   const setupTimer = () => {
     log(`setupTimer with server ${uri}`)
-    let nextWakeUp = lastWakeUp + WAKE_UP_MS
+    let nextWakeUp = lastWakeUp + wakeUpMs
     for (const request of Object.values(pendingRequests)) {
       const to = request.startTime + timeout
       if (to < nextWakeUp) nextWakeUp = to
@@ -352,23 +374,13 @@ const asResponseDefault = (raw) => [
               } else {
                 nextValue = responseMessage.data
               }
-              request.generator
-                .next(nextValue)
-                .then(result => {
-                  const task = result.value
-                  if (typeof task === 'boolean') {
-                    return
-                  }
-                  instance.submitTask(task, request.generator)
-                })
-                .catch(e => {
-                  log.error(e.message)
-                })
+              submitNextTask(
+                request.generator,
+                request.generator.next(nextValue)
+              )
             } catch (error) {
               console.log({ uri, error, response: responseMessage, request })
-              request.generator.throw(error).catch(e => {
-                log.error(e.message)
-              })
+              submitNextTask(request.generator, request.generator.throw(error))
             }
             continue
           }

package/lib/common/utxobased/network/electrumApi.js

@@ -144,13 +144,32 @@ var _cleaners = require('cleaners');
  const pingMessage = () => {
   return {
     method: 'server.ping',
-    params: undefined,
+    // Electrum servers such as Fulcrum reject the `{}` the socket sends for
+    // missing params as named params, so an empty array is required:
+    params: [],
     cleaner: exports.asElectrumResponse.call(void 0, exports.asPingResponse)
   }
 }; exports.pingMessage = pingMessage
 
  const asPingResponse = _cleaners.asMaybe.call(void 0, _cleaners.asUndefined); exports.asPingResponse = asPingResponse
 
+/**
+ * Subscribe to Headers (Get Block Height)
+ */
+ const headersSubscribeMessage = () => ({
+  method: 'blockchain.headers.subscribe',
+  params: [],
+  cleaner: exports.asElectrumResponse.call(void 0, exports.asHeadersSubscribeResponse)
+}); exports.headersSubscribeMessage = headersSubscribeMessage
+
+
+
+// The chain tip's header, which the server also sends for each new tip:
+ const asHeadersSubscribeResponse = _cleaners.asObject.call(void 0, {
+  height: _cleaners.asNumber,
+  hex: _cleaners.asString
+}); exports.asHeadersSubscribeResponse = asHeadersSubscribeResponse
+
 /**
  * List Unspent (Get UTXOs)
  */
@@ -201,3 +220,32 @@ var _cleaners = require('cleaners');
 }); exports.transactionMessage = transactionMessage
 
  const asTransactionResponse = exports.asElectrumTransaction; exports.asTransactionResponse = asTransactionResponse
+
+/**
+ * Get Raw Transaction
+ */
+ const rawTransactionMessage = (
+  txHash
+) => ({
+  method: 'blockchain.transaction.get',
+  params: [txHash, false],
+  cleaner: exports.asElectrumResponse.call(void 0, exports.asRawTransactionResponse)
+}); exports.rawTransactionMessage = rawTransactionMessage
+
+ const asRawTransactionResponse = _cleaners.asString; exports.asRawTransactionResponse = asRawTransactionResponse
+
+/**
+ * Broadcast Transaction
+ */
+ const broadcastTransactionMessage = (
+  rawTx
+) => ({
+  method: 'blockchain.transaction.broadcast',
+  params: [rawTx],
+  cleaner: exports.asElectrumResponse.call(void 0, exports.asBroadcastTransactionResponse)
+}); exports.broadcastTransactionMessage = broadcastTransactionMessage
+
+
+
+// The server answers with the transaction's txid:
+ const asBroadcastTransactionResponse = _cleaners.asString; exports.asBroadcastTransactionResponse = asBroadcastTransactionResponse

package/lib/src/common/plugin/EngineEmitter.d.ts

@@ -6,11 +6,11 @@ export declare interface EngineEmitter {
     emit: ((event: EngineEvent.SEEN_TX_CHECKPOINT, checkpoint: string) => boolean) & ((event: EngineEvent.TRANSACTIONS, transactionEvents: EdgeTransactionEvent[]) => boolean) & ((event: EngineEvent.TRANSACTIONS_CHANGED, transactions: EdgeTransaction[]) => boolean) & ((event: EngineEvent.ADDRESS_BALANCE_CHANGED, currencyCode: string, addressBalanceChanges: Array<{
         scriptPubkey: string;
         balance: string;
-    }>) => boolean) & ((event: EngineEvent.WALLET_BALANCE_CHANGED, currencyCode: string, nativeBalance: string) => boolean) & ((event: EngineEvent.BLOCK_HEIGHT_CHANGED, uri: string, blockHeight: number) => boolean) & ((event: EngineEvent.NEW_ADDRESS_TRANSACTION, uri: string, newTx: SubscribeAddressResponse) => boolean) & ((event: EngineEvent.ADDRESSES_CHECKED, progressRatio: number) => boolean) & ((event: EngineEvent.TXIDS_CHANGED, txids: EdgeTxidMap) => boolean);
+    }>) => boolean) & ((event: EngineEvent.WALLET_BALANCE_CHANGED, currencyCode: string, nativeBalance: string) => boolean) & ((event: EngineEvent.BLOCK_HEIGHT_CHANGED, uri: string, blockHeight: number) => boolean) & ((event: EngineEvent.NEW_ADDRESS_TRANSACTION, uri: string, newTx: SubscribeAddressResponse) => boolean) & ((event: EngineEvent.ADDRESSES_CHECKED, progressRatio: number) => boolean) & ((event: EngineEvent.TXIDS_CHANGED, txids: EdgeTxidMap) => boolean) & ((event: EngineEvent.SERVER_DROPPED, uri: string) => boolean);
     on: ((event: EngineEvent.SEEN_TX_CHECKPOINT, listener: (checkpoint: string) => Promise<void> | void) => this) & ((event: EngineEvent.TRANSACTIONS, listener: (transactionEvents: EdgeTransactionEvent[]) => Promise<void> | void) => boolean) & ((event: EngineEvent.TRANSACTIONS_CHANGED, listener: (transactions: EdgeTransaction[]) => Promise<void> | void) => this) & ((event: EngineEvent.ADDRESS_BALANCE_CHANGED, listener: (currencyCode: string, addressBalanceChanges: Array<{
         scriptPubkey: string;
         balance: string;
-    }>) => Promise<void> | void) => this) & ((event: EngineEvent.WALLET_BALANCE_CHANGED, listener: (currencyCode: string, nativeBalance: string) => Promise<void> | void) => this) & ((event: EngineEvent.BLOCK_HEIGHT_CHANGED, listener: (uri: string, blockHeight: number) => Promise<void> | void) => this) & ((event: EngineEvent.NEW_ADDRESS_TRANSACTION, listener: (uri: string, newTx: SubscribeAddressResponse) => Promise<void> | void) => this) & ((event: EngineEvent.ADDRESSES_CHECKED, listener: (progressRatio: number) => Promise<void> | void) => this) & ((event: EngineEvent.TXIDS_CHANGED, listener: (txids: EdgeTxidMap) => Promise<void> | void) => this);
+    }>) => Promise<void> | void) => this) & ((event: EngineEvent.WALLET_BALANCE_CHANGED, listener: (currencyCode: string, nativeBalance: string) => Promise<void> | void) => this) & ((event: EngineEvent.BLOCK_HEIGHT_CHANGED, listener: (uri: string, blockHeight: number) => Promise<void> | void) => this) & ((event: EngineEvent.NEW_ADDRESS_TRANSACTION, listener: (uri: string, newTx: SubscribeAddressResponse) => Promise<void> | void) => this) & ((event: EngineEvent.ADDRESSES_CHECKED, listener: (progressRatio: number) => Promise<void> | void) => this) & ((event: EngineEvent.TXIDS_CHANGED, listener: (txids: EdgeTxidMap) => Promise<void> | void) => this) & ((event: EngineEvent.SERVER_DROPPED, listener: (uri: string) => Promise<void> | void) => this);
 }
 export declare class EngineEmitter extends EventEmitter {
 }
@@ -25,6 +25,11 @@ export declare enum EngineEvent {
     NEW_ADDRESS_TRANSACTION = "address:transaction:changed",
     ADDRESSES_CHECKED = "addresses:checked",
     TXIDS_CHANGED = "txids:changed",
+    /**
+     * The engine disconnected a server on purpose because it was found to be
+     * out of sync. Data fetched through it may be behind the chain.
+     */
+    SERVER_DROPPED = "server:dropped",
     CONNECTION_OPEN = "connection:open",
     CONNECTION_CLOSE = "connection:close",
     CONNECTION_TIMER = "connection:timer"

package/lib/src/common/plugin/PluginState.d.ts

@@ -1,8 +1,23 @@
 import { Disklet } from 'disklet';
 import { EdgeIo, EdgeLog } from 'edge-core-js/types';
+import { ServerHealth } from '../utxobased/engine/ServerStates';
 import { UtxoUserSettings } from '../utxobased/engine/types';
 import { UtxoEngineProcessor } from '../utxobased/engine/UtxoEngineProcessor';
 import { InfoPayload } from './types';
+/**
+ * How long a server dropped for being out of sync stays out of the pick
+ * order. Long enough for a lagging indexer to catch up, short enough that a
+ * recovered server is tried again without an app restart. After expiry the
+ * server is probed again on connect and dropped again if still behind.
+ */
+export declare const SERVER_QUARANTINE_MS: number;
+/**
+ * Runs a server's health probe, or hands back the one started for the same
+ * URI less than `minIntervalMs` ago, whether it is still in flight or has
+ * already answered.
+ */
+export declare type ShareServerProbe = (uri: string, minIntervalMs: number, probe: () => Promise<ServerHealth>) => Promise<ServerHealth>;
+export declare function makeShareServerProbe(): ShareServerProbe;
 /** A JSON object (as opposed to an array or primitive). */
 interface JsonObject {
     [name: string]: unknown;
@@ -28,6 +43,21 @@ export interface PluginState {
     load: () => Promise<PluginState>;
     serverScoreDown: (uri: string) => void;
     serverScoreUp: (uri: string, score: number) => void;
+    /**
+     * Keeps a server out of getLocalServers for a while. Shared by every
+     * engine of this plugin, so one wallet's finding spares the others the
+     * same connect-probe-drop cycle. In memory only: it does not outlive the
+     * plugin, and a restart gives the server a fresh chance.
+     */
+    quarantineServer: (uri: string, durationMs?: number) => void;
+    isServerQuarantined: (uri: string) => boolean;
+    hasQuarantinedServers: () => boolean;
+    /**
+     * Shares health probes between every engine of this plugin, so N wallets
+     * connected to the same server cost one REST request per interval rather
+     * than N. Each engine still applies the answer to its own connection.
+     */
+    shareServerProbe: ShareServerProbe;
     clearCache: () => Promise<void>;
     getLocalServers: (numServersWanted: number, includePatterns?: Array<string | RegExp>) => string[];
     refreshServers: (updatedCustomServers?: string[]) => Promise<void>;

package/lib/src/common/plugin/types.d.ts

@@ -161,6 +161,16 @@ export interface CoinInfo {
      * build-in replay-protection mechanisms.
      */
     sighash?: number;
+    /**
+     * Optional nLockTime value set on every transaction. This is used by forks
+     * whose nodes treat a magic nLockTime as final while the parent chain reads
+     * it as an unreachable block height, making the fork's transactions
+     * impossible to replay on the parent chain.
+     *
+     * Transactions for these currencies always have a non-final input sequence,
+     * since nodes ignore nLockTime when every input sequence is final.
+     */
+    lockTime?: number;
     /**
      * A function to be passed to AltcoinJS `signInput` method. This is used to
      * get the input hash for the signature algorithm before signing the input.