@totemsdk/core 1.0.0

package/dist/scripts/types.js

@@ -0,0 +1,145 @@
+function kissHex(hex) {
+    const raw = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    return '0x' + raw.toUpperCase();
+}
+export function convertFlatChunkToSDK(chunk) {
+    return {
+        isLeft: chunk.isLeft,
+        mmrData: { data: chunk.data, value: 0n }
+    };
+}
+export function convertLegacyProofToSDK(legacy) {
+    return {
+        proof: {
+            chunks: legacy.proofChain.map(convertFlatChunkToSDK)
+        },
+        blockTime: legacy.blockTime
+    };
+}
+export function createEmptyMMRProof() {
+    return { chunks: [] };
+}
+export function createSignedByDescriptor(address, wotsRootPublicKey) {
+    return {
+        address,
+        scriptType: 'signedby',
+        script: `RETURN SIGNEDBY(${kissHex(wotsRootPublicKey)})`,
+        wotsRootPublicKey,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}
+export function createMultisigDescriptor(address, publicKey1, publicKey2, ownPublicKey) {
+    return {
+        address,
+        scriptType: 'multisig',
+        script: `RETURN SIGNEDBY(${kissHex(publicKey1)}) AND SIGNEDBY(${kissHex(publicKey2)})`,
+        wotsRootPublicKey: ownPublicKey,
+        multisigKeys: [publicKey1, publicKey2],
+        multisigThreshold: 2,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}
+export function createMofNMultisigDescriptor(address, threshold, publicKeys, ownPublicKey) {
+    const formattedKeys = publicKeys.map(pk => kissHex(pk)).join(' ');
+    return {
+        address,
+        scriptType: 'multisig_mofn',
+        script: `RETURN MULTISIG(${threshold} ${formattedKeys})`,
+        wotsRootPublicKey: ownPublicKey,
+        multisigKeys: publicKeys,
+        multisigThreshold: threshold,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}
+export function createTimelockDescriptor(address, publicKey, unlockBlock) {
+    return {
+        address,
+        scriptType: 'timelock',
+        script: `RETURN SIGNEDBY(${kissHex(publicKey)}) AND @BLOCK GT ${unlockBlock}`,
+        wotsRootPublicKey: publicKey,
+        timelockBlock: unlockBlock,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}
+export function createHTLCDescriptor(address, ownerPublicKey, recipientPublicKey, hashLock, timeoutBlock, isOwner, preimage) {
+    const script = `IF @BLOCK GT ${timeoutBlock} AND SIGNEDBY(${kissHex(ownerPublicKey)}) THEN RETURN TRUE ENDIF RETURN (SIGNEDBY(${kissHex(recipientPublicKey)}) AND SHA3(STATE(1)) EQ ${kissHex(hashLock)})`;
+    const descriptor = {
+        address,
+        scriptType: 'htlc',
+        script,
+        wotsRootPublicKey: isOwner ? ownerPublicKey : recipientPublicKey,
+        htlcHash: hashLock,
+        timelockBlock: timeoutBlock,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+    if (preimage) {
+        descriptor.htlcPreimage = preimage;
+        descriptor.stateVariables = [{ port: 1, value: preimage, type: 'string' }];
+    }
+    return descriptor;
+}
+export function createMASTDescriptor(address, rootHash, branchScript, branchProof, wotsPublicKey) {
+    return {
+        address,
+        scriptType: 'mast',
+        script: `MAST ${kissHex(rootHash)}`,
+        wotsRootPublicKey: wotsPublicKey,
+        extraScripts: new Map([[branchScript, branchProof]]),
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}
+export function createExchangeDescriptor(address, ownerPublicKey, desiredAddress, desiredAmount, desiredTokenId) {
+    const ownerPk = kissHex(ownerPublicKey);
+    const script = `IF SIGNEDBY(PREVSTATE(0)) THEN RETURN TRUE ENDIF ASSERT VERIFYOUT(@INPUT PREVSTATE(1) PREVSTATE(2) PREVSTATE(3) TRUE) RETURN TRUE`;
+    return {
+        address,
+        scriptType: 'exchange',
+        script,
+        wotsRootPublicKey: ownerPublicKey,
+        stateVariables: [
+            { port: 0, value: ownerPk, type: 'hex' },
+            { port: 1, value: desiredAddress, type: 'hex' },
+            { port: 2, value: desiredAmount, type: 'number' },
+            { port: 3, value: desiredTokenId, type: 'hex' }
+        ],
+        verifyOutExpectations: [{
+                inputIndex: '@INPUT',
+                outputAddress: desiredAddress,
+                amount: desiredAmount,
+                tokenId: desiredTokenId,
+                keepState: true
+            }],
+        mastProof: createEmptyMMRProof(),
+        storeState: true
+    };
+}
+export function createFlashCashDescriptor(address, ownerPublicKey, interestMultiplier = '1.01') {
+    const script = `IF SIGNEDBY(PREVSTATE(1)) THEN RETURN TRUE ENDIF ASSERT SAMESTATE(1 1) RETURN VERIFYOUT(@INPUT @ADDRESS @AMOUNT*${interestMultiplier} @TOKENID TRUE)`;
+    return {
+        address,
+        scriptType: 'flashcash',
+        script,
+        wotsRootPublicKey: ownerPublicKey,
+        stateVariables: [{ port: 1, value: ownerPublicKey, type: 'hex' }],
+        mastProof: createEmptyMMRProof(),
+        storeState: true
+    };
+}
+export function createSlowCashDescriptor(address, ownerPublicKey, withdrawalPercent = '0.9', cooldownBlocks = 10000n) {
+    const script = `IF @COINAGE LT ${cooldownBlocks} THEN RETURN FALSE ENDIF ASSERT SIGNEDBY(${kissHex(ownerPublicKey)}) AND VERIFYOUT(@INPUT @ADDRESS @AMOUNT*${withdrawalPercent} @TOKENID TRUE)`;
+    return {
+        address,
+        scriptType: 'slowcash',
+        script,
+        wotsRootPublicKey: ownerPublicKey,
+        timelockBlock: cooldownBlocks,
+        mastProof: createEmptyMMRProof(),
+        storeState: false
+    };
+}

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

@@ -0,0 +1,29 @@
+import type { MMRProof, MMRProofChunk } from '../mmr.js';
+import type { ScriptDescriptor, StateValue, ExternalSignature, ScriptProofResult } from './types.js';
+declare function concat(...arrays: Uint8Array[]): Uint8Array;
+export declare function encodeMiniNumber(value: bigint, scale?: number): Uint8Array;
+export declare function encodeMiniData(data: Uint8Array): Uint8Array;
+export declare function encodeMiniString(str: string): Uint8Array;
+export declare function serializeMMRProofChunk(chunk: MMRProofChunk): Uint8Array;
+export declare function serializeRealMMRProof(proof: MMRProof, blockTime?: bigint): Uint8Array;
+export declare function parseMMRProofFromHex(proofHex: string): {
+    proof: MMRProof;
+    blockTime: bigint;
+};
+export declare function serializeScriptProofWithProof(script: string, proof: MMRProof, blockTime?: bigint): Uint8Array;
+export declare const STATETYPE_HEX = 1;
+export declare const STATETYPE_NUMBER = 2;
+export declare const STATETYPE_STRING = 4;
+export declare const STATETYPE_BOOL = 8;
+export declare function encodeStateValue(stateValue: StateValue): Uint8Array;
+export declare function serializeStateVariables(stateValues: StateValue[]): Uint8Array;
+export declare function buildScriptProofFromDescriptor(descriptor: ScriptDescriptor): ScriptProofResult;
+export declare function deduplicateScriptDescriptors(descriptors: ScriptDescriptor[]): Map<string, ScriptDescriptor>;
+export declare function serializeExtraScripts(extraScripts: Map<string, string>): Uint8Array;
+export declare function aggregateSignatures(totemSignature: {
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+}, externalSignatures: ExternalSignature[]): 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

@@ -0,0 +1,288 @@
+import { sha3_256 } from '@noble/hashes/sha3';
+import { serializeMMRProof } from '../mmr.js';
+import { mxToHex } from '../minima32.js';
+function hexToBytes(hex) {
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (cleanHex.length % 2 !== 0) {
+        throw new Error('Invalid hex string');
+    }
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < cleanHex.length; i += 2) {
+        bytes[i / 2] = parseInt(cleanHex.slice(i, i + 2), 16);
+    }
+    return bytes;
+}
+function normalizeHexValue(value) {
+    if (!value)
+        return '0x00';
+    const trimmed = value.trim();
+    if (trimmed.toLowerCase().startsWith('mx')) {
+        return mxToHex(trimmed);
+    }
+    return trimmed.startsWith('0x') ? trimmed : '0x' + trimmed;
+}
+function bytesToHex(bytes) {
+    return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function concat(...arrays) {
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+export function encodeMiniNumber(value, scale = 0) {
+    if (typeof value !== 'bigint') {
+        throw new Error(`encodeMiniNumber requires bigint, got ${typeof value}`);
+    }
+    if (value === 0n) {
+        return new Uint8Array([scale & 0xff, 1, 0]);
+    }
+    if (value < 0n) {
+        throw new Error(`encodeMiniNumber does not support negative values: ${value}`);
+    }
+    let hex = value.toString(16);
+    if (hex.length % 2 !== 0) {
+        hex = '0' + hex;
+    }
+    let unscaledBytes = hexToBytes(hex);
+    if (unscaledBytes.length > 0 && (unscaledBytes[0] & 0x80) !== 0) {
+        const withLeadingZero = new Uint8Array(unscaledBytes.length + 1);
+        withLeadingZero[0] = 0x00;
+        withLeadingZero.set(unscaledBytes, 1);
+        unscaledBytes = withLeadingZero;
+    }
+    const length = unscaledBytes.length;
+    if (length > 32) {
+        throw new Error(`MiniNumber data too large: ${length} bytes (max 32)`);
+    }
+    const result = new Uint8Array(1 + 1 + length);
+    result[0] = scale & 0xff;
+    result[1] = length & 0xff;
+    result.set(unscaledBytes, 2);
+    return result;
+}
+export function encodeMiniData(data) {
+    const length = data.length;
+    const lengthBytes = new Uint8Array([
+        (length >> 24) & 0xff,
+        (length >> 16) & 0xff,
+        (length >> 8) & 0xff,
+        length & 0xff
+    ]);
+    return concat(lengthBytes, data);
+}
+export function encodeMiniString(str) {
+    const utf8Bytes = new TextEncoder().encode(str);
+    return encodeMiniData(utf8Bytes);
+}
+function encodeMiniByte(value) {
+    return new Uint8Array([value ? 1 : 0]);
+}
+export function serializeMMRProofChunk(chunk) {
+    const parts = [];
+    parts.push(encodeMiniByte(chunk.isLeft));
+    parts.push(encodeMiniData(chunk.mmrData.data));
+    parts.push(encodeMiniNumber(chunk.mmrData.value));
+    return concat(...parts);
+}
+export function serializeRealMMRProof(proof, blockTime = 0n) {
+    return serializeMMRProof(proof, blockTime);
+}
+export function parseMMRProofFromHex(proofHex) {
+    const bytes = hexToBytes(proofHex);
+    let offset = 0;
+    const { value: blockTime, bytesRead: btRead } = readMiniNumber(bytes, offset);
+    offset += btRead;
+    const { value: chainLength, bytesRead: clRead } = readMiniNumber(bytes, offset);
+    offset += clRead;
+    const chunks = [];
+    for (let i = 0; i < Number(chainLength); i++) {
+        const { chunk, bytesRead } = readMMRProofChunk(bytes, offset);
+        chunks.push(chunk);
+        offset += bytesRead;
+    }
+    return { proof: { chunks }, blockTime };
+}
+function readMiniNumber(bytes, offset) {
+    const scale = bytes[offset];
+    const length = (bytes[offset + 1] << 24) | (bytes[offset + 2] << 16) |
+        (bytes[offset + 3] << 8) | bytes[offset + 4];
+    if (length === 0) {
+        return { value: 0n, bytesRead: 5 };
+    }
+    const dataBytes = bytes.slice(offset + 5, offset + 5 + length);
+    let value = 0n;
+    for (const b of dataBytes) {
+        value = (value << 8n) | BigInt(b);
+    }
+    return { value, bytesRead: 5 + length };
+}
+function readMMRProofChunk(bytes, offset) {
+    let pos = offset;
+    const isLeft = bytes[pos] === 1;
+    pos += 1;
+    const dataLength = (bytes[pos] << 24) | (bytes[pos + 1] << 16) |
+        (bytes[pos + 2] << 8) | bytes[pos + 3];
+    pos += 4;
+    const data = bytes.slice(pos, pos + dataLength);
+    pos += dataLength;
+    const { value, bytesRead: valueRead } = readMiniNumber(bytes, pos);
+    pos += valueRead;
+    return {
+        chunk: { isLeft, mmrData: { data, value } },
+        bytesRead: pos - offset
+    };
+}
+export function serializeScriptProofWithProof(script, proof, blockTime = 0n) {
+    const scriptBytes = encodeMiniString(script);
+    const proofBytes = serializeRealMMRProof(proof, blockTime);
+    return concat(scriptBytes, proofBytes);
+}
+export const STATETYPE_HEX = 1;
+export const STATETYPE_NUMBER = 2;
+export const STATETYPE_STRING = 4;
+export const STATETYPE_BOOL = 8;
+export function encodeStateValue(stateValue) {
+    if (stateValue.port < 0 || stateValue.port > 255) {
+        throw new Error(`StateVariable port must be 0-255, got ${stateValue.port}`);
+    }
+    const portByte = new Uint8Array([stateValue.port]);
+    let typeByte;
+    let dataBytes;
+    switch (stateValue.type) {
+        case 'bool':
+            typeByte = new Uint8Array([STATETYPE_BOOL]);
+            if (typeof stateValue.value === 'boolean') {
+                dataBytes = new Uint8Array([stateValue.value ? 1 : 0]);
+            }
+            else if (typeof stateValue.value === 'string') {
+                const boolValue = stateValue.value.toUpperCase() === 'TRUE';
+                dataBytes = new Uint8Array([boolValue ? 1 : 0]);
+            }
+            else {
+                throw new Error(`Invalid bool state value: ${stateValue.value}`);
+            }
+            break;
+        case 'number':
+            typeByte = new Uint8Array([STATETYPE_NUMBER]);
+            if (typeof stateValue.value === 'bigint') {
+                dataBytes = encodeMiniNumber(stateValue.value);
+            }
+            else if (typeof stateValue.value === 'string') {
+                const numValue = BigInt(stateValue.value);
+                dataBytes = encodeMiniNumber(numValue);
+            }
+            else {
+                throw new Error(`Invalid number state value: ${stateValue.value}`);
+            }
+            break;
+        case 'hex':
+            typeByte = new Uint8Array([STATETYPE_HEX]);
+            if (typeof stateValue.value === 'string') {
+                const normalizedHex = normalizeHexValue(stateValue.value);
+                dataBytes = encodeMiniData(hexToBytes(normalizedHex));
+            }
+            else if (stateValue.value instanceof Uint8Array) {
+                dataBytes = encodeMiniData(stateValue.value);
+            }
+            else {
+                throw new Error(`Invalid hex state value: ${stateValue.value}`);
+            }
+            break;
+        case 'string':
+            typeByte = new Uint8Array([STATETYPE_STRING]);
+            if (typeof stateValue.value === 'string') {
+                let bracketedValue = stateValue.value;
+                if (!stateValue.value.startsWith('[') || !stateValue.value.endsWith(']')) {
+                    bracketedValue = `[${stateValue.value}]`;
+                }
+                dataBytes = encodeMiniString(bracketedValue);
+            }
+            else {
+                throw new Error(`Invalid string state value: ${stateValue.value}`);
+            }
+            break;
+        default:
+            throw new Error(`Unknown state value type: ${stateValue.type}`);
+    }
+    return concat(portByte, typeByte, dataBytes);
+}
+export function serializeStateVariables(stateValues) {
+    const parts = [];
+    const countBytes = encodeMiniNumber(BigInt(stateValues.length));
+    parts.push(countBytes);
+    const sorted = [...stateValues].sort((a, b) => a.port - b.port);
+    for (const sv of sorted) {
+        parts.push(encodeStateValue(sv));
+    }
+    return concat(...parts);
+}
+export function buildScriptProofFromDescriptor(descriptor) {
+    const proof = descriptor.mastProof || { chunks: [] };
+    const serialized = serializeScriptProofWithProof(descriptor.script, proof);
+    return {
+        script: descriptor.script,
+        proof,
+        serialized
+    };
+}
+export function deduplicateScriptDescriptors(descriptors) {
+    const unique = new Map();
+    for (const desc of descriptors) {
+        const normalizedAddr = desc.address.toLowerCase();
+        if (!unique.has(normalizedAddr)) {
+            unique.set(normalizedAddr, desc);
+        }
+    }
+    return unique;
+}
+export function serializeExtraScripts(extraScripts) {
+    const parts = [];
+    const countBytes = encodeMiniNumber(BigInt(extraScripts.size));
+    parts.push(countBytes);
+    for (const [script, proofHex] of extraScripts) {
+        const { proof, blockTime } = proofHex
+            ? parseMMRProofFromHex(proofHex)
+            : { proof: { chunks: [] }, blockTime: 0n };
+        parts.push(serializeScriptProofWithProof(script, proof, blockTime));
+    }
+    return concat(...parts);
+}
+export function aggregateSignatures(totemSignature, externalSignatures) {
+    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}`);
+            continue;
+        }
+        const proof = extSig.proof || { chunks: [] };
+        allSigProofs.push(serializeSignatureProof(hexToBytes(extSig.publicKey), hexToBytes(extSig.signature), proof));
+    }
+    return allSigProofs;
+}
+function serializeSignatureProof(publicKey, signature, proof) {
+    const parts = [];
+    parts.push(encodeMiniData(publicKey));
+    parts.push(encodeMiniData(signature));
+    parts.push(serializeRealMMRProof(proof));
+    return concat(...parts);
+}
+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;
+}
+export function computeScriptAddress(script) {
+    const cleanScript = script.trim().toUpperCase();
+    const scriptBytes = new TextEncoder().encode(cleanScript);
+    const hashBytes = sha3_256(scriptBytes);
+    return bytesToHex(hashBytes);
+}
+export { concat };

package/dist/transaction.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Transaction Serialization & Digest Computation
+ *
+ * Port of the extension's MinimaTransactionBuilder serialization logic
+ * to the SDK core for full parity with the Totem wallet extension.
+ *
+ * Matches Minima Java's Transaction.writeDataStream() and Coin.writeDataStream() exactly.
+ *
+ * CRITICAL: Before computing the transaction digest for signing, you MUST call
+ * precomputeTransactionCoinID() to set output coin IDs. Without this, the signed
+ * digest won't match what the Minima node verifies, causing allsignaturesvalid=false.
+ */
+export interface MinimaTransaction {
+    linkHash: Uint8Array;
+    inputs: MinimaCoin[];
+    outputs: MinimaCoin[];
+    state: StateVariable[];
+}
+export interface MinimaCoin {
+    coinId: Uint8Array;
+    address: Uint8Array;
+    amount: string;
+    tokenId: Uint8Array;
+    token: MinimaToken | null;
+    storeState: boolean;
+    state: StateVariable[] | RawStateVariable[];
+    mmrEntryNumber: bigint;
+    spent: boolean;
+    created: bigint;
+    rawAmountBytes?: Uint8Array;
+    rawMmrEntryBytes?: Uint8Array;
+    rawBlockCreatedBytes?: Uint8Array;
+    rawTokenData?: Uint8Array;
+}
+export interface ParsedMiniNumber {
+    scale: number;
+    unscaledValue: bigint;
+}
+export interface MinimaToken {
+    coinId: Uint8Array;
+    scale: number;
+    totalAmount: bigint;
+    name: Uint8Array;
+    script: Uint8Array;
+    created?: bigint;
+}
+export interface StateVariable {
+    port: number;
+    value: string | bigint | boolean | Uint8Array;
+    type: 'bool' | 'number' | 'hex' | 'string';
+}
+export interface RawStateVariable {
+    port: number;
+    type: number;
+    rawData: Uint8Array;
+}
+export interface CoinProofData {
+    coinId: Uint8Array;
+    address: Uint8Array;
+    rawAmountBytes: Uint8Array;
+    tokenId: Uint8Array;
+    storeState: boolean;
+    mmrEntryNumber: bigint;
+    rawMmrEntryBytes: Uint8Array;
+    spent: boolean;
+    blockCreated: bigint;
+    rawBlockCreatedBytes: Uint8Array;
+    state: RawStateVariable[];
+    rawTokenData?: Uint8Array;
+}
+export interface SpendableCoinInput {
+    coinId: string;
+    address: string;
+    amount: string;
+    tokenId: string;
+    rawAmountBytes?: Uint8Array;
+    coinProofData?: CoinProofData;
+}
+export interface TransactionBuildResult {
+    transaction: MinimaTransaction;
+    digestTx: Uint8Array;
+    digestTxHex: string;
+    serialized: Uint8Array;
+    serializedHex: 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;
+export declare function precomputeTransactionCoinID(tx: MinimaTransaction): void;
+export declare function createDefaultTransaction(): MinimaTransaction;
+export declare function buildMinimaCoin(opts: {
+    coinId?: Uint8Array;
+    address: Uint8Array;
+    amount: string;
+    tokenId?: Uint8Array;
+    storeState?: boolean;
+    state?: StateVariable[];
+    mmrEntryNumber?: bigint;
+    spent?: boolean;
+    created?: bigint;
+    rawAmountBytes?: Uint8Array;
+    rawMmrEntryBytes?: Uint8Array;
+    rawBlockCreatedBytes?: Uint8Array;
+    coinProofData?: CoinProofData;
+}): MinimaCoin;