@totemsdk/txpow 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,76 @@
+# @totemsdk/txpow
+
+**TxPoW — Minima's spam-prevention proof-of-work on every transaction.**
+
+Every Minima transaction must carry a proof-of-work envelope before it can be broadcast. This package handles the full TxPoW lifecycle: serialize, mine, verify, and calibrate.
+
+## Install
+
+```bash
+npm install @totemsdk/txpow
+```
+
+## What's inside
+
+| Export | What it does |
+|--------|-------------|
+| `serializeTxHeader` / `serializeTxBody` / `serializeTxPoW` | Byte-identical TxPoW envelope assembly |
+| `computeTxPoWId` | Derive the canonical TxPoW ID used for deduplication |
+| `mineTxPoW(txBody, target)` | Local PoW mining loop — returns `{ minedHeaderBytes }` |
+| `fetchTxPowTarget(axiaBaseUrl)` | Fetch current network difficulty from Axia |
+| `verifyProofOfWork(txpowId, difficulty)` | Verify a received TxPoW (for relay nodes) |
+| `calibrateHashRate()` | Benchmark local hardware hash rate |
+| `estimateMiningCost(difficulty)` | Estimate mining time at current hash rate |
+| `MAX_HASH`, `TX_POW_MIN_DIFFICULTY`, `CASCADE_LEVELS`, `MAIN_NET_CHAIN_ID` | Chain constants |
+
+## Usage
+
+### Mine and broadcast a transaction
+
+```typescript
+import {
+  mineTxPoW,
+  fetchTxPowTarget,
+  serializeTxPoW,
+  computeTxPoWId,
+} from '@totemsdk/txpow';
+
+// 1. Fetch current difficulty
+const target = await fetchTxPowTarget('https://api.axia.to');
+
+// 2. Mine (this runs the PoW loop — may take seconds)
+const { minedHeaderBytes } = await mineTxPoW(txBodyBytes, target);
+
+// 3. Assemble the final TxPoW envelope
+const txpowBytes = serializeTxPoW(minedHeaderBytes, txBodyBytes);
+const txpowId    = computeTxPoWId(txpowBytes);
+console.log('TxPoW ID:', txpowId);
+
+// 4. Broadcast
+await provider.broadcastTxPoW(Buffer.from(txpowBytes).toString('hex'));
+```
+
+### Verify received TxPoW
+
+```typescript
+import { verifyProofOfWork } from '@totemsdk/txpow';
+
+const ok = verifyProofOfWork(txpowId, difficulty);
+if (!ok) throw new Error('Invalid proof-of-work');
+```
+
+### Calibrate hardware
+
+```typescript
+import { calibrateHashRate, estimateMiningCost } from '@totemsdk/txpow';
+
+const hashesPerSecond = await calibrateHashRate();
+const estimatedMs     = estimateMiningCost(targetDifficulty, hashesPerSecond);
+console.log(`Expected mining time: ${estimatedMs}ms`);
+```
+
+## See also
+
+- [`@totemsdk/tx-builder`](../tx-builder) — construct `txBodyBytes` before mining
+- [`@totemsdk/node`](../node) — Node.js wallet that uses txpow internally
+- [`@totemsdk/chain-provider`](../chain-provider) — `broadcastTxPoW` endpoint

package/dist/index.d.ts

