psf-bch-api 1.1.0 → 1.3.0

package/src/controllers/rest-api/full-node/blockchain/controller.js

@@ -48,7 +48,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/ Service status
+   * @api {get} /v6/full-node/blockchain/ Service status
    * @apiName BlockchainRoot
    * @apiGroup Blockchain
    *
@@ -61,13 +61,13 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getBestBlockHash Get best block hash
+   * @api {get} /v6/full-node/blockchain/getBestBlockHash Get best block hash
    * @apiName GetBestBlockHash
    * @apiGroup Blockchain
    * @apiDescription Returns the hash of the best (tip) block in the longest block chain.
    *
    * @apiExample Example usage:
-   * curl -X GET "https://api.fullstack.cash/v5/blockchain/getBestBlockHash" -H "accept: application/json"
+   * curl -X GET "https://api.fullstack.cash/v6/full-node/blockchain/getBestBlockHash" -H "accept: application/json"
    *
    * @apiSuccess {String} bestBlockHash Hash of the best block
    */
@@ -81,7 +81,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getBlockchainInfo Get blockchain info
+   * @api {get} /v6/full-node/blockchain/getBlockchainInfo Get blockchain info
    * @apiName GetBlockchainInfo
    * @apiGroup Blockchain
    * @apiDescription Returns various state info regarding blockchain processing.
@@ -96,7 +96,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getBlockCount Get block count
+   * @api {get} /v6/full-node/blockchain/getBlockCount Get block count
    * @apiName GetBlockCount
    * @apiGroup Blockchain
    * @apiDescription Returns the number of blocks in the longest blockchain.
@@ -111,7 +111,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getBlockHeader/:hash Get single block header
+   * @api {get} /v6/full-node/blockchain/getBlockHeader/:hash Get single block header
    * @apiName GetSingleBlockHeader
    * @apiGroup Blockchain
    * @apiDescription Returns serialized block header data.
@@ -136,7 +136,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/getBlockHeader Get multiple block headers
+   * @api {post} /v6/full-node/blockchain/getBlockHeader Get multiple block headers
    * @apiName GetBulkBlockHeader
    * @apiGroup Blockchain
    * @apiDescription Returns serialized block header data for multiple hashes.
@@ -155,7 +155,7 @@ class BlockchainRESTController {
         })
       }
 
-      if (!this.adapters.fullNode.validateArraySize(hashes.length, { isProUser: Boolean(req.locals?.proLimit) })) {
+      if (!this.adapters.fullNode.validateArraySize(hashes.length)) {
         return res.status(400).json({ error: 'Array too large.' })
       }
 
@@ -173,7 +173,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getChainTips Get chain tips
+   * @api {get} /v6/full-node/blockchain/getChainTips Get chain tips
    * @apiName GetChainTips
    * @apiGroup Blockchain
    * @apiDescription Returns information about known tips in the block tree.
@@ -188,7 +188,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getDifficulty Get difficulty
+   * @api {get} /v6/full-node/blockchain/getDifficulty Get difficulty
    * @apiName GetDifficulty
    * @apiGroup Blockchain
    * @apiDescription Returns the current difficulty value.
@@ -203,7 +203,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getMempoolEntry/:txid Get single mempool entry
+   * @api {get} /v6/full-node/blockchain/getMempoolEntry/:txid Get single mempool entry
    * @apiName GetMempoolEntry
    * @apiGroup Blockchain
    * @apiDescription Returns mempool data for a transaction.
@@ -223,7 +223,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/getMempoolEntry Get bulk mempool entry
+   * @api {post} /v6/full-node/blockchain/getMempoolEntry Get bulk mempool entry
    * @apiName GetMempoolEntryBulk
    * @apiGroup Blockchain
    * @apiDescription Returns mempool data for multiple transactions.
@@ -238,7 +238,7 @@ class BlockchainRESTController {
         })
       }
 
