@wishknish/knishio-client-js 0.8.1 → 0.9.0

package/package.json

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

package/src/Atom.js

@@ -212,7 +212,7 @@ export default class Atom {
 
   /**
    * Returns JSON-ready object for cross-SDK compatibility (2025 JS best practices)
-   * 
+   *
    * Provides clean serialization of atomic operations with optional OTS fragments.
    * Follows 2025 JavaScript best practices with proper type safety and validation.
    *
@@ -226,15 +226,15 @@ export default class Atom {
     const {
       includeOtsFragments = true,
       validateFields = false
-    } = options;
+    } = options
 
     try {
       // Validate required fields if requested
       if (validateFields) {
-        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token']
         for (const field of requiredFields) {
           if (!this[field]) {
-            throw new Error(`Required field '${field}' is missing or empty`);
+            throw new Error(`Required field '${field}' is missing or empty`)
           }
         }
       }
@@ -258,23 +258,22 @@ export default class Atom {
         index: this.index,
         createdAt: this.createdAt,
         version: this.version
-      };
+      }
 
       // Optional OTS fragments (can be large, so optional)
       if (includeOtsFragments && this.otsFragment) {
-        serialized.otsFragment = this.otsFragment;
+        serialized.otsFragment = this.otsFragment
       }
 
-      return serialized;
-
+      return serialized
     } catch (error) {
-      throw new Error(`Atom serialization failed: ${error.message}`);
+      throw new Error(`Atom serialization failed: ${error.message}`)
     }
   }
 
   /**
    * Creates an Atom instance from JSON data (2025 JS best practices)
-   * 
+   *
    * Handles cross-SDK atom deserialization with robust error handling.
    * Essential for reconstructing atoms from other SDK implementations.
    *
@@ -289,18 +288,18 @@ export default class Atom {
     const {
       validateStructure = true,
       strictMode = false
-    } = options;
+    } = options
 
     try {
       // Parse JSON safely
-      const data = typeof json === 'string' ? JSON.parse(json) : json;
+      const data = typeof json === 'string' ? JSON.parse(json) : json
 
       // Validate required fields in strict mode
       if (strictMode || validateStructure) {
-        const requiredFields = ['position', 'walletAddress', 'isotope', 'token'];
+        const requiredFields = ['position', 'walletAddress', 'isotope', 'token']
         for (const field of requiredFields) {
           if (!data[field]) {
-            throw new Error(`Required field '${field}' is missing or empty`);
+            throw new Error(`Required field '${field}' is missing or empty`)
           }
         }
       }
@@ -318,20 +317,19 @@ export default class Atom {
         meta: data.meta,
         index: data.index,
         version: data.version
-      });
+      })
 
       // Set additional properties that may not be in constructor
       if (data.otsFragment) {
-        atom.otsFragment = data.otsFragment;
+        atom.otsFragment = data.otsFragment
       }
       if (data.createdAt) {
-        atom.createdAt = data.createdAt;
+        atom.createdAt = data.createdAt
       }
 
-      return atom;
-
+      return atom
     } catch (error) {
-      throw new Error(`Atom deserialization failed: ${error.message}`);
+      throw new Error(`Atom deserialization failed: ${error.message}`)
     }
   }
 

package/src/KnishIOClient.js

@@ -88,7 +88,6 @@ import ActiveWalletSubscribe from './subscribe/ActiveWalletSubscribe.js'
 import ActiveSessionSubscribe from './subscribe/ActiveSessionSubscribe.js'
 import MutationActiveSession from './mutation/MutationActiveSession.js'
 import QueryActiveSession from './query/QueryActiveSession.js'
-import QueryUserActivity from './query/QueryUserActivity.js'
 import QueryToken from './query/QueryToken.js'
 import BatchIdException from './exception/BatchIdException.js'
 import AuthorizationRejectedException from './exception/AuthorizationRejectedException.js'
@@ -582,15 +581,15 @@ export default class KnishIOClient {
    * @param molecule
    */
   async createMoleculeMutation ({
-    mutationClass,
+    mutationClass: MutationClass,
     molecule = null
   }) {
-    this.log('info', `KnishIOClient::createMoleculeQuery() - Creating a new ${ mutationClass.name } query...`)
+    this.log('info', `KnishIOClient::createMoleculeQuery() - Creating a new ${ MutationClass.name } query...`)
 
     // If you don't supply the molecule, we'll generate one for you
     const _molecule = molecule || await this.createMolecule({})
 
-    const mutation = new mutationClass(this.client(), this, _molecule)
+    const mutation = new MutationClass(this.client(), this, _molecule)
 
     if (!(mutation instanceof MutationProposeMolecule)) {
       throw new CodeException(`${ this.constructor.name }::createMoleculeMutation() - This method only accepts MutationProposeMolecule!`)
@@ -1216,50 +1215,6 @@ export default class KnishIOClient {
     })
   }
 
-  /**
-   * Queries user activity based on the provided parameters.
-   *
-   * @param {string} bundleHash - The bundle hash.
-   * @param {string} metaType - The meta type.
-   * @param {string} metaId - The meta ID.
-   * @param {string} ipAddress - The IP address.
-   * @param {string} browser - The browser.
-   * @param {string} osCpu - The operating system and CPU.
-   * @param {string} resolution - The screen resolution.
-   * @param {string} timeZone - The time zone.
-   * @param {string} countBy - The count by parameter.
-   * @param {string} interval - The interval parameter.
-   *
-   * @returns {Promise<ResponseQueryUserActivity>} The result of the query.
-   */
-  async queryUserActivity ({
-    bundleHash,
-    metaType,
-    metaId,
-    ipAddress,
-    browser,
-    osCpu,
-    resolution,
-    timeZone,
-    countBy,
-    interval
-  }) {
-    const query = this.createQuery(QueryUserActivity)
-
-    return await this.executeQuery(query, {
-      bundleHash,
-      metaType,
-      metaId,
-      ipAddress,
-      browser,
-      osCpu,
-      resolution,
-      timeZone,
-      countBy,
-      interval
-    })
-  }
-
   /**
    * Builds and executes a molecule to declare an active session for the given MetaType
    *
@@ -1966,6 +1921,109 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Transfers tokens from one source wallet to MULTIPLE recipients in a single molecule.
+   *
+   * One molecule funds N recipients (WP line 544: "utilizing the sender's Wallet to fund multiple
+   * recipients with one transaction"). Each recipient receives its own amount and, for stackable
+   * tokens, its own subset of token units. The source is fully drained and the unsent change
+   * returns via the remainder atom (UTXO), so the V-atoms conserve. Single-recipient transfers
+   * should keep using transferToken(); this is its N-recipient generalization.
+   *
+   * @param {Object} options - The transfer options.
+   * @param {string} options.token - The token to transfer.
+   * @param {Array} options.recipients - [{ bundleHash, amount?, units?, batchId? }] per recipient.
+   * @param {Object} [options.sourceWallet=null] - The source wallet; queried if not provided.
+   *
+   * @returns {Promise} - A Promise that resolves to the transaction result.
+   *
+   * @throws {StackableUnitAmountException} - If a recipient provides both amount and units.
+   * @throws {TransferBalanceException} - If the source wallet does not have enough balance.
+   */
+  async transferTokens ({
+    token,
+    recipients,
+    sourceWallet = null
+  }) {
+    // Per-recipient amount: units.length for stackable, else the explicit amount
+    const amounts = recipients.map(recipient => {
+      const units = recipient.units || []
+      if (units.length > 0) {
+        // Can't move stackable units AND provide amount
+        if (recipient.amount > 0) {
+          throw new StackableUnitAmountException()
+        }
+        return units.length
+      }
+      return recipient.amount || 0
+    })
+    const total = amounts.reduce((sum, value) => sum + value, 0)
+
+    // Get a source wallet (loads its token units)
+    if (sourceWallet === null) {
+      sourceWallet = await this.querySourceWallet({
+        token,
+        amount: total
+      })
+    }
+
+    // Do you have enough tokens?
+    if (sourceWallet === null || Decimal.cmp(sourceWallet.balance, total) < 0) {
+      throw new TransferBalanceException()
+    }
+
+    // Build a shadow recipient wallet per recipient, each with its own batch ID
+    const recipientWallets = recipients.map(recipient => {
+      const recipientWallet = Wallet.create({
+        bundle: recipient.bundleHash,
+        token
+      })
+
+      // Compute the batch ID for the recipient (typically used by stackable tokens)
+      if (recipient.batchId !== undefined && recipient.batchId !== null) {
+        recipientWallet.batchId = recipient.batchId
+      } else {
+        recipientWallet.initBatchId({
+          sourceWallet
+        })
+      }
+
+      return recipientWallet
+    })
+
+    // Create a remainder from the source wallet
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // --- Token units splitting (N-way): source keeps the union, each recipient its subset,
+    //     remainder the kept units
+    sourceWallet.splitUnitsMulti(
+      recipients.map(recipient => recipient.units || []),
+      recipientWallets,
+      remainderWallet
+    )
+    // ---
+
+    // Build the molecule itself
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+    /**
+     * @type {MutationTransferTokens}
+     */
+    const query = await this.createMoleculeMutation({
+      mutationClass: MutationTransferTokens,
+      molecule
+    })
+
+    query.fillMoleculeMulti({
+      recipientWallets,
+      amounts
+    })
+
+    return await this.executeQuery(query)
+  }
+
   /**
    * Deposits buffer token into the source wallet.
    *
@@ -2343,7 +2401,15 @@ export default class KnishIOClient {
       molecule
     })
 
-    query.fillMolecule({ meta: { encrypt: (encrypt ? 'true' : 'false') } })
+    // PQ-transport Phase E (cycle 163): convey the AUTH source wallet's ML-KEM768 public key as a
+    // SIGNED `walletPubkey` meta on the U-atom (fillMolecule → initAuthorization → sign), so the
+    // validator can encrypt CipherHash responses back to THIS wallet (the one that decrypts them).
+    // Signed → tamper-proof. Only when present (PQ-capable wallet).
+    const authMeta = { encrypt: (encrypt ? 'true' : 'false') }
+    if (wallet.pubkey) {
+      authMeta.walletPubkey = wallet.pubkey
+    }
+    query.fillMolecule({ meta: authMeta })
     /**
      * @type {ResponseRequestAuthorization}
      */

package/src/Molecule.js

@@ -264,7 +264,13 @@ export default class Molecule {
         const condition = totalCondition ? mappedHashArray[index] < 8 : mappedHashArray[index] > -8
 
         if (condition) {
-          const process = totalCondition ? [++mappedHashArray[index], ++total] : [--mappedHashArray[index], --total]
+          if (totalCondition) {
+            ++mappedHashArray[index]
+            ++total
+          } else {
+            --mappedHashArray[index]
+            --total
+          }
 
           if (total === 0) {
             break
@@ -571,6 +577,11 @@ export default class Molecule {
     recipientWallet,
     amount
   }) {
+    // Canonical token transfer (incl. stackable): a UTXO-style FULL-balance debit + remainder.
+    // The source wallet is fully drained (-balance) and the change returns via the remainder atom,
+    // so the 3 V-atoms conserve (sum == 0) and the validator's stackable full-drain guard accepts.
+    // Per-unit (stackable) movement is layered by calling Wallet.splitUnits(units, remainder,
+    // recipient) BEFORE this — there is no separate partial-debit transfer mode.
     if (this.sourceWallet.balance - amount < 0) {
       throw new BalanceInsufficientException()
     }
@@ -602,54 +613,55 @@ export default class Molecule {
   }
 
   /**
-   * Creates a stackable V-isotope transfer with 3 atoms:
-   * source debit, recipient credit, remainder.
-   * Propagates batchId from source wallet.
+   * Multi-recipient value transfer (WP line 544: one molecule funds N recipients).
+   *
+   * Builds 1 source atom (full-balance debit, carrying the SENT union of all units) + one atom
+   * per recipient (its amount + its own units, walletBundle-bonded) + 1 remainder atom (the KEPT
+   * change). Conservation: -balance + Σ amounts + (balance - Σ amounts) == 0.
    *
-   * @param {Wallet} recipientWallet - wallet receiving the tokens
-   * @param {number} amount - amount to transfer
+   * Per-unit (stackable) routing is layered by calling Wallet.splitUnitsMulti(...) BEFORE this —
+   * it sets the source's tokenUnits to the union, each recipient's to its subset, and the
+   * remainder's to the kept units. The single-recipient initValue() is the N=1 special case.
+   *
+   * @param {Wallet[]} recipientWallets
+   * @param {number[]} amounts - parallel to recipientWallets
    * @return {Molecule}
    */
-  addStackableTransfer ({
-    recipientWallet,
-    amount
+  initValues ({
+    recipientWallets,
+    amounts
   }) {
-    if (amount <= 0) {
-      throw new NegativeAmountException('Molecule::addStackableTransfer() - Amount must be positive!')
-    }
+    const total = amounts.reduce((sum, value) => sum + Number(value), 0)
 
-    if (this.sourceWallet.balance - amount < 0) {
+    if (this.sourceWallet.balance - total < 0) {
       throw new BalanceInsufficientException()
     }
 
-    const batchId = this.sourceWallet.batchId || generateBatchId({})
-
-    // Source debit atom
+    // Source atom: debit the full balance (UTXO); carries the SENT union of all units
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.sourceWallet,
-      value: -amount,
-      batchId
+      value: -this.sourceWallet.balance
     }))
 
-    // Recipient credit atom
-    this.addAtom(Atom.create({
-      isotope: 'V',
-      wallet: recipientWallet,
-      value: amount,
-      metaType: 'walletBundle',
-      metaId: recipientWallet.bundle,
-      batchId: generateBatchId({})
-    }))
+    // One atom per recipient: its amount + its own units, bonded to the recipient bundle
+    recipientWallets.forEach((recipientWallet, index) => {
+      this.addAtom(Atom.create({
+        isotope: 'V',
+        wallet: recipientWallet,
+        value: amounts[index],
+        metaType: 'walletBundle',
+        metaId: recipientWallet.bundle
+      }))
+    })
 
-    // Remainder atom
+    // Remainder atom: the change back to the sender; carries the KEPT units
     this.addAtom(Atom.create({
       isotope: 'V',
       wallet: this.remainderWallet,
-      value: this.sourceWallet.balance - amount,
+      value: this.sourceWallet.balance - total,
       metaType: 'walletBundle',
-      metaId: this.remainderWallet.bundle,
-      batchId
+      metaId: this.remainderWallet.bundle
     }))
 
     return this
@@ -716,7 +728,7 @@ export default class Molecule {
   }) {
     // Calculate final amount from all recipients
     let amount = 0
-    for (const [recipientBundle, recipientAmount] of Object.entries(recipients || {})) {
+    for (const recipientAmount of Object.values(recipients || {})) {
       amount += recipientAmount
     }
     if (this.sourceWallet.balance - amount < 0) {
@@ -1184,7 +1196,7 @@ export default class Molecule {
     const {
       includeValidationContext = false,
       includeOtsFragments = true
-    } = options;
+    } = options
 
     try {
       // Core molecule properties (server-compatible fields only)
@@ -1199,7 +1211,7 @@ export default class Molecule {
         atoms: this.atoms.map(atom => atom.toJSON({
           includeOtsFragments
         }))
-      };
+      }
 
       // Parent molecular hashes for DAG linkage (only include when non-empty
       // to maintain backward compatibility with servers that don't support it)
@@ -1225,7 +1237,7 @@ export default class Molecule {
             tokenUnits: this.sourceWallet.tokenUnits || [],
             tradeRates: this.sourceWallet.tradeRates || {},
             molecules: this.sourceWallet.molecules || {}
-          };
+          }
         }
 
         if (this.remainderWallet) {
@@ -1241,14 +1253,13 @@ export default class Molecule {
             tokenUnits: this.remainderWallet.tokenUnits || [],
             tradeRates: this.remainderWallet.tradeRates || {},
             molecules: this.remainderWallet.molecules || {}
-          };
+          }
         }
       }
 
-      return serialized;
-
+      return serialized
     } catch (error) {
-      throw new Error(`Molecule serialization failed: ${error.message}`);
+      throw new Error(`Molecule serialization failed: ${error.message}`)
     }
   }
 
@@ -1269,16 +1280,16 @@ export default class Molecule {
     const {
       includeValidationContext = false,
       validateStructure = true
-    } = options;
+    } = options
 
     try {
       // Parse JSON safely
-      const data = typeof json === 'string' ? JSON.parse(json) : json;
+      const data = typeof json === 'string' ? JSON.parse(json) : json
 
       // Validate required fields in strict mode
       if (validateStructure) {
         if (!data.molecularHash || !Array.isArray(data.atoms)) {
-          throw new Error('Invalid molecule data: missing molecularHash or atoms array');
+          throw new Error('Invalid molecule data: missing molecularHash or atoms array')
         }
       }
 
@@ -1288,24 +1299,24 @@ export default class Molecule {
         bundle: data.bundle || null,
         cellSlug: data.cellSlug || null,
         version: data.version || null
-      });
+      })
 
       // Populate core properties
