@totemsdk/core 1.2.10 → 1.2.11

package/dist/cjs/tx/TransactionReceiptStore.js

@@ -37,33 +37,28 @@ class TransactionReceiptStore {
         return this._initialized;
     }
     async load() {
-        try {
-            const receipts = await this.storage.get(this.storageKey);
-            if (receipts) {
-                this.receipts = receipts;
-                this.logger.debug(`Loaded ${this.receipts.length} transaction receipts`);
-            }
-        }
-        catch (error) {
-            this.logger.error('Failed to load receipts:', error);
+        const receipts = await this.storage.get(this.storageKey);
+        if (receipts) {
+            this.receipts = receipts;
+            this.logger.debug(`Loaded ${this.receipts.length} transaction receipts`);
         }
     }
     async persist() {
+        const trimmedReceipts = this.receipts.slice(-this.maxReceipts);
+        await this.storage.set(this.storageKey, trimmedReceipts);
+        this.receipts = trimmedReceipts;
+    }
+    async add(receipt) {
+        this.receipts.push(receipt);
+        this.logger.debug(`Added receipt: ${receipt.txpowid}`);
         try {
-            const trimmedReceipts = this.receipts.slice(-this.maxReceipts);
-            await this.storage.set(this.storageKey, trimmedReceipts);
-            this.receipts = trimmedReceipts;
+            await this.persist();
         }
         catch (error) {
-            this.logger.error('Failed to persist receipts:', error);
+            this.receipts.pop();
             throw error;
         }
     }
-    async add(receipt) {
-        this.receipts.push(receipt);
-        this.logger.debug(`Added receipt: ${receipt.txpowid}`);
-        await this.persist();
-    }
     getAll() {
         return [...this.receipts].reverse();
     }
@@ -76,15 +71,29 @@ class TransactionReceiptStore {
     async updateStatus(txpowid, status) {
         const receipt = this.receipts.find(r => r.txpowid === txpowid);
         if (receipt) {
+            const previousStatus = receipt.status;
             receipt.status = status;
             this.logger.debug(`Updated receipt status: ${txpowid} → ${status}`);
-            await this.persist();
+            try {
+                await this.persist();
+            }
+            catch (error) {
+                receipt.status = previousStatus;
+                throw error;
+            }
         }
     }
     async clear() {
+        const previous = this.receipts;
         this.receipts = [];
-        await this.storage.remove(this.storageKey);
-        this.logger.debug('Cleared all receipts');
+        try {
+            await this.storage.remove(this.storageKey);
+            this.logger.debug('Cleared all receipts');
+        }
+        catch (error) {
+            this.receipts = previous;
+            throw error;
+        }
     }
     count() {
         return this.receipts.length;

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { mmrRootFromPublicKeys, verifyMMRProof, } from './wasm-sync.js';
 export { phraseToSeed, generateWordList, validatePhrase, cleanSeedPhrase, } from './bip39.js';
 export { makeMxAddress, parseMxAddress, wotsAddressFromKeypair, } from './wasm-sync.js';
 export { serializeTransaction, computeTransactionDigest, } from './wasm-sync.js';
+export { deserializeTransaction } from './transaction.js';
 export { timingSafeEqual, createChallenge, validateChallenge, } from './wasm-sync.js';
 export { scriptFromWotsPk } from './script.js';
 export { makeMxAddress as encodeMx, parseMxAddress as decodeMx } from './wasm-sync.js';
@@ -30,13 +31,13 @@ export * from './scripts/index.js';
 export { scriptToAddress, addressToRoot } from './derive.js';
 export { WORD_LIST, convertStringToSeed, convertWordListToSeed, generateSeedPhrase, } from './bip39.js';
 export { MiniNumber } from './MiniNumber.js';
-export { type MinimaTransaction, type MinimaCoin, type ParsedMiniNumber, type MinimaToken, type StateVariable, type RawStateVariable, type CoinProofData, type SpendableCoinInput, type TransactionBuildResult, parseDecimalToMiniNumber, serializeCoin, createDefaultTransaction, buildMinimaCoin, } from './transaction.js';
+export { type MinimaTransaction, type MinimaCoin, type ParsedMiniNumber, type MinimaToken, type StateVariable, type RawStateVariable, type CoinProofData, type SpendableCoinInput, type TransactionBuildResult, parseDecimalToMiniNumber, serializeCoin, serializeTransaction as serializeTransactionObject, computeTokenId, serializeTokenDescriptor, createDefaultTransaction, buildMinimaCoin, } from './transaction.js';
 export { verifySignature, verifySignatureDetailed, verifyTreeSignatureDetailed, deriveAddressFromPublicKey, normalizeHex, type VerificationResult, } from './verify.js';
-export { writeMiniByte, writeMMREntryNumber, concat, bigIntToByteArray, type Bytes, } from './Streamable.js';
+export { writeMiniByte, writeMMREntryNumber, writeSignature, writeSignatureProof, concat, bigIntToByteArray, type Bytes, } from './Streamable.js';
 export { serializeMiniNumber, serializeMiniData, hashAllObjects, deriveChildTreeSeedJava, hashObject, serializeMiniNumberZERO, serializeMiniNumberONE, writeHashToStream, javaHashAllObjects, indexToMiniDataBytes, deriveUnifiedChildSeed, createMMREntryNumber, serializeMMREntryNumber, serializeMMRData, serializeMMREntry, type MMREntryNumber as JavaMMREntryNumber, type MMRData as JavaMMRData, type MMREntry as JavaMMREntry, } from './javaStreamables.js';
-export { TreeKey, TreeKeyNode, serializeTreeSignature, deserializeTreeSignature, getRootPublicKey, DEFAULT_KEYS_PER_LEVEL, DEFAULT_LEVELS, createUnifiedChildTreeKeyAsync, createPerAddressTreeKey, createPerAddressTreeKeyAsync, type KeyGenProgress, type ProgressCallback, type SignatureProof, type TreeSignature, } from './treekey.js';
+export { TreeKey, TreeKeyNode, serializeTreeSignature, deserializeTreeSignature, getRootPublicKey, DEFAULT_KEYS_PER_LEVEL, DEFAULT_LEVELS, createUnifiedChildTreeKeyAsync, createPerAddressTreeKey, createPerAddressTreeKeyAsync, setTreeKeyLogger, disableTreeKeyLogger, type KeyGenProgress, type ProgressCallback, type SignatureProof, type TreeSignature, } from './treekey.js';
 export type { WotsKeypair, WotsSignature } from './wots.js';
-export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, wotsSignLegacy, } from './wots.js';
+export { F, hex, fromHex, setWotsLogger, disableWotsLogger, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, wotsSignLegacy, } from './wots.js';
 export { toHex, canonicalJson, hashCanonical } from './canonical.js';
 export { utf8ToBytes, bytesToUtf8 } from './utils.js';
 export declare const MINIMA_CONSTANTS: {

package/dist/index.js

@@ -45,6 +45,8 @@ export { phraseToSeed, generateWordList, validatePhrase, cleanSeedPhrase, } from
 export { makeMxAddress, parseMxAddress, wotsAddressFromKeypair, } from './wasm-sync.js';
 // Transaction Serialization & Digest
 export { serializeTransaction, computeTransactionDigest, } from './wasm-sync.js';
+// Transaction deserialization (byte-exact inverse of the TS serializer)
+export { deserializeTransaction } from './transaction.js';
 // Verification
 export { timingSafeEqual, createChallenge, validateChallenge, } from './wasm-sync.js';
 // ---------------------------------------------------------------------------
@@ -72,16 +74,16 @@ export { WORD_LIST, convertStringToSeed, convertWordListToSeed, generateSeedPhra
 // MiniNumber class (matches Java MiniNumber/BigDecimal semantics)
 export { MiniNumber } from './MiniNumber.js';
 // Transaction types (from JS)
-export { parseDecimalToMiniNumber, serializeCoin, createDefaultTransaction, buildMinimaCoin, } from './transaction.js';
+export { parseDecimalToMiniNumber, serializeCoin, serializeTransaction as serializeTransactionObject, computeTokenId, serializeTokenDescriptor, createDefaultTransaction, buildMinimaCoin, } from './transaction.js';
 // High-level Verification API (convenience functions for integrators)
 export { verifySignature, verifySignatureDetailed, verifyTreeSignatureDetailed, deriveAddressFromPublicKey, normalizeHex, } from './verify.js';
 // Streamable primitives (low-level serialization building blocks)
-export { writeMiniByte, writeMMREntryNumber, concat, bigIntToByteArray, } from './Streamable.js';
+export { writeMiniByte, writeMMREntryNumber, writeSignature, writeSignatureProof, concat, bigIntToByteArray, } from './Streamable.js';
 // Java-Compatible Serialization Helpers (non-crypto)
 export { serializeMiniNumber, serializeMiniData, hashAllObjects, deriveChildTreeSeedJava, hashObject, serializeMiniNumberZERO, serializeMiniNumberONE, writeHashToStream, javaHashAllObjects, indexToMiniDataBytes, deriveUnifiedChildSeed, createMMREntryNumber, serializeMMREntryNumber, serializeMMRData, serializeMMREntry, } from './javaStreamables.js';
 // TreeKey/TreeKeyNode — JS types and helpers
-export { TreeKey, TreeKeyNode, serializeTreeSignature, deserializeTreeSignature, getRootPublicKey, DEFAULT_KEYS_PER_LEVEL, DEFAULT_LEVELS, createUnifiedChildTreeKeyAsync, createPerAddressTreeKey, createPerAddressTreeKeyAsync, } from './treekey.js';
-export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, wotsSignLegacy, } from './wots.js';
+export { TreeKey, TreeKeyNode, serializeTreeSignature, deserializeTreeSignature, getRootPublicKey, DEFAULT_KEYS_PER_LEVEL, DEFAULT_LEVELS, createUnifiedChildTreeKeyAsync, createPerAddressTreeKey, createPerAddressTreeKeyAsync, setTreeKeyLogger, disableTreeKeyLogger, } from './treekey.js';
+export { F, hex, fromHex, setWotsLogger, disableWotsLogger, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, wotsSignLegacy, } from './wots.js';
 // Canonical helpers (deterministic JSON + hashing)
 export { toHex, canonicalJson, hashCanonical } from './canonical.js';
 // Byte/string utilities

package/dist/lease/LeaseStore.d.ts

@@ -33,6 +33,7 @@ export interface LeaseStoreConfig {
 export declare class LeaseStore {
     private leases;
     private _initialized;
+    private mutationTail;
     private readonly storageKey;
     private readonly storage;
     private readonly logger;
@@ -42,16 +43,22 @@ export declare class LeaseStore {
     private load;
     private persist;
     save(lease: StoredLease): Promise<void>;
+    private saveUnlocked;
+    delete(leaseId: string): Promise<boolean>;
+    private deleteUnlocked;
     get(leaseId: string): StoredLease | undefined;
     getByToken(leaseToken: string): StoredLease | undefined;
     getAll(): StoredLease[];
     getActive(): StoredLease[];
     getExpiringSoon(thresholdMs?: number): StoredLease[];
-    delete(leaseId: string): Promise<boolean>;
     deleteByToken(leaseToken: string): Promise<boolean>;
     updateStatus(leaseId: string, status: LeaseStatus): Promise<void>;
+    private updateStatusUnlocked;
     cleanupExpired(): Promise<number>;
+    private cleanupExpiredUnlocked;
     clear(): Promise<void>;
+    private clearUnlocked;
+    private mutate;
     getMinimumTTL(): number | null;
     calculateMonitoringInterval(): number;
     private flattenIndex;

package/dist/lease/LeaseStore.js

@@ -11,9 +11,19 @@
  */
 import { NoopLogger } from '../adapters/index.js';
 const DEFAULT_STORAGE_KEY = 'totem_wots_leases';
+/** Drop fields whose value is `undefined` (strict adapters reject `undefined`). */
+function stripUndefined(value) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
 export class LeaseStore {
     leases = new Map();
     _initialized = false;
+    mutationTail = Promise.resolve();
     storageKey;
     storage;
     logger;
@@ -42,11 +52,12 @@ export class LeaseStore {
         }
         catch (error) {
             this.logger.error('Failed to load leases:', error);
+            throw error;
         }
     }
     async persist() {
         try {
-            const leasesArray = Array.from(this.leases.values());
+            const leasesArray = Array.from(this.leases.values()).map((lease) => stripUndefined(lease));
             await this.storage.set(this.storageKey, leasesArray);
         }
         catch (error) {
@@ -55,12 +66,45 @@ export class LeaseStore {
         }
     }
     async save(lease) {
+        return this.mutate(() => this.saveUnlocked(lease));
+    }
+    async saveUnlocked(lease) {
         const flatIndex = this.flattenIndex(lease.indices);
         this.logger.debug(`Storing lease: ${lease.leaseId}`);
         this.logger.debug(`  indices: (addressIndex=${lease.indices.addressIndex}, l1=${lease.indices.l1}, l2=${lease.indices.l2}) [${flatIndex}/262,144]`);
         this.logger.debug(`  status: ${lease.status}, TTL: ${lease.leaseTTL}ms`);
+        const previous = this.leases.get(lease.leaseId);
         this.leases.set(lease.leaseId, lease);
-        await this.persist();
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            if (previous)
+                this.leases.set(lease.leaseId, previous);
+            else
+                this.leases.delete(lease.leaseId);
+            throw error;
+        }
+    }
+    async delete(leaseId) {
+        return this.mutate(() => this.deleteUnlocked(leaseId));
+    }
+    async deleteUnlocked(leaseId) {
+        const lease = this.leases.get(leaseId);
+        if (lease) {
+            this.logger.debug(`Deleting lease: ${leaseId}, final status: ${lease.status}`);
+        }
+        const existed = this.leases.delete(leaseId);
+        if (existed) {
+            try {
+                await this.persist();
+            }
+            catch (error) {
+                this.leases.set(leaseId, lease);
+                throw error;
+            }
+        }
+        return existed;
     }
     get(leaseId) {
         return this.leases.get(leaseId);
@@ -81,17 +125,6 @@ export class LeaseStore {
             lease.expiresAt > now &&
             lease.expiresAt <= now + thresholdMs);
     }
-    async delete(leaseId) {
-        const lease = this.leases.get(leaseId);
-        if (lease) {
-            this.logger.debug(`Deleting lease: ${leaseId}, final status: ${lease.status}`);
-        }
-        const existed = this.leases.delete(leaseId);
-        if (existed) {
-            await this.persist();
-        }
-        return existed;
-    }
     async deleteByToken(leaseToken) {
         const lease = this.getByToken(leaseToken);
         if (lease) {
@@ -100,34 +133,71 @@ export class LeaseStore {
         return false;
     }
     async updateStatus(leaseId, status) {
+        return this.mutate(() => this.updateStatusUnlocked(leaseId, status));
+    }
+    async updateStatusUnlocked(leaseId, status) {
         const lease = this.leases.get(leaseId);
         if (lease) {
             const oldStatus = lease.status;
             this.logger.debug(`Lease status change: ${leaseId} ${oldStatus} → ${status}`);
             lease.status = status;
-            await this.persist();
+            try {
+                await this.persist();
+            }
+            catch (error) {
+                lease.status = oldStatus;
+                throw error;
+            }
         }
     }
     async cleanupExpired() {
+        return this.mutate(() => this.cleanupExpiredUnlocked());
+    }
+    async cleanupExpiredUnlocked() {
         const now = Date.now();
-        const expiredLeaseIds = [];
+        const expiredLeases = [];
         for (const [leaseId, lease] of this.leases.entries()) {
-            if (lease.expiresAt <= now && lease.status !== 'finalized') {
+            if (lease.expiresAt <= now && (lease.status === 'active' || lease.status === 'pending')) {
+                expiredLeases.push({ leaseId, status: lease.status });
                 lease.status = 'expired';
-                expiredLeaseIds.push(leaseId);
             }
         }
-        if (expiredLeaseIds.length > 0) {
-            this.logger.debug(`Marked ${expiredLeaseIds.length} leases as expired`);
-            await this.persist();
+        if (expiredLeases.length > 0) {
+            this.logger.debug(`Marked ${expiredLeases.length} leases as expired`);
+            try {
+                await this.persist();
+            }
+            catch (error) {
+                for (const { leaseId, status } of expiredLeases)
+                    this.leases.get(leaseId).status = status;
+                throw error;
+            }
         }
-        return expiredLeaseIds.length;
+        return expiredLeases.length;
     }
     async clear() {
+        await this.mutate(() => this.clearUnlocked());
+    }
+    async clearUnlocked() {
+        const previous = new Map(this.leases);
         this.leases.clear();
-        await this.storage.remove(this.storageKey);
+        try {
+            await this.storage.remove(this.storageKey);
+        }
+        catch (error) {
+            this.leases = previous;
+            throw error;
+        }
         this.logger.debug('Cleared all leases');
     }
+    mutate(operation) {
+        const prior = this.mutationTail;
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const run = prior.then(() => operation()).finally(() => release());
+        this.mutationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
     getMinimumTTL() {
         const activeLeases = this.getActive();
         if (activeLeases.length === 0)

package/dist/lease/WatermarkStore.js

@@ -47,19 +47,13 @@ export class WatermarkStore {
         return this._initialized;
     }
     async load() {
-        try {
-            const watermark = await this.storage.get(this.storageKey);
-            if (watermark) {
-                this.state = watermark;
-                this.logger.debug('Loaded watermark from storage');
-                return this.state;
-            }
-            return null;
-        }
-        catch (error) {
-            this.logger.error('Failed to load watermark:', error);
-            return null;
+        const watermark = await this.storage.get(this.storageKey);
+        if (watermark) {
+            this.state = watermark;
+            this.logger.debug('Loaded watermark from storage');
+            return this.state;
         }
+        return null;
     }
     async save(watermark) {
         try {

package/dist/scripts/witness-serializer.d.ts

@@ -23,7 +23,7 @@ export declare function serializeExtraScripts(extraScripts: Map<string, string>)
 export declare function aggregateSignatures(totemSignature: {
     publicKey: Uint8Array;
     signature: Uint8Array;
-}, externalSignatures: ExternalSignature[]): Uint8Array[];
+}, externalSignatures: ExternalSignature[], transactionDigest: Uint8Array): Uint8Array[];
 export declare function validateExternalSignature(signature: ExternalSignature, transactionDigest: Uint8Array): boolean;
 export declare function computeScriptAddress(script: string): string;
 export { concat };

package/dist/scripts/witness-serializer.js

@@ -1,4 +1,5 @@
 import { sha3_256 } from '../wasm-sync.js';
+import { wotsVerifyDigest } from '../wots.js';
 import { serializeMMRProof } from '../mmr.js';
 import { mxToHex } from '../minima32.js';
 function hexToBytes(hex) {
@@ -252,12 +253,26 @@ export function serializeExtraScripts(extraScripts) {
     }
     return concat(...parts);
 }
-export function aggregateSignatures(totemSignature, externalSignatures) {
+export function aggregateSignatures(totemSignature, externalSignatures, transactionDigest) {
+    // RFC-020 C5: the aggregate must never include an unverified signature.
+    // The totem signature is verified against the transaction digest; external
+    // signatures are verified here as well as gated on their `validated` flag.
+    const totemValid = (() => {
+        try {
+            return wotsVerifyDigest(totemSignature.signature, transactionDigest, totemSignature.publicKey);
+        }
+        catch {
+            return false;
+        }
+    })();
+    if (!totemValid) {
+        throw new Error('aggregateSignatures: the totem signature is invalid over the transaction digest');
+    }
     const allSigProofs = [];
     allSigProofs.push(serializeSignatureProof(totemSignature.publicKey, totemSignature.signature, { chunks: [] }));
     for (const extSig of externalSignatures) {
-        if (!extSig.validated) {
-            console.warn(`[AggregateSignatures] Skipping unvalidated signature from ${extSig.publicKey}`);
+        if (!extSig.validated || !validateExternalSignature(extSig, transactionDigest)) {
+            console.warn(`[AggregateSignatures] Skipping unverified signature from ${extSig.publicKey}`);
             continue;
         }
         const proof = extSig.proof || { chunks: [] };
@@ -276,8 +291,16 @@ export function validateExternalSignature(signature, transactionDigest) {
     if (!signature.publicKey || !signature.signature) {
         return false;
     }
-    console.log(`[ValidateSignature] Validating signature from ${signature.publicKey.substring(0, 16)}...`);
-    return true;
+    // RFC-020 C5: real WOTS verification (was an unconditional `true` stub).
+    if (signature.signatureType && signature.signatureType !== 'wots') {
+        return false;
+    }
+    try {
+        return wotsVerifyDigest(hexToBytes(signature.signature), transactionDigest, hexToBytes(signature.publicKey));
+    }
+    catch {
+        return false;
+    }
 }
 export function computeScriptAddress(script) {
     const cleanScript = script.trim().toUpperCase();

package/dist/transaction.d.ts

@@ -43,6 +43,12 @@ export interface MinimaToken {
     name: Uint8Array;
     script: Uint8Array;
     created?: bigint;
+    /**
+     * MiniNumber scale of `totalAmount` in the serialized Token. Minima's
+     * `tokencreate` builds the minima amount from `MINI_UNIT` (1E-44) times
+     * integers, so its scale is always 44; default accordingly.
+     */
+    totalAmountScale?: number;
 }
 export interface StateVariable {
     port: number;
@@ -82,11 +88,27 @@ export interface TransactionBuildResult {
     digestTxHex: string;
     serialized: Uint8Array;
     serializedHex: string;
+    /** Set when the transaction creates a token (RFC-005 #2/#11). */
+    tokenId?: string;
 }
 export declare function parseDecimalToMiniNumber(decimal: string): ParsedMiniNumber;
 export declare function serializeCoin(coin: MinimaCoin): Uint8Array;
 export declare function serializeTransaction(tx: MinimaTransaction): Uint8Array;
 export declare function computeTransactionDigest(tx: MinimaTransaction): Uint8Array;
+/**
+ * Compute a Minima **token id** — SHA3-256 of the MiniData-wrapped serialized
+ * Token, matching Java `Token.calculateTokenID()`. A newly created token's coins
+ * carry this value as their `tokenId`; token creation returns it.
+ */
+export declare function computeTokenId(token: MinimaToken): Uint8Array;
+/** Serialize a token descriptor (Java `Token.writeDataStream()` order). */
+export declare function serializeTokenDescriptor(token: MinimaToken): Uint8Array;
+/**
+ * Deserialize a transaction produced by {@link serializeTransaction}. The
+ * inverse is byte-exact for canonically-encoded transactions (outputs/inputs
+ * written from decimal amounts, MMR entry numbers and tokens).
+ */
+export declare function deserializeTransaction(bytes: Uint8Array): MinimaTransaction;
 export declare function precomputeTransactionCoinID(tx: MinimaTransaction): void;
 export declare function createDefaultTransaction(): MinimaTransaction;
 export declare function buildMinimaCoin(opts: {

package/dist/transaction.js

@@ -116,11 +116,11 @@ function serializeStateVariable(sv) {
         case 'string':
             typeByte = new Uint8Array([STATETYPE_STRING]);
             if (typeof sv.value === 'string') {
-                let bracketedValue = sv.value;
-                if (!sv.value.startsWith('[') || !sv.value.endsWith(']')) {
-                    bracketedValue = `[${sv.value}]`;
-                }
-                const utf8Bytes = new TextEncoder().encode(bracketedValue);
+                // Minima stores a string state variable as MiniString: MiniData of the
+                // raw UTF-8 bytes. The `[ … ]` form is KISSVM literal syntax, NOT part
+                // of the stored value (the C++ StateVariable::writeDataStream writes
+                // mData directly; the deserializer likewise strips no brackets).
+                const utf8Bytes = new TextEncoder().encode(sv.value);
                 dataBytes = writeMiniData(utf8Bytes);
             }
             else {
@@ -138,7 +138,10 @@ function serializeToken(token) {
     parts.push(writeHashToStream(token.coinId));
     parts.push(writeMiniData(token.script));
     parts.push(writeMiniNumber(BigInt(token.scale), 0));
-    parts.push(writeMiniNumber(token.totalAmount, 0));
+    // The minima amount is a MiniNumber carrying its own scale (Java
+    // Token.writeDataStream → mTokenMinimaAmount.writeDataStream). Minima's
+    // tokencreate always builds it from MINI_UNIT (scale 44).
+    parts.push(writeMiniNumber(token.totalAmount, token.totalAmountScale ?? 44));
     parts.push(writeMiniData(token.name));
     parts.push(writeMiniNumber(token.created ?? 0n, 0));
     return concat(...parts);
@@ -224,6 +227,151 @@ export function computeTransactionDigest(tx) {
     const serialized = serializeTransaction(tx);
     return sha3_256(serialized);
 }
+/**
+ * Compute a Minima **token id** — SHA3-256 of the MiniData-wrapped serialized
+ * Token, matching Java `Token.calculateTokenID()`. A newly created token's coins
+ * carry this value as their `tokenId`; token creation returns it.
+ */
+export function computeTokenId(token) {
+    return sha3_256(writeMiniData(serializeToken(token)));
+}
+/** Serialize a token descriptor (Java `Token.writeDataStream()` order). */
+export function serializeTokenDescriptor(token) {
+    return serializeToken(token);
+}
+function txReadBytes(data, c, n) {
+    if (n < 0 || c.offset + n > data.length) {
+        throw new Error(`deserializeTransaction: unexpected end of input at offset ${c.offset} (need ${n})`);
+    }
+    const out = data.slice(c.offset, c.offset + n);
+    c.offset += n;
+    return out;
+}
+function txReadMiniByte(data, c) {
+    return txReadBytes(data, c, 1)[0];
+}
+/** MiniData / hash: 4-byte big-endian length + bytes. */
+function txReadMiniData(data, c) {
+    const lenBytes = txReadBytes(data, c, 4);
+    const len = ((lenBytes[0] << 24) | (lenBytes[1] << 16) | (lenBytes[2] << 8) | lenBytes[3]) >>> 0;
+    return txReadBytes(data, c, len);
+}
+/** MiniNumber: 1-byte scale + 1-byte length + two's-complement unscaled bytes. */
+function txReadMiniNumber(data, c) {
+    const scale = txReadBytes(data, c, 1)[0];
+    const len = txReadBytes(data, c, 1)[0];
+    const bytes = txReadBytes(data, c, len);
+    let value = 0n;
+    for (const b of bytes)
+        value = (value << 8n) | BigInt(b);
+    // RFC-020 P2-10 (TXB-SERIAL-003): Java's BigInteger.toByteArray() (and the
+    // canonical writers here) use two's-complement big-endian; a set high bit
+    // means the value is negative. Previously this was read as unsigned.
+    if (bytes.length > 0 && (bytes[0] & 0x80) !== 0) {
+        value -= 1n << BigInt(8 * bytes.length);
+    }
+    return { value, scale };
+}
+function txBytesToBigInt(bytes) {
+    let value = 0n;
+    for (const b of bytes)
+        value = (value << 8n) | BigInt(b);
+    return value;
+}
+/** MMREntryNumber: MiniNumber(scale) followed by MiniData(unscaled). */
+function txReadMMREntryNumber(data, c) {
+    txReadMiniNumber(data, c); // scale (always 0 for integer entry numbers)
+    return txBytesToBigInt(txReadMiniData(data, c));
+}
+function miniNumberToDecimal(value, scale) {
+    if (scale === 0)
+        return value.toString();
+    const digits = value.toString().padStart(scale + 1, '0');
+    const whole = digits.slice(0, digits.length - scale);
+    const frac = digits.slice(digits.length - scale);
+    return `${whole}.${frac}`;
+}
+function txReadStateVariable(data, c) {
+    const port = txReadBytes(data, c, 1)[0];
+    const type = txReadBytes(data, c, 1)[0];
+    switch (type) {
+        case STATETYPE_HEX:
+            return { port, type: 'hex', value: txReadMiniData(data, c) };
+        case STATETYPE_NUMBER:
+            return { port, type: 'number', value: txReadMiniNumber(data, c).value };
+        case STATETYPE_STRING:
+            return { port, type: 'string', value: new TextDecoder().decode(txReadMiniData(data, c)) };
+        case STATETYPE_BOOL:
+            return { port, type: 'bool', value: txReadMiniByte(data, c) === 1 };
+        default:
+            throw new Error(`deserializeTransaction: unknown StateVariable type ${type}`);
+    }
+}
+function txReadToken(data, c) {
+    const coinId = txReadMiniData(data, c);
+    const script = txReadMiniData(data, c);
+    const { value: scale } = txReadMiniNumber(data, c);
+    // RFC-020 P2-10 (TXB-SERIAL-002): carry the totalAmount's own scale so a
+    // serialize→deserialize→serialize round-trip is byte-exact (previously the
+    // scale was dropped and re-defaulted to 44).
+    const { value: totalAmount, scale: totalAmountScale } = txReadMiniNumber(data, c);
+    const name = txReadMiniData(data, c);
+    const { value: created } = txReadMiniNumber(data, c);
+    return { coinId, script, scale: Number(scale), totalAmount, totalAmountScale, name, created };
+}
+function txReadCoin(data, c) {
+    const coinId = txReadMiniData(data, c);
+    const address = txReadMiniData(data, c);
+    const { value: amountUnscaled, scale } = txReadMiniNumber(data, c);
+    const tokenId = txReadMiniData(data, c);
+    const storeState = txReadMiniByte(data, c) === 1;
+    const mmrEntryNumber = txReadMMREntryNumber(data, c);
+    const spent = txReadMiniByte(data, c) === 1;
+    const { value: created } = txReadMiniNumber(data, c);
+    const stateCount = Number(txReadMiniNumber(data, c).value);
+    const state = [];
+    for (let i = 0; i < stateCount; i++)
+        state.push(txReadStateVariable(data, c));
+    const hasToken = txReadMiniByte(data, c) === 1;
+    const token = hasToken ? txReadToken(data, c) : null;
+    return {
+        coinId,
+        address,
+        amount: miniNumberToDecimal(amountUnscaled, scale),
+        tokenId,
+        token,
+        storeState,
+        state,
+        mmrEntryNumber,
+        spent,
+        created,
+    };
+}
+/**
+ * Deserialize a transaction produced by {@link serializeTransaction}. The
+ * inverse is byte-exact for canonically-encoded transactions (outputs/inputs
+ * written from decimal amounts, MMR entry numbers and tokens).
+ */
+export function deserializeTransaction(bytes) {
+    const c = { offset: 0 };
+    const inputCount = Number(txReadMiniNumber(bytes, c).value);
+    const inputs = [];
+    for (let i = 0; i < inputCount; i++)
+        inputs.push(txReadCoin(bytes, c));
+    const outputCount = Number(txReadMiniNumber(bytes, c).value);
+    const outputs = [];
+    for (let i = 0; i < outputCount; i++)
+        outputs.push(txReadCoin(bytes, c));
+    const stateCount = Number(txReadMiniNumber(bytes, c).value);
+    const state = [];
+    for (let i = 0; i < stateCount; i++)
+        state.push(txReadStateVariable(bytes, c));
+    const linkHash = txReadMiniData(bytes, c);
+    if (c.offset !== bytes.length) {
+        throw new Error(`deserializeTransaction: ${bytes.length - c.offset} trailing byte(s) after transaction`);
+    }
+    return { linkHash, inputs, outputs, state };
+}
 export function precomputeTransactionCoinID(tx) {
     if (tx.inputs.length === 0)
         return;