@wishknish/knishio-client-ts 0.7.4 → 0.7.7

package/src/core/Molecule.ts

@@ -49,9 +49,11 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 import Atom from './Atom'
 import AtomMeta from './AtomMeta'
 import Wallet from './Wallet'
+import Rule from '@/instance/rules/Rule'
 import CheckMolecule from '@/libraries/CheckMolecule'
 import { chunkSubstr, hexToBase64 } from '@/libraries/strings'
-import { generateBundleHash, generateOTSSignature } from '@/libraries/crypto'
+import { generateBundleHash, generateBatchId, generateOTSSignature } from '@/libraries/crypto'
+import versions from '@/versions'
 import {
   AtomsMissingException,
   BalanceInsufficientException,
@@ -75,7 +77,9 @@ export default class Molecule {
   public sourceWallet: Wallet | null
   public remainderWallet: Wallet | null
   public atoms: Atom[]
-  public version: string | null
+  public version: string | null | undefined
+  public continuIdPosition: string | null
+  public parentHashes: string[]
   public local?: number
 
   /**
@@ -88,7 +92,8 @@ export default class Molecule {
     sourceWallet = null,
     remainderWallet = null,
     cellSlug = null,
-    version = null
+    version = null,
+    continuIdPosition = null
   }: {
     secret?: string | null
     bundle?: string | null
@@ -96,6 +101,7 @@ export default class Molecule {
     remainderWallet?: Wallet | null
     cellSlug?: string | null
     version?: string | number | null
+    continuIdPosition?: string | null
   } = {}) {
     this.status = null
     this.molecularHash = null
@@ -104,13 +110,17 @@ export default class Molecule {
     this.secret = secret
     this.bundle = bundle
     this.sourceWallet = sourceWallet
+    this.continuIdPosition = continuIdPosition
     this.atoms = []
-    
-    if (version !== null) {
+    this.parentHashes = []
+
+    const versionRegistry = versions as Record<string | number, any>
+    if (version !== null && Object.prototype.hasOwnProperty.call(versionRegistry, version)) {
       this.version = String(version)
-    } else {
-      this.version = null
     }
+    // Only set version if it's a recognized version in the registry (matching JS SDK).
+    // When version is not recognized, this.version stays undefined.
+    // JSON.stringify omits undefined properties, so the server won't see a version field.
 
     // Set the remainder wallet for this transaction
     if (remainderWallet || sourceWallet) {
@@ -149,7 +159,7 @@ export default class Molecule {
     if (!Array.isArray(isotopes)) {
       isotopes = [isotopes]
     }
-    return atoms.filter(atom => isotopes.includes(atom.isotope))
+    return atoms.filter(atom => atom.isotope !== null && isotopes.includes(atom.isotope))
   }
 
   /**
@@ -176,7 +186,7 @@ export default class Molecule {
 
     // Set atom's index
     atom.index = this.generateIndex()
-    atom.version = this.version ? Number(this.version) : 4
+    atom.version = this.version ?? undefined
 
     // Add atom
     this.atoms.push(atom)
@@ -189,19 +199,78 @@ export default class Molecule {
 
   /**
    * Add user remainder atom for ContinuID
+   * Matches JavaScript SDK addContinuIdAtom exactly
    */
   addContinuIdAtom(): Molecule {
-    if (!this.remainderWallet) {
-      throw new Error('Remainder wallet required for ContinuID atom')
+    // If remainder wallet is not USER token, create a new USER remainder wallet
+    if (!this.remainderWallet || this.remainderWallet.token !== 'USER') {
+      this.remainderWallet = Wallet.create({
+        secret: this.secret!,
+        bundle: this.bundle!
+      })
+    }
+
+    // ContinuID metadata for chain integrity validation
+    const continuIdMeta: Record<string, any> = {}
+
+    // previousPosition: the current USER ContinuID position being consumed.
+    // For non-USER source wallets (V/B isotopes), use the explicitly passed
+    // continuIdPosition from createMolecule() instead of the TOKEN wallet position.
+    if (this.continuIdPosition) {
+      continuIdMeta.previousPosition = this.continuIdPosition
+    } else if (this.sourceWallet && this.sourceWallet.position) {
+      continuIdMeta.previousPosition = this.sourceWallet.position
     }
 
-    this.addAtom(new Atom({
+    // pubkey: ML-KEM public key for encrypted communication
+    if (this.remainderWallet.pubkey) {
+      continuIdMeta.pubkey = this.remainderWallet.pubkey
+    }
+
+    // characters: encoding format for the wallet
+    if (this.remainderWallet.characters) {
+      continuIdMeta.characters = this.remainderWallet.characters
+    }
+
+    this.addAtom(Atom.create({
       isotope: 'I',
-      position: this.remainderWallet.position!,
-      walletAddress: this.remainderWallet.address! as any,
-      token: 'USER',
+      wallet: this.remainderWallet!,
       metaType: 'walletBundle',
-      metaId: this.remainderWallet.bundle!
+      metaId: this.remainderWallet!.bundle!,
+      meta: new AtomMeta(continuIdMeta)
+    }))
+    return this
+  }
+
+  /**
+   * Add a policy R-isotope atom (matching JS SDK)
+   */
+  addPolicyAtom({
+    metaType,
+    metaId,
+    meta = {},
+    policy = {}
+  }: {
+    metaType: string
+    metaId: string
+    meta?: any
+    policy?: Record<string, any>
+  }): Molecule {
+    const atomMeta = new AtomMeta(meta)
+    atomMeta.addPolicy(policy)
+
+    const wallet = Wallet.create({
+      secret: this.secret!,
+      bundle: this.sourceWallet!.bundle!,
+      token: 'USER'
+    })
+
+    this.addAtom(Atom.create({
+      wallet,
+      isotope: 'R',
+      metaType,
+      metaId,
+      meta: atomMeta
     }))
     return this
   }
@@ -221,43 +290,31 @@ export default class Molecule {
       throw new Error('Source wallet required for value transfer')
     }
 
-    if (this.sourceWallet.balance - amount < 0) {
+    if (Number(this.sourceWallet.balance) - amount < 0) {
       throw new BalanceInsufficientException()
     }
 
-    // Initializing a new Atom to remove entire balance from source (UTXO model)
-    this.addAtom(new Atom({
+    // Initializing a new Atom to remove tokens from source (debit full balance)
+    this.addAtom(Atom.create({
       isotope: 'V',
-      position: this.sourceWallet.position!,
-      walletAddress: this.sourceWallet.address! as any,
-      token: this.sourceWallet.token,
-      value: -this.sourceWallet.balance
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance)
     }))
-
     // Initializing a new Atom to add tokens to recipient
-    this.addAtom(new Atom({
+    this.addAtom(Atom.create({
       isotope: 'V',
-      position: recipientWallet.position!,
-      walletAddress: recipientWallet.address! as any,
-      token: recipientWallet.token,
+      wallet: recipientWallet,
       value: amount,
       metaType: 'walletBundle',
       metaId: recipientWallet.bundle!
     }))
-
-    // Initializing a remainder atom (matching JavaScript SDK - uses existing remainderWallet)
-    if (!this.remainderWallet) {
-      throw new Error('Remainder wallet required for value transfer')
-    }
-    
-    this.addAtom(new Atom({
+    // Initializing a remainder atom
+    this.addAtom(Atom.create({
       isotope: 'V',
-      position: this.remainderWallet.position!,
-      walletAddress: this.remainderWallet.address! as any,
-      token: this.remainderWallet.token,
-      value: this.sourceWallet.balance - amount,
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - amount,
       metaType: 'walletBundle',
-      metaId: this.remainderWallet.bundle!
+      metaId: this.remainderWallet!.bundle!
     }))
 
     return this
@@ -300,6 +357,21 @@ export default class Molecule {
     // Set signing position from the first atom
     let signingPosition = signingAtom.position
 
+    // Get signing wallet from first atom's metas (matching JS SDK exactly)
+    // This handles buffer withdraw reconciliation where a different wallet signs
+    const signingWalletMeta = signingAtom.aggregatedMeta ? signingAtom.aggregatedMeta() : null
+    const signingWalletJson = signingWalletMeta?.signingWallet as string | undefined
+    if (signingWalletJson) {
+      try {
+        const parsedSigningWallet = JSON.parse(signingWalletJson)
+        if (parsedSigningWallet.position) {
+          signingPosition = parsedSigningWallet.position
+        }
+      } catch {
+        // Invalid JSON in signingWallet meta, use default position
+      }
+    }
+
     // Signing position is required
     if (!signingPosition) {
       throw new SignatureMalformedException('Signing wallet must have a position!')
@@ -448,7 +520,7 @@ export default class Molecule {
     secureMode?: boolean
   } = {}): any {
     const {
-      includeValidationContext = true,
+      includeValidationContext = false,
       includeOtsFragments = true,
       secureMode = false
     } = options
@@ -459,30 +531,37 @@ export default class Molecule {
         throw new Error('Cannot serialize molecule with secret in secure mode')
       }
 
-      // Core molecule properties (always included)
+      // Core molecule properties (server-compatible fields only)
       const serialized: any = {
         status: this.status,
         molecularHash: this.molecularHash,
         createdAt: this.createdAt,
         cellSlug: this.cellSlug,
-        cellSlugOrigin: this.cellSlugOrigin,
-        version: this.version,
         bundle: this.bundle,
-        
+
         // Serialized atoms array with optional OTS fragments
-        atoms: this.atoms.map(atom => atom.toJSON({ 
-          includeOtsFragments 
+        atoms: this.atoms.map(atom => atom.toJSON({
+          includeOtsFragments
         }))
       }
 
-      // Validation context (essential for cross-SDK validation)
+      // 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
+        serialized.version = this.version
+
         if (this.sourceWallet) {
           serialized.sourceWallet = {
             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',
@@ -499,7 +578,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',
@@ -532,6 +611,7 @@ export default class Molecule {
 
   /**
    * Initialize token creation
+   * Matches JavaScript SDK initTokenCreation implementation
    */
   initTokenCreation({
     recipientWallet,
@@ -542,32 +622,28 @@ export default class Molecule {
     amount: number
     meta: any
   }): Molecule {
-    // Create a new token by adding atoms
-    this.addAtom(new Atom({
-      isotope: 'T',
-      position: recipientWallet.position!,
-      walletAddress: recipientWallet.address! as any,
-      token: recipientWallet.token,
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for token creation')
+    }
+
+    // Build meta using AtomMeta class (matching JavaScript SDK exactly)
+    const atomMeta = new AtomMeta(meta)
+    atomMeta.setMetaWallet(recipientWallet)
+
+    // The primary atom tells the ledger that a certain amount of the new token is being issued
+    this.addAtom(Atom.create({
+      isotope: 'C',
+      wallet: this.sourceWallet,
       value: amount,
       metaType: 'token',
       metaId: recipientWallet.token,
-      meta: meta ? [{ key: 'tokenMeta', value: JSON.stringify(meta) }] : []
+      meta: atomMeta,
+      batchId: recipientWallet.batchId
     }))
-    
-    // Add wallet bundle metadata
-    this.addAtom(new Atom({
-      isotope: 'M',
-      position: recipientWallet.position!,
-      walletAddress: recipientWallet.address! as any,
-      token: recipientWallet.token,
-      metaType: 'walletBundle',
-      metaId: recipientWallet.bundle!,
-      meta: meta ? [{ key: 'tokenMeta', value: JSON.stringify(meta) }] : []
-    }))
-    
+
     // Add ContinuID atom (matching JavaScript SDK)
     this.addContinuIdAtom()
-    
+
     return this
   }
 
@@ -576,7 +652,7 @@ export default class Molecule {
    */
   burnToken({
     amount,
-    walletBundle = null
+    walletBundle: _walletBundle = null
   }: {
     amount: number
     walletBundle?: string | null
@@ -585,25 +661,68 @@ export default class Molecule {
       throw new Error('Source wallet required for token burning')
     }
     
-    if (amount <= 0) {
-      throw new NegativeAmountException()
+    if (amount < 0) {
+      throw new NegativeAmountException('Molecule::burnToken() - Amount to burn must be positive!')
     }
-    
-    if (this.sourceWallet.balance - amount < 0) {
+
+    if (Number(this.sourceWallet.balance) - amount < 0) {
       throw new BalanceInsufficientException()
     }
-    
-    // Burn tokens by removing from source
-    this.addAtom(new Atom({
+
+    // Create burn address wallet (null bundle = token destruction)
+    const burnWallet = new Wallet({
+      bundle: '0000000000000000000000000000000000000000000000000000000000000000',
+      token: this.sourceWallet.token
+    })
+
+    // V-atom 1: Debit full balance from source
+    this.addAtom(Atom.create({
       isotope: 'V',
-      position: this.sourceWallet.position!,
-      walletAddress: this.sourceWallet.address! as any,
-      token: this.sourceWallet.token,
-      value: -amount,
-      metaType: walletBundle ? 'walletBundle' : null,
-      metaId: walletBundle || null
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance)
     }))
-    
+
+    // V-atom 2: Credit burn amount to burn address
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: burnWallet,
+      value: amount,
+      metaType: 'walletBundle',
+      metaId: burnWallet.bundle!
+    }))
+
+    // V-atom 3: Remainder back to source identity
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - amount,
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet!.bundle!
+    }))
+
+    return this
+  }
+
+  /**
+   * Initialize authorization request
+   * Creates U-isotope (authorization) atom for requesting auth token
+   * Matches JavaScript SDK Molecule.initAuthorization
+   */
+  initAuthorization({ meta }: { meta: Record<string, any> }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for authorization')
+    }
+
+    // Create U-isotope atom for authorization (matching JS SDK)
+    this.addAtom(Atom.create({
+      isotope: 'U',
+      wallet: this.sourceWallet,
+      meta: new AtomMeta(meta)
+    }))
+
+    // Add ContinuID atom (matching JavaScript SDK)
+    this.addContinuIdAtom()
+
     return this
   }
 
@@ -625,78 +744,171 @@ export default class Molecule {
       throw new Error('Source wallet required for meta creation')
     }
     
-    const metaArray: Array<{ key: string; value: any }> = []
-    
-    // Convert meta to array format
-    if (meta) {
-      if (Array.isArray(meta)) {
-        metaArray.push(...meta)
-      } else if (typeof meta === 'object') {
-        for (const [key, value] of Object.entries(meta)) {
-          metaArray.push({ key, value })
-        }
-      } else {
-        metaArray.push({ key: 'value', value: meta })
-      }
-    }
-    
-    // Add policy if provided
-    if (policy) {
-      metaArray.push({ key: 'policy', value: JSON.stringify(policy) })
-    }
-    
-    // Create meta atom
-    this.addAtom(new Atom({
+    // Initializing a new Atom to hold our metadata (matching JS SDK)
+    this.addAtom(Atom.create({
       isotope: 'M',
-      position: this.sourceWallet.position!,
-      walletAddress: this.sourceWallet.address! as any,
-      token: this.sourceWallet.token,
+      wallet: this.sourceWallet,
       metaType,
       metaId,
-      meta: metaArray
+      meta: new AtomMeta(meta)
     }))
-    
-    // Add ContinuID atom (matching JavaScript SDK)
+
+    // Only add policy atom if policy is provided and not empty
+    if (policy && Object.keys(policy).length > 0) {
+      this.addPolicyAtom({
+        metaType,
+        metaId,
+        meta,
+        policy
+      })
+    }
+
+    // User remainder atom
     this.addContinuIdAtom()
-    
+
     return this
   }
 
   /**
    * Initialize wallet creation
+   * Uses source wallet for atom properties (matching JavaScript SDK)
+   * The wallet being created is stored in metadata
    */
   initWalletCreation(wallet: Wallet, atomMeta: AtomMeta | null = null): Molecule {
-    // Create wallet creation atom
-    const atom = new Atom({
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for wallet creation')
+    }
+
+    // Matching JS SDK: use AtomMeta.setMetaWallet() for wallet metadata
+    if (!atomMeta) {
+      atomMeta = new AtomMeta()
+    }
+    atomMeta.setMetaWallet(wallet)
+
+    const creationAtom = Atom.create({
       isotope: 'C',
-      position: wallet.position!,
-      walletAddress: wallet.address! as any,
-      token: wallet.token,
+      wallet: this.sourceWallet,
       metaType: 'wallet',
       metaId: wallet.address!,
-      meta: atomMeta ? atomMeta.get() as any : []
+      meta: atomMeta,
+      batchId: wallet.batchId
     })
-    
-    // Add wallet metadata
-    if (!atomMeta) {
-      atom.meta.push(
-        { key: 'position', value: wallet.position! },
-        { key: 'bundle', value: wallet.bundle! },
-        { key: 'token', value: wallet.token },
-        { key: 'batchId', value: wallet.batchId || '' },
-        { key: 'characters', value: wallet.characters || '' }
-      )
-      
-      if (wallet.pubkey) {
-        atom.meta.push({ key: 'pubkey', value: wallet.pubkey })
-      }
+    this.addAtom(creationAtom)
+    this.addContinuIdAtom()
+
+    return this
+  }
+
+  /**
+   * Creates atoms for rule definition
+   * Matches JavaScript SDK Molecule.createRule method
+   *
+   * @param metaType - The meta type for the rule
+   * @param metaId - The meta ID for the rule
+   * @param rule - Array of Rule objects or rule data
+   * @param policy - Optional policy object
+   * @return This molecule instance for chaining
+   */
+  createRule({
+    metaType,
+    metaId,
+    rule,
+    policy = {}
+  }: {
+    metaType: string
+    metaId: string
+    rule: Rule[] | any[] | any  // Accept single object or array
+    policy?: Record<string, any>
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for createRule')
     }
-    
-    this.addAtom(atom)
-    
-    // Add ContinuID atom (matching JavaScript SDK)
+
+    // Normalize rule to array (accept single object or array)
+    const ruleArray = Array.isArray(rule) ? rule : [rule]
+
+    // Convert rules to objects (matching JavaScript SDK)
+    const rules: Record<string, any>[] = []
+    for (const r of ruleArray) {
+      rules.push(r instanceof Rule ? r : Rule.toObject(r))
+    }
+
+    // Create atom meta with rules
+    const atomMeta = new AtomMeta({
+      rule: JSON.stringify(rules)
+    })
+
+    // Add policies to meta object only if policy exists and has keys (matching JS SDK)
+    if (policy && Object.keys(policy).length > 0) {
+      atomMeta.addPolicy(policy)
+    }
+
+    // Create R-isotope atom for rule (matching JS SDK)
+    this.addAtom(Atom.create({
+      isotope: 'R',
+      wallet: this.sourceWallet,
+      metaType,
+      metaId,
+      meta: atomMeta
+    }))
+
+    // Add ContinuID atom
     this.addContinuIdAtom()
-    
+
+    return this
+  }
+
+  /**
+   * Initializes a token request molecule
+   * Matches JavaScript SDK Molecule.initTokenRequest method
+   *
+   * @param token - Token slug to request
+   * @param amount - Amount of tokens to request
+   * @param metaType - Meta type (typically 'walletBundle')
+   * @param metaId - Meta ID (typically recipient bundle hash)
+   * @param meta - Optional additional metadata
+   * @param batchId - Optional batch ID
+   * @return This molecule instance for chaining
+   */
+  initTokenRequest({
+    token,
+    amount,
+    metaType,
+    metaId,
+    meta = {},
+    batchId = null
+  }: {
+    token: string
+    amount: number
+    metaType: string
+    metaId: string
+    meta?: Record<string, any>
+    batchId?: string | null
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for initTokenRequest')
+    }
+
+    // Add token and amount to meta (matching JavaScript SDK exactly)
+    const metaWithToken = { ...meta, token, amount: String(amount) }
+
+    // Mark as local molecule
+    this.local = 1
+
+    // Create T-isotope atom for token request (matching JS SDK)
+    this.addAtom(Atom.create({
+      isotope: 'T',
+      wallet: this.sourceWallet,
+      value: amount,
+      metaType,
+      metaId,
+      meta: new AtomMeta(metaWithToken),
+      batchId
+    }))
+
+    // Add ContinuID atom
+    this.addContinuIdAtom()
+
     return this
   }
 
@@ -761,6 +973,9 @@ export default class Molecule {
         })
       }
 
+      // Reconstruct parent hashes for DAG linkage
+      molecule.parentHashes = Array.isArray(data.parentHashes) ? [...data.parentHashes] : []
+
       // Reconstruct validation context if available and requested
       if (includeValidationContext) {
         if (data.sourceWallet) {
@@ -775,7 +990,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 as any
           if (data.sourceWallet.pubkey) {
             molecule.sourceWallet.pubkey = data.sourceWallet.pubkey
@@ -797,7 +1012,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 as any
           if (data.remainderWallet.pubkey) {
             molecule.remainderWallet.pubkey = data.remainderWallet.pubkey
@@ -821,4 +1036,255 @@ export default class Molecule {
   static jsonToObject(json: string): Molecule {
     return Molecule.fromJSON(json)
   }
+
+  // =============================================================================
+  // ISOTOPE INIT METHODS - MATCHING JAVASCRIPT SDK PARITY
+  // =============================================================================
+
+  /**
+   * Initialize a P-type molecule for peer registration
+   * Matches JavaScript SDK Molecule.initPeering implementation exactly
+   *
+   * @param host - The peer host URL to register
+   * @return This molecule instance for chaining
+   */
+  initPeering({ host }: { host: string }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for peer registration')
+    }
+
+    this.addAtom(Atom.create({
+      isotope: 'P',
+      wallet: this.sourceWallet,
+      metaType: 'walletBundle',
+      metaId: this.bundle!,
+      meta: new AtomMeta({ peerHost: host })
+    }))
+
+    this.addContinuIdAtom()
+
+    return this
+  }
+
+  /**
+   * Initialize an A-type molecule for an append request
+   * Matches JavaScript SDK Molecule.initAppendRequest implementation exactly
+   *
+   * @param metaType - The target MetaType to append to
+   * @param metaId - The target MetaId to append to
+   * @param action - The action to perform
+   * @param meta - Additional metadata
+   * @return This molecule instance for chaining
+   */
+  initAppendRequest({
+    metaType,
+    metaId,
+    action,
+    meta = {}
+  }: {
+    metaType: string
+    metaId: string
+    action: string
+    meta?: Record<string, any>
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for append request')
+    }
+
+    this.addAtom(Atom.create({
+      isotope: 'A',
+      wallet: this.sourceWallet,
+      metaType,
+      metaId,
+      meta: new AtomMeta({ action, ...meta })
+    }))
+
+    this.addContinuIdAtom()
+
+    return this
+  }
+
+  /**
+   * Initialize a deposit buffer operation (B-isotope)
+   * Matches JavaScript SDK Molecule.initDepositBuffer implementation exactly
+   *
+   * @param amount - Amount to deposit into buffer
+   * @param tradeRates - Trade rates for the buffer wallet
+   * @return This molecule instance for chaining
+   */
+  initDepositBuffer({
+    amount,
+    tradeRates
+  }: {
+    amount: number
+    tradeRates?: Record<string, any>
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for buffer deposit')
+    }
+
+    if (Number(this.sourceWallet.balance) - amount < 0) {
+      throw new BalanceInsufficientException()
+    }
+
+    // Create a buffer wallet
+    const bufferWallet = Wallet.create({
+      secret: this.secret!,
+      bundle: this.bundle,
+      token: this.sourceWallet.token,
+      batchId: this.sourceWallet.batchId
+    })
+    if (tradeRates) {
+      bufferWallet.tradeRates = tradeRates
+    }
+
+    // Debit full balance from source (V-isotope)
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance)
+    }))
+
+    // Deposit amount to buffer (B-isotope)
+    this.addAtom(Atom.create({
+      isotope: 'B',
+      wallet: bufferWallet,
+      value: amount,
+      metaType: 'walletBundle',
+      metaId: this.sourceWallet.bundle!
+    }))
+
+    // Remainder back to source
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - amount,
+      metaType: 'walletBundle',
+      metaId: this.sourceWallet.bundle!
+    }))
+
+    return this
+  }
+
+  /**
+   * Initialize a withdraw buffer operation (B-isotope)
+   * Matches JavaScript SDK Molecule.initWithdrawBuffer implementation exactly
+   *
+   * @param recipients - Map of recipientBundle → amount
+   * @param signingWallet - Optional signing wallet for reconciliation
+   * @return This molecule instance for chaining
+   */
+  initWithdrawBuffer({
+    recipients,
+    signingWallet = null
+  }: {
+    recipients: Record<string, number>
+    signingWallet?: any | null
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for buffer withdrawal')
+    }
+
+    // Calculate total from all recipients
+    let amount = 0
+    for (const recipientAmount of Object.values(recipients || {})) {
+      amount += recipientAmount
+    }
+
+    if (Number(this.sourceWallet.balance) - amount < 0) {
+      throw new BalanceInsufficientException()
+    }
+
+    // Set a meta signing position for molecule correct reconciliation
+    const firstAtomMeta = new AtomMeta()
+    if (signingWallet) {
+      firstAtomMeta.setSigningWallet(signingWallet)
+    }
+
+    // Debit full balance from source (B-isotope)
+    this.addAtom(Atom.create({
+      isotope: 'B',
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance),
+      meta: firstAtomMeta,
+      metaType: 'walletBundle',
+      metaId: this.sourceWallet.bundle!
+    }))
+
+    // Add recipient V-atoms (matching JS SDK: uses `new Atom()` with explicit token)
+    for (const [recipientBundle, recipientAmount] of Object.entries(recipients || {})) {
+      this.addAtom(new Atom({
+        isotope: 'V',
+        token: this.sourceWallet.token,
+        value: recipientAmount as number,
+        batchId: this.sourceWallet.batchId ? generateBatchId({}) : null,
+        metaType: 'walletBundle',
+        metaId: recipientBundle
+      }))
+    }
+
+    // Remainder back to buffer
+    this.addAtom(Atom.create({
+      isotope: 'B',
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - amount,
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet!.bundle!
+    }))
+
+    return this
+  }
+
+  /**
+   * Initialize shadow wallet claim
+   * Matches JavaScript SDK Molecule.initShadowWalletClaim implementation exactly
+   *
+   * @param wallet - The shadow wallet to claim
+   * @return This molecule instance for chaining
+   */
+  initShadowWalletClaim(wallet: Wallet): Molecule {
+    const atomMeta = new AtomMeta()
+    atomMeta.setShadowWalletClaim(true)
+    return this.initWalletCreation(wallet, atomMeta)
+  }
+
+  /**
+   * Initialize identifier creation
+   * Matches JavaScript SDK Molecule.initIdentifierCreation implementation exactly
+   *
+   * @param type - Identifier type (phone or email)
+   * @param contact - Phone number or email string
+   * @param code - Verification code
+   * @return This molecule instance for chaining
+   */
+  initIdentifierCreation({
+    type,
+    contact,
+    code
+  }: {
+    type: string
+    contact: string
+    code: string
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for identifier creation')
+    }
+
+    const meta = {
+      code,
+      hash: generateBundleHash(contact.trim(), 'Molecule::initIdentifierCreation')
+    }
+
+    this.addAtom(Atom.create({
+      isotope: 'C',
+      wallet: this.sourceWallet,
+      metaType: 'identifier',
+      metaId: type,
+      meta: new AtomMeta(meta)
+    }))
+
+    this.addContinuIdAtom()
+
+    return this
+  }
 }