-      if (!this.adapters.fullNode.validateArraySize(txids.length, { isProUser: Boolean(req.locals?.proLimit) })) {
+      if (!this.adapters.fullNode.validateArraySize(txids.length)) {
         return res.status(400).json({ error: 'Array too large.' })
       }
 
@@ -256,7 +256,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getMempoolAncestors/:txid Get mempool ancestors
+   * @api {get} /v6/full-node/blockchain/getMempoolAncestors/:txid Get mempool ancestors
    * @apiName GetMempoolAncestors
    * @apiGroup Blockchain
    * @apiDescription Returns mempool ancestor data for a transaction.
@@ -281,7 +281,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getMempoolInfo Get mempool info
+   * @api {get} /v6/full-node/blockchain/getMempoolInfo Get mempool info
    * @apiName GetMempoolInfo
    * @apiGroup Blockchain
    * @apiDescription Returns details on the state of the mempool.
@@ -296,7 +296,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getRawMempool Get raw mempool
+   * @api {get} /v6/full-node/blockchain/getRawMempool Get raw mempool
    * @apiName GetRawMempool
    * @apiGroup Blockchain
    * @apiDescription Returns all transaction ids in the mempool.
@@ -314,7 +314,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getTxOut/:txid/:n Get transaction output
+   * @api {get} /v6/full-node/blockchain/getTxOut/:txid/:n Get transaction output
    * @apiName GetTxOut
    * @apiGroup Blockchain
    * @apiDescription Returns details about an unspent transaction output.
@@ -347,7 +347,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/getTxOut Validate a UTXO
+   * @api {post} /v6/full-node/blockchain/getTxOut Validate a UTXO
    * @apiName GetTxOutPost
    * @apiGroup Blockchain
    * @apiDescription Returns details about an unspent transaction output.
@@ -380,7 +380,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getTxOutProof/:txid Get TxOut proof
+   * @api {get} /v6/full-node/blockchain/getTxOutProof/:txid Get TxOut proof
    * @apiName GetTxOutProofSingle
    * @apiGroup Blockchain
    * @apiDescription Returns a hex-encoded proof that the transaction was included in a block.
@@ -400,7 +400,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/getTxOutProof Get TxOut proofs
+   * @api {post} /v6/full-node/blockchain/getTxOutProof Get TxOut proofs
    * @apiName GetTxOutProofBulk
    * @apiGroup Blockchain
    * @apiDescription Returns hex-encoded proofs for transactions.
@@ -415,7 +415,7 @@ class BlockchainRESTController {
         })
       }
 
-      if (!this.adapters.fullNode.validateArraySize(txids.length, { isProUser: Boolean(req.locals?.proLimit) })) {
+      if (!this.adapters.fullNode.validateArraySize(txids.length)) {
         return res.status(400).json({ error: 'Array too large.' })
       }
 
@@ -435,7 +435,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/verifyTxOutProof/:proof Verify TxOut proof
+   * @api {get} /v6/full-node/blockchain/verifyTxOutProof/:proof Verify TxOut proof
    * @apiName VerifyTxOutProofSingle
    * @apiGroup Blockchain
    * @apiDescription Verifies a hex-encoded proof was included in a block.
@@ -455,7 +455,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/verifyTxOutProof Verify TxOut proofs
+   * @api {post} /v6/full-node/blockchain/verifyTxOutProof Verify TxOut proofs
    * @apiName VerifyTxOutProofBulk
    * @apiGroup Blockchain
    * @apiDescription Verifies hex-encoded proofs were included in blocks.
@@ -470,7 +470,7 @@ class BlockchainRESTController {
         })
       }
 
