@wishknish/knishio-client-ts 0.7.2 → 0.7.6

package/src/constants.ts

@@ -63,7 +63,7 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
  * Immutable array of atom isotopes with const assertion
  * Provides compile-time type safety and runtime immutability
  */
-export const ISOTOPES = ['C', 'V', 'U', 'T', 'M', 'I', 'R', 'B', 'F'] as const
+export const ISOTOPES = ['C', 'V', 'U', 'T', 'M', 'I', 'R', 'B', 'F', 'P', 'A'] as const
 export type AtomIsotope = typeof ISOTOPES[number]
 
 /**
@@ -71,14 +71,16 @@ export type AtomIsotope = typeof ISOTOPES[number]
  */
 export const ISOTOPE_DESCRIPTIONS = {
   C: 'Continue - Position continuation',
-  V: 'Value - Token value transfer', 
+  V: 'Value - Token value transfer',
   U: 'User - User token operations',
   T: 'Token - Token creation/management',
   M: 'Meta - Metadata operations',
   I: 'Identity - Identity operations',
   R: 'Rule - Policy operations',
   B: 'Buffer - Buffer token operations',
-  F: 'Fuse - Token fusion operations'
+  F: 'Fuse - Token fusion operations',
+  P: 'Peer - Peer registration operations',
+  A: 'Append - Append request operations'
 } as const satisfies Record<AtomIsotope, string>
 
 // =============================================================================

package/src/core/Atom.ts

@@ -56,8 +56,10 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 
 import { convertToBase17 } from '@/libraries/crypto'
 import JsSHA from 'jssha'
-import { PROTOCOL_CONFIG } from '@/constants'
+import versions from '@/versions'
 import { handleIsotope, isWalletAddress, isPosition } from '@/types/guards'
