psffpp 1.0.1

package/index.js

@@ -0,0 +1,329 @@
+/*
+  This library implement PS009 specification:
+  https://github.com/Permissionless-Software-Foundation/specifications/blob/master/ps009-multisig-approval.md
+*/
+
+// global libraries
+const bitcore = require('bitcore-lib-cash')
+const axios = require('axios')
+
+// Local libraries
+const NFTs = require('./lib/nfts')
+const UtilLib = require('./lib/util')
+
+class MultisigApproval {
+  constructor (localConfig = {}) {
+    // Dependency Injection
+    this.wallet = localConfig.wallet
+    if (!this.wallet) {
+      throw new Error('Instance of minimal-slp-wallet must be passed in as a property called \'wallet\', when initializing the psf-multisig-approval library.')
+    }
+
+    // The default IPFS gateway can be overwritten by the user when this library
+    // is instantiated.
+    this.ipfsGateway = localConfig.ipfsGateway
+    if (!this.ipfsGateway) {
+      this.ipfsGateway = 'https://p2wdb-gateway-678.fullstack.cash'
+    }
+
+    // Encapsulate dependencies
+    this.bchjs = this.wallet.bchjs
+    this.bitcore = bitcore
+    this.axios = axios
+    this.nfts = new NFTs(localConfig)
+    this.util = new UtilLib(localConfig)
+
+    // Bind the this object to all subfunctions in this class
+    this.getNftHolderInfo = this.getNftHolderInfo.bind(this)
+    this.createMultisigAddress = this.createMultisigAddress.bind(this)
+    this.getApprovalTx = this.getApprovalTx.bind(this)
+
+    // Create a transaction details cache, to reduce the number of API calls.
+    this.txCache = {}
+  }
+
+  // This function retrieves the NFTs associated with a Group token ID. It then
+  // tries to retrieve the BCH addresses and public keys of the holders of those
+  // NFTs. It returns an object with all that information in it.
+  // The function defaults to the PSF Minting Council, but any Group token ID
+  // can be used.
+  async getNftHolderInfo (groupTokenId = '8e8d90ebdb1791d58eba7acd428ff3b1e21c47fb7aba2ba3b5b815aa0fe7d6d5') {
+    try {
+      // console.log('groupTokenId: ', groupTokenId)
+
+      const nfts = await this.nfts.getNftsFromGroup()
+      // console.log('getNftHolderInfo() nfts: ', nfts)
+
+      const addrs = await this.nfts.getAddrsFromNfts(nfts)
+      // console.log('getNftHolderInfo() addrs: ', addrs)
+
+      const { keys, keysNotFound } = await this.nfts.findKeys(addrs, nfts)
+
+      return { keys, keysNotFound }
+    } catch (err) {
+      console.error('Error in getNftHolderInfo()')
+      throw err
+    }
+  }
+
+  // Generate a P2SH multisignature wallet from the public keys of the NFT holders.
+  // The address for the wallet is returned.
+  // The input for this function should be the `keys` output from
+  // getNftHolderInfo()
+  createMultisigAddress (inObj = {}) {
+    try {
+      const { keys } = inObj
+      let requiredSigners = inObj.requiredSigners
+
+      // Input validation
+      if (!Array.isArray(keys)) {
+        throw new Error('keys must be an array containing public keys')
+      }
+
+      // Isolate just an array of public keys.
+      const pubKeys = []
+      for (let i = 0; i < keys.length; i++) {
+        const thisPair = keys[i]
+
+        pubKeys.push(thisPair.pubKey)
+      }
+
+      // If the number of required signers is not specified, then default to
+      // a 50% + 1 threashold.
+      if (!requiredSigners) {
+        requiredSigners = Math.floor(pubKeys.length / 2) + 1
+      }
+
+      // Multisig Address
+      const msAddr = new bitcore.Address(pubKeys, requiredSigners)
+
+      // Locking Script in hex representation.
+      const scriptHex = new bitcore.Script(msAddr).toHex()
+
+      const walletObj = {
+        address: msAddr.toString(),
+        scriptHex,
+        publicKeys: pubKeys,
+        requiredSigners
+      }
+
+      return walletObj
+    } catch (err) {
+      console.error('Error in createMultisigWallet()')
+      throw err
+    }
+  }
+
+  // Given a BCH address, scan its transaction history to find the latest
+  // APPROVAL transaction. This function returns the TXID of the UPDATE
+  // transaction that the APPROVAL transaction approves.
+  // If no APPROVAL transaction can be found, then function returns null.
+  // An optional input, filterTxids, is an array of transaction IDs to ignore. This can
+  // be used to ignore/skip any known, fake approval transactions.
+  async getApprovalTx (inObj = {}) {
+    try {
+      let address = inObj.address
+      const { filterTxids } = inObj
+
+      // Input validation
+      if (address.includes('simpleledger:')) {
+        address = this.bchjs.SLP.Address.toCashAddress(address)
+      }
+      if (!address.includes('bitcoincash:')) {
+        throw new Error('Input address must start with bitcoincash: or simpleledger:')
+      }
+
+      // Get the transaction history for the address
+      const txHistory = await this.wallet.getTransactions(address)
+      // console.log('txHistory: ', JSON.stringify(txHistory, null, 2))
+
+      // Loop through the transaction history
+      for (let i = 0; i < txHistory.length; i++) {
+        const thisTxid = txHistory[i]
+
+        // const height = thisTxid.height
+        const txid = thisTxid.tx_hash
+
+        // Skip the txid if it is in the filter list.
+        if (Array.isArray(filterTxids)) {
+          const txidFound = filterTxids.find(x => x === txid)
+          // console.log('txidFound: ', txidFound)
+          if (txidFound) {
+            continue
+          }
+        }
+
+        // Get the transaction details for the transaction
+        const txDetails = await this.util.getTxData(txid)
+        // console.log('txDetails: ', JSON.stringify(txDetails, null, 2))
+        // console.log(`txid: ${txid}`)
+
+        const out2ascii = Buffer.from(txDetails.vout[0].scriptPubKey.hex, 'hex').toString('ascii')
+        // console.log('out2ascii: ', out2ascii)
+
+        // If the first output is not an OP_RETURN, then the tx can be discarded.
+        if (!out2ascii.includes('APPROVE')) {
+          continue
+        }
+
+        const updateTxid = out2ascii.slice(10)
+        // console.log('updateTxid: ', updateTxid)
+
+        const outObj = {
+          approvalTxid: txid,
+          updateTxid,
+          approvalTxDetails: txDetails,
+          opReturn: out2ascii
+        }
+
+        return outObj
+      }
+
+      return null
+    } catch (err) {
+      console.error('Error in getApprovedData()')
+      throw err
+    }
+  }
+
+  // This function will retrieve an update transaction, given its txid. It will
+  // return an object with data about the transaction, including the CID and
+  // timestamp values encoded in the transactions OP_RETURN.
+  async getUpdateTx (inObj = {}) {
+    try {
+      const { txid } = inObj
+
+      // Input validation
+      if (!txid) {
+        throw new Error('txid required')
+      }
+
+      // Get the transaction details for the transaction
+      const txDetails = await this.util.getTxData(txid)
+      // console.log('txDetails: ', JSON.stringify(txDetails, null, 2))
+      // console.log(`txid: ${txid}`)
+
+      let updateObj = {}
+      try {
+        const out2ascii = Buffer.from(txDetails.vout[0].scriptPubKey.hex, 'hex').toString('ascii')
+        // console.log('out2ascii: ', out2ascii)
+
+        const jsonStr = out2ascii.slice(4)
+        // console.log('jsonStr: ', jsonStr)
+
+        updateObj = JSON.parse(jsonStr)
+      } catch (err) {
+        throw new Error('Could not parse JSON inside the transaction')
+      }
+
+      updateObj.txid = txid
+      updateObj.txDetails = txDetails
+
+      return updateObj
+    } catch (err) {
+      console.error('Error in getUpdateTx()')
+      throw err
+    }
+  }
+
+  // Given an CID, this function will retrieve the update data from an IPFS
+  // gateway.
+  async getCidData (inObj = {}) {
+    try {
+      const { cid } = inObj
+
+      // Input validation
+      if (!cid) {
+        throw new Error('cid a required input')
+      }
+
+      const urlStr = `${this.ipfsGateway}/ipfs/${cid}/data.json`
+      // console.log('urlStr: ', urlStr)
+
+      const request = await this.axios.get(urlStr)
+
+      return request.data
+    } catch (err) {
+      console.error('Error in getCidData()')
+      throw err
+    }
+  }
+
+  // This function will validate the approval transaction.
+  // This function will return true or false, to indicate the validity of the
+  // approval transaction.
+  // The input to this function is the output of several of the above function:
+  // - approvalObj is the output of getApprovalTx()
+  // - updateObj is the output of getUpdateTx()
+  // - updateData is the IPFS CID data retrieved with getCidData()
+  // - groupTokenId is optional. If not specified, it will default to the Group
+  //   token used to generate the PSF Minting Council NFTs.
+  async validateApproval (inObj = {}) {
+    try {
+      // console.log('inObj: ', JSON.stringify(inObj, null, 2))
+
+      const { approvalObj, updateObj, updateData, groupTokenId } = inObj
+
+      let validationResult = false
+
+      // Input validation
+      if (!approvalObj) {
+        throw new Error('Output object of getApprovalTx() is expected as input to this function, as \'approvalObj\'')
+      }
+      if (!updateObj) {
+        throw new Error('Output object of getUpdateTx() is expected as input to this function, as \'updateObj\'')
+      }
+      if (!updateData) {
+        throw new Error('Update CID JSON data is expected as input to this function, as \'updateData\'')
+      }
+
+      // Regenerate the multisig address from the pubkeys in the update data.
+      // Ensure it matches the input address to the approval transaction.
+      const pubKeys = updateData.walletObj.publicKeys
+      const requiredSigners = updateData.walletObj.requiredSigners
+      const approvalInputAddr = approvalObj.approvalTxDetails.vin[0].address
+      const msAddr = new this.bitcore.Address(pubKeys, requiredSigners).toString()
+      if (msAddr !== approvalInputAddr) {
+        console.log(`Approval TX input address (${approvalInputAddr}) does not match calculated multisig address ${msAddr}`)
+        return validationResult
+      }
+
+      // Get public key data for each NFT holder, from the blockchain.
+      const nftData = await this.getNftHolderInfo(groupTokenId)
+      const tokenPubKeys = nftData.keys
+
+      // Loop through the public keys from the token data, and count the matches.
+      let matches = 0
+      for (let i = 0; i < tokenPubKeys.length; i++) {
+        const thisTokenPubKey = tokenPubKeys[i].pubKey
+
+        // Loop through the public keys from the update data
+        for (let j = 0; j < pubKeys.length; j++) {
+          const thisUpdatePubKey = pubKeys[j]
+
+          if (thisTokenPubKey === thisUpdatePubKey) {
+            matches++
+            break
+          }
+        }
+      }
+
+      // Set a threshold for success.
+      let threshold = 2 // Minimum
+      if (requiredSigners > threshold) threshold = requiredSigners
+
+      // If the threshold of public keys match, then the approval transaction
+      // has been validated.
+      if (matches >= threshold) {
+        validationResult = true
+      }
+
+      return validationResult
+    } catch (err) {
+      console.error('Error in validateApproval()')
+      throw err
+    }
+  }
+}
+
+module.exports = MultisigApproval