@@ -22,5 +22,5 @@ export { MAX_HASH, ZERO_HASH, TX_POW_MIN_DIFFICULTY, CASCADE_LEVELS, MAIN_NET_CH
 export { serializeMagic } from './magic.js';
 export { mineTxPoW, isLessThan, type MineResult, type MineOptions, } from './mine.js';
 export { fetchTxPowTarget, type TxPowParams } from './difficulty.js';
-export { verifyProofOfWork, type VerifyResult } from './verify.js';
+export { verifyProofOfWork, verifyTxPoWWork, type VerifyResult } from './verify.js';
 export { calibrateHashRate, estimateMiningCost, type MiningEstimate, } from './calibrate.js';

package/dist/index.js

@@ -22,5 +22,5 @@ export { MAX_HASH, ZERO_HASH, TX_POW_MIN_DIFFICULTY, CASCADE_LEVELS, MAIN_NET_CH
 export { serializeMagic } from './magic.js';
 export { mineTxPoW, isLessThan, } from './mine.js';
 export { fetchTxPowTarget } from './difficulty.js';
-export { verifyProofOfWork } from './verify.js';
+export { verifyProofOfWork, verifyTxPoWWork } from './verify.js';
 export { calibrateHashRate, estimateMiningCost, } from './calibrate.js';

package/dist/verify.d.ts

@@ -3,6 +3,11 @@
  *
  * verifyProofOfWork checks that a given txpowId beats the difficulty target
  * without re-mining. Used by relay nodes to reject under-work submissions.
+ *
+ * verifyTxPoWWork is a convenience wrapper for relay nodes that receive raw
+ * TxPoW hex: it hashes the full bytes as a proxy txpowId and checks against
+ * the network minimum difficulty. PureMinima performs authoritative validation
+ * on submission; this is a first-pass spam filter.
  */
 export interface VerifyResult {
     valid: boolean;
@@ -19,3 +24,14 @@ export interface VerifyResult {
  * @param mTxnDifficulty The 32-byte difficulty target from the TxBody.
  */
 export declare function verifyProofOfWork(txpowId: Uint8Array, mTxnDifficulty: Uint8Array): VerifyResult;
+/**
+ * Relay-side work verification from raw TxPoW hex.
+ *
+ * Validates hex format, minimum length (spam filter), then computes
+ * SHA3-256 of the serialized bytes as a proxy txpowId and checks it
+ * against TX_POW_MIN_DIFFICULTY.
+ *
+ * Note: full structural parsing of TxPoW headers is deferred to a future
+ * parser. PureMinima performs authoritative work verification on submission.
+ */
+export declare function verifyTxPoWWork(txpowHex: string): VerifyResult;

package/dist/verify.js

@@ -3,8 +3,15 @@
  *
  * verifyProofOfWork checks that a given txpowId beats the difficulty target
  * without re-mining. Used by relay nodes to reject under-work submissions.
+ *
+ * verifyTxPoWWork is a convenience wrapper for relay nodes that receive raw
+ * TxPoW hex: it hashes the full bytes as a proxy txpowId and checks against
+ * the network minimum difficulty. PureMinima performs authoritative validation
+ * on submission; this is a first-pass spam filter.
  */
 import { isLessThan } from './mine.js';
+import { computeTxPoWId } from './serialization.js';
+import { TX_POW_MIN_DIFFICULTY } from './constants.js';
 function toHex(bytes) {
     return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
 }
@@ -41,3 +48,34 @@ export function verifyProofOfWork(txpowId, mTxnDifficulty) {
         reason: valid ? undefined : 'txpowId ≥ mTxnDifficulty',
     };
 }
+/**
+ * Relay-side work verification from raw TxPoW hex.
+ *
+ * Validates hex format, minimum length (spam filter), then computes
+ * SHA3-256 of the serialized bytes as a proxy txpowId and checks it
+ * against TX_POW_MIN_DIFFICULTY.
+ *
+ * Note: full structural parsing of TxPoW headers is deferred to a future
+ * parser. PureMinima performs authoritative work verification on submission.
+ */
+export function verifyTxPoWWork(txpowHex) {
+    if (typeof txpowHex !== 'string' || !/^[0-9a-fA-F]+$/.test(txpowHex)) {
+        return {
+            valid: false,
+            txpowId: '',
+            difficulty: toHex(TX_POW_MIN_DIFFICULTY),
+            reason: 'invalid hex encoding',
+        };
+    }
+    if (txpowHex.length < 200) {
+        return {
+            valid: false,
+            txpowId: '',
+            difficulty: toHex(TX_POW_MIN_DIFFICULTY),
+            reason: 'TxPoW too short (spam filter: minimum 100 bytes)',
+        };
+    }
+    const bytes = Uint8Array.from(Buffer.from(txpowHex, 'hex'));
+    const proxyId = computeTxPoWId(bytes);
+    return verifyProofOfWork(proxyId, TX_POW_MIN_DIFFICULTY);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/txpow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TxPoW envelope serialization and proof-of-work mining for the Minima protocol",
   "type": "module",
   "main": "dist/index.js",
@@ -11,20 +11,15 @@
       "import": "./dist/index.js"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "jest --passWithNoTests"
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@totemsdk/core": "^1.0.5"
+    "@totemsdk/core": "file:../core"
   },
   "peerDependencies": {
-    "@noble/hashes": ">=1.3.0"
+    "@noble/hashes": ">=1.3.0 <2.0.0"
   },
   "peerDependenciesMeta": {
     "@noble/hashes": {
@@ -45,5 +40,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  }
+}

package/src/index.ts

@@ -47,7 +47,7 @@ export {
 
 export { fetchTxPowTarget, type TxPowParams } from './difficulty.js';
 
-export { verifyProofOfWork, type VerifyResult } from './verify.js';
+export { verifyProofOfWork, verifyTxPoWWork, type VerifyResult } from './verify.js';
 
 export {
   calibrateHashRate,

package/src/verify.ts

@@ -3,9 +3,16 @@
  *
  * verifyProofOfWork checks that a given txpowId beats the difficulty target
  * without re-mining. Used by relay nodes to reject under-work submissions.
+ *
+ * verifyTxPoWWork is a convenience wrapper for relay nodes that receive raw
+ * TxPoW hex: it hashes the full bytes as a proxy txpowId and checks against
+ * the network minimum difficulty. PureMinima performs authoritative validation
+ * on submission; this is a first-pass spam filter.
  */
 
 import { isLessThan } from './mine.js';
+import { computeTxPoWId } from './serialization.js';
+import { TX_POW_MIN_DIFFICULTY } from './constants.js';
 
 export interface VerifyResult {
   valid: boolean;
@@ -55,3 +62,35 @@ export function verifyProofOfWork(
     reason: valid ? undefined : 'txpowId ≥ mTxnDifficulty',
   };
 }
+
+/**
+ * Relay-side work verification from raw TxPoW hex.
+ *
+ * Validates hex format, minimum length (spam filter), then computes
+ * SHA3-256 of the serialized bytes as a proxy txpowId and checks it
+ * against TX_POW_MIN_DIFFICULTY.
+ *
+ * Note: full structural parsing of TxPoW headers is deferred to a future
+ * parser. PureMinima performs authoritative work verification on submission.
+ */
+export function verifyTxPoWWork(txpowHex: string): VerifyResult {
+  if (typeof txpowHex !== 'string' || !/^[0-9a-fA-F]+$/.test(txpowHex)) {
+    return {
+      valid: false,
+      txpowId: '',
+      difficulty: toHex(TX_POW_MIN_DIFFICULTY),
+      reason: 'invalid hex encoding',
+    };
+  }
+  if (txpowHex.length < 200) {
+    return {
+      valid: false,
+      txpowId: '',
+      difficulty: toHex(TX_POW_MIN_DIFFICULTY),
+      reason: 'TxPoW too short (spam filter: minimum 100 bytes)',
+    };
+  }
+  const bytes = Uint8Array.from(Buffer.from(txpowHex, 'hex'));
+  const proxyId = computeTxPoWId(bytes);
+  return verifyProofOfWork(proxyId, TX_POW_MIN_DIFFICULTY);
+}