@txfence/provenance 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @txfence/provenance
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release — policy engine, intent execution, formal verification, adversarial stress testing, cryptographic provenance chains, temporal rules, and MEV protection across EVM, Solana, and Cosmos
+
+### Patch Changes
+
+- Updated dependencies
+  - @txfence/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Chauhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @txfence/provenance
+
+Cryptographically linked provenance records for txfence transactions.
+
+## What this is
+
+Every transaction gets a provenance record capturing: which agent submitted it,
+which policy version evaluated it, what the simulation returned, who approved it,
+and the final on-chain receipt. Records form a hash chain and a Merkle tree.
+
+At any point you can:
+- Prove a specific transaction was authorized under a specific policy
+- Verify the chain has not been tampered with
+- Generate a compact Merkle proof for any record
+
+## Use case
+
+Hand a compliance officer cryptographic proof that every transaction
+followed your policy:
+
+```typescript
+import { createFileProvenanceChain } from '@txfence/provenance'
+
+const chain = createFileProvenanceChain('./provenance.jsonl')
+
+// Append a record after each pipeline execution
+await chain.append({
+  agentId: '0xAGENT',
+  policyVersionId: getPolicyVersionId(policy),
+  action,
+  simulationResult,
+  approvalDecision: 'not_required',
+  outcome: { status: 'success', txHash: '0x...', confirmedAtBlock: 1000, gasUsed: '21000' },
+})
+
+// Verify the chain has not been tampered with
+const result = await chain.verify()
+console.log(result.valid)  // true if unmodified
+
+// Generate a proof for a specific transaction
+const proof = await chain.generateProof(entryHash)
+
+// Verify the proof
+console.log(chain.verifyProof(proof))  // true
+```
+
+## Tamper evidence
+
+Hash chaining: each record includes the hash of the previous record.
+Modifying any record invalidates all subsequent records.
+
+Merkle tree: the root hash commits to all records. A Merkle proof proves
+a record exists without revealing all other records.
+
+## Known limitation
+
+The chain file must be stored on tamper-evident infrastructure (S3 with
+object lock, WORM storage) for strict compliance requirements.
+The hash chain detects tampering but does not prevent it on a writable filesystem.
+
+---
+
+Full project README: https://github.com/AdityaChauhanX07/txfence
+

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { Action, SimulationResult, PolicyRejectionReason, ExecutionFailureReason, SuccessReceipt, ChainId } from '@txfence/core';
+
+type ProvenanceOutcome = {
+    status: 'success';
+    txHash: string;
+    confirmedAtBlock: number;
+    gasUsed: string;
+} | {
+    status: 'policy_rejected';
+    reason: PolicyRejectionReason;
+} | {
+    status: 'simulation_failed';
+} | {
+    status: 'approval_timeout';
+} | {
+    status: 'execution_failed';
+    reason: ExecutionFailureReason;
+} | {
+    status: 'simulation_stale';
+    stalenessMs: number;
+};
+type ProvenanceRecord = {
+    id: string;
+    previousHash: string;
+    entryHash: string;
+    timestamp: number;
+    agentId: string;
+    policyVersionId: string;
+    action: Action;
+    simulationResult?: SimulationResult;
+    approvalDecision?: 'approved' | 'rejected' | 'not_required';
+    approver?: string;
+    submittedAtBlock?: number;
+    submittedAtBlockHash?: string;
+    outcome: ProvenanceOutcome;
+    receipt?: SuccessReceipt;
+};
+type ProvenanceRecordInput = Omit<ProvenanceRecord, 'id' | 'previousHash' | 'entryHash'>;
+type MerkleProof = {
+    entryHash: string;
+    siblings: Array<{
+        hash: string;
+        position: 'left' | 'right';
+    }>;
+    root: string;
+    leafIndex: number;
+};
+type ProvenanceFilter = {
+    agentId?: string;
+    policyVersionId?: string;
+    status?: ProvenanceOutcome['status'];
+    from?: number;
+    to?: number;
+    chain?: ChainId;
+};
+type ChainViolation = {
+    entryId: string;
+    entryHash: string;
+    violation: 'hash_mismatch' | 'chain_broken' | 'invalid_hash';
+    details: string;
+};
+type ProvenanceVerificationResult = {
+    valid: boolean;
+    entryCount: number;
+    firstHash: string;
+    lastHash: string;
+    merkleRoot: string;
+    violations: ChainViolation[];
+    verifiedAt: number;
+};
+type ProvenanceChain = {
+    append: (record: ProvenanceRecordInput) => Promise<ProvenanceRecord>;
+    get: (entryHash: string) => Promise<ProvenanceRecord | null>;
+    list: (filter?: ProvenanceFilter) => Promise<ProvenanceRecord[]>;
+    head: () => Promise<ProvenanceRecord | null>;
+    verify: () => Promise<ProvenanceVerificationResult>;
+    generateProof: (entryHash: string) => Promise<MerkleProof | null>;
+    verifyProof: (proof: MerkleProof) => boolean;
+    getMerkleRoot: () => Promise<string>;
+};
+
+declare function createMemoryProvenanceChain(): ProvenanceChain;
+
+declare function createFileProvenanceChain(filePath: string): ProvenanceChain;
+
+declare function computeEntryHash(previousHash: string, record: ProvenanceRecordInput): string;
+declare const GENESIS_HASH: string;
+
+declare function buildMerkleTree(leafHashes: string[]): string[][];
+declare function getMerkleRoot(leafHashes: string[]): string;
+declare function generateMerkleProof(leafHashes: string[], targetHash: string): MerkleProof | null;
+declare function verifyMerkleProof(proof: MerkleProof): boolean;
+
+export { type ChainViolation, GENESIS_HASH, type MerkleProof, type ProvenanceChain, type ProvenanceFilter, type ProvenanceOutcome, type ProvenanceRecord, type ProvenanceRecordInput, type ProvenanceVerificationResult, buildMerkleTree, computeEntryHash, createFileProvenanceChain, createMemoryProvenanceChain, generateMerkleProof, getMerkleRoot, verifyMerkleProof };

