@wishknish/knishio-client-js 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "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'
@@ -72,6 +73,7 @@ import MutationClaimShadowWallet from './mutation/MutationClaimShadowWallet.js'
 import MutationCreateMeta from './mutation/MutationCreateMeta.js'
 import MutationPeering from './mutation/MutationPeering.js'
 import MutationAppendRequest from './mutation/MutationAppendRequest.js'
+import MutationLinkIdentifier from './mutation/MutationLinkIdentifier.js'
 import MutationCreateWallet from './mutation/MutationCreateWallet.js'
 import MutationRequestAuthorizationGuest from './mutation/MutationRequestAuthorizationGuest.js'
 import TransferBalanceException from './exception/TransferBalanceException.js'
@@ -93,6 +95,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 +780,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 +798,7 @@ export default class KnishIOClient {
     count = null,
     countBy = null,
     throughAtom = true,
+    throughMolecule = false,
     values = null,
     keys = null,
     atomValues = null
@@ -803,7 +808,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 +868,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
    *
@@ -1208,8 +1249,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
         mutationClass: MutationCreateRule,
         molecule: await this.createMolecule({
-          secret: this.getSecret(),
-          sourceWallet: await this.getSourceWallet()
+          secret: this.getSecret()
         })
       }
     )
@@ -1245,8 +1285,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
         mutationClass: MutationCreateMeta,
         molecule: await this.createMolecule({
-          secret: this.getSecret(),
-          sourceWallet: await this.getSourceWallet()
+          secret: this.getSecret()
         })
       }
     )
@@ -1278,8 +1317,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
       mutationClass: MutationPeering,
       molecule: await this.createMolecule({
-        secret: this.getSecret(),
-        sourceWallet: await this.getSourceWallet()
+        secret: this.getSecret()
       })
     })
 
@@ -1311,8 +1349,7 @@ export default class KnishIOClient {
     const query = await this.createMoleculeMutation({
       mutationClass: MutationAppendRequest,
       molecule: await this.createMolecule({
-        secret: this.getSecret(),
-        sourceWallet: await this.getSourceWallet()
+        secret: this.getSecret()
       })
     })
 
@@ -1355,6 +1392,25 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Links an identifier to the current wallet bundle
+   *
+   * @param {string} type - The type of the identifier.
+   * @param {string} contact - The contact associated with the identifier.
+   * @returns {Promise<ResponseLinkIdentifier>} - A promise that resolves to the link result.
+   */
+  async linkIdentifier ({
+    type,
+    contact
+  }) {
+    const query = this.createQuery(MutationLinkIdentifier)
+    return await this.executeQuery(query, {
+      bundle: this.getBundle(),
+      type,
+      content: contact
+    })
+  }
+
   /**
    * Creates a policy for a given metaType and metaId.
    *
@@ -1433,7 +1489,7 @@ export default class KnishIOClient {
 
     return this.executeQuery(walletQuery, {
       bundleHash: bundle || this.getBundle(),
-      tokenSlug: token,
+      token,
       unspent
     })
       .then((response) => {
@@ -2022,6 +2078,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]
@@ -2086,7 +2147,7 @@ export default class KnishIOClient {
       // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
       const authToken = AuthToken.create({
         token: response.token(),
-        expiresAt: response.time(),
+        expiresAt: response.expiresAt(),
         pubkey: response.pubKey(),
         encrypt: response.encrypt()
       }, wallet)
@@ -2143,7 +2204,7 @@ export default class KnishIOClient {
       // Map server payload field names (time/key) to AuthToken constructor names (expiresAt/pubkey)
       const authToken = AuthToken.create({
         token: response.token(),
-        expiresAt: response.time(),
+        expiresAt: response.expiresAt(),
         pubkey: response.pubKey(),
         encrypt: response.encrypt()
       }, wallet)

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 {*[]}