-      molecule.status = data.status;
-      molecule.molecularHash = data.molecularHash;
-      molecule.createdAt = data.createdAt || String(+new Date());
-      molecule.cellSlugOrigin = data.cellSlugOrigin;
-      molecule.parentHashes = Array.isArray(data.parentHashes) ? [...data.parentHashes] : [];
+      molecule.status = data.status
+      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)) {
         molecule.atoms = data.atoms.map((atomData, index) => {
           try {
-            return Atom.fromJSON(atomData);
+            return Atom.fromJSON(atomData)
           } catch (error) {
-            throw new Error(`Failed to reconstruct atom ${index}: ${error.message}`);
+            throw new Error(`Failed to reconstruct atom ${index}: ${error.message}`)
           }
-        });
+        })
       }
 
       // Reconstruct validation context if available and requested
@@ -1319,17 +1330,17 @@ export default class Molecule {
             bundle: data.sourceWallet.bundle,
             batchId: data.sourceWallet.batchId,
             characters: data.sourceWallet.characters
-          });
+          })
 
           // Set additional properties for validation context
-          molecule.sourceWallet.balance = String(data.sourceWallet.balance != null ? data.sourceWallet.balance : 0);
-          molecule.sourceWallet.address = data.sourceWallet.address;
+          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;
+            molecule.sourceWallet.pubkey = data.sourceWallet.pubkey
           }
