@wishknish/knishio-client-js 0.6.4 → 0.7.5

package/src/libraries/CheckMolecule.js

@@ -45,32 +45,33 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
-import AtomIndexException from './../exception/AtomIndexException'
-import AtomsMissingException from './../exception/AtomsMissingException'
-import MolecularHashMismatchException from './../exception/MolecularHashMismatchException'
-import MolecularHashMissingException from './../exception/MolecularHashMissingException'
-import PolicyInvalidException from './../exception/PolicyInvalidException'
-import SignatureMalformedException from './../exception/SignatureMalformedException'
-import SignatureMismatchException from './../exception/SignatureMismatchException'
-import TransferBalanceException from './../exception/TransferBalanceException'
-import TransferMalformedException from './../exception/TransferMalformedException'
-import TransferMismatchedException from './../exception/TransferMismatchedException'
-import TransferRemainderException from './../exception/TransferRemainderException'
-import TransferToSelfException from './../exception/TransferToSelfException'
-import TransferUnbalancedException from './../exception/TransferUnbalancedException'
-import MetaMissingException from './../exception/MetaMissingException'
-import WrongTokenTypeException from './../exception/WrongTokenTypeException'
-import BatchIdException from './../exception/BatchIdException'
-import Atom from './../Atom'
-import Meta from './../Meta'
-import Wallet from './../Wallet'
-import Rule from '../instance/Rules/Rule'
+import AtomIndexException from './../exception/AtomIndexException.js'
+import AtomsMissingException from './../exception/AtomsMissingException.js'
+import MolecularHashMismatchException from './../exception/MolecularHashMismatchException.js'
+import MolecularHashMissingException from './../exception/MolecularHashMissingException.js'
+import PolicyInvalidException from './../exception/PolicyInvalidException.js'
+import SignatureMalformedException from './../exception/SignatureMalformedException.js'
+import SignatureMismatchException from './../exception/SignatureMismatchException.js'
+import TransferBalanceException from './../exception/TransferBalanceException.js'
+import TransferMalformedException from './../exception/TransferMalformedException.js'
+import TransferMismatchedException from './../exception/TransferMismatchedException.js'
+import TransferRemainderException from './../exception/TransferRemainderException.js'
+import TransferToSelfException from './../exception/TransferToSelfException.js'
+import TransferUnbalancedException from './../exception/TransferUnbalancedException.js'
+import MetaMissingException from './../exception/MetaMissingException.js'
+import WrongTokenTypeException from './../exception/WrongTokenTypeException.js'
+import BatchIdException from './../exception/BatchIdException.js'
+import Atom from './../Atom.js'
+import Meta from './../Meta.js'
+import Molecule from './../Molecule.js'
+import Wallet from './../Wallet.js'
+import Rule from '../instance/Rules/Rule.js'
 import {
   base64ToHex,
   chunkSubstr
-} from './strings'
+} from './strings.js'
 import JsSHA from 'jssha'
