@totemsdk/txpow 0.1.0

package/src/serialization.ts

@@ -0,0 +1,236 @@
+/**
+ * serialization.ts — TxPoW envelope serialization.
+ *
+ * Ports serializeTxHeader / serializeTxBody / serializeTxPoW from
+ * packages/totem-extension/src/core/transaction/MinimaTransactionBuilder.ts
+ * into the standalone @totemsdk/txpow package.
+ *
+ * KEY DESIGN DECISIONS
+ * ─────────────────────────────────────────────────────────────────────────
+ * • serializeTxBody accepts PRE-SERIALIZED transaction bytes and witness bytes.
+ *   Callers use @totemsdk/core's serializeTransaction() + their own witness
+ *   serializer, then pass the byte arrays here. This keeps @totemsdk/txpow
+ *   free of WotsSignatureData / InputScriptInfo / CoinProof dependencies.
+ *
+ * • txnDifficulty defaults to MAX_HASH (all 0xFF) to produce byte-identical
+ *   output to the extension's current MEG-mined path. For locally mined TxPoWs
+ *   the caller MUST pass a value ≤ TX_POW_MIN_DIFFICULTY, otherwise the
+ *   transaction will fail TxPoWChecker.checkTxPoWSimple() at block inclusion.
+ *
+ * • nonce defaults to 0n (the mining loop updates it). timeMilli defaults to
+ *   Date.now() at call time.
+ *
+ * WIRE FORMAT REFERENCE
+ * ─────────────────────────────────────────────────────────────────────────
+ * TxHeader.writeDataStream():
+ *   1. mNonce           MiniNumber
+ *   2. mChainID         MiniData   (MAIN_NET = [0x00])
+ *   3. mTimeMilli       MiniNumber
+ *   4. mBlockNumber     MiniNumber (0 for fresh TxPoW)
+ *   5. mBlockDifficulty MiniData   (MAX_HASH for fresh TxPoW)
+ *   6. Super Parents    RLE: 1 byte count + writeHashToStream(parent)
+ *   7. mMMRRoot         writeHashToStream (ZERO_HASH for fresh TxPoW)
+ *   8. mMMRTotal        MiniNumber (0)
+ *   9. mMagic           Magic.writeDataStream()
+ *  10. mCustomHash      writeHashToStream (ZERO_HASH)
+ *  11. mTxBodyHash      writeHashToStream
+ *
+ * TxBody.writeDataStream():
+ *   1. mPRNG            writeHashToStream (32 random bytes)
+ *   2. mTxnDifficulty   MiniData
+ *   3. mTransaction     Transaction.writeDataStream() (pre-serialized)
+ *   4. mWitness         Witness.writeDataStream() (pre-serialized)
+ *   5. mBurnTransaction Transaction.writeDataStream() (empty)
+ *   6. mBurnWitness     Witness.writeDataStream() (empty)
+ *   7. mTxPowIDList     MiniNumber(0)
+ *
+ * TxPoW.writeDataStream():
+ *   TxHeader bytes + MiniByte(0x01=hasBody) + TxBody bytes
+ *
+ * TxPoW ID:
+ *   SHA3-256( TxHeader bytes )  — Java: Crypto.getInstance().hashObject(mHeader)
+ */
+
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import {
+  writeMiniNumber,
+  writeMiniData,
+  concat,
+  writeHashToStream,
+} from '@totemsdk/core';
+import { serializeMagic } from './magic.js';
+import {
+  MAX_HASH,
+  ZERO_HASH,
+  CASCADE_LEVELS,
+  MAIN_NET_CHAIN_ID,
+} from './constants.js';
+
+export interface TxHeaderOptions {
+  /** Proof-of-work nonce. Defaults to 0n. The mining loop iterates this. */
+  nonce?: bigint;
+  /** Block timestamp in milliseconds. Defaults to Date.now() at call time. */
+  timeMilli?: bigint;
+}
+
+export interface TxBodyOptions {
+  /**
+   * Transaction difficulty target (32-byte MiniData).
+   * • MEG-side-mined path:  leave undefined → MAX_HASH (all 0xFF)
+   * • Locally mined path:   MUST be ≤ TX_POW_MIN_DIFFICULTY, typically fetched
+   *   via fetchTxPowTarget() from the same package.
+   * Setting MAX_HASH for locally mined TxPoWs will cause block-level rejection.
+   */
+  txnDifficulty?: Uint8Array;
+  /** Override the 32-byte PRNG field. Useful for deterministic tests only. */
+  prng?: Uint8Array;
+}
+
+export type TxPoWOptions = TxHeaderOptions & TxBodyOptions;
+
+/**
+ * Serialize a TxHeader per Minima's TxHeader.writeDataStream().
+ *
+ * @param txBodyHash  SHA3-256 of the serialized TxBody (32 bytes)
+ * @param options     Optional nonce and timeMilli overrides
+ */
+export function serializeTxHeader(
+  txBodyHash: Uint8Array,
+  options?: TxHeaderOptions
+): Uint8Array {
+  const nonce = options?.nonce ?? 0n;
+  const timeMilli = options?.timeMilli ?? BigInt(Date.now());
+
+  const parts: Uint8Array[] = [];
+
+  parts.push(writeMiniNumber(nonce));
+  parts.push(writeMiniData(MAIN_NET_CHAIN_ID));
+  parts.push(writeMiniNumber(timeMilli));
+  parts.push(writeMiniNumber(0n));
+  parts.push(writeMiniData(MAX_HASH));
+
+  parts.push(new Uint8Array([CASCADE_LEVELS]));
+  parts.push(writeHashToStream(ZERO_HASH));
+
+  parts.push(writeHashToStream(ZERO_HASH));
+  parts.push(writeMiniNumber(0n));
+
+  parts.push(serializeMagic());
+
+  parts.push(writeHashToStream(ZERO_HASH));
+
+  parts.push(writeHashToStream(txBodyHash));
+
+  return concat(...parts);
+}
+
+/**
+ * Compute TxPoW ID = SHA3-256(TxHeader bytes).
+ * Matches Java: Crypto.getInstance().hashObject(mHeader) via SHA3Digest(256).
+ */
+export function computeTxPoWId(headerBytes: Uint8Array): Uint8Array {
+  return sha3_256(headerBytes);
+}
+
+/**
+ * Build the empty burn transaction bytes.
+ *
+ * Equivalent to serializeTransaction({ linkHash: new Uint8Array([0x00]),
+ *                                       inputs: [], outputs: [], state: [] })
+ * which produces:
+ *   writeMiniNumber(0n)              inputs count
+ *   writeMiniNumber(0n)              outputs count
+ *   writeMiniNumber(0n)              state count
+ *   writeHashToStream([0x00])        linkHash = ZERO_TXPOWID (1 byte)
+ */
+function buildEmptyBurnTxBytes(): Uint8Array {
+  return concat(
+    writeMiniNumber(0n),
+    writeMiniNumber(0n),
+    writeMiniNumber(0n),
+    writeHashToStream(new Uint8Array([0x00]))
+  );
+}
+
+/**
+ * Build the empty burn witness bytes.
+ *
+ * Equivalent to serializeWitness() with no arguments:
+ *   writeMiniNumber(0n)   signature count
+ *   writeMiniNumber(0n)   coinproof count
+ *   writeMiniNumber(0n)   scriptproof count
+ */
+function buildEmptyBurnWitnessBytes(): Uint8Array {
+  return concat(
+    writeMiniNumber(0n),
+    writeMiniNumber(0n),
+    writeMiniNumber(0n)
+  );
+}
+
+/**
+ * Serialize a TxBody per Minima's TxBody.writeDataStream().
+ *
+ * @param txBytes       Pre-serialized Transaction bytes (from @totemsdk/core's serializeTransaction)
+ * @param witnessBytes  Pre-serialized Witness bytes (from extension's serializeWitness)
+ * @param options       Optional txnDifficulty override and test PRNG
+ */
+export function serializeTxBody(
+  txBytes: Uint8Array,
+  witnessBytes: Uint8Array,
+  options?: TxBodyOptions
+): Uint8Array {
+  const txnDifficulty = options?.txnDifficulty ?? MAX_HASH;
+
+  let prng: Uint8Array;
+  if (options?.prng) {
+    prng = options.prng;
+  } else {
+    prng = new Uint8Array(32);
+    if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+      throw new Error(
+        'SECURITY: crypto.getRandomValues unavailable — cannot generate secure random bytes for transaction PRNG'
+      );
+    }
+    crypto.getRandomValues(prng);
+  }
+
+  return concat(
+    writeHashToStream(prng),
+    writeMiniData(txnDifficulty),
+    txBytes,
+    witnessBytes,
+    buildEmptyBurnTxBytes(),
+    buildEmptyBurnWitnessBytes(),
+    writeMiniNumber(0n)
+  );
+}
+
+/**
+ * Serialize a complete TxPoW per Minima's TxPoW.writeDataStream().
+ *
+ * Assembles TxBody from pre-serialized tx+witness bytes, hashes the body to
+ * obtain mTxBodyHash, builds TxHeader with nonce=0, then concatenates:
+ *   TxHeader | 0x01 (hasBody) | TxBody
+ *
+ * The returned bytes have nonce=0. Pass them to mineTxPoW() to find a valid
+ * nonce for local mining, or send as-is when MEG will re-mine.
+ *
+ * @param txBytes       Pre-serialized Transaction bytes
+ * @param witnessBytes  Pre-serialized Witness bytes
+ * @param options       Optional txnDifficulty, nonce, timeMilli, prng
+ */
+export function serializeTxPoW(
+  txBytes: Uint8Array,
+  witnessBytes: Uint8Array,
+  options?: TxPoWOptions
+): Uint8Array {
+  const txBody = serializeTxBody(txBytes, witnessBytes, options);
+  const txBodyHash = sha3_256(txBody);
+
+  return concat(
+    serializeTxHeader(txBodyHash, options),
+    new Uint8Array([0x01]),
+    txBody
+  );
+}

