@wishknish/knishio-client-js 0.7.4 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",

package/src/KnishIOClient.js

@@ -54,6 +54,7 @@ import {
 } from './libraries/crypto.js'
 import Molecule from './Molecule.js'
 import Wallet from './Wallet.js'
+import TokenUnit from './TokenUnit.js'
 import AuthToken from './AuthToken.js'
 import QueryContinuId from './query/QueryContinuId.js'
 import QueryWalletBundle from './query/QueryWalletBundle.js'
@@ -93,6 +94,7 @@ import AuthorizationRejectedException from './exception/AuthorizationRejectedExc
 import QueryAtom from './query/QueryAtom.js'
 import QueryPolicy from './query/QueryPolicy.js'
 import QueryMetaTypeViaAtom from './query/QueryMetaTypeViaAtom.js'
+import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
 import MutationCreateRule from './mutation/MutationCreateRule.js'
 import MutationDepositBufferToken from './mutation/MutationDepositBufferToken.js'
 import MutationWithdrawBufferToken from './mutation/MutationWithdrawBufferToken.js'
@@ -777,10 +779,11 @@ export default class KnishIOClient {
    * @param {string|null} count
    * @param {string|null} countBy
    * @param {boolean} throughAtom
+   * @param {boolean} throughMolecule
    * @param {array|null} values
    * @param {array|null} keys
    * @param {array|null} atomValues
-   * @return {Promise<ResponseMetaType>}
+   * @return {Promise<ResponseMetaType|ResponseMetaTypeViaAtom|ResponseMetaTypeViaMolecule>}
    */
   queryMeta ({
     metaType,
@@ -794,6 +797,7 @@ export default class KnishIOClient {
     count = null,
     countBy = null,
     throughAtom = true,
+    throughMolecule = false,
     values = null,
     keys = null,
     atomValues = null
@@ -803,7 +807,26 @@ export default class KnishIOClient {
     let query
     let variables
 
-    if (throughAtom) {
+    if (throughMolecule) {
+      /**
+       * @type {QueryMetaTypeViaMolecule}
+       */
+      query = this.createQuery(QueryMetaTypeViaMolecule)
+      variables = QueryMetaTypeViaMolecule.createVariables({
+        metaType,
+        metaId,
+        key,
+        value,
+        latest,
+        filter,
+        queryArgs,
+        countBy,
+        values,
+        keys,
+        atomValues,
+        cellSlug: this.getCellSlug()
+      })
+    } else if (throughAtom) {
       /**
        * @type {QueryMetaTypeViaAtom}
        */
@@ -844,6 +867,23 @@ export default class KnishIOClient {
     return this.executeQuery(query, variables)
   }
 
+  /**
+   * Queries meta assets and verifies cryptographic integrity of associated molecules.
+   * Returns the same response as queryMeta(), with an additional `integrity` field on the payload
+   * containing verification results for each molecule.
+   *
+   * @param {object} params - Same parameters as queryMeta()
+   * @return {Promise<ResponseMetaType|ResponseMetaTypeViaAtom|ResponseMetaTypeViaMolecule>}
+   */
+  async queryMetaVerified (params) {
+    const response = await this.queryMeta(params)
+    const payload = response.payload()
+    if (payload) {
+      payload.integrity = response.verifyIntegrity()
+    }
+    return response
+  }
+
   /**
    * Query batch to get cascading meta instances by batchID
    *
@@ -2022,6 +2062,11 @@ export default class KnishIOClient {
     // Split token units (fused)
     sourceWallet.splitUnits(fusedTokenUnitIds, remainderWallet)
 
+    // Coerce string newTokenUnit to TokenUnit object
+    if (typeof newTokenUnit === 'string') {
+      newTokenUnit = new TokenUnit(newTokenUnit, newTokenUnit, {})
+    }
+
     // Set recipient new fused token unit
     newTokenUnit.metas.fusedTokenUnits = sourceWallet.getTokenUnitsData()
     recipientWallet.tokenUnits = [newTokenUnit]

package/src/Molecule.js

@@ -96,6 +96,7 @@ export default class Molecule {
     this.bundle = bundle
     this.sourceWallet = sourceWallet
     this.atoms = []
+    this.parentHashes = []
     if (version !== null && Object.prototype.hasOwnProperty.call(versions, version)) {
       this.version = String(version)
     }
@@ -112,6 +113,17 @@ export default class Molecule {
     }
   }
 
+  /**
+   * Sets parent molecular hashes for DAG linkage
+   *
+   * @param {string[]} hashes - Array of parent molecular hash strings
+   * @return {Molecule} this instance for chaining
+   */
+  withParentHashes (hashes) {
+    this.parentHashes = Array.isArray(hashes) ? [...hashes] : []
+    return this
+  }
+
   /**
    * Returns the cell slug delimiter
    *
@@ -327,20 +339,21 @@ export default class Molecule {
       })
     }
 
-    // Build ContinuID chain metadata (matches Rust SDK GAP-07-002)
+    // ContinuID metadata for chain integrity validation (matching Rust SDK GAP-07-002).
+    // These are atom meta fields (not core fields), so they don't affect molecular hash.
     const continuIdMeta = {}
 
-    // previousPosition: source wallet position being consumed
+    // previousPosition: the source wallet's position being consumed
     if (this.sourceWallet && this.sourceWallet.position) {
       continuIdMeta.previousPosition = this.sourceWallet.position
     }
 
-    // pubkey: remainder wallet's public key for chain verification
+    // pubkey: ML-KEM public key for encrypted communication
     if (this.remainderWallet.pubkey) {
       continuIdMeta.pubkey = this.remainderWallet.pubkey
     }
 
-    // characters: encoding format
+    // characters: encoding format for the wallet
     if (this.remainderWallet.characters) {
       continuIdMeta.characters = this.remainderWallet.characters
     }
@@ -493,28 +506,28 @@ export default class Molecule {
       for (const unit of units) {
         this.remainderWallet.tokenUnits.push(unit)
       }
-      this.remainderWallet.balance = this.remainderWallet.tokenUnits.length
+      this.remainderWallet.balance = String(this.remainderWallet.tokenUnits.length)
 
       // Override first atom's token units to replenish values
       this.sourceWallet.tokenUnits = units
-      this.sourceWallet.balance = this.sourceWallet.tokenUnits.length
+      this.sourceWallet.balance = String(this.sourceWallet.tokenUnits.length)
     } else {
       // Update wallet's balances
-      this.remainderWallet.balance = this.sourceWallet.balance + amount
-      this.sourceWallet.balance = amount
+      this.remainderWallet.balance = String(Number(this.sourceWallet.balance) + amount)
+      this.sourceWallet.balance = String(amount)
     }
 
     // Initializing a new Atom to remove tokens from source
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.sourceWallet,
-      value: this.sourceWallet.balance
+      value: Number(this.sourceWallet.balance)
     }))
 
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.remainderWallet,
-      value: this.remainderWallet.balance,
+      value: Number(this.remainderWallet.balance),
       metaType: 'walletBundle',
       metaId: this.remainderWallet.bundle
     }))
@@ -564,6 +577,60 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Creates a stackable V-isotope transfer with 3 atoms:
+   * source debit, recipient credit, remainder.
+   * Propagates batchId from source wallet.
+   *
+   * @param {Wallet} recipientWallet - wallet receiving the tokens
+   * @param {number} amount - amount to transfer
+   * @return {Molecule}
+   */
+  addStackableTransfer ({
+    recipientWallet,
+    amount
+  }) {
+    if (amount <= 0) {
+      throw new NegativeAmountException('Molecule::addStackableTransfer() - Amount must be positive!')
+    }
+
+    if (this.sourceWallet.balance - amount < 0) {
+      throw new BalanceInsufficientException()
+    }
+
+    const batchId = this.sourceWallet.batchId || generateBatchId({})
+
+    // Source debit atom
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: -amount,
+      batchId
+    }))
+
+    // Recipient credit atom
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: recipientWallet,
+      value: amount,
+      metaType: 'walletBundle',
+      metaId: recipientWallet.bundle,
+      batchId: generateBatchId({})
+    }))
+
+    // Remainder atom
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet,
+      value: this.sourceWallet.balance - amount,
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet.bundle,
+      batchId
+    }))
+
+    return this
+  }
+
   /**
    *
    * @param amount
@@ -1053,6 +1120,20 @@ export default class Molecule {
     return lastPosition
   }
 
+  /**
+   * Synchronous signing — identical to sign() since all operations are CPU-bound.
+   * Provided for API parity with Rust SDK's sign_sync().
+   *
+   * @param {object} options
+   * @param {string|null} options.bundle
+   * @param {boolean} options.anonymous
+   * @param {boolean} options.compressed
+   * @return {string|null}
+   */
+  signSync (options = {}) {
+    return this.sign(options)
+  }
+
   /**
    * Returns the base cell slug portion
    *
@@ -1096,6 +1177,12 @@ export default class Molecule {
         }))
       };
 
+      // Parent molecular hashes for DAG linkage (only include when non-empty
+      // to maintain backward compatibility with servers that don't support it)
+      if (this.parentHashes && this.parentHashes.length > 0) {
+        serialized.parentHashes = this.parentHashes
+      }
+
       // Extended context for Rust validator and local validation
       if (includeValidationContext) {
         serialized.cellSlugOrigin = this.cellSlugOrigin
@@ -1106,7 +1193,7 @@ export default class Molecule {
             address: this.sourceWallet.address,
             position: this.sourceWallet.position,
             token: this.sourceWallet.token,
-            balance: this.sourceWallet.balance || 0,
+            balance: this.sourceWallet.balance || '0',
             bundle: this.sourceWallet.bundle,
             batchId: this.sourceWallet.batchId || null,
             characters: this.sourceWallet.characters || 'BASE64',
@@ -1122,7 +1209,7 @@ export default class Molecule {
             address: this.remainderWallet.address,
             position: this.remainderWallet.position,
             token: this.remainderWallet.token,
-            balance: this.remainderWallet.balance || 0,
+            balance: this.remainderWallet.balance || '0',
             bundle: this.remainderWallet.bundle,
             batchId: this.remainderWallet.batchId || null,
             characters: this.remainderWallet.characters || 'BASE64',
@@ -1184,6 +1271,7 @@ export default class Molecule {
       molecule.molecularHash = data.molecularHash;
       molecule.createdAt = data.createdAt || String(+new Date());
       molecule.cellSlugOrigin = data.cellSlugOrigin;
+      molecule.parentHashes = Array.isArray(data.parentHashes) ? [...data.parentHashes] : [];
 
       // Reconstruct atoms array with proper Atom instances
       if (Array.isArray(data.atoms)) {
@@ -1210,7 +1298,7 @@ export default class Molecule {
           });
 
           // Set additional properties for validation context
-          molecule.sourceWallet.balance = data.sourceWallet.balance || 0;
+          molecule.sourceWallet.balance = String(data.sourceWallet.balance != null ? data.sourceWallet.balance : 0);
           molecule.sourceWallet.address = data.sourceWallet.address;
           if (data.sourceWallet.pubkey) {
             molecule.sourceWallet.pubkey = data.sourceWallet.pubkey;
@@ -1232,7 +1320,7 @@ export default class Molecule {
           });
 
           // Set additional properties for validation context
-          molecule.remainderWallet.balance = data.remainderWallet.balance || 0;
+          molecule.remainderWallet.balance = String(data.remainderWallet.balance != null ? data.remainderWallet.balance : 0);
           molecule.remainderWallet.address = data.remainderWallet.address;
           if (data.remainderWallet.pubkey) {
             molecule.remainderWallet.pubkey = data.remainderWallet.pubkey;

package/src/Wallet.js

@@ -87,7 +87,7 @@ export default class Wallet {
     characters = null
   }) {
     this.token = token
-    this.balance = 0
+    this.balance = '0'
     this.molecules = {}
 
     // Empty values
@@ -208,6 +208,13 @@ export default class Wallet {
     token,
     position
   }) {
+    if (!secret) {
+      throw new WalletCredentialException('Wallet::generateKey() - Secret is required!')
+    }
+    if (!position) {
+      throw new WalletCredentialException('Wallet::generateKey() - Position is required!')
+    }
+
     // Normalize non-hex secret via SHAKE256 (matching Rust/Kotlin behavior)
     const secretHex = isHex(secret) ? secret : shake256(secret, 1024)
     // Normalize non-hex position via SHAKE256
@@ -301,6 +308,46 @@ export default class Wallet {
     return new Uint8Array(binaryString.length).map((_, i) => binaryString.charCodeAt(i))
   }
 
+  /**
+   * Returns balance as a Number for arithmetic operations.
+   * WARNING: Precision loss for values > 2^53.
+   *
+   * @return {number}
+   */
+  balanceAsNumber () {
+    return Number(this.balance)
+  }
+
+  /**
+   * Returns balance as a BigInt for precision-safe integer arithmetic.
+   * Truncates any fractional component.
+   *
+   * @return {bigint}
+   */
+  balanceAsBigInt () {
+    const str = String(this.balance)
+    const intPart = str.includes('.') ? str.split('.')[0] : str
+    return BigInt(intPart || '0')
+  }
+
+  /**
+   * Sets balance from a BigInt value
+   *
+   * @param {bigint} value
+   */
+  setBalanceBigInt (value) {
+    this.balance = value.toString()
+  }
+
+  /**
+   * Sets balance from a Number value, storing as String
+   *
+   * @param {number} value
+   */
+  setBalanceNumber (value) {
+    this.balance = String(value)
+  }
+
   /**
    *
    * @returns {*[]}

package/src/index.js

@@ -53,8 +53,10 @@ import Meta from './Meta.js'
 import KnishIOClient from './KnishIOClient.js'
 import MutationPeering from './mutation/MutationPeering.js'
 import MutationAppendRequest from './mutation/MutationAppendRequest.js'
+import QueryMetaTypeViaMolecule from './query/QueryMetaTypeViaMolecule.js'
 import ResponsePeering from './response/ResponsePeering.js'
 import ResponseAppendRequest from './response/ResponseAppendRequest.js'
+import ResponseMetaTypeViaMolecule from './response/ResponseMetaTypeViaMolecule.js'
 import {
   base64ToHex,
   bufferToHexString,
@@ -78,6 +80,9 @@ export {
   Meta,
   KnishIOClient,
 
+  // queries
+  QueryMetaTypeViaMolecule,
+
   // mutations
   MutationPeering,
   MutationAppendRequest,
@@ -85,6 +90,7 @@ export {
   // responses
   ResponsePeering,
   ResponseAppendRequest,
+  ResponseMetaTypeViaMolecule,
 
   // strings
   chunkSubstr,