package/lib/nfts.js

@@ -0,0 +1,113 @@
+/*
+  This library contains code for handling NFT and Group SLP tokens. Specifically
+  it has functions around looking up the NFTs related to a Group token, then
+  retrieving data on the holders of those NFTs.
+*/
+
+class NFTs {
+  constructor (localConfig = {}) {
+    this.wallet = localConfig.wallet
+    if (!this.wallet) {
+      throw new Error('Instance of minimal-slp-wallet must be passed in as a property called \'wallet\', when initializing the nfts.js library.')
+    }
+  }
+
+  // Retrieve a list of NFTs from the Group token that spawned them.
+  // The default value is the PSF Minting Council Group token.
+  async getNftsFromGroup (groupId = '8e8d90ebdb1791d58eba7acd428ff3b1e21c47fb7aba2ba3b5b815aa0fe7d6d5') {
+    try {
+      const groupData = await this.wallet.getTokenData(groupId)
+      // console.log('groupData: ', groupData)
+
+      const nfts = groupData.genesisData.nfts
+
+      return nfts
+    } catch (err) {
+      console.error('Error in getNftsFromGroup()')
+      throw err
+    }
+  }
+
+  // This function expects an array of strings as input. Each element in the
+  // input array is expected to be the Token ID of the an NFT. The address
+  // holding each NFT is looked up on the blockchain. The array of returned
+  // addresses are filtered for duplicates, before being returned.
+  async getAddrsFromNfts (nfts = []) {
+    try {
+      let addrs = []
+
+      // Loop through each NFT Token ID in the array.
+      for (let i = 0; i < nfts.length; i++) {
+        const thisNft = nfts[i]
+
+        // console.log('getAddrsFromNfts() this.wallet.bchjs.restURL: ', this.wallet.bchjs.restURL)
+
+        const nftData = await this.wallet.getTokenData(thisNft, true)
+        // console.log('getAddrsFromNfts() nftData: ', nftData)
+
+        if (!nftData.genesisData.nftHolder) {
+          throw new Error(`SLP indexer data does not include a holder address for this NFT. nftData: ${JSON.stringify(nftData, null, 2)}`)
+        }
+
+        addrs.push(nftData.genesisData.nftHolder)
+      }
+
+      // Remove duplicate addresses
+      addrs = [...new Set(addrs)]
+
+      return addrs
+    } catch (err) {
+      console.error('Error in getAddrsFromNfts(): ', err)
+      throw err
+    }
+  }
+
+  // The input to this function is the output of getNftsFromGroup() and
+  // getAddrsFromNfts(). It expects two arrays of strings, one an array of
+  // NFT Token IDs, the other an array of addresses holding those NFTs.
+  //
+  // For each address, it attempts to lookup the public key for that address.
+  // It returns an object with a keys and keysNotFound property:
+  // - keys - Object containing address and public key
+  // - keysNotFound - Array of addresses whos public keys could not be found.
+  async findKeys (addrs, nfts) {
+    // It is assumed that element 1 in the addrs array is associated with
+    // element 1 in the nfts array.
+
+    try {
+      const keys = []
+      const keysNotFound = []
+
+      for (let i = 0; i < addrs.length; i++) {
+        const thisAddr = addrs[i]
+        const thisNft = nfts[i]
+
+        // console.log('findKeys() thisAddr: ', thisAddr)
+        // console.log('this.wallet: ', this.wallet)
+        // console.log('this.wallet.interface: ', this.wallet.interface)
+        // console.log('this.wallet.restURL: ', this.wallet.restURL)
+
+        // Get public Key for reciever from the blockchain.
+        const publicKey = await this.wallet.getPubKey(thisAddr)
+        // console.log(`publicKey: ${JSON.stringify(publicKey, null, 2)}`)
+
+        if (publicKey.includes('not found')) {
+          keysNotFound.push(thisAddr)
+        } else {
+          keys.push({
+            addr: thisAddr,
+            pubKey: publicKey,
+            nft: thisNft
+          })
+        }
+      }
+
+      return { keys, keysNotFound }
+    } catch (err) {
+      console.error('Error in findKeys()')
+      throw err
+    }
+  }
+}
+
+module.exports = NFTs

