@wishknish/knishio-client-js 0.7.4 → 0.7.6

package/src/index.js

@@ -46,15 +46,112 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
 
+// =============================================================================
+// CORE CLASSES
+// =============================================================================
+
 import Atom from './Atom.js'
+import AtomMeta from './AtomMeta.js'
 import Molecule from './Molecule.js'
 import Wallet from './Wallet.js'
 import Meta from './Meta.js'
+import AuthToken from './AuthToken.js'
+import TokenUnit from './TokenUnit.js'
+import PolicyMeta from './PolicyMeta.js'
 import KnishIOClient from './KnishIOClient.js'
-import MutationPeering from './mutation/MutationPeering.js'
+
+// Validation
+import CheckMolecule from './libraries/CheckMolecule.js'
+
+// Utilities
+import Dot from './libraries/Dot.js'
+import Decimal from './libraries/Decimal.js'
+
+// =============================================================================
+// BASE CLASSES
+// =============================================================================
+
+import Query from './query/Query.js'
+import Mutation from './mutation/Mutation.js'
+import Response from './response/Response.js'
+
+// =============================================================================
+// QUERY CLASSES
+// =============================================================================
+
+import QueryActiveSession from './query/QueryActiveSession.js'
+import QueryAtom from './query/QueryAtom.js'
+import QueryBalance from './query/QueryBalance.js'
+import QueryBatch from './query/QueryBatch.js'
+import QueryBatchHistory from './query/QueryBatchHistory.js'
+import QueryContinuId from './query/QueryContinuId.js'
+import QueryMetaType from './query/QueryMetaType.js'
+import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
+import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
+import QueryPolicy from './query/QueryPolicy.js'
+import QueryToken from './query/QueryToken.js'
+import QueryUserActivity from './query/QueryUserActivity.js'
+import QueryWalletBundle from './query/QueryWalletBundle.js'
+import QueryWalletList from './query/QueryWalletList.js'
+
+// =============================================================================
+// MUTATION CLASSES
+// =============================================================================
+
+import MutationActiveSession from './mutation/MutationActiveSession.js'
 import MutationAppendRequest from './mutation/MutationAppendRequest.js'
-import ResponsePeering from './response/ResponsePeering.js'
+import MutationClaimShadowWallet from './mutation/MutationClaimShadowWallet.js'
+import MutationCreateIdentifier from './mutation/MutationCreateIdentifier.js'
+import MutationCreateMeta from './mutation/MutationCreateMeta.js'
+import MutationCreateRule from './mutation/MutationCreateRule.js'
+import MutationCreateToken from './mutation/MutationCreateToken.js'
+import MutationCreateWallet from './mutation/MutationCreateWallet.js'
+import MutationDepositBufferToken from './mutation/MutationDepositBufferToken.js'
+import MutationLinkIdentifier from './mutation/MutationLinkIdentifier.js'
+import MutationPeering from './mutation/MutationPeering.js'
+import MutationProposeMolecule from './mutation/MutationProposeMolecule.js'
+import MutationRequestAuthorization from './mutation/MutationRequestAuthorization.js'
+import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest.js'
+import MutationRequestTokens from './mutation/MutationRequestTokens.js'
+import MutationTransferTokens from './mutation/MutationTransferTokens.js'
+import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken.js'
+
+// =============================================================================
+// RESPONSE CLASSES
+// =============================================================================
+
+import ResponseActiveSession from './response/ResponseActiveSession.js'
 import ResponseAppendRequest from './response/ResponseAppendRequest.js'