package/dist/index.js

@@ -0,0 +1,396 @@
+// src/memory.ts
+import { randomUUID } from "crypto";
+
+// src/hash.ts
+import { createHash } from "crypto";
+function canonicalize(value) {
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = canonicalize(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function computeEntryHash(previousHash, record) {
+  const content = {
+    previousHash,
+    agentId: record.agentId,
+    policyVersionId: record.policyVersionId,
+    action: record.action,
+    simulationResult: record.simulationResult,
+    approvalDecision: record.approvalDecision,
+    approver: record.approver,
+    submittedAtBlock: record.submittedAtBlock,
+    submittedAtBlockHash: record.submittedAtBlockHash,
+    outcome: record.outcome,
+    timestamp: record.timestamp
+  };
+  const canonical = JSON.stringify(canonicalize(content));
+  return createHash("sha256").update(canonical).digest("hex");
+}
+var GENESIS_HASH = "0".repeat(64);
+
+// src/merkle.ts
+import { createHash as createHash2 } from "crypto";
+function hashPair(left, right) {
+  return createHash2("sha256").update(left + right).digest("hex");
+}
+function buildMerkleTree(leafHashes) {
+  if (leafHashes.length === 0) return [[]];
+  const levels = [leafHashes];
+  let current = leafHashes;
+  while (current.length > 1) {
+    const next = [];
+    for (let i = 0; i < current.length; i += 2) {
+      const left = current[i];
+      const right = current[i + 1] ?? current[i];
+      next.push(hashPair(left, right));
+    }
+    levels.push(next);
+    current = next;
+  }
+  return levels;
+}
+function getMerkleRoot(leafHashes) {
+  if (leafHashes.length === 0) return "0".repeat(64);
+  const tree = buildMerkleTree(leafHashes);
+  return tree[tree.length - 1]?.[0] ?? "0".repeat(64);
+}
+function generateMerkleProof(leafHashes, targetHash) {
+  const leafIndex = leafHashes.indexOf(targetHash);
+  if (leafIndex === -1) return null;
+  const tree = buildMerkleTree(leafHashes);
+  const root = tree[tree.length - 1]?.[0] ?? "0".repeat(64);
+  const siblings = [];
+  let index = leafIndex;
+  for (let level = 0; level < tree.length - 1; level++) {
+    const levelNodes = tree[level];
+    const isLeftNode = index % 2 === 0;
+    const siblingIndex = isLeftNode ? index + 1 : index - 1;
+    const siblingHash = levelNodes[siblingIndex] ?? levelNodes[index];
+    siblings.push({
+      hash: siblingHash,
+      position: isLeftNode ? "right" : "left"
+    });
+    index = Math.floor(index / 2);
+  }
+  return {
+    entryHash: targetHash,
+    siblings,
+    root,
+    leafIndex
+  };
+}
+function verifyMerkleProof(proof) {
+  let current = proof.entryHash;
+  for (const sibling of proof.siblings) {
+    if (sibling.position === "right") {
+      current = hashPair(current, sibling.hash);
+    } else {
+      current = hashPair(sibling.hash, current);
+    }
+  }
+  return current === proof.root;
+}
+
+// src/memory.ts
+function createMemoryProvenanceChain() {
+  const records = [];
+  async function append(input) {
+    const previousHash = records.length > 0 ? records[records.length - 1].entryHash : GENESIS_HASH;
+    const entryHash = computeEntryHash(previousHash, input);
+    const record = {
+      id: randomUUID(),
+      previousHash,
+      entryHash,
+      ...input
+    };
+    records.push(record);
+    return record;
+  }
+  async function get(entryHash) {
+    return records.find((r) => r.entryHash === entryHash) ?? null;
+  }
+  async function list(filter) {
+    let result = [...records];
+    if (filter?.agentId !== void 0) {
+      const v = filter.agentId;
+      result = result.filter((r) => r.agentId === v);
+    }
+    if (filter?.policyVersionId !== void 0) {
+      const v = filter.policyVersionId;
+      result = result.filter((r) => r.policyVersionId === v);
+    }
+    if (filter?.status !== void 0) {
+      const v = filter.status;
+      result = result.filter((r) => r.outcome.status === v);
+    }
+    if (filter?.from !== void 0) {
+      const v = filter.from;
+      result = result.filter((r) => r.timestamp >= v);
+    }
+    if (filter?.to !== void 0) {
+      const v = filter.to;
+      result = result.filter((r) => r.timestamp <= v);
+    }
+    if (filter?.chain !== void 0) {
+      const v = filter.chain;
+      result = result.filter((r) => r.action.chain === v);
+    }
+    return result;
+  }
+  async function head() {
+    return records[records.length - 1] ?? null;
+  }
+  async function verify() {
+    const violations = [];
+    for (let i = 0; i < records.length; i++) {
+      const record = records[i];
+      const expectedPreviousHash = i === 0 ? GENESIS_HASH : records[i - 1].entryHash;
+      if (record.previousHash !== expectedPreviousHash) {
+        violations.push({
+          entryId: record.id,
+          entryHash: record.entryHash,
+          violation: "chain_broken",
+          details: `Entry ${i}: previousHash mismatch. Expected ${expectedPreviousHash.slice(0, 8)}... got ${record.previousHash.slice(0, 8)}...`
+        });
+      }
+      const { id: _id, previousHash, entryHash, ...input } = record;
+      void _id;
+      const recomputed = computeEntryHash(previousHash, input);
+      if (recomputed !== entryHash) {
+        violations.push({
+          entryId: record.id,
+          entryHash: record.entryHash,
+          violation: "hash_mismatch",
+          details: `Entry ${i}: hash mismatch. Stored ${entryHash.slice(0, 8)}... recomputed ${recomputed.slice(0, 8)}...`
+        });
+      }
+    }
+    const leafHashes = records.map((r) => r.entryHash);
+    const merkleRoot = getMerkleRoot(leafHashes);
+    return {
+      valid: violations.length === 0,
+      entryCount: records.length,
+      firstHash: records[0]?.entryHash ?? GENESIS_HASH,
+      lastHash: records[records.length - 1]?.entryHash ?? GENESIS_HASH,
+      merkleRoot,
+      violations,
+      verifiedAt: Date.now()
+    };
+  }
+  async function generateProof(entryHash) {
+    const leafHashes = records.map((r) => r.entryHash);
+    return generateMerkleProof(leafHashes, entryHash);
+  }
+  function verifyProof(proof) {
+    return verifyMerkleProof(proof);
+  }
+  async function getMerkleRootFn() {
+    const leafHashes = records.map((r) => r.entryHash);
+    return getMerkleRoot(leafHashes);
+  }
+  return {
+    append,
+    get,
+    list,
+    head,
+    verify,
+    generateProof,
+    verifyProof,
+    getMerkleRoot: getMerkleRootFn
+  };
+}
+
+// src/file.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  renameSync,
+  mkdirSync
+} from "fs";
+import { dirname } from "path";
+import { bigintReplacer } from "@txfence/core";
+function createFileProvenanceChain(filePath) {
+  function ensureDir() {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+  function reviveRecord(raw) {
+    const action = raw["action"];
+    if (action["kind"] === "transfer") {
+      const token = action["token"];
+      if (typeof token["amount"] === "string") {
+        token["amount"] = BigInt(token["amount"]);
+      }
+    }
+    if (action["kind"] === "swap") {
+      const from = action["from"];
+      if (typeof from["amount"] === "string") {
+        from["amount"] = BigInt(from["amount"]);
+      }
+    }
+    if (action["kind"] === "contract_call" && action["value"] !== void 0) {
+      const value = action["value"];
+      if (typeof value["amount"] === "string") {
+        value["amount"] = BigInt(value["amount"]);
+      }
+    }
+    if (raw["simulationResult"] !== void 0) {
+      const sim = raw["simulationResult"];
+      if (typeof sim["gasEstimate"] === "string") {
+        sim["gasEstimate"] = BigInt(sim["gasEstimate"]);
+      }
+    }
+    return raw;
+  }
+  function readAll() {
+    if (!existsSync(filePath)) return [];
+    const content = readFileSync(filePath, "utf-8").trim();
+    if (content.length === 0) return [];
+    return content.split("\n").map((line) => {
+      const parsed = JSON.parse(line);
+      return reviveRecord(parsed);
+    });
+  }
+  function appendRecord(record) {
+    ensureDir();
+    const line = JSON.stringify(record, bigintReplacer) + "\n";
+    const tmpPath = filePath + ".tmp";
+    const existing = existsSync(filePath) ? readFileSync(filePath, "utf-8") : "";
+    writeFileSync(tmpPath, existing + line, "utf-8");
+    try {
+      renameSync(tmpPath, filePath);
+    } catch {
+      writeFileSync(filePath, existing + line, "utf-8");
+    }
+  }
+  async function append(input) {
+    const records = readAll();
+    const previousHash = records.length > 0 ? records[records.length - 1].entryHash : GENESIS_HASH;
+    const entryHash = computeEntryHash(previousHash, input);
+    const record = {
+      id: randomUUID2(),
+      previousHash,
+      entryHash,
+      ...input
+    };
+    appendRecord(record);
+    return record;
+  }
+  async function get(entryHash) {
+    const records = readAll();
+    return records.find((r) => r.entryHash === entryHash) ?? null;
+  }
+  async function list(filter) {
+    let records = readAll();
+    if (filter?.agentId !== void 0) {
+      const v = filter.agentId;
+      records = records.filter((r) => r.agentId === v);
+    }
+    if (filter?.policyVersionId !== void 0) {
+      const v = filter.policyVersionId;
+      records = records.filter((r) => r.policyVersionId === v);
+    }
+    if (filter?.status !== void 0) {
+      const v = filter.status;
+      records = records.filter((r) => r.outcome.status === v);
+    }
+    if (filter?.from !== void 0) {
+      const v = filter.from;
+      records = records.filter((r) => r.timestamp >= v);
+    }
+    if (filter?.to !== void 0) {
+      const v = filter.to;
+      records = records.filter((r) => r.timestamp <= v);
+    }
+    if (filter?.chain !== void 0) {
+      const v = filter.chain;
+      records = records.filter((r) => r.action.chain === v);
+    }
+    return records;
+  }
+  async function head() {
+    const records = readAll();
+    return records[records.length - 1] ?? null;
+  }
+  async function verify() {
+    const records = readAll();
+    const violations = [];
+    for (let i = 0; i < records.length; i++) {
+      const record = records[i];
+      const expectedPreviousHash = i === 0 ? GENESIS_HASH : records[i - 1].entryHash;
+      if (record.previousHash !== expectedPreviousHash) {
+        violations.push({
+          entryId: record.id,
+          entryHash: record.entryHash,
+          violation: "chain_broken",
+          details: `Entry ${i}: previousHash mismatch`
+        });
+      }
+      const { id: _id, previousHash, entryHash, ...input } = record;
+      void _id;
+      const recomputed = computeEntryHash(previousHash, input);
+      if (recomputed !== entryHash) {
+        violations.push({
+          entryId: record.id,
+          entryHash: record.entryHash,
+          violation: "hash_mismatch",
+          details: `Entry ${i}: hash mismatch. Record may have been tampered with.`
+        });
+      }
+    }
+    const leafHashes = records.map((r) => r.entryHash);
+    const merkleRoot = getMerkleRoot(leafHashes);
+    return {
+      valid: violations.length === 0,
+      entryCount: records.length,
+      firstHash: records[0]?.entryHash ?? GENESIS_HASH,
+      lastHash: records[records.length - 1]?.entryHash ?? GENESIS_HASH,
+      merkleRoot,
+      violations,
+      verifiedAt: Date.now()
+    };
+  }
+  async function generateProof(entryHash) {
+    const records = readAll();
+    const leafHashes = records.map((r) => r.entryHash);
+    return generateMerkleProof(leafHashes, entryHash);
+  }
+  function verifyProof(proof) {
+    return verifyMerkleProof(proof);
+  }
+  async function getMerkleRootFn() {
+    const records = readAll();
+    const leafHashes = records.map((r) => r.entryHash);
+    return getMerkleRoot(leafHashes);
+  }
+  return {
+    append,
+    get,
+    list,
+    head,
+    verify,
+    generateProof,
+    verifyProof,
+    getMerkleRoot: getMerkleRootFn
+  };
+}
+export {
+  GENESIS_HASH,
+  buildMerkleTree,
+  computeEntryHash,
+  createFileProvenanceChain,
+  createMemoryProvenanceChain,
+  generateMerkleProof,
+  getMerkleRoot,
+  verifyMerkleProof
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@txfence/provenance",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@txfence/core": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5",
+    "tsup": "^8.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}