package/lib/util.js

@@ -0,0 +1,50 @@
+/*
+  Generic utility functions that might be used in multiple places of the library.
+*/
+
+class UtilLib {
+  constructor (localConfig = {}) {
+    // Dependecy Injection
+    this.wallet = localConfig.wallet
+    if (!this.wallet) {
+      throw new Error('Instance of minimal-slp-wallet must be passed in as a property called \'wallet\', when initializing the util library.')
+    }
+
+    // Bind the 'this' object to all subfunctions.
+    this.getTxData = this.getTxData.bind(this)
+
+    // Create a transaction details cache, to reduce the number of API calls.
+    this.txCache = {}
+  }
+
+  // Given a transaction ID, retrieve the transaction details. If the details
+  // have already been downloaded, then they will be stored in a local cache.
+  // The cache speeds things up and reduces the number of API calls.
+  async getTxData (txid) {
+    try {
+      if (!txid) {
+        throw new Error('txid (transactoin ID) required')
+      }
+
+      // Try to get the transaction details from the cache
+      let txDetails = this.txCache[txid]
+
+      // Download from the full node if details are not in the cache.
+      if (!txDetails) {
+        // Get the transaction details from the full node
+        txDetails = await this.wallet.getTxData([txid])
+        txDetails = txDetails[0]
+
+        // Add the details to the cache
+        this.txCache[txid] = txDetails
+      }
+
+      return txDetails
+    } catch (err) {
+      console.error('Error in getTxData()')
+      throw err
+    }
+  }
+}
+
+module.exports = UtilLib

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "psffpp",
+  "version": "1.0.1",
+  "description": "PS010 PSF File Pinning Protocol",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "test": "npm run lint && TEST=unit nyc mocha test/unit/",
+    "test:integration": "mocha --timeout 120000 test/integration/",
+    "lint": "standard --env mocha --fix",
+    "docs": "./node_modules/.bin/apidoc -i src/ -o docs",
+    "coverage:report": "nyc --reporter=html mocha test/unit/ --exit"
+  },
+  "keywords": [
+    "bitcoin",
+    "bitcoin cash",
+    "wallet",
+    "javascript",
+    "cryptocurrency",
+    "react",
+    "front end",
+    "client",
+    "apidoc",
+    "slp",
+    "tokens"
+  ],
+  "author": "Chris Troutner <chris.troutner@gmail.com>",
+  "license": "MIT",
+  "apidoc": {
+    "title": "psffpp",
+    "url": "localhost:5000"
+  },
+  "repository": "Permissionless-Software-Foundation/psffpp",
+  "dependencies": {
+    "axios": "1.3.5",
+    "bitcore-lib-cash": "10.0.2"
+  },
+  "devDependencies": {
+    "apidoc": "0.54.0",
+    "chai": "4.3.7",
+    "husky": "8.0.3",
+    "lodash.clonedeep": "4.5.0",
+    "minimal-slp-wallet": "5.8.8",
+    "mocha": "10.2.0",
+    "nyc": "15.1.0",
+    "semantic-release": "19.0.5",
+    "sinon": "15.0.3",
+    "standard": "17.0.0"
+  },
+  "release": {
+    "publish": [
+      {
+        "path": "@semantic-release/npm",
+        "npmPublish": true
+      }
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run lint"
+    }
+  }
+}