-import Dot from './../libraries/Dot'
+import Dot from './../libraries/Dot.js'
 
 /**
  *
@@ -117,6 +118,10 @@ export default class CheckMolecule {
       this.isotopeU() &&
       this.isotopeI() &&
       this.isotopeR() &&
+      this.isotopeP() &&
+      this.isotopeA() &&
+      this.isotopeB() &&
+      this.isotopeF() &&
       this.isotopeV(senderWallet)
   }
 
@@ -332,6 +337,154 @@ export default class CheckMolecule {
     return true
   }
 
+  /**
+   * Validates P-isotope (Peering) atoms
+   *
+   * @returns {boolean}
+   */
+  isotopeP () {
+    for (const atom of this.molecule.getIsotopes('P')) {
+      if (atom.token !== 'USER') {
+        throw new WrongTokenTypeException(`Check::isotopeP() - "${ atom.token }" is not a valid Token slug for "${ atom.isotope }" isotope Atoms!`)
+      }
+
+      const metas = atom.aggregatedMeta()
+
+      if (!Object.prototype.hasOwnProperty.call(metas, 'peerHost') || !metas.peerHost) {
+        throw new MetaMissingException('Check::isotopeP() - Required meta field "peerHost" is missing!')
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Validates A-isotope (Append Request) atoms
+   *
+   * @returns {boolean}
+   */
+  isotopeA () {
+    for (const atom of this.molecule.getIsotopes('A')) {
+      if (atom.token !== 'USER') {
+        throw new WrongTokenTypeException(`Check::isotopeA() - "${ atom.token }" is not a valid Token slug for "${ atom.isotope }" isotope Atoms!`)
+      }
+
+      if (!atom.metaType) {
+        throw new MetaMissingException('Check::isotopeA() - Required field "metaType" is missing!')
+      }
+
+      if (!atom.metaId) {
+        throw new MetaMissingException('Check::isotopeA() - Required field "metaId" is missing!')
+      }
+
+      const metas = atom.aggregatedMeta()
+
+      if (!Object.prototype.hasOwnProperty.call(metas, 'action') || !metas.action) {
+        throw new MetaMissingException('Check::isotopeA() - Required meta field "action" is missing!')
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Validates B-isotope (Buffer/Exchange) atoms
+   *
+   * @returns {boolean}
+   */
+  isotopeB () {
+    const isotopeB = this.molecule.getIsotopes('B')
+
+    if (isotopeB.length === 0) {
+      return true
+    }
+
+    for (const atom of isotopeB) {
+      // B atoms must reference a wallet bundle
+      if (!atom.metaType || atom.metaType !== 'walletBundle') {
+        throw new MetaMissingException('Check::isotopeB() - B-isotope atoms must have metaType "walletBundle"!')
+      }
+
+      if (!atom.metaId) {
+        throw new MetaMissingException('Check::isotopeB() - B-isotope atoms must have a metaId!')
+      }
+
+      // Value must be parseable as a number
+      const value = Number(atom.value)
+      if (Number.isNaN(value)) {
+        throw new TransferMalformedException('Check::isotopeB() - B-isotope atom value is not a valid number!')
+      }
+    }
+
+    // V+B balance conservation: sum of all V and B atom values must equal zero
+    const vAtoms = this.molecule.getIsotopes('V')
+    if (vAtoms.length > 0) {
+      let sum = 0
+      for (const atom of [...vAtoms, ...isotopeB]) {
+        const value = Number(atom.value)
+        if (!Number.isNaN(value)) {
+          sum += value
+        }
+      }
+      if (sum !== 0) {
+        throw new TransferUnbalancedException('Check::isotopeB() - V+B atom values do not balance to zero!')
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Validates F-isotope (Fusion/NFT) atoms
+   *
+   * @returns {boolean}
+   */
+  isotopeF () {
+    const isotopeF = this.molecule.getIsotopes('F')
+
+    if (isotopeF.length === 0) {
+      return true
+    }
+
+    for (const atom of isotopeF) {
+      // F atoms must reference a wallet bundle
+      if (!atom.metaType || atom.metaType !== 'walletBundle') {
+        throw new MetaMissingException('Check::isotopeF() - F-isotope atoms must have metaType "walletBundle"!')
+      }
+
+      if (!atom.metaId) {
+        throw new MetaMissingException('Check::isotopeF() - F-isotope atoms must have a metaId!')
+      }
+
+      // Value must be parseable
+      const value = Number(atom.value)
+      if (Number.isNaN(value)) {
+        throw new TransferMalformedException('Check::isotopeF() - F-isotope atom value is not a valid number!')
+      }
+
+      if (value < 0) {
+        throw new TransferMalformedException('Check::isotopeF() - F-isotope atom value must not be negative!')
+      }
+    }
+
+    // V+F balance conservation: sum of all V and F atom values must equal zero
+    const vAtoms = this.molecule.getIsotopes('V')
+    if (vAtoms.length > 0) {
+      let sum = 0
+      for (const atom of [...vAtoms, ...isotopeF]) {
+        const value = Number(atom.value)
+        if (!Number.isNaN(value)) {
+          sum += value
+        }
+      }
+      if (sum !== 0) {
+        throw new TransferUnbalancedException('Check::isotopeF() - V+F atom values do not balance to zero!')
+      }
+    }
+
+    return true
+  }
+
   /**
    *
    * @param senderWallet
@@ -344,9 +497,14 @@ export default class CheckMolecule {
       return true
     }
 
+    // When B or F atoms are present, cross-isotope conservation is validated
+    // by isotopeB()/isotopeF() — skip V-only conservation check
+    const hasCrossIsotope = this.molecule.getIsotopes('B').length > 0 ||
+      this.molecule.getIsotopes('F').length > 0
+
     const firstAtom = this.molecule.atoms[0]
 
-    if (firstAtom.isotope === 'V' && isotopeV.length === 2) {
+    if (!hasCrossIsotope && firstAtom.isotope === 'V' && isotopeV.length === 2) {
       const endAtom = isotopeV[isotopeV.length - 1]
 
       if (firstAtom.token !== endAtom.token) {
@@ -357,6 +515,11 @@ export default class CheckMolecule {
         throw new TransferMalformedException()
       }
 
+      // Conservation check for 2-atom transfers
+      if ((Number(firstAtom.value) + Number(endAtom.value)) !== 0) {
+        throw new TransferUnbalancedException()
+      }
+
       return true
     }
 
@@ -402,8 +565,8 @@ export default class CheckMolecule {
       }
     }
 
-    // Does the total sum of all atoms equal the remainder atom's value? (all other atoms must add up to zero)
-    if (sum !== value) {
+    // V-only conservation: all V atoms must sum to zero (skip for B/F cross-isotope)
+    if (!hasCrossIsotope && sum !== 0) {
       throw new TransferUnbalancedException()
     }
 
@@ -415,7 +578,7 @@ export default class CheckMolecule {
         throw new TypeError('Invalid isotope "V" values')
       }
 
-      const remainder = senderWallet.balance + value
+      const remainder = Number(senderWallet.balance) + value
 
       // Is there enough balance to send?
       if (remainder < 0) {
@@ -423,7 +586,8 @@ export default class CheckMolecule {
       }
 
       // Does the remainder match what should be there in the source wallet, if provided?
-      if (remainder !== sum) {
+      // Skip for cross-isotope (B/F) — conservation is validated by isotopeB()/isotopeF()
+      if (!hasCrossIsotope && remainder !== sum) {
         throw new TransferRemainderException()
       }
     } else if (value !== 0) {
@@ -526,4 +690,98 @@ export default class CheckMolecule {
     // Looks like we passed all the tests!
     return true
   }
+
+  /**
+   * Converts server-side molecule data (from GraphQL meta query responses)
+   * into a Molecule instance suitable for verification via CheckMolecule.
+   *
+   * Handles field mapping differences between server and client:
+   * - tokenSlug → token
+   * - metasJson (JSON string) → meta (array of {key, value})
+   * - bundleHash → bundle
+   *
+   * @param {object} serverData - Molecule data from GraphQL response
+   * @param {string} serverData.molecularHash
+   * @param {string} serverData.bundleHash
+   * @param {string|null} serverData.cellSlug
+   * @param {string|null} serverData.status
+   * @param {string|null} serverData.createdAt
+   * @param {array} serverData.atoms - Array of server-format atom objects
+   * @return {Molecule}
+   */
+  static fromServerData ({
+    molecularHash,
+    bundleHash,
+    cellSlug = null,
+    status = null,
+    createdAt = null,
+    atoms = []
+  }) {
+    const mappedAtoms = atoms.map(serverAtom => {
+      let meta = []
+      if (serverAtom.metasJson) {
+        try {
+          const parsed = JSON.parse(serverAtom.metasJson)
+          if (Array.isArray(parsed)) {
+            // Already in [{key, value}] format
+            meta = parsed
+          } else if (parsed && typeof parsed === 'object') {
+            // Object format {key1: val1, key2: val2} — convert to [{key, value}] pairs
+            meta = Object.entries(parsed).map(([key, value]) => ({ key, value }))
+          }
+        } catch (e) {
+          meta = []
+        }
+      }
+
+      return {
+        position: serverAtom.position || null,
+        walletAddress: serverAtom.walletAddress || null,
+        isotope: serverAtom.isotope || null,
+        token: serverAtom.tokenSlug || serverAtom.token || null,
+        value: serverAtom.value != null ? String(serverAtom.value) : null,
+        batchId: serverAtom.batchId || null,
+        metaType: serverAtom.metaType || null,
+        metaId: serverAtom.metaId || null,
+        meta,
+        index: serverAtom.index != null ? serverAtom.index : null,
+        otsFragment: serverAtom.otsFragment || null,
+        createdAt: serverAtom.createdAt || null
+      }
+    })
+
+    return Molecule.fromJSON({
+      molecularHash,
+      bundle: bundleHash,
+      cellSlug,
+      status,
+      createdAt,
+      atoms: mappedAtoms
+    })
+  }
+
+  /**
+   * Verifies a molecule reconstructed from server-side GraphQL data.
+   * Returns an object with verification result and any error details.
+   *
+   * @param {object} moleculeData - Server molecule data (same format as fromServerData)
+   * @return {{ molecularHash: string, verified: boolean, error: string|null }}
+   */
+  static verifyFromServerData (moleculeData) {
+    try {
+      const molecule = CheckMolecule.fromServerData(moleculeData)
+      new CheckMolecule(molecule).verify()
+      return {
+        molecularHash: moleculeData.molecularHash,
+        verified: true,
+        error: null
+      }
+    } catch (error) {
+      return {
+        molecularHash: moleculeData.molecularHash || null,
+        verified: false,
+        error: error.message || String(error)
+      }
+    }
+  }
 }

package/src/libraries/crypto.js

@@ -45,7 +45,7 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
-import { randomString } from './strings'
+import { randomString } from './strings.js'
 import JsSHA from 'jssha'
 
 /**
@@ -60,6 +60,7 @@ export function generateSecret (seed = null, length = 2048) {
   if (seed) {
     const sponge = new JsSHA('SHAKE256', 'TEXT')
     sponge.update(seed)
+    // Fix: outputLen is in BITS, so for 'length' hex chars (length/2 bytes), we need length*2 bits
     return sponge.getHash('HEX', { outputLen: length * 2 })
   } else {
     return randomString(length)
@@ -76,7 +77,20 @@ export function generateSecret (seed = null, length = 2048) {
 export function generateBundleHash (secret, source = null) {
   const sponge = new JsSHA('SHAKE256', 'TEXT')
   sponge.update(secret)
-  return sponge.getHash('HEX', { outputLen: 256 })
+  return sponge.getHash('HEX', { outputLen: 64 * 4 }) // 64 bytes = 512 bits
+}
+
+/**
+ * SHAKE256 hash function
+ *
+ * @param {string} input - The input string to hash
+ * @param {number} outputLength - The desired output length in bits
+ * @return {string} The hex-encoded hash
+ */
+export function shake256 (input, outputLength) {
+  const sponge = new JsSHA('SHAKE256', 'TEXT')
+  sponge.update(input)
+  return sponge.getHash('HEX', { outputLen: outputLength })
 }
 
 /**

package/src/libraries/strings.js

@@ -1,4 +1,4 @@
-import Hex from './Hex'
+import Hex from './Hex.js'
 
 if (!String.prototype.trim) {
   String.prototype.trim = function () {

package/src/libraries/urql/UrqlClientWrapper.js

@@ -47,7 +47,9 @@ class UrqlClientWrapper {
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        }
+        },
+        // Add 60 second timeout for debugging
+        signal: AbortSignal.timeout(60000)
       })
     })
   }

package/src/mutation/Mutation.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import Query from '../query/Query'
-import Response from '../response/Response'
+import Query from '../query/Query.js'
+import Response from '../response/Response.js'
 
 /**
  * Base class used to construct various GraphQL mutations

package/src/mutation/MutationActiveSession.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import Mutation from '../mutation/Mutation'
-import ResponseActiveSession from '../response/ResponseActiveSession'
+import Mutation from '../mutation/Mutation.js'
+import ResponseActiveSession from '../response/ResponseActiveSession.js'
 import { gql } from '@urql/core'
 
 /**

package/src/mutation/MutationAppendRequest.js

@@ -0,0 +1,91 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseAppendRequest from '../response/ResponseAppendRequest.js'
+
+/**
+ * Mutation for submitting an append request via the A-isotope
+ */
+export default class MutationAppendRequest extends MutationProposeMolecule {
+  /**
+   * Fills a molecule with an A-isotope append request atom
+   *
+   * @param {string} metaType
+   * @param {string} metaId
+   * @param {string} action
+   * @param {object} meta
+   */
+  fillMolecule ({
+    metaType,
+    metaId,
+    action,
+    meta = {}
+  }) {
+    this.$__molecule.initAppendRequest({
+      metaType,
+      metaId,
+      action,
+      meta
+    })
+    this.$__molecule.sign({})
+    this.$__molecule.check()
+  }
+
+  /**
+   * Builds a new Response object from a JSON string
+   *
+   * @param {object} json
+   * @return {ResponseAppendRequest}
+   */
+  createResponse (json) {
+    return new ResponseAppendRequest({
+      query: this,
+      json
+    })
+  }
+}

package/src/mutation/MutationClaimShadowWallet.js

@@ -45,9 +45,9 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import Wallet from '../Wallet'
-import ResponseClaimShadowWallet from '../response/ResponseClaimShadowWallet'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import Wallet from '../Wallet.js'
+import ResponseClaimShadowWallet from '../response/ResponseClaimShadowWallet.js'
 
 /**
  * Mutation for claiming a Shadow Wallet

package/src/mutation/MutationCreateIdentifier.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import ResponseCreateIdentifier from '../response/ResponseCreateIdentifier'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseCreateIdentifier from '../response/ResponseCreateIdentifier.js'
 
 /**
  * Query for creating a new Identifier

package/src/mutation/MutationCreateMeta.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import ResponseCreateMeta from '../response/ResponseCreateMeta'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseCreateMeta from '../response/ResponseCreateMeta.js'
 
 /**
  * Query for creating new Meta attached to some MetaType

package/src/mutation/MutationCreateRule.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import ResponseCreateRule from '../response/ResponseCreateRule'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseCreateRule from '../response/ResponseCreateRule.js'
 
 /**
  * Query for creating new Meta attached to some MetaType

package/src/mutation/MutationCreateToken.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import ResponseCreateToken from '../response/ResponseCreateToken'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseCreateToken from '../response/ResponseCreateToken.js'
 
 /**
  * Query for creating new Tokens

package/src/mutation/MutationCreateWallet.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
-import ResponseCreateWallet from '../response/ResponseCreateWallet'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
+import ResponseCreateWallet from '../response/ResponseCreateWallet.js'
 
 /**
  * Query for creating new Wallets

package/src/mutation/MutationDepositBufferToken.js

@@ -45,7 +45,7 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import MutationProposeMolecule from './MutationProposeMolecule'
+import MutationProposeMolecule from './MutationProposeMolecule.js'
 
 /**
  *

package/src/mutation/MutationLinkIdentifier.js

@@ -45,8 +45,8 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
 */
-import Mutation from '../mutation/Mutation'
-import ResponseLinkIdentifier from '../response/ResponseLinkIdentifier'
+import Mutation from '../mutation/Mutation.js'
+import ResponseLinkIdentifier from '../response/ResponseLinkIdentifier.js'
 import { gql } from '@urql/core'
 
 /**