+import Meta from '@/core/Meta'
+import AtomMeta from '@/core/AtomMeta'
 import type {
   AtomIsotope,
   AtomParams,
@@ -87,7 +89,7 @@ export const ATOM_DEFAULTS = {
   META: [],
   OTS_FRAGMENT: null,
   INDEX: null,
-  VERSION: PROTOCOL_CONFIG.DEFAULT_SDK_VERSION
+  VERSION: null
 } as const satisfies {
   readonly POSITION: string
   readonly WALLET_ADDRESS: string
@@ -100,7 +102,7 @@ export const ATOM_DEFAULTS = {
   readonly META: readonly []
   readonly OTS_FRAGMENT: null
   readonly INDEX: null
-  readonly VERSION: number
+  readonly VERSION: null
 }
 
 /**
@@ -119,12 +121,12 @@ export const ATOM_VALIDATION = {
 
 export interface AtomMetaData {
   readonly key: string
-  readonly value: string | number | boolean | null
-  readonly [additionalProps: string]: unknown
+  readonly value: string | null
+  readonly [props: string]: unknown
 }
 
 export interface AtomCreationParams extends AtomParams {
-  version?: number
+  version?: string | number | null | undefined
 }
 
 export interface AtomHashableData {
@@ -139,6 +141,7 @@ export interface AtomHashableData {
   meta: AtomMetaData[] | null
   createdAt: string
   index: number
+  version?: string | number | null
 }
 
 // =============================================================================
@@ -150,12 +153,12 @@ export interface AtomHashableData {
  * Maintains full compatibility with JavaScript SDK implementation
  */
 export default class Atom {
-  // Core properties matching JS SDK exactly
-  public position: string
-  public walletAddress: WalletAddress | string
-  public isotope: AtomIsotope
-  public token: TokenSlug | string
-  public value: string | number | null
+  // Core properties matching JS SDK exactly (all default to null)
+  public position: string | null
+  public walletAddress: WalletAddress | string | null
+  public isotope: AtomIsotope | null
+  public token: TokenSlug | string | null
+  public value: string | null
   public batchId: BatchId | string | null
   public metaType: MetaType | string | null
   public metaId: MetaId | string | null
@@ -163,42 +166,45 @@ export default class Atom {
   public otsFragment: string | null
   public index: number | null
   public createdAt: string
-  public version: number
+  public version: string | undefined
 
   /**
    * Create a new Atom instance
    * Constructor signature matches JavaScript SDK exactly
    */
   constructor({
-    position = ATOM_DEFAULTS.POSITION,
-    walletAddress = ATOM_DEFAULTS.WALLET_ADDRESS as any,
-    isotope = ATOM_DEFAULTS.ISOTOPE as AtomIsotope,
-    token = ATOM_DEFAULTS.TOKEN,
-    value = ATOM_DEFAULTS.VALUE,
-    batchId = ATOM_DEFAULTS.BATCH_ID,
-    metaType = ATOM_DEFAULTS.META_TYPE,
-    metaId = ATOM_DEFAULTS.META_ID,
+    position = null,
+    walletAddress = null,
+    isotope = null,
+    token = null,
+    value = null,
+    batchId = null,
+    metaType = null,
+    metaId = null,
     meta = null,
-    otsFragment = ATOM_DEFAULTS.OTS_FRAGMENT,
-    index = ATOM_DEFAULTS.INDEX,
+    otsFragment = null,
+    index = null,
     createdAt = null,
-    version = ATOM_DEFAULTS.VERSION
+    version = null
   }: AtomCreationParams = {}) {
     
-    // Use const assertion values with nullish coalescing (2025 pattern)
-    this.position = position ?? ATOM_DEFAULTS.POSITION
-    this.walletAddress = walletAddress ?? ATOM_DEFAULTS.WALLET_ADDRESS
-    this.isotope = isotope ?? ATOM_DEFAULTS.ISOTOPE
-    this.token = token ?? ATOM_DEFAULTS.TOKEN
-    this.value = value
+    // Match JS SDK constructor exactly
+    this.position = position
+    this.walletAddress = walletAddress
+    this.isotope = isotope
+    this.token = token
+    this.value = value !== null && value !== undefined ? String(value) : null
     this.batchId = batchId
     this.metaType = metaType
     this.metaId = metaId
-    this.meta = meta ? [...meta] : [...ATOM_DEFAULTS.META]
+    this.meta = meta ? Meta.normalizeMeta(meta) as AtomMetaData[] : []
     this.otsFragment = otsFragment
     this.index = index
-    this.version = version ?? ATOM_DEFAULTS.VERSION
-    // CRITICAL: Use provided createdAt or generate timestamp in milliseconds as string (Implementation Guide requirement)
+    // Match JS SDK: only set version if it exists in the version registry
+    if (version !== null && version !== undefined && Object.prototype.hasOwnProperty.call(versions as Record<string, any>, version)) {
+      this.version = String(version)
+    }
+    // Match JS SDK: always generate fresh createdAt (JS SDK has no createdAt parameter)
     this.createdAt = createdAt || String(+new Date())
   }
 
@@ -260,15 +266,17 @@ export default class Atom {
     return {
       position: this.position || '',
       walletAddress: this.walletAddress?.toString() || '',
-      isotope: this.isotope,
+      isotope: (this.isotope || 'C') as AtomIsotope,
       token: this.token?.toString() || '',
       value: this.value !== null ? this.value.toString() : null,
       batchId: this.batchId?.toString() || null,
       metaType: this.metaType?.toString() || null,
       metaId: this.metaId?.toString() || null,
-      meta: this.meta.length > 0 ? [...this.meta] : null,
+      // Always return array for meta (server expects Vec<MetaItemInput>, not null)
+      meta: this.meta.length > 0 ? [...this.meta] : [],
       createdAt: this.createdAt,
-      index: this.index !== null ? this.index : 0
+      index: this.index !== null ? this.index : 0,
+      version: this.version ?? null
     }
   }
 
@@ -286,8 +294,9 @@ export default class Atom {
    */
   public toJSON(options: {
     includeOtsFragments?: boolean
+    includeValidationContext?: boolean
     validateFields?: boolean
-  } = {}): AtomHashableData & { otsFragment?: string | null } {
+  } = {}): Record<string, unknown> {
     const {
       includeOtsFragments = true,
       validateFields = false
@@ -304,10 +313,22 @@ export default class Atom {
         }
       }
 
-      // Core atom properties (always included) - use structured data for JSON
-      const structuredData = this.getStructuredData()
-      const serialized: AtomHashableData & { otsFragment?: string | null } = {
-        ...structuredData
+      // Core atom properties — matches JavaScript SDK Atom.toJSON() exactly
+      // Uses ?? (nullish coalescing) not || (falsy coalescing) to preserve 0/false/"" values
+      // No .toString() calls — raw values must match what getHashableValues() hashed
+      const serialized: Record<string, unknown> = {
+        position: this.position ?? '',
+        walletAddress: this.walletAddress ?? '',
+        isotope: this.isotope,
+        token: this.token ?? '',
+        value: this.value,
+        batchId: this.batchId,
+        metaType: this.metaType,
+        metaId: this.metaId,
+        meta: this.meta || [],
+        index: this.index,
+        createdAt: this.createdAt,
+        version: this.version
       }
 
       // Optional OTS fragments (can be large, so optional)
@@ -329,8 +350,8 @@ export default class Atom {
     return new Atom({
       position: this.position,
       walletAddress: this.walletAddress as any,
-      isotope: this.isotope,
-      token: this.token,
+      isotope: this.isotope as AtomIsotope,
+      token: this.token as string,
       value: this.value,
       batchId: this.batchId,
       metaType: this.metaType,
@@ -352,6 +373,9 @@ export default class Atom {
       return false
     }
 
+    // Null isotope is invalid
+    if (!this.isotope) return false
+
     // Exhaustive isotope validation with compile-time completeness
     return handleIsotope(this.isotope, {
       V: () => this.value !== null && !isNaN(Number(this.value)), // Value atoms must have numeric value
@@ -362,7 +386,9 @@ export default class Atom {
       I: () => true, // Identity atoms
       R: () => true, // Rule atoms
       B: () => true, // Buffer atoms
-      F: () => true  // Fuse atoms
+      F: () => true, // Fuse atoms
+      P: () => true, // Peer atoms
+      A: () => Boolean(this.metaType && this.metaId) // Append atoms must have metaType and metaId
     })
   }
 
@@ -397,25 +423,67 @@ export default class Atom {
    */
   static getUnclaimedProps(): string[] {
     return [
-      'position',
-      'walletAddress',
-      'isotope', 
-      'token',
-      'value',
-      'batchId',
-      'metaType',
-      'metaId',
-      'meta',
-      'createdAt'
+      'otsFragment'
     ]
   }
 
   /**
    * Create atom from parameters - factory method
-   * Matches JavaScript SDK Atom.create static method
+   * Matches JavaScript SDK Atom.create static method exactly
+   * Processes wallet meta, extracts wallet fields, normalizes meta
    */
-  static create(params: AtomCreationParams): Atom {
-    return new Atom(params)
+  static create({
+    isotope,
+    wallet = null,
+    value = null,
+    metaType = null,
+    metaId = null,
+    meta = null,
+    batchId = null
+  }: {
+    isotope: AtomIsotope | string
+    wallet?: any | null
+    value?: string | number | null
+    metaType?: string | null
+    metaId?: string | null
+    meta?: AtomMeta | any[] | Record<string, any> | null
+    batchId?: string | null
+  }): Atom {
+    // If meta object is not passed - create it
+    let atomMeta: AtomMeta
+    if (!meta) {
+      atomMeta = new AtomMeta()
+    } else if (meta instanceof AtomMeta) {
+      // If meta object is already an instance of AtomMeta - use it
+      atomMeta = meta
+    } else {
+      // Otherwise create from meta
+      atomMeta = new AtomMeta(meta)
+    }
+
+    // If wallet has been passed => add related metas
+    if (wallet) {
+      // Add wallet's meta
+      atomMeta.setAtomWallet(wallet)
+
+      // If batch ID not passed: set it from the wallet
+      if (!batchId) {
+        batchId = wallet.batchId
+      }
+    }
+
+    // Create the final atom
+    return new Atom({
+      position: wallet ? wallet.position : null,
+      walletAddress: wallet ? wallet.address : null,
+      isotope: isotope as AtomIsotope,
+      token: wallet ? wallet.token : null,
+      value,
+      batchId,
+      metaType,
+      metaId,
+      meta: atomMeta.get() as any
+    })
   }
 
   /**
@@ -506,33 +574,37 @@ export default class Atom {
     if (!atoms || atoms.length === 0) {
       return ''
     }
-    
+
     // Step 1: Sort atoms by index to ensure deterministic hashing (matches JS SDK)
     const atomList = Atom.sortAtoms(atoms)
-    const numberOfAtoms = String(atoms.length)
-    let hashableValues: string[] = []
-
-    // Step 2: Build hashableValues array exactly like JavaScript SDK
-    for (const atom of atomList) {
-      // Add number of atoms (matching JS SDK comment: "Add number of atoms (???)")
-      hashableValues.push(numberOfAtoms)
-      
-      // Add atom's properties - concatenate the array returned by getHashableValues
-      hashableValues = hashableValues.concat(atom.getHashableValues())
-    }
-
-    // Step 3: Create molecular hash using SHAKE256 exactly like JS SDK (iterative updates)
     const molecularSponge = new JsSHA('SHAKE256', 'TEXT')
-    
-    // CRITICAL FIX: Use iterative updates like JavaScript, not string concatenation
-    for (const hashableValue of hashableValues) {
-      molecularSponge.update(hashableValue)  // Match JavaScript SDK exactly
+
+    // Step 2: Check for versioned hashing (matches JS SDK Atom.hashAtoms lines 365-366)
+    const versionRegistry = versions as Record<number | string, any>
+    if (atomList.every(atom => atom.version && Object.prototype.hasOwnProperty.call(versionRegistry, atom.version))) {
+      // Versioned path: create structured view of each atom and hash as JSON
+      molecularSponge.update(JSON.stringify(
+        atomList.map(atom => versionRegistry[atom.version!].create(atom).view())
+      ))
+    } else {
+      // Legacy path: field-by-field with incremental SHAKE256 updates
+      const numberOfAtoms = String(atoms.length)
+      let hashableValues: string[] = []
+
+      for (const atom of atomList) {
+        hashableValues.push(numberOfAtoms)
+        hashableValues = hashableValues.concat(atom.getHashableValues())
+      }
+
+      for (const hashableValue of hashableValues) {
+        molecularSponge.update(hashableValue)
+      }
     }
-    
-    // Step 4: Get hex hash (256 bits = 64 hex chars) and convert to base17
+
+    // Step 3: Get hex hash (256 bits = 64 hex chars) and convert to base17
     const hexHash = molecularSponge.getHash('HEX', { outputLen: 256 })
-    
-    // Step 5: Convert hex hash to base17 format (Implementation Guide requirement)
+
+    // Step 4: Convert hex hash to base17 format (Implementation Guide requirement)
     return convertToBase17(hexHash.toLowerCase())
   }
 
@@ -541,10 +613,9 @@ export default class Atom {
    * Matches JavaScript SDK sortAtoms method
    */
   static sortAtoms(atoms: Atom[]): Atom[] {
-    return [...atoms].sort((a, b) => {
-      const indexA = a.index !== null ? a.index : 0
-      const indexB = b.index !== null ? b.index : 0
-      return indexA - indexB
+    return [...atoms].sort((first, second) => {
+      // Match JS SDK exactly: first.index < second.index ? -1 : 1
+      return first.index! < second.index! ? -1 : 1
     })
   }
 
@@ -553,15 +624,7 @@ export default class Atom {
    * Matches JavaScript SDK generateNextAtomIndex method
    */
   static generateNextAtomIndex(atoms: Atom[]): number {
-    if (!atoms || atoms.length === 0) {
-      return 0
-    }
-
-    const indices = atoms
-      .map(atom => atom.index !== null ? atom.index : 0)
-      .filter(index => typeof index === 'number')
-
-    return indices.length > 0 ? Math.max(...indices) + 1 : 0
+    return atoms.length
   }
 
   /**
@@ -570,7 +633,7 @@ export default class Atom {
    */
   static isotopeFilter(isotopes: AtomIsotope | AtomIsotope[], atoms: Atom[]): Atom[] {
     const targetIsotopes = Array.isArray(isotopes) ? isotopes : [isotopes]
-    return atoms.filter(atom => targetIsotopes.includes(atom.isotope))
+    return atoms.filter(atom => atom.isotope !== null && targetIsotopes.includes(atom.isotope))
   }
 
   // =============================================================================
@@ -598,7 +661,7 @@ export default class Atom {
   /**
    * Check if atom is a specific isotope type
    */
-  static isIsotope(atom: Atom, isotope: AtomIsotope): boolean {
+  static isIsotope(atom: Atom, isotope: AtomIsotope | null): boolean {
     return atom.isotope === isotope
   }
 
@@ -608,7 +671,9 @@ export default class Atom {
   static getUniqueIsotopes(atoms: Atom[]): AtomIsotope[] {
     const isotopes = new Set<AtomIsotope>()
     for (const atom of atoms) {
-      isotopes.add(atom.isotope)
+      if (atom.isotope !== null) {
+        isotopes.add(atom.isotope)
+      }
     }
     return Array.from(isotopes)
   }
@@ -627,14 +692,16 @@ export default class Atom {
    */
   static groupByIsotope(atoms: Atom[]): Record<AtomIsotope, Atom[]> {
     const groups: Partial<Record<AtomIsotope, Atom[]>> = {}
-    
+
     for (const atom of atoms) {
-      if (!groups[atom.isotope]) {
-        groups[atom.isotope] = []
+      const iso = atom.isotope
+      if (iso === null) continue
+      if (!groups[iso]) {
+        groups[iso] = []
       }
-      groups[atom.isotope]!.push(atom)
+      groups[iso]!.push(atom)
     }
-    
+
     return groups as Record<AtomIsotope, Atom[]>
   }
 }

package/src/core/AtomMeta.ts

@@ -73,25 +73,9 @@ export default class AtomMeta {
    * @return This instance for chaining
    */
   merge(meta: Record<string, any> | NormalizedMeta[]): AtomMeta {
-    const normalized = Meta.normalizeMeta(meta)
-    
-    // Use Set to avoid duplicates based on key
-    const existingKeys = new Set(this.meta.map(m => m.key))
-    
-    for (const item of normalized) {
-      if (existingKeys.has(item.key)) {
-        // Update existing key
-        const index = this.meta.findIndex(m => m.key === item.key)
-        if (index !== -1) {
-          this.meta[index] = item
-        }
-      } else {
-        // Add new key
-        this.meta.push(item)
-        existingKeys.add(item.key)
-      }
-    }
-    
+    // Match JS SDK exactly: Array.from(new Set([...this.meta, ...Meta.normalizeMeta(meta)]))
+    // Set uses reference equality for objects, so it never deduplicates — effectively concatenation
+    this.meta = [...this.meta, ...Meta.normalizeMeta(meta)]
     return this
   }
 
@@ -115,23 +99,22 @@ export default class AtomMeta {
    * @return This instance for chaining
    */
   setAtomWallet(wallet: any): AtomMeta {
-    const walletMeta: Record<string, any> = {
-      pubkey: wallet.pubkey,
-      characters: wallet.characters
-    }
+    const walletMeta: Record<string, any> = {}
 
-    // Add token units meta key if present
+    // Add token units meta key (matches JS SDK exactly — no pubkey/characters)
     if (wallet.tokenUnits && wallet.tokenUnits.length) {
       walletMeta.tokenUnits = JSON.stringify(wallet.getTokenUnitsData ? wallet.getTokenUnitsData() : wallet.tokenUnits)
     }
 
-    // Add trade rates meta key if present
-    if (wallet.tradeRates && Object.keys(wallet.tradeRates).length) {
+    // Add trade rates meta key
+    if (wallet.tradeRates && wallet.tradeRates.length) {
       walletMeta.tradeRates = JSON.stringify(wallet.tradeRates)
     }
 
-    // Merge all wallet's metas
-    this.merge(walletMeta)
+    // Merge all wallet's metas (if any)
+    if (Object.keys(walletMeta).length > 0) {
+      this.merge(walletMeta)
+    }
     return this
   }
 

package/src/core/Meta.ts

@@ -61,8 +61,8 @@ import type { MetaData } from '@/types'
 
 export interface NormalizedMeta {
   key: string
-  value: string | number | boolean | null
-  [additionalProps: string]: unknown
+  value: string | null
+  [props: string]: unknown
 }
 
 export interface MetaItem {
@@ -95,37 +95,40 @@ export default class Meta {
       return []
     }
 
-    // Handle array of meta items
+    // Handle array of meta items — matches JS SDK exactly
     if (Array.isArray(meta)) {
       return meta.map(item => {
         if (typeof item === 'object' && item !== null && 'key' in item) {
           return {
-            ...item,
             key: String(item.key),
-            value: item.value as string | number | boolean | null
+            value: (item as any).value == null ? null : String((item as any).value)
           }
         }
-        
+
         // Fallback for invalid items
         return {
           key: 'unknown',
-          value: String(item) as string | number | boolean | null
+          value: String(item)
         }
       })
     }
 
-    // Handle object metadata - convert to array format
+    // Handle object metadata - convert to array format (matches JS SDK object path)
     if (typeof meta === 'object' && meta !== null) {
-      return Object.entries(meta).map(([key, value]) => ({
-        key,
-        value: value as string | number | boolean | null
-      }))
+      const target: NormalizedMeta[] = []
+      for (const property in meta) {
+        if (Object.prototype.hasOwnProperty.call(meta, property)) {
+          const raw = (meta as any)[property]
+          target.push({ key: property, value: raw == null ? null : String(raw) })
+        }
+      }
+      return target
     }
 
     // Handle primitive values
     return [{
       key: 'value',
-      value: meta as string | number | boolean | null
+      value: String(meta)
     }]
   }
 
@@ -264,7 +267,7 @@ export default class Meta {
     
     const newItem: NormalizedMeta = {
       key,
-      value: value as string | number | boolean | null
+      value: value == null ? null : String(value)
     }
     
     if (existingIndex >= 0) {
@@ -310,7 +313,7 @@ export default class Meta {
 
     return Object.entries(jsonData).map(([key, value]) => ({
       key,
-      value: value as string | number | boolean | null
+      value: value == null ? null : String(value)
     }))
   }