-      if (!this.adapters.fullNode.validateArraySize(proofs.length, { isProUser: Boolean(req.locals?.proLimit) })) {
+      if (!this.adapters.fullNode.validateArraySize(proofs.length)) {
         return res.status(400).json({ error: 'Array too large.' })
       }
 
@@ -490,7 +490,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {post} /full-node/blockchain/getBlock Get block details
+   * @api {post} /v6/full-node/blockchain/getBlock Get block details
    * @apiName GetBlock
    * @apiGroup Blockchain
    * @apiDescription Returns block details for a hash.
@@ -519,7 +519,7 @@ class BlockchainRESTController {
   }
 
   /**
-   * @api {get} /full-node/blockchain/getBlockHash/:height Get block hash
+   * @api {get} /v6/full-node/blockchain/getBlockHash/:height Get block hash
    * @apiName GetBlockHash
    * @apiGroup Blockchain
    * @apiDescription Returns the hash of a block by height.

package/src/controllers/rest-api/full-node/blockchain/{index.js → router.js}

@@ -28,7 +28,11 @@ class BlockchainRouter {
 
     this.blockchainController = new BlockchainRESTController(dependencies)
 
-    this.baseUrl = '/full-node/blockchain'
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/full-node/blockchain`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
     this.router = express.Router()
   }
 

package/src/controllers/rest-api/full-node/control/controller.js

@@ -0,0 +1,68 @@
+/*
+  REST API Controller for the /full-node/control routes.
+*/
+
+import wlogger from '../../../../adapters/wlogger.js'
+
+class ControlRESTController {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Control REST Controller.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases || !this.useCases.control) {
+      throw new Error(
+        'Instance of Control use cases required when instantiating Control REST Controller.'
+      )
+    }
+
+    this.controlUseCases = this.useCases.control
+
+    this.root = this.root.bind(this)
+    this.getNetworkInfo = this.getNetworkInfo.bind(this)
+    this.handleError = this.handleError.bind(this)
+  }
+
+  /**
+   * @api {get} /v6/full-node/control/ Service status
+   * @apiName ControlRoot
+   * @apiGroup Control
+   *
+   * @apiDescription Returns the status of the control service.
+   *
+   * @apiSuccess {String} status Service identifier
+   */
+  async root (req, res) {
+    return res.status(200).json({ status: 'control' })
+  }
+
+  /**
+   * @api {get} /v6/full-node/control/getNetworkInfo Get Network Info
+   * @apiName GetNetworkInfo
+   * @apiGroup Control
+   * @apiDescription RPC call that gets basic full node information.
+   */
+  async getNetworkInfo (req, res) {
+    try {
+      const result = await this.controlUseCases.getNetworkInfo()
+      return res.status(200).json(result)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  handleError (err, res) {
+    wlogger.error('Error in ControlRESTController:', err)
+
+    const status = err.status || 500
+    const message = err.message || 'Internal server error'
+
+    return res.status(status).json({ error: message })
+  }
+}
+
+export default ControlRESTController

package/src/controllers/rest-api/full-node/control/router.js

@@ -0,0 +1,51 @@
+/*
+  REST API router for /full-node/control routes.
+*/
+
+import express from 'express'
+import ControlRESTController from './controller.js'
+
+class ControlRouter {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Control REST Router.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error(
+        'Instance of Use Cases library required when instantiating Control REST Router.'
+      )
+    }
+
+    const dependencies = {
+      adapters: this.adapters,
+      useCases: this.useCases
+    }
+
+    this.controlController = new ControlRESTController(dependencies)
+
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/full-node/control`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
+    this.router = express.Router()
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching REST API controllers.')
+    }
+
+    this.router.get('/', this.controlController.root)
+    this.router.get('/getNetworkInfo', this.controlController.getNetworkInfo)
+
+    app.use(this.baseUrl, this.router)
+  }
+}
+
+export default ControlRouter

package/src/controllers/rest-api/full-node/dsproof/controller.js

@@ -0,0 +1,90 @@
+/*
+  REST API Controller for the /full-node/dsproof routes.
+*/
+
+import wlogger from '../../../../adapters/wlogger.js'
+
+class DSProofRESTController {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating DSProof REST Controller.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases || !this.useCases.dsproof) {
+      throw new Error(
+        'Instance of DSProof use cases required when instantiating DSProof REST Controller.'
+      )
+    }
+
+    this.dsproofUseCases = this.useCases.dsproof
+
+    this.root = this.root.bind(this)
+    this.getDSProof = this.getDSProof.bind(this)
+    this.handleError = this.handleError.bind(this)
+  }
+
+  /**
+   * @api {get} /v6/full-node/dsproof/ Service status
+   * @apiName DSProofRoot
+   * @apiGroup DSProof
+   *
+   * @apiDescription Returns the status of the dsproof service.
+   *
+   * @apiSuccess {String} status Service identifier
+   */
+  async root (req, res) {
+    return res.status(200).json({ status: 'dsproof' })
+  }
+
+  /**
+   * @api {get} /v6/full-node/dsproof/getDSProof/:txid Get Double-Spend Proof
+   * @apiName GetDSProof
+   * @apiGroup DSProof
+   * @apiDescription Get information for a double-spend proof.
+   *
+   * @apiParam {String} txid Transaction ID
+   * @apiParam {String} verbose Verbose level (`false`, `true`) for compatibility with legacy API
+   */
+  async getDSProof (req, res) {
+    try {
+      const txid = req.params.txid
+
+      if (!txid) {
+        return res.status(400).json({
+          success: false,
+          error: 'txid can not be empty'
+        })
+      }
+
+      if (txid.length !== 64) {
+        return res.status(400).json({
+          success: false,
+          error: `txid must be of length 64 (not ${txid.length})`
+        })
+      }
+
+      let verbose = 2
+      if (req.query.verbose === 'true') verbose = 3
+
+      const result = await this.dsproofUseCases.getDSProof({ txid, verbose })
+      return res.status(200).json(result)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  handleError (err, res) {
+    wlogger.error('Error in DSProofRESTController:', err)
+
+    const status = err.status || 500
+    const message = err.message || 'Internal server error'
+
+    return res.status(status).json({ error: message })
+  }
+}
+
+export default DSProofRESTController

package/src/controllers/rest-api/full-node/dsproof/router.js

@@ -0,0 +1,51 @@
+/*
+  REST API router for /full-node/dsproof routes.
+*/
+
+import express from 'express'
+import DSProofRESTController from './controller.js'
+
+class DSProofRouter {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating DSProof REST Router.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error(
+        'Instance of Use Cases library required when instantiating DSProof REST Router.'
+      )
+    }
+
+    const dependencies = {
+      adapters: this.adapters,
+      useCases: this.useCases
+    }
+
+    this.dsproofController = new DSProofRESTController(dependencies)
+
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/full-node/dsproof`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
+    this.router = express.Router()
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching REST API controllers.')
+    }
+
+    this.router.get('/', this.dsproofController.root)
+    this.router.get('/getDSProof/:txid', this.dsproofController.getDSProof)
+
+    app.use(this.baseUrl, this.router)
+  }
+}
+
+export default DSProofRouter