-          molecule.sourceWallet.tokenUnits = data.sourceWallet.tokenUnits || [];
-          molecule.sourceWallet.tradeRates = data.sourceWallet.tradeRates || {};
-          molecule.sourceWallet.molecules = data.sourceWallet.molecules || {};
+          molecule.sourceWallet.tokenUnits = data.sourceWallet.tokenUnits || []
+          molecule.sourceWallet.tradeRates = data.sourceWallet.tradeRates || {}
+          molecule.sourceWallet.molecules = data.sourceWallet.molecules || {}
         }
 
         if (data.remainderWallet) {
@@ -1341,24 +1352,23 @@ export default class Molecule {
             bundle: data.remainderWallet.bundle,
             batchId: data.remainderWallet.batchId,
             characters: data.remainderWallet.characters
-          });
+          })
 
           // Set additional properties for validation context
-          molecule.remainderWallet.balance = String(data.remainderWallet.balance != null ? data.remainderWallet.balance : 0);
-          molecule.remainderWallet.address = data.remainderWallet.address;
+          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;
+            molecule.remainderWallet.pubkey = data.remainderWallet.pubkey
           }
-          molecule.remainderWallet.tokenUnits = data.remainderWallet.tokenUnits || [];
-          molecule.remainderWallet.tradeRates = data.remainderWallet.tradeRates || {};
-          molecule.remainderWallet.molecules = data.remainderWallet.molecules || {};
+          molecule.remainderWallet.tokenUnits = data.remainderWallet.tokenUnits || []
+          molecule.remainderWallet.tradeRates = data.remainderWallet.tradeRates || {}
+          molecule.remainderWallet.molecules = data.remainderWallet.molecules || {}
         }
       }
 
-      return molecule;
-
+      return molecule
     } catch (error) {
-      throw new Error(`Molecule deserialization failed: ${error.message}`);
+      throw new Error(`Molecule deserialization failed: ${error.message}`)
     }
   }