package/src/verify.ts

@@ -0,0 +1,57 @@
+/**
+ * verify.ts — TxPoW proof-of-work verification.
+ *
+ * verifyProofOfWork checks that a given txpowId beats the difficulty target
+ * without re-mining. Used by relay nodes to reject under-work submissions.
+ */
+
+import { isLessThan } from './mine.js';
+
+export interface VerifyResult {
+  valid: boolean;
+  txpowId: string;
+  difficulty: string;
+  reason?: string;
+}
+
+function toHex(bytes: Uint8Array): string {
+  return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Verify that a TxPoW ID beats the stated difficulty target.
+ *
+ * valid = txpowId < mTxnDifficulty (big-endian 256-bit comparison)
+ *
+ * @param txpowId        The 32-byte TxPoW ID (SHA3-256 of the header).
+ * @param mTxnDifficulty The 32-byte difficulty target from the TxBody.
+ */
+export function verifyProofOfWork(
+  txpowId: Uint8Array,
+  mTxnDifficulty: Uint8Array
+): VerifyResult {
+  if (txpowId.length !== 32) {
+    return {
+      valid: false,
+      txpowId: toHex(txpowId),
+      difficulty: toHex(mTxnDifficulty),
+      reason: `txpowId must be 32 bytes, got ${txpowId.length}`,
+    };
+  }
+  if (mTxnDifficulty.length !== 32) {
+    return {
+      valid: false,
+      txpowId: toHex(txpowId),
+      difficulty: toHex(mTxnDifficulty),
+      reason: `mTxnDifficulty must be 32 bytes, got ${mTxnDifficulty.length}`,
+    };
+  }
+
+  const valid = isLessThan(txpowId, mTxnDifficulty);
+  return {
+    valid,
+    txpowId: toHex(txpowId),
+    difficulty: toHex(mTxnDifficulty),
+    reason: valid ? undefined : 'txpowId ≥ mTxnDifficulty',
+  };
+}

package/src/wasm/miner.c

@@ -0,0 +1,165 @@
+/**
+ * miner.c — SHA3-256 proof-of-work mining loop for WASM compilation.
+ *
+ * Compile (requires Emscripten):
+ *   emcc -O3 -o miner.wasm miner.c \
+ *     -s WASM=1 -s SIDE_MODULE=1 \
+ *     -s EXPORTED_FUNCTIONS='["_mine","_malloc","_free"]' \
+ *     --no-entry
+ *
+ * Or set EMSCRIPTEN env var and run: npm run build:wasm
+ *
+ * WASM interface:
+ *   uint32_t mine(
+ *     uint8_t* header,       // header buffer in WASM linear memory
+ *     int      headerLen,    // total header length
+ *     int      nonceOffset,  // byte offset of nonce VALUE (= 2, after scale+len)
+ *     int      nonceLen,     // byte length of nonce value (1, 2, or 3)
+ *     uint8_t* target,       // 32-byte target in WASM linear memory
+ *     uint32_t startNonce,   // first nonce to try
+ *     uint32_t chunkSize     // number of hashes to attempt
+ *   )
+ * Returns: found nonce (0 = found at nonce 0, 0xFFFFFFFF = not found in chunk)
+ *
+ * SHA3-256 implementation: keccak-tiny (public domain, David Leon Gil, 2015)
+ * Inlined here so the WASM binary has no external dependencies.
+ */
+
+#include <stdint.h>
+#include <string.h>
+
+/* ── keccak-tiny ─────────────────────────────────────────────────────────── */
+
+#define SHA3_256_RATE 136
+#define SHA3_256_CAP  64
+
+static const uint64_t KECCAK_ROUND_CONSTANTS[24] = {
+  0x0000000000000001ULL, 0x0000000000008082ULL, 0x800000000000808AULL,
+  0x8000000080008000ULL, 0x000000000000808BULL, 0x0000000080000001ULL,
+  0x8000000080008081ULL, 0x8000000000008009ULL, 0x000000000000008AULL,
+  0x0000000000000088ULL, 0x0000000080008009ULL, 0x000000008000000AULL,
+  0x000000008000808BULL, 0x800000000000008BULL, 0x8000000000008089ULL,
+  0x8000000000008003ULL, 0x8000000000008002ULL, 0x8000000000000080ULL,
+  0x000000000000800AULL, 0x800000008000000AULL, 0x8000000080008081ULL,
+  0x8000000000008080ULL, 0x0000000080000001ULL, 0x8000000080008008ULL,
+};
+
+static const int KECCAK_RHO[24] = {
+  1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15,
+  21, 8, 18, 2, 61, 56, 14
+};
+static const int KECCAK_PI[24] = {
+  10, 7, 11, 17, 18, 3, 5, 16, 8, 21, 24, 4, 15, 23, 19, 13, 12,
+  2, 20, 14, 22, 9, 6, 1
+};
+
+#define ROL64(a, b) (((a) << (b)) | ((a) >> (64 - (b))))
+
+static void keccak_f(uint64_t* state) {
+  for (int round = 0; round < 24; round++) {
+    uint64_t C[5], D[5], tmp;
+    for (int x = 0; x < 5; x++)
+      C[x] = state[x] ^ state[x+5] ^ state[x+10] ^ state[x+15] ^ state[x+20];
+    for (int x = 0; x < 5; x++) {
+      D[x] = C[(x+4)%5] ^ ROL64(C[(x+1)%5], 1);
+      for (int y = 0; y < 5; y++) state[x + y*5] ^= D[x];
+    }
+    tmp = state[1];
+    for (int i = 0; i < 24; i++) {
+      int j = KECCAK_PI[i];
+      uint64_t t = state[j];
+      state[j] = ROL64(tmp, KECCAK_RHO[i]);
+      tmp = t;
+    }
+    for (int y = 0; y < 5; y++) {
+      uint64_t lane[5];
+      for (int x = 0; x < 5; x++) lane[x] = state[x + y*5];
+      for (int x = 0; x < 5; x++)
+        state[x + y*5] = lane[x] ^ (~lane[(x+1)%5] & lane[(x+2)%5]);
+    }
+    state[0] ^= KECCAK_ROUND_CONSTANTS[round];
+  }
+}
+
+static void sha3_256_hash(const uint8_t* msg, int msgLen, uint8_t* out) {
+  uint64_t state[25];
+  memset(state, 0, sizeof(state));
+
+  uint8_t buf[SHA3_256_RATE];
+  int absorbed = 0;
+
+  while (msgLen > 0) {
+    int take = msgLen < SHA3_256_RATE ? msgLen : SHA3_256_RATE;
+    if (absorbed + take < SHA3_256_RATE) {
+      memcpy(buf + absorbed, msg, take);
+      absorbed += take;
+      msgLen -= take;
+      msg += take;
+    } else {
+      memcpy(buf + absorbed, msg, SHA3_256_RATE - absorbed);
+      for (int i = 0; i < SHA3_256_RATE; i++)
+        ((uint8_t*)state)[i] ^= buf[i];
+      keccak_f(state);
+      absorbed = 0;
+      msg += (SHA3_256_RATE - absorbed + take - (SHA3_256_RATE - absorbed));
+      msgLen -= take;
+    }
+  }
+
+  /* Padding: SHA-3 domain = 0x06, last byte 0x80 */
+  memset(buf + absorbed, 0, SHA3_256_RATE - absorbed);
+  buf[absorbed] = 0x06;
+  buf[SHA3_256_RATE - 1] ^= 0x80;
+  for (int i = 0; i < SHA3_256_RATE; i++)
+    ((uint8_t*)state)[i] ^= buf[i];
+  keccak_f(state);
+
+  memcpy(out, state, 32);
+}
+
+/* ── Mining export ────────────────────────────────────────────────────────── */
+
+/**
+ * Mine a chunk: iterate nonce from startNonce to startNonce+chunkSize−1.
+ * Write the nonce big-endian into header[nonceOffset..nonceOffset+nonceLen).
+ * Hash the header with SHA3-256 and compare to target (32 bytes).
+ *
+ * Returns the found nonce, or 0xFFFFFFFF if not found in this chunk.
+ *
+ * NOTE: nonce value is written big-endian. For nonce 0: all zero bytes.
+ *       The caller ensures startNonce..startNonce+chunkSize stay within
+ *       the current MiniNumber encoding length boundary.
+ */
+__attribute__((used))
+uint32_t mine(
+  uint8_t* header,
+  int      headerLen,
+  int      nonceOffset,
+  int      nonceLen,
+  uint8_t* target,
+  uint32_t startNonce,
+  uint32_t chunkSize
+) {
+  uint8_t hash[32];
+
+  for (uint32_t n = startNonce; n < startNonce + chunkSize; n++) {
+    /* Write nonce big-endian */
+    uint32_t tmp = n;
+    for (int i = nonceLen - 1; i >= 0; i--) {
+      header[nonceOffset + i] = (uint8_t)(tmp & 0xFF);
+      tmp >>= 8;
+    }
+
+    sha3_256_hash(header, headerLen, hash);
+
+    /* Big-endian 256-bit compare: hash < target? */
+    int lt = 0;
+    for (int i = 0; i < 32; i++) {
+      if (hash[i] < target[i]) { lt = 1; break; }
+      if (hash[i] > target[i]) { lt = 0; break; }
+    }
+    if (lt) return n;
+  }
+
+  return 0xFFFFFFFFU;
+}