package/src/controllers/rest-api/full-node/mining/controller.js

@@ -0,0 +1,99 @@
+/*
+  REST API Controller for the /full-node/mining routes.
+*/
+
+import wlogger from '../../../../adapters/wlogger.js'
+
+class MiningRESTController {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Mining REST Controller.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases || !this.useCases.mining) {
+      throw new Error(
+        'Instance of Mining use cases required when instantiating Mining REST Controller.'
+      )
+    }
+
+    this.miningUseCases = this.useCases.mining
+
+    // Bind functions
+    this.root = this.root.bind(this)
+    this.getMiningInfo = this.getMiningInfo.bind(this)
+    this.getNetworkHashPS = this.getNetworkHashPS.bind(this)
+    this.handleError = this.handleError.bind(this)
+  }
+
+  /**
+   * @api {get} /v6/full-node/mining/ Service status
+   * @apiName MiningRoot
+   * @apiGroup Mining
+   *
+   * @apiDescription Returns the status of the mining service.
+   *
+   * @apiSuccess {String} status Service identifier
+   */
+  async root (req, res) {
+    return res.status(200).json({ status: 'mining' })
+  }
+
+  /**
+   * @api {get} /v6/full-node/mining/getMiningInfo Get Mining Info
+   * @apiName GetMiningInfo
+   * @apiGroup Mining
+   * @apiDescription Returns a json object containing mining-related information.
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/full-node/mining/getMiningInfo" -H "accept: application/json"
+   */
+  async getMiningInfo (req, res) {
+    try {
+      const result = await this.miningUseCases.getMiningInfo()
+      return res.status(200).json(result)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  /**
+   * @api {get} /v6/full-node/mining/getNetworkHashPS Get Estimated network hashes per second
+   * @apiName GetNetworkHashPS
+   * @apiGroup Mining
+   * @apiDescription Returns the estimated network hashes per second based on the last n blocks. Pass in [nblocks] to override # of blocks, -1 specifies since last difficulty change. Pass in [height] to estimate the network speed at the time when a certain block was found.
+   *
+   * @apiParam {Number} nblocks Number of blocks to use for estimation (default: 120)
+   * @apiParam {Number} height Block height to estimate at (default: -1)
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/full-node/mining/getNetworkHashPS?nblocks=120&height=-1" -H "accept: application/json"
+   */
+  async getNetworkHashPS (req, res) {
+    try {
+      let nblocks = 120 // Default
+      let height = -1 // Default
+      if (req.query.nblocks) nblocks = parseInt(req.query.nblocks)
+      if (req.query.height) height = parseInt(req.query.height)
+
+      const result = await this.miningUseCases.getNetworkHashPS({ nblocks, height })
+      return res.status(200).json(result)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  handleError (err, res) {
+    wlogger.error('Error in MiningRESTController:', err)
+
+    const status = err.status || 500
+    const message = err.message || 'Internal server error'
+
+    return res.status(status).json({ error: message })
+  }
+}
+
+export default MiningRESTController

package/src/controllers/rest-api/full-node/mining/router.js

@@ -0,0 +1,52 @@
+/*
+  REST API router for /full-node/mining routes.
+*/
+
+import express from 'express'
+import MiningRESTController from './controller.js'
+
+class MiningRouter {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Mining REST Router.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error(
+        'Instance of Use Cases library required when instantiating Mining REST Router.'
+      )
+    }
+
+    const dependencies = {
+      adapters: this.adapters,
+      useCases: this.useCases
+    }
+
+    this.miningController = new MiningRESTController(dependencies)
+
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/full-node/mining`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
+    this.router = express.Router()
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching REST API controllers.')
+    }
+
+    this.router.get('/', this.miningController.root)
+    this.router.get('/getMiningInfo', this.miningController.getMiningInfo)
+    this.router.get('/getNetworkHashPS', this.miningController.getNetworkHashPS)
+
+    app.use(this.baseUrl, this.router)
+  }
+}
+
+export default MiningRouter