+import ResponseAtom from './response/ResponseAtom.js'
+import ResponseAuthorizationGuest from './response/ResponseAuthorizationGuest.js'
+import ResponseBalance from './response/ResponseBalance.js'
+import ResponseClaimShadowWallet from './response/ResponseClaimShadowWallet.js'
+import ResponseContinuId from './response/ResponseContinuId.js'
+import ResponseCreateIdentifier from './response/ResponseCreateIdentifier.js'
+import ResponseCreateMeta from './response/ResponseCreateMeta.js'
+import ResponseCreateRule from './response/ResponseCreateRule.js'
+import ResponseCreateToken from './response/ResponseCreateToken.js'
+import ResponseCreateWallet from './response/ResponseCreateWallet.js'
+import ResponseLinkIdentifier from './response/ResponseLinkIdentifier.js'
+import ResponseMetaType from './response/ResponseMetaType.js'
+import ResponseMetaTypeViaAtom from './response/ResponseMetaTypeViaAtom.js'
+import ResponseMetaTypeViaMolecule from './response/ResponseMetaTypeViaMolecule.js'
+import ResponsePeering from './response/ResponsePeering.js'
+import ResponsePolicy from './response/ResponsePolicy.js'
+import ResponseProposeMolecule from './response/ResponseProposeMolecule.js'
+import ResponseQueryActiveSession from './response/ResponseQueryActiveSession.js'
+import ResponseQueryUserActivity from './response/ResponseQueryUserActivity.js'
+import ResponseRequestAuthorization from './response/ResponseRequestAuthorization.js'
+import ResponseRequestAuthorizationGuest from './response/ResponseRequestAuthorizationGuest.js'
+import ResponseRequestTokens from './response/ResponseRequestTokens.js'
+import ResponseTransferTokens from './response/ResponseTransferTokens.js'
+import ResponseWalletBundle from './response/ResponseWalletBundle.js'
+import ResponseWalletList from './response/ResponseWalletList.js'
+
+// =============================================================================
+// LIBRARY FUNCTIONS
+// =============================================================================
+
 import {
   base64ToHex,
   bufferToHexString,
@@ -63,30 +160,149 @@ import {
   hexStringToBuffer,
   hexToBase64,
   isHex,
+  isNumeric,
   randomString
 } from './libraries/strings.js'
+
 import {
+  generateBatchId,
   generateBundleHash,
   generateSecret,
   shake256
 } from './libraries/crypto.js'
 
+import {
+  chunkArray,
+  deepCloning,
+  diff,
+  intersect
+} from './libraries/array.js'
+
+// =============================================================================
+// EXCEPTION SYSTEM
+// =============================================================================
+
 export {
+  AtomIndexException,
+  AtomsMissingException,
+  AuthorizationRejectedException,
+  BalanceInsufficientException,
+  BatchIdException,
+  CodeException,
+  InvalidResponseException,
+  MetaMissingException,
+  MolecularHashMismatchException,
+  MolecularHashMissingException,
+  NegativeAmountException,
+  PolicyInvalidException,
+  SignatureMalformedException,
+  SignatureMismatchException,
+  StackableUnitAmountException,
+  StackableUnitDecimalsException,
+  TransferBalanceException,
+  TransferMalformedException,
+  TransferMismatchedException,
+  TransferRemainderException,
+  TransferToSelfException,
+  TransferUnbalancedException,
+  UnauthenticatedException,
+  WalletShadowException,
+  WrongTokenTypeException
+} from './exception/index.js'
+
+// =============================================================================
+// NAMED EXPORTS
+// =============================================================================
+
+export {
+  // Core classes
   Atom,
+  AtomMeta,
   Molecule,
   Wallet,
   Meta,
+  AuthToken,
+  TokenUnit,
+  PolicyMeta,
   KnishIOClient,
 
-  // mutations
-  MutationPeering,
+  // Validation
+  CheckMolecule,
+
+  // Utilities
+  Dot,
+  Decimal,
+
+  // Base classes
+  Query,
+  Mutation,
+  Response,
+
+  // Queries
+  QueryActiveSession,
+  QueryAtom,
+  QueryBalance,
+  QueryBatch,
+  QueryBatchHistory,
+  QueryContinuId,
+  QueryMetaType,
+  QueryMetaTypeViaAtom,
+  QueryMetaTypeViaMolecule,
+  QueryPolicy,
+  QueryToken,
+  QueryUserActivity,
+  QueryWalletBundle,
+  QueryWalletList,
+
+  // Mutations
+  MutationActiveSession,
   MutationAppendRequest,
+  MutationClaimShadowWallet,
+  MutationCreateIdentifier,
+  MutationCreateMeta,
+  MutationCreateRule,
+  MutationCreateToken,
+  MutationCreateWallet,
+  MutationDepositBufferToken,
+  MutationLinkIdentifier,
+  MutationPeering,
+  MutationProposeMolecule,
+  MutationRequestAuthorization,
+  MutationRequestAuthorizationGuest,
+  MutationRequestTokens,
+  MutationTransferTokens,
+  MutationWithdrawBufferToken,
 
-  // responses
-  ResponsePeering,
+  // Responses
+  ResponseActiveSession,
   ResponseAppendRequest,
+  ResponseAtom,
+  ResponseAuthorizationGuest,
+  ResponseBalance,
+  ResponseClaimShadowWallet,
+  ResponseContinuId,
+  ResponseCreateIdentifier,
+  ResponseCreateMeta,
+  ResponseCreateRule,
+  ResponseCreateToken,
+  ResponseCreateWallet,
+  ResponseLinkIdentifier,
+  ResponseMetaType,
+  ResponseMetaTypeViaAtom,
+  ResponseMetaTypeViaMolecule,
+  ResponsePeering,
+  ResponsePolicy,
+  ResponseProposeMolecule,
+  ResponseQueryActiveSession,
+  ResponseQueryUserActivity,
+  ResponseRequestAuthorization,
+  ResponseRequestAuthorizationGuest,
+  ResponseRequestTokens,
+  ResponseTransferTokens,
+  ResponseWalletBundle,
+  ResponseWalletList,
 
-  // strings
+  // String utilities
   chunkSubstr,
   base64ToHex,
   bufferToHexString,
@@ -94,10 +310,18 @@ export {
   hexStringToBuffer,
   hexToBase64,
   isHex,
+  isNumeric,
   randomString,
 
-  // crypto
+  // Crypto utilities
   generateSecret,
   generateBundleHash,
-  shake256
+  generateBatchId,
+  shake256,
+
+  // Array utilities
+  chunkArray,
+  deepCloning,
+  diff,
+  intersect
 }

package/src/libraries/CheckMolecule.js

@@ -63,6 +63,7 @@ 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 {
@@ -119,6 +120,8 @@ export default class CheckMolecule {
       this.isotopeR() &&
       this.isotopeP() &&
       this.isotopeA() &&
+      this.isotopeB() &&
+      this.isotopeF() &&
       this.isotopeV(senderWallet)
   }
 
@@ -384,6 +387,104 @@ export default class CheckMolecule {
     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
@@ -396,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) {
@@ -409,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
     }
 
@@ -454,8 +565,8 @@ export default class CheckMolecule {
       }
     }
 
-    // All atoms must sum to zero for a balanced transaction
-    if (sum !== 0) {
+    // V-only conservation: all V atoms must sum to zero (skip for B/F cross-isotope)
+    if (!hasCrossIsotope && sum !== 0) {
       throw new TransferUnbalancedException()
     }
 
@@ -467,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) {
@@ -475,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) {
@@ -578,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/query/QueryContinuId.js

@@ -75,6 +75,14 @@ export default class QueryContinuId extends Query {
     }`
   }
 
+  /**
+   * Force network-only for ContinuID queries to prevent URQL cache from
+   * returning stale wallet positions after mutations advance the ContinuID chain
+   */
+  createQueryContext () {
+    return { requestPolicy: 'network-only' }
+  }
+
   /**
    * Returns a Response object
    *