package/test/integration/main-index-integration.js

@@ -0,0 +1,117 @@
+/*
+  Integration tests for the main library.
+*/
+
+// Global npm libraries
+const SlpWallet = require('minimal-slp-wallet')
+const assert = require('chai').assert
+
+// Local libraries
+const MultisigApproval = require('../../index')
+
+describe('#psf-multisig-approval', () => {
+  let uut
+
+  before(async () => {
+    const wallet = new SlpWallet(undefined, {
+      interface: 'consumer-api',
+      // restURL: 'https://bch-consumer-anacortes-wa-usa.fullstackcash.nl'
+      restURL: 'https://free-bch.fullstack.cash'
+    })
+    await wallet.walletInfoPromise
+
+    uut = new MultisigApproval({ wallet })
+  })
+
+  describe('#getNftHolderInfo', () => {
+    it('should get address and pubkeys for Minting Council NFT holders', async () => {
+      const result = await uut.getNftHolderInfo()
+      // console.log('result: ', result)
+
+      // Assert expected properties exist
+      assert.property(result, 'keys')
+      assert.property(result, 'keysNotFound')
+
+      // Assert that each property is an array.
+      assert.isArray(result.keys)
+      assert.isArray(result.keysNotFound)
+    })
+  })
+
+  describe('#createMultisigAddress', () => {
+    it('should generate a multisig address from token holder info', async () => {
+      const tokenHolderInfo = await uut.getNftHolderInfo()
+
+      const keys = tokenHolderInfo.keys
+
+      const result = await uut.createMultisigAddress({ keys })
+      // console.log('result: ', result)
+
+      assert.property(result, 'address')
+      assert.property(result, 'scriptHex')
+      assert.property(result, 'publicKeys')
+      assert.property(result, 'requiredSigners')
+    })
+  })
+
+  describe('#getApprovalTx', () => {
+    it('should retrieve the latest APPROVAL transaction from an address', async () => {
+      const address = 'bitcoincash:qrwe6kxhvu47ve6jvgrf2d93w0q38av7s5xm9xfehr'
+
+      const result = await uut.getApprovalTx({ address })
+      // const result = await uut.getApprovalTx({ address, filterTxids: ['a63f9fbcc901316e6e89f5a8caaad6b2ab268278b29866c6c22088bd3ab93900'] })
+      // console.log('result: ', result)
+
+      assert.equal(result.updateTxid.length, 64)
+    })
+  })
+
+  describe('#getUpdateTx', () => {
+    it('should retrieve an update transaction', async () => {
+      const txid = 'f8ea1fcd4481adfd62c6251c6a4f63f3d5ac3d5fdcc38b350d321d93254df65f'
+
+      const result = await uut.getUpdateTx({ txid })
+      // console.log('result: ', result)
+
+      // Assert returned object has expected properties
+      assert.property(result, 'cid')
+      assert.property(result, 'ts')
+      assert.property(result, 'txid')
+      assert.property(result, 'txDetails')
+    })
+  })
+
+  describe('#getCidData', () => {
+    it('should get JSON data from an IPFS gateway', async () => {
+      const cid = 'bafybeib5d6s6t3tq4lhwp2ocvz7y2ws4czgkrmhlhv5y5aeyh6bqrmsxxi'
+      const result = await uut.getCidData({ cid })
+      // console.log('result: ', result)
+
+      // Assert expected properties exist
+      assert.property(result, 'groupId')
+      assert.property(result, 'keys')
+      assert.property(result, 'walletObj')
+      assert.property(result, 'multisigAddr')
+      assert.property(result, 'p2wdbWritePrice')
+    })
+  })
+
+  describe('#validateApproval', () => {
+    it('should validate a valid approval transaction', async () => {
+      const address = 'bitcoincash:qrwe6kxhvu47ve6jvgrf2d93w0q38av7s5xm9xfehr'
+      const approvalObj = await uut.getApprovalTx({ address })
+
+      const txid = 'f8ea1fcd4481adfd62c6251c6a4f63f3d5ac3d5fdcc38b350d321d93254df65f'
+      const updateObj = await uut.getUpdateTx({ txid })
+
+      const cid = 'bafybeib5d6s6t3tq4lhwp2ocvz7y2ws4czgkrmhlhv5y5aeyh6bqrmsxxi'
+      const updateData = await uut.getCidData({ cid })
+
+      const inObj = { approvalObj, updateObj, updateData }
+      const result = await uut.validateApproval(inObj)
+      // console.log('result: ', result)
+
+      assert.equal(result, true)
+    })
+  })
+})