solana-privacy-scanner-core 0.6.2 → 0.7.1

package/dist/index.cjs

@@ -30,7 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ALL_TEMPLATES: () => ALL_TEMPLATES,
+  CATEGORY_DEFINITIONS: () => CATEGORY_DEFINITIONS,
   DEFAULT_CONFIG: () => DEFAULT_CONFIG,
+  FileNicknameProvider: () => FileNicknameProvider,
+  MemoryNicknameProvider: () => MemoryNicknameProvider,
   PERMISSIVE_CONFIG: () => PERMISSIVE_CONFIG,
   PrivacyConfigSchema: () => PrivacyConfigSchema,
   RPCClient: () => RPCClient,
@@ -43,7 +47,10 @@ __export(index_exports, {
   collectTransactionData: () => collectTransactionData,
   collectWalletData: () => collectWalletData,
   compareImplementations: () => compareImplementations,
+  createAddressFormatter: () => createAddressFormatter,
   createDefaultLabelProvider: () => createDefaultLabelProvider,
+  createFileNicknameProvider: () => createFileNicknameProvider,
+  createMemoryNicknameProvider: () => createMemoryNicknameProvider,
   detectATALinkage: () => detectATALinkage,
   detectAddressReuse: () => detectAddressReuse,
   detectCounterpartyReuse: () => detectCounterpartyReuse,
@@ -52,6 +59,7 @@ __export(index_exports, {
   detectIdentityMetadataExposure: () => detectIdentityMetadataExposure,
   detectInstructionFingerprinting: () => detectInstructionFingerprinting,
   detectKnownEntityInteraction: () => detectKnownEntityInteraction,
+  detectLocationInference: () => detectLocationInference,
   detectMemoExposure: () => detectMemoExposure,
   detectMemoPII: () => detectMemoPII,
   detectPriorityFeeFingerprinting: () => detectPriorityFeeFingerprinting,
@@ -59,20 +67,34 @@ __export(index_exports, {
   detectStakingDelegationPatterns: () => detectStakingDelegationPatterns,
   detectTimingPatterns: () => detectTimingPatterns,
   detectTokenAccountLifecycle: () => detectTokenAccountLifecycle,
+  determineIdentifiability: () => determineIdentifiability,
+  displayAddress: () => displayAddress,
+  displayAddresses: () => displayAddresses,
   evaluateHeuristics: () => evaluateHeuristics,
+  findTemplate: () => findTemplate,
+  generateConclusion: () => generateConclusion,
+  generateNarrative: () => generateNarrative,
+  generateNarrativeText: () => generateNarrativeText,
   generateReport: () => generateReport,
+  getAddressDisplayInfo: () => getAddressDisplayInfo,
+  getCategoriesInOrder: () => getCategoriesInOrder,
   getEnvironmentConfig: () => getEnvironmentConfig,
+  getIdentifiabilityDescription: () => getIdentifiabilityDescription,
   getMemoRecommendations: () => getMemoRecommendations,
+  getSignalCategory: () => getSignalCategory,
   getTestWallet: () => getTestWallet,
   groupIssuesByFile: () => groupIssuesByFile,
   loadConfig: () => loadConfig,
   normalizeProgramData: () => normalizeProgramData,
   normalizeTransactionData: () => normalizeTransactionData,
   normalizeWalletData: () => normalizeWalletData,
+  parseNicknameStore: () => parseNicknameStore,
+  serializeNicknameStore: () => serializeNicknameStore,
   shouldEnforce: () => shouldEnforce,
   simulateTransactionFlow: () => simulateTransactionFlow,
   simulateTransactionPrivacy: () => simulateTransactionPrivacy,
-  sortIssues: () => sortIssues
+  sortIssues: () => sortIssues,
+  truncateAddress: () => truncateAddress
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -80,9 +102,9 @@ module.exports = __toCommonJS(index_exports);
 var import_web3 = require("@solana/web3.js");
 
 // src/constants.ts
-var _RPC_ENCODED = "aHR0cHM6Ly9zZXJlbmUtcm91Z2gtcG9vbC5zb2xhbmEtbWFpbm5ldC5xdWlrbm9kZS5wcm8vYTliM2RkNGRkMzc0MzYwYzQzNzY4YzQyMTI2NmE2ZGNlZDU4MTI3Ny8=";
+var _RPC_ENCODED = "aHR0cHM6Ly9sYXRlLWhhcmR3b3JraW5nLXdhdGVyZmFsbC5zb2xhbmEtbWFpbm5ldC5xdWlrbm9kZS5wcm8vNDAxN2I0OGFjZjNhMmExNjY1NjAzY2FjMDk2ODIyY2U0YmVjM2E5MC8=";
 var DEFAULT_RPC_URL = /* @__PURE__ */ Buffer.from(_RPC_ENCODED, "base64").toString("utf-8");
-var VERSION = "0.6.2";
+var VERSION = "0.7.1";
 
 // src/rpc/client.ts
 var RateLimiter = class {
@@ -433,23 +455,38 @@ var PROGRAM_IDS = {
   MEMO: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
   MEMO_V1: "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo"
 };
+function getAccountKeys(tx) {
+  const message = tx?.transaction?.message;
+  if (!message) return [];
+  if (message.accountKeys && Array.isArray(message.accountKeys)) {
+    return message.accountKeys.map(
+      (key) => typeof key === "string" ? key : key.pubkey?.toString() || key.toString()
+    );
+  }
+  if (message.staticAccountKeys && Array.isArray(message.staticAccountKeys)) {
+    const staticKeys = message.staticAccountKeys.map(
+      (key) => typeof key === "string" ? key : key.toString()
+    );
+    return staticKeys;
+  }
+  return [];
+}
 function extractTransactionMetadata(tx, signature) {
-  if (!tx || !tx.transaction || !tx.transaction.message || !tx.transaction.message.accountKeys) {
+  const accountKeys = getAccountKeys(tx);
+  if (!tx || !tx.transaction || !tx.transaction.message || accountKeys.length === 0) {
     return {
       signature,
-      blockTime: tx?.blockTime || null,
+      blockTime: tx?.blockTime ?? null,
       feePayer: "unknown",
       signers: []
     };
   }
-  const feePayer = tx.transaction.message.accountKeys[0];
-  const feePayerAddress = typeof feePayer === "string" ? feePayer : feePayer.pubkey.toString();
-  const signers = [];
-  const accountKeys = tx.transaction.message.accountKeys;
-  signers.push(feePayerAddress);
-  if (accountKeys && Array.isArray(accountKeys)) {
-    for (let i = 1; i < accountKeys.length; i++) {
-      const key = accountKeys[i];
+  const feePayerAddress = accountKeys[0];
+  const signers = [feePayerAddress];
+  const legacyKeys = tx.transaction.message.accountKeys;
+  if (legacyKeys && Array.isArray(legacyKeys)) {
+    for (let i = 1; i < legacyKeys.length; i++) {
+      const key = legacyKeys[i];
       const address = typeof key === "string" ? key : key.pubkey?.toString();
       if (typeof key !== "string" && key.signer) {
         if (address && !signers.includes(address)) {
@@ -458,26 +495,75 @@ function extractTransactionMetadata(tx, signature) {
       }
     }
   }
+  const header = tx.transaction.message.header;
+  if (header && header.numRequiredSignatures > 1) {
+    for (let i = 1; i < header.numRequiredSignatures && i < accountKeys.length; i++) {
+      if (!signers.includes(accountKeys[i])) {
+        signers.push(accountKeys[i]);
+      }
+    }
+  }
   let memo;
-  const instructions = tx.transaction.message.instructions;
-  if (instructions && Array.isArray(instructions)) {
-    for (const instruction of instructions) {
-      if (!instruction || !instruction.programId) continue;
-      const programId = instruction.programId.toString();
-      if (programId === PROGRAM_IDS.MEMO || programId === PROGRAM_IDS.MEMO_V1) {
-        if ("parsed" in instruction && instruction.parsed) {
-          const parsed = instruction.parsed;
-          if (parsed.type === "memo" && typeof parsed.info === "string") {
-            memo = parsed.info;
+  const legacyInstructions = tx.transaction.message.instructions;
+  if (legacyInstructions && Array.isArray(legacyInstructions)) {
+    for (const instruction of legacyInstructions) {
+      if (!instruction) continue;
+      if (instruction.programId) {
+        const programId = instruction.programId.toString();
+        if (programId === PROGRAM_IDS.MEMO || programId === PROGRAM_IDS.MEMO_V1) {
+          if ("parsed" in instruction && instruction.parsed) {
+            const parsed = instruction.parsed;
+            if (parsed.type === "memo" && typeof parsed.info === "string") {
+              memo = parsed.info;
+            }
+          } else if ("data" in instruction && typeof instruction.data === "string") {
+            try {
+              memo = Buffer.from(instruction.data, "base64").toString("utf8");
+            } catch {
+              memo = instruction.data;
+            }
           }
-        } else if ("data" in instruction && typeof instruction.data === "string") {
-          try {
-            memo = Buffer.from(instruction.data, "base64").toString("utf8");
-          } catch {
-            memo = instruction.data;
+          break;
+        }
+      } else if ("programIdIndex" in instruction && accountKeys.length > 0) {
+        const programIdIndex = instruction.programIdIndex;
+        if (programIdIndex >= 0 && programIdIndex < accountKeys.length) {
+          const programId = accountKeys[programIdIndex];
+          if (programId === PROGRAM_IDS.MEMO || programId === PROGRAM_IDS.MEMO_V1) {
+            const data = instruction.data;
+            if (data) {
+              try {
+                memo = Buffer.from(data, "base64").toString("utf8");
+              } catch {
+                memo = data;
+              }
+            }
+            break;
+          }
+        }
+      }
+    }
+  }
+  if (!memo) {
+    const compiledInstructions = tx.transaction.message.compiledInstructions;
+    if (compiledInstructions && Array.isArray(compiledInstructions) && accountKeys.length > 0) {
+      for (const instruction of compiledInstructions) {
+        if (!instruction) continue;
+        const programIdIndex = instruction.programIdIndex;
+        if (programIdIndex >= 0 && programIdIndex < accountKeys.length) {
+          const programId = accountKeys[programIdIndex];
+          if (programId === PROGRAM_IDS.MEMO || programId === PROGRAM_IDS.MEMO_V1) {
+            const data = instruction.data;
+            if (data) {
+              try {
+                memo = Buffer.from(data, "base64").toString("utf8");
+              } catch {
+                memo = data;
+              }
+            }
+            break;
           }
         }
-        break;
       }
     }
   }
@@ -491,7 +577,7 @@ function extractTransactionMetadata(tx, signature) {
   }
   return {
     signature,
-    blockTime: tx.blockTime,
+    blockTime: tx.blockTime ?? null,
     feePayer: feePayerAddress,
     signers,
     computeUnitsUsed,
@@ -738,35 +824,78 @@ function extractInstructions(tx, signature) {
     return instructions;
   }
   const message = tx.transaction.message;
-  const allInstructions = message.instructions;
-  if (!allInstructions || !Array.isArray(allInstructions)) {
-    return instructions;
-  }
-  for (const instruction of allInstructions) {
-    if (!instruction || !instruction.programId) {
-      continue;
-    }
-    const programId = instruction.programId.toString();
-    const category = categorizeInstruction(instruction);
-    let data;
-    if ("parsed" in instruction) {
-      data = instruction.parsed;
+  const accountKeys = getAccountKeys(tx);
+  const legacyInstructions = message.instructions;
+  if (legacyInstructions && Array.isArray(legacyInstructions)) {
+    for (const instruction of legacyInstructions) {
+      if (!instruction) continue;
+      if (instruction.programId) {
+        const programId = instruction.programId.toString();
+        const category = categorizeInstruction(instruction);
+        let data;
+        if ("parsed" in instruction) {
+          data = instruction.parsed;
+        }
+        const accounts = [];
+        if ("accounts" in instruction && Array.isArray(instruction.accounts)) {
+          for (const acc of instruction.accounts) {
+            const address = typeof acc === "string" ? acc : acc.toString();
+            accounts.push(address);
+          }
+        }
+        instructions.push({
+          programId,
+          category,
+          signature,
+          blockTime: tx.blockTime,
+          data,
+          accounts: accounts.length > 0 ? accounts : void 0
+        });
+      } else if ("programIdIndex" in instruction && accountKeys.length > 0) {
+        const programIdIndex = instruction.programIdIndex;
+        if (programIdIndex >= 0 && programIdIndex < accountKeys.length) {
+          const programId = accountKeys[programIdIndex];
+          const accounts = [];
+          const accountIndices = instruction.accounts || instruction.accountKeyIndexes || [];
+          for (const idx of accountIndices) {
+            if (idx >= 0 && idx < accountKeys.length) {
+              accounts.push(accountKeys[idx]);
+            }
+          }
+          instructions.push({
+            programId,
+            category: "program_interaction",
+            signature,
+            blockTime: tx.blockTime,
+            accounts: accounts.length > 0 ? accounts : void 0
+          });
+        }
+      }
     }
-    const accounts = [];
-    if ("accounts" in instruction && Array.isArray(instruction.accounts)) {
-      for (const acc of instruction.accounts) {
-        const address = typeof acc === "string" ? acc : acc.toString();
-        accounts.push(address);
+  }
+  const compiledInstructions = message.compiledInstructions;
+  if (compiledInstructions && Array.isArray(compiledInstructions) && accountKeys.length > 0) {
+    for (const instruction of compiledInstructions) {
+      if (!instruction) continue;
+      const programIdIndex = instruction.programIdIndex;
+      if (programIdIndex >= 0 && programIdIndex < accountKeys.length) {
+        const programId = accountKeys[programIdIndex];
+        const accounts = [];
+        const accountIndices = instruction.accountKeyIndexes || [];
+        for (const idx of accountIndices) {
+          if (idx >= 0 && idx < accountKeys.length) {
+            accounts.push(accountKeys[idx]);
+          }
+        }
+        instructions.push({
+          programId,
+          category: "program_interaction",
+          signature,
+          blockTime: tx.blockTime,
+          accounts: accounts.length > 0 ? accounts : void 0
+        });
       }
     }
-    instructions.push({
-      programId,
-      category,
-      signature,
-      blockTime: tx.blockTime,
-      data,
-      accounts: accounts.length > 0 ? accounts : void 0
-    });
   }
   return instructions;
 }
@@ -823,7 +952,6 @@ function normalizeWalletData(rawData, labelProvider) {
     }
   }
   const counterparties = extractCounterparties(allTransfers, rawData.address);
-  const labels = labelProvider ? labelProvider.lookupMany(Array.from(counterparties)) : /* @__PURE__ */ new Map();
   const timeRange = calculateTimeRange(transactions);
   const tokenAccounts = rawData.tokenAccounts.map((ta) => {
     try {
@@ -848,6 +976,8 @@ function normalizeWalletData(rawData, labelProvider) {
   for (const instruction of allInstructions) {
     programs.add(instruction.programId);
   }
+  const allAddressesToLookup = [...counterparties, ...programs];
+  const labels = labelProvider ? labelProvider.lookupMany(allAddressesToLookup) : /* @__PURE__ */ new Map();
   return {
     target: rawData.address,
     targetType: "wallet",
@@ -908,7 +1038,8 @@ function normalizeTransactionData(rawData, labelProvider) {
       console.warn(`Failed to normalize transaction ${rawData.signature}:`, error);
     }
   }
-  const labels = labelProvider ? labelProvider.lookupMany(Array.from(counterparties)) : /* @__PURE__ */ new Map();
+  const allAddressesToLookup = [...counterparties, ...programs];
+  const labels = labelProvider ? labelProvider.lookupMany(allAddressesToLookup) : /* @__PURE__ */ new Map();
   return {
     target: rawData.signature,
     targetType: "transaction",
@@ -1275,6 +1406,12 @@ function detectKnownEntityInteraction(context) {
         }
       }
     }
+    if (context.programs.has(address)) {
+      const programUsageCount = context.instructions.filter(
+        (instr) => instr.programId === address
+      ).length;
+      interactionCount += programUsageCount || 1;
+    }
     if (interactionCount > 0) {
       if (!entityTypeGroups.has(label.type)) {
         entityTypeGroups.set(label.type, []);
@@ -1329,7 +1466,68 @@ function detectKnownEntityInteraction(context) {
       evidence
     });
   }
-  const others = Array.from(entityTypeGroups.entries()).filter(([type]) => type !== "exchange" && type !== "bridge");
+  const feePayers = entityTypeGroups.get("fee-payer");
+  if (feePayers && feePayers.length > 0) {
+    const evidence = feePayers.map((entity) => ({
+      description: `${entity.count} interaction(s) with ${entity.label.name}`,
+      severity: "HIGH",
+      reference: entity.address
+    }));
+    const totalFeePayerTxs = feePayers.reduce((sum, e) => sum + e.count, 0);
+    signals.push({
+      id: "known-entity-fee-payer",
+      name: "Fee Payer / Relay Service Usage",
+      severity: "HIGH",
+      confidence: 0.9,
+      category: "identity-linkage",
+      reason: `This wallet used ${feePayers.length} fee payer or relay service(s) across ${totalFeePayerTxs} transaction(s). These services process your transactions and may log activity.`,
+      impact: "Fee payer services see all transactions they sponsor. If the service keeps logs or requires authentication, your wallet activity could be linked to your identity.",
+      mitigation: "Only use fee payer services that have strong privacy policies. Consider using your own SOL for transaction fees when privacy is critical.",
+      evidence
+    });
+  }
+  const marketplaces = entityTypeGroups.get("marketplace");
+  if (marketplaces && marketplaces.length > 0) {
+    const evidence = marketplaces.map((entity) => ({
+      description: `${entity.count} interaction(s) with ${entity.label.name}`,
+      severity: "MEDIUM",
+      reference: entity.address
+    }));
+    signals.push({
+      id: "known-entity-marketplace",
+      name: "NFT Marketplace Activity",
+      severity: "MEDIUM",
+      confidence: 0.8,
+      category: "behavioral",
+      reason: `This wallet traded on ${marketplaces.length} NFT marketplace(s). NFT transactions reveal collecting interests and can be linked to social profiles.`,
+      impact: "NFT purchases are public and often tied to social accounts (Twitter, Discord). Unique NFT holdings can identify you across platforms.",
+      mitigation: "Use a dedicated wallet for NFT trading. Avoid linking NFT wallets to public social profiles.",
+      evidence
+    });
+  }
+  const privacyProtocols = entityTypeGroups.get("privacy");
+  const mixers = entityTypeGroups.get("mixer");
+  const allPrivacy = [...privacyProtocols || [], ...mixers || []];
+  if (allPrivacy.length > 0) {
+    const evidence = allPrivacy.map((entity) => ({
+      description: `${entity.count} interaction(s) with ${entity.label.name}`,
+      severity: "LOW",
+      reference: entity.address
+    }));
+    signals.push({
+      id: "known-entity-privacy",
+      name: "Privacy Protocol Usage",
+      severity: "LOW",
+      confidence: 0.85,
+      category: "behavioral",
+      reason: `This wallet interacted with ${allPrivacy.length} privacy-enhancing protocol(s). While privacy tools improve anonymity, the interaction itself is publicly visible.`,
+      impact: "Using privacy protocols is a positive step, but observers can see you used these services. Some jurisdictions scrutinize privacy tool usage.",
+      mitigation: "Continue using privacy tools but be aware the interaction is visible. Consider using a separate wallet for privacy protocol interactions.",
+      evidence
+    });
+  }
+  const handledTypes = ["exchange", "bridge", "fee-payer", "marketplace", "privacy", "mixer"];
+  const others = Array.from(entityTypeGroups.entries()).filter(([type]) => !handledTypes.includes(type));
   if (others.length > 0) {
     const allOtherEntities = others.flatMap(([_, entities]) => entities);
     const evidence = allOtherEntities.slice(0, 5).map((entity) => ({
@@ -1359,10 +1557,11 @@ function detectKnownEntityInteraction(context) {
     }
     const concentration = interactionCount / context.transfers.length;
     if (concentration > 0.3 && interactionCount >= 5) {
+      const isHighRiskType = label.type === "exchange" || label.type === "fee-payer";
       signals.push({
         id: `known-entity-frequent-${address.slice(0, 8)}`,
         name: "Frequent Single Entity Interaction",
-        severity: label.type === "exchange" ? "HIGH" : "MEDIUM",
+        severity: isHighRiskType ? "HIGH" : "MEDIUM",
         confidence: 0.85,
         category: "behavioral",
         reason: `${Math.round(concentration * 100)}% of this wallet's transfers (${interactionCount} out of ${context.transfers.length}) go to or come from ${label.name}. This makes it easy to see what service you use the most.`,
@@ -1370,7 +1569,7 @@ function detectKnownEntityInteraction(context) {
         mitigation: "Spread your activity across different services, or use a dedicated wallet for each service you use frequently.",
         evidence: [{
           description: `${interactionCount} transfers with ${label.name} (${label.type})`,
-          severity: label.type === "exchange" ? "HIGH" : "MEDIUM",
+          severity: isHighRiskType ? "HIGH" : "MEDIUM",
           reference: address
         }]
       });
@@ -2466,6 +2665,238 @@ function detectIdentityMetadataExposure(context) {
   return signals;
 }
 
+// src/heuristics/location-inference.ts
+var TIMEZONE_REGIONS = {
+  "UTC-12": { offset: -12, region: "Baker Island, Howland Island" },
+  "UTC-11": { offset: -11, region: "American Samoa, Niue" },
+  "UTC-10": { offset: -10, region: "Hawaii, Tahiti" },
+  "UTC-9": { offset: -9, region: "Alaska" },
+  "UTC-8": { offset: -8, region: "US Pacific (LA, San Francisco)" },
+  "UTC-7": { offset: -7, region: "US Mountain (Denver, Phoenix)" },
+  "UTC-6": { offset: -6, region: "US Central (Chicago, Dallas)" },
+  "UTC-5": { offset: -5, region: "US Eastern (NYC, Miami)" },
+  "UTC-4": { offset: -4, region: "Atlantic (Puerto Rico, Bermuda)" },
+  "UTC-3": { offset: -3, region: "Brazil, Argentina" },
+  "UTC-2": { offset: -2, region: "Mid-Atlantic" },
+  "UTC-1": { offset: -1, region: "Azores, Cape Verde" },
+  "UTC+0": { offset: 0, region: "UK, Portugal, West Africa" },
+  "UTC+1": { offset: 1, region: "Western Europe (Paris, Berlin)" },
+  "UTC+2": { offset: 2, region: "Eastern Europe (Cairo, Athens)" },
+  "UTC+3": { offset: 3, region: "Moscow, Middle East" },
+  "UTC+4": { offset: 4, region: "UAE, Armenia" },
+  "UTC+5": { offset: 5, region: "Pakistan, West Asia" },
+  "UTC+5.5": { offset: 5.5, region: "India, Sri Lanka" },
+  "UTC+6": { offset: 6, region: "Bangladesh, Central Asia" },
+  "UTC+7": { offset: 7, region: "Thailand, Vietnam, Indonesia" },
+  "UTC+8": { offset: 8, region: "China, Singapore, Hong Kong" },
+  "UTC+9": { offset: 9, region: "Japan, Korea" },
+  "UTC+10": { offset: 10, region: "Australia East (Sydney)" },
+  "UTC+11": { offset: 11, region: "Solomon Islands, Vanuatu" },
+  "UTC+12": { offset: 12, region: "New Zealand, Fiji" }
+};
+function detectLocationInference(context) {
+  const signals = [];
+  if (!context.transactions || context.transactions.length < 20) {
+    return signals;
+  }
+  const timestamps = context.transactions.map((tx) => tx.blockTime).filter((time) => time !== void 0).sort((a, b) => a - b);
+  if (timestamps.length < 20) {
+    return signals;
+  }
+  const timeSpanDays = (timestamps[timestamps.length - 1] - timestamps[0]) / 86400;
+  if (timeSpanDays < 3) {
+    return signals;
+  }
+  const sleepAnalysis = analyzeSleepGaps(timestamps);
+  if (sleepAnalysis) {
+    signals.push(sleepAnalysis);
+  }
+  const dayOfWeekAnalysis = analyzeDayOfWeekPatterns(timestamps);
+  if (dayOfWeekAnalysis) {
+    signals.push(dayOfWeekAnalysis);
+  }
+  const timezoneEstimate = estimateTimezone(timestamps);
+  if (timezoneEstimate) {
+    signals.push(timezoneEstimate);
+  }
+  return signals;
+}
+function analyzeSleepGaps(timestamps) {
+  const dayGroups = /* @__PURE__ */ new Map();
+  timestamps.forEach((ts) => {
+    const date = new Date(ts * 1e3);
+    const dayKey = `${date.getUTCFullYear()}-${date.getUTCMonth()}-${date.getUTCDate()}`;
+    if (!dayGroups.has(dayKey)) {
+      dayGroups.set(dayKey, []);
+    }
+    dayGroups.get(dayKey).push(ts);
+  });
+  if (dayGroups.size < 5) {
+    return null;
+  }
+  const gaps = [];
+  for (let i = 1; i < timestamps.length; i++) {
+    const gapSeconds = timestamps[i] - timestamps[i - 1];
+    const gapHours = gapSeconds / 3600;
+    if (gapHours >= 5 && gapHours <= 12) {
+      const startDate = new Date(timestamps[i - 1] * 1e3);
+      const endDate = new Date(timestamps[i] * 1e3);
+      gaps.push({
+        gapHours,
+        startHour: startDate.getUTCHours(),
+        endHour: endDate.getUTCHours()
+      });
+    }
+  }
+  if (gaps.length < 5) {
+    return null;
+  }
+  const gapStartHours = gaps.map((g) => g.startHour);
+  const hourBuckets = /* @__PURE__ */ new Map();
+  gapStartHours.forEach((hour) => {
+    const bucket = Math.round(hour / 2) * 2;
+    hourBuckets.set(bucket, (hourBuckets.get(bucket) || 0) + 1);
+  });
+  let peakBucket = 0;
+  let peakCount = 0;
+  hourBuckets.forEach((count, bucket) => {
+    if (count > peakCount) {
+      peakCount = count;
+      peakBucket = bucket;
+    }
+  });
+  const gapConcentration = peakCount / gaps.length;
+  if (gapConcentration < 0.5) {
+    return null;
+  }
+  const avgGapHours = gaps.reduce((sum, g) => sum + g.gapHours, 0) / gaps.length;
+  const sleepStartUTC = peakBucket;
+  const sleepEndUTC = (peakBucket + Math.round(avgGapHours)) % 24;
+  const estimatedOffset = (23 - sleepStartUTC + 12) % 24 - 12;
+  const evidence = [{
+    description: `${gaps.length} sleep-like gaps detected (avg ${avgGapHours.toFixed(1)} hours)`,
+    severity: "MEDIUM",
+    reference: void 0
+  }, {
+    description: `Gaps typically start around ${sleepStartUTC}:00-${(sleepStartUTC + 2) % 24}:00 UTC`,
+    severity: "MEDIUM",
+    reference: void 0
+  }];
+  return {
+    id: "location-sleep-pattern",
+    name: "Sleep Pattern Detected",
+    severity: "MEDIUM",
+    confidence: 0.6 + gapConcentration * 0.2,
+    // Higher confidence with more consistent gaps
+    category: "behavioral",
+    reason: `Your transaction history shows consistent ${avgGapHours.toFixed(1)}-hour gaps that look like sleep periods. These gaps typically start around ${sleepStartUTC}:00 UTC, suggesting you may be in a timezone around UTC${estimatedOffset >= 0 ? "+" : ""}${estimatedOffset}.`,
+    impact: "Sleep patterns are one of the strongest indicators of geographic location. Combined with other timing data, this can narrow down where you live to a specific timezone.",
+    mitigation: "Schedule some transactions during your typical sleep hours using automation. Even occasional activity during sleep hours breaks this pattern.",
+    evidence
+  };
+}
+function analyzeDayOfWeekPatterns(timestamps) {
+  const dayCounts = [0, 0, 0, 0, 0, 0, 0];
+  timestamps.forEach((ts) => {
+    const day = new Date(ts * 1e3).getUTCDay();
+    dayCounts[day]++;
+  });
+  const weekdayCount = dayCounts[1] + dayCounts[2] + dayCounts[3] + dayCounts[4] + dayCounts[5];
+  const weekendCount = dayCounts[0] + dayCounts[6];
+  const weekdayRate = weekdayCount / 5;
+  const weekendRate = weekendCount / 2;
+  const totalTx = timestamps.length;
+  const weekdayRatio = weekdayCount / totalTx;
+  const weekendRatio = weekendCount / totalTx;
+  const rateRatio = weekdayRate > 0 && weekendRate > 0 ? Math.max(weekdayRate / weekendRate, weekendRate / weekdayRate) : 0;
+  if (rateRatio < 2) {
+    return null;
+  }
+  const moreActiveOn = weekdayRate > weekendRate ? "weekdays" : "weekends";
+  const lessActiveOn = weekdayRate > weekendRate ? "weekends" : "weekdays";
+  const evidence = [{
+    description: `${Math.round(weekdayRatio * 100)}% weekday / ${Math.round(weekendRatio * 100)}% weekend activity`,
+    severity: "LOW",
+    reference: void 0
+  }];
+  const dayNames = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  const dayBreakdown = dayCounts.map((count, i) => `${dayNames[i]}: ${count}`).join(", ");
+  evidence.push({
+    description: `Daily breakdown: ${dayBreakdown}`,
+    severity: "LOW",
+    reference: void 0
+  });
+  return {
+    id: "location-weekday-pattern",
+    name: "Weekday/Weekend Activity Pattern",
+    severity: "LOW",
+    confidence: 0.65,
+    category: "behavioral",
+    reason: `You are ${rateRatio.toFixed(1)}x more active on ${moreActiveOn} than ${lessActiveOn}. This pattern is consistent with typical work schedules and can indicate your occupation type.`,
+    impact: "Different activity levels on weekdays vs weekends can reveal whether you have a traditional work schedule, shift work, or other lifestyle patterns.",
+    mitigation: "Spread transactions more evenly across the week, or use scheduled transactions to add activity on your less active days.",
+    evidence
+  };
+}
+function estimateTimezone(timestamps) {
+  const hourCounts = new Array(24).fill(0);
+  timestamps.forEach((ts) => {
+    const hour = new Date(ts * 1e3).getUTCHours();
+    hourCounts[hour]++;
+  });
+  let minActivityWindow = { start: 0, count: Infinity };
+  for (let start = 0; start < 24; start++) {
+    let windowCount = 0;
+    for (let i = 0; i < 8; i++) {
+      windowCount += hourCounts[(start + i) % 24];
+    }
+    if (windowCount < minActivityWindow.count) {
+      minActivityWindow = { start, count: windowCount };
+    }
+  }
+  const totalTx = timestamps.length;
+  const avgTxPerHour = totalTx / 24;
+  const inactiveWindowAvg = minActivityWindow.count / 8;
+  if (inactiveWindowAvg >= avgTxPerHour * 0.5) {
+    return null;
+  }
+  const inactiveStartUTC = minActivityWindow.start;
+  let estimatedOffset = -inactiveStartUTC;
+  if (estimatedOffset < -12) estimatedOffset += 24;
+  if (estimatedOffset > 12) estimatedOffset -= 24;
+  const offsetKey = estimatedOffset === Math.floor(estimatedOffset) ? `UTC${estimatedOffset >= 0 ? "+" : ""}${estimatedOffset}` : `UTC${estimatedOffset >= 0 ? "+" : ""}${estimatedOffset}`;
+  const timezoneInfo = TIMEZONE_REGIONS[offsetKey];
+  const regionHint = timezoneInfo?.region || "Unknown region";
+  const inactiveRatio = inactiveWindowAvg / avgTxPerHour;
+  const confidence = Math.min(0.85, 0.5 + (1 - inactiveRatio) * 0.4);
+  const activeStartUTC = (minActivityWindow.start + 8) % 24;
+  const activeEndUTC = minActivityWindow.start;
+  const evidence = [{
+    description: `Least active: ${minActivityWindow.start}:00-${(minActivityWindow.start + 8) % 24}:00 UTC (${minActivityWindow.count} tx)`,
+    severity: "HIGH",
+    reference: void 0
+  }, {
+    description: `Most active: ${activeStartUTC}:00-${activeEndUTC}:00 UTC`,
+    severity: "HIGH",
+    reference: void 0
+  }, {
+    description: `Estimated timezone: UTC${estimatedOffset >= 0 ? "+" : ""}${estimatedOffset} (${regionHint})`,
+    severity: "HIGH",
+    reference: void 0
+  }];
+  return {
+    id: "location-timezone-estimate",
+    name: "Geographic Location Inference",
+    severity: "HIGH",
+    confidence,
+    category: "behavioral",
+    reason: `Based on your transaction timing patterns, you appear to be active between ${activeStartUTC}:00-${activeEndUTC}:00 UTC and inactive between ${minActivityWindow.start}:00-${(minActivityWindow.start + 8) % 24}:00 UTC. This suggests a timezone around UTC${estimatedOffset >= 0 ? "+" : ""}${estimatedOffset}, which corresponds to regions like: ${regionHint}.`,
+    impact: "Timezone estimation is a powerful deanonymization technique. Combined with other data (language preferences, protocol usage), it can significantly narrow down your geographic location.",
+    mitigation: "Use transaction scheduling to maintain activity during your typical inactive hours. Random timing offsets make timezone inference much harder.",
+    evidence
+  };
+}
+
 // src/scanner/index.ts
 var REPORT_VERSION = "1.0.0";
 var HEURISTICS = [
@@ -2483,7 +2914,9 @@ var HEURISTICS = [
   detectPriorityFeeFingerprinting,
   detectStakingDelegationPatterns,
   // Timing analysis
-  detectTimingPatterns
+  detectTimingPatterns,
+  // Location inference (requires more data)
+  detectLocationInference
 ];
 function calculateOverallRisk(signals) {
   if (signals.length === 0) {
@@ -2693,6 +3126,247 @@ function createDefaultLabelProvider() {
   return new StaticLabelProvider();
 }
 
+// src/nicknames/provider.ts
+var import_fs2 = require("fs");
+function isValidNicknameStore(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const store = obj;
+  return store.version === "1.0.0" && typeof store.nicknames === "object" && store.nicknames !== null && typeof store.createdAt === "number" && typeof store.updatedAt === "number";
+}
+var MemoryNicknameProvider = class {
+  nicknames;
+  createdAt;
+  updatedAt;
+  constructor(initialStore) {
+    this.nicknames = /* @__PURE__ */ new Map();
+    const now = Date.now();
+    this.createdAt = now;
+    this.updatedAt = now;
+    if (initialStore) {
+      this.import(initialStore, true);
+    }
+  }
+  get(address) {
+    return this.nicknames.get(address) ?? null;
+  }
+  set(address, nickname) {
+    if (!address || !nickname) {
+      throw new Error("Address and nickname are required");
+    }
+    if (address.length < 32 || address.length > 44) {
+      throw new Error("Invalid Solana address length");
+    }
+    const trimmed = nickname.trim().slice(0, 50);
+    if (trimmed.length === 0) {
+      throw new Error("Nickname cannot be empty");
+    }
+    this.nicknames.set(address, trimmed);
+    this.updatedAt = Date.now();
+  }
+  remove(address) {
+    if (this.nicknames.delete(address)) {
+      this.updatedAt = Date.now();
+    }
+  }
+  has(address) {
+    return this.nicknames.has(address);
+  }
+  getAll() {
+    return new Map(this.nicknames);
+  }
+  count() {
+    return this.nicknames.size;
+  }
+  export() {
+    return {
+      version: "1.0.0",
+      nicknames: Object.fromEntries(this.nicknames),
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt
+    };
+  }
+  import(store, overwrite = false) {
+    if (!isValidNicknameStore(store)) {
+      throw new Error("Invalid nickname store format");
+    }
+    for (const [address, nickname] of Object.entries(store.nicknames)) {
+      if (overwrite || !this.nicknames.has(address)) {
+        if (typeof nickname === "string" && nickname.trim().length > 0) {
+          this.nicknames.set(address, nickname.trim().slice(0, 50));
+        }
+      }
+    }
+    this.updatedAt = Date.now();
+  }
+  clear() {
+    this.nicknames.clear();
+    this.updatedAt = Date.now();
+  }
+};
+var FileNicknameProvider = class extends MemoryNicknameProvider {
+  filePath;
+  autoSave;
+  /**
+   * Create a file-based nickname provider
+   * @param filePath - Path to the JSON file
+   * @param autoSave - Whether to automatically save on every change (default: true)
+   */
+  constructor(filePath, autoSave = true) {
+    super();
+    this.filePath = filePath;
+    this.autoSave = autoSave;
+    this.loadFromFile();
+  }
+  /**
+   * Load nicknames from the file
+   */
+  loadFromFile() {
+    if (!(0, import_fs2.existsSync)(this.filePath)) {
+      return;
+    }
+    try {
+      const data = (0, import_fs2.readFileSync)(this.filePath, "utf-8");
+      const parsed = JSON.parse(data);
+      if (isValidNicknameStore(parsed)) {
+        this.import(parsed, true);
+        this.createdAt = parsed.createdAt;
+      } else {
+        console.warn(`Invalid nickname store format in ${this.filePath}`);
+      }
+    } catch (error) {
+      console.warn(`Failed to load nicknames from ${this.filePath}:`, error);
+    }
+  }
+  /**
+   * Save nicknames to the file
+   */
+  save() {
+    try {
+      const store = this.export();
+      (0, import_fs2.writeFileSync)(this.filePath, JSON.stringify(store, null, 2), "utf-8");
+    } catch (error) {
+      console.error(`Failed to save nicknames to ${this.filePath}:`, error);
+      throw error;
+    }
+  }
+  set(address, nickname) {
+    super.set(address, nickname);
+    if (this.autoSave) {
+      this.save();
+    }
+  }
+  remove(address) {
+    super.remove(address);
+    if (this.autoSave) {
+      this.save();
+    }
+  }
+  import(store, overwrite = false) {
+    super.import(store, overwrite);
+    if (this.autoSave) {
+      this.save();
+    }
+  }
+  clear() {
+    super.clear();
+    if (this.autoSave) {
+      this.save();
+    }
+  }
+  /**
+   * Get the file path
+   */
+  getFilePath() {
+    return this.filePath;
+  }
+};
+function createFileNicknameProvider(filePath) {
+  return new FileNicknameProvider(filePath);
+}
+function createMemoryNicknameProvider() {
+  return new MemoryNicknameProvider();
+}
+function parseNicknameStore(json) {
+  const parsed = JSON.parse(json);
+  if (!isValidNicknameStore(parsed)) {
+    throw new Error("Invalid nickname store format");
+  }
+  return parsed;
+}
+function serializeNicknameStore(store) {
+  return JSON.stringify(store, null, 2);
+}
+
+// src/utils/display-address.ts
+function truncateAddress(address, chars = 4) {
+  if (!address || address.length <= chars * 2 + 3) {
+    return address;
+  }
+  return `${address.slice(0, chars)}...${address.slice(-chars)}`;
+}
+function displayAddress(address, options = {}) {
+  const {
+    nicknames,
+    labels,
+    truncateChars = 4,
+    showAddressSuffix = true,
+    format = "smart"
+  } = options;
+  if (format === "full") {
+    return address;
+  }
+  if (format === "truncated") {
+    return truncateAddress(address, truncateChars);
+  }
+  const nickname = nicknames?.get(address);
+  if (nickname) {
+    if (showAddressSuffix) {
+      return `${nickname} (${truncateAddress(address, truncateChars)})`;
+    }
+    return nickname;
+  }
+  const label = labels?.lookup(address);
+  if (label) {
+    return label.name;
+  }
+  return truncateAddress(address, truncateChars);
+}
+function getAddressDisplayInfo(address, nicknames, labels) {
+  const truncated = truncateAddress(address, 4);
+  const nickname = nicknames?.get(address) ?? void 0;
+  const labelData = labels?.lookup(address);
+  let displayText;
+  let type;
+  if (nickname) {
+    displayText = nickname;
+    type = "nickname";
+  } else if (labelData) {
+    displayText = labelData.name;
+    type = "label";
+  } else {
+    displayText = truncated;
+    type = "address";
+  }
+  return {
+    address,
+    displayText,
+    type,
+    truncated,
+    nickname,
+    label: labelData ? {
+      name: labelData.name,
+      type: labelData.type,
+      description: labelData.description
+    } : void 0
+  };
+}
+function displayAddresses(addresses, options = {}) {
+  return addresses.map((addr) => displayAddress(addr, options));
+}
+function createAddressFormatter(options) {
+  return (address) => displayAddress(address, options);
+}
+
 // src/analyzer/utils.ts
 var fs = __toESM(require("fs/promises"), 1);
 var path = __toESM(require("path"), 1);
@@ -3590,7 +4264,7 @@ var PERMISSIVE_CONFIG = {
 };
 
 // src/config/loader.ts
-var import_fs2 = require("fs");
+var import_fs3 = require("fs");
 var import_path2 = require("path");
 function loadConfig(cwd = process.cwd()) {
   const configPaths = [
@@ -3600,9 +4274,9 @@ function loadConfig(cwd = process.cwd()) {
   ];
   for (const configPath of configPaths) {
     const fullPath = (0, import_path2.join)(cwd, configPath);
-    if ((0, import_fs2.existsSync)(fullPath)) {
+    if ((0, import_fs3.existsSync)(fullPath)) {
       try {
-        const content = (0, import_fs2.readFileSync)(fullPath, "utf-8");
+        const content = (0, import_fs3.readFileSync)(fullPath, "utf-8");
         const parsed = JSON.parse(content);
         return validateConfig(parsed);
       } catch (error) {
@@ -3613,9 +4287,9 @@ function loadConfig(cwd = process.cwd()) {
     }
   }
   const packageJsonPath = (0, import_path2.join)(cwd, "package.json");
-  if ((0, import_fs2.existsSync)(packageJsonPath)) {
+  if ((0, import_fs3.existsSync)(packageJsonPath)) {
     try {
-      const content = (0, import_fs2.readFileSync)(packageJsonPath, "utf-8");
+      const content = (0, import_fs3.readFileSync)(packageJsonPath, "utf-8");
       const parsed = JSON.parse(content);
       if (parsed.privacy) {
         return validateConfig(parsed.privacy);
@@ -3663,9 +4337,877 @@ function getTestWallet(config) {
       return config.testWallets.devnet;
   }
 }
+
+// src/narrative/interpolator.ts
+function interpolate(template, data) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in data) {
+      return String(data[key]);
+    }
+    return match;
+  });
+}
+function extractEntityNames(descriptions) {
+  const names = [];
+  for (const desc of descriptions) {
+    const match = desc.match(/with\s+([A-Z][a-zA-Z0-9\s]+?)(?:\s+\(|$|,|\.|:)/);
+    if (match) {
+      names.push(match[1].trim());
+    }
+  }
+  return [...new Set(names)];
+}
+function parseCountFromDescription(description) {
+  const match = description.match(/(\d+)\s+(?:transaction|interaction|transfer|time)/i);
+  return match ? parseInt(match[1], 10) : 1;
+}
+
+// src/narrative/templates.ts
+var IDENTITY_TEMPLATES = [
+  // Exchange interactions - highest identity risk
+  {
+    pattern: "known-entity-exchange",
+    category: "identity",
+    template: "I can see that this wallet has directly interacted with {exchangeCount} centralized exchange(s) including {exchangeNames}. Since exchanges require KYC verification, I can potentially link this wallet to a real-world identity by requesting records from these exchanges.",
+    detailTemplates: ["The wallet had {interactionCount} interaction(s) with {exchangeName}."],
+    extractVariables: (signal) => {
+      const names = extractEntityNames(signal.evidence.map((e) => e.description));
+      return {
+        exchangeCount: signal.evidence.length || 1,
+        exchangeNames: names.length > 0 ? names.join(", ") : "known exchanges",
+        interactionCount: parseCountFromDescription(signal.evidence[0]?.description || ""),
+        exchangeName: names[0] || "an exchange"
+      };
+    }
+  },
+  // Bridge interactions - cross-chain tracking
+  {
+    pattern: "known-entity-bridge",
+    category: "identity",
+    template: "I can follow this wallet's bridge transactions to find their addresses on other blockchains. This allows me to correlate activity across multiple chains and build a more complete profile.",
+    extractVariables: (signal) => {
+      const names = extractEntityNames(signal.evidence.map((e) => e.description));
+      return {
+        bridgeCount: signal.evidence.length,
+        bridgeNames: names.join(", ") || "cross-chain bridges"
+      };
+    }
+  },
+  // Domain name linkage - permanent identity link
+  {
+    pattern: "domain-name-linkage",
+    category: "identity",
+    template: "I discovered that this wallet has registered or interacted with a .sol domain name. This creates a direct, permanent link between this cryptographic address and a human-readable identity that anyone can look up.",
+    extractVariables: () => ({})
+  },
+  // NFT metadata exposure - creator identity
+  {
+    pattern: "nft-metadata-exposure",
+    category: "identity",
+    template: "I can see that this wallet has created or updated NFTs via Metaplex. The on-chain metadata permanently associates this wallet with the creator identity, allowing me to identify the owner through their creative work.",
+    extractVariables: (signal) => ({
+      interactionCount: signal.evidence.length
+    })
+  },
+  // Frequent entity interaction (dynamic ID)
+  {
+    pattern: /^known-entity-frequent-/,
+    category: "identity",
+    template: "I notice that {concentration}% of this wallet's activity is concentrated with {entityName}. This heavy usage pattern makes it easy to track this user's habits and potentially correlate with off-chain records.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)%/);
+      const names = extractEntityNames([signal.reason || ""]);
+      return {
+        concentration: match?.[1] || "30",
+        entityName: names[0] || "a known service"
+      };
+    }
+  }
+];
+var CONNECTIONS_TEMPLATES = [
+  // Fee payer - never self (critical)
+  {
+    pattern: "fee-payer-never-self",
+    category: "connections",
+    template: "I have identified that this wallet NEVER pays its own transaction fees. All {txCount} transactions were funded by {feePayerCount} other wallet(s). This tells me definitively that someone else controls or funds this account - I can identify the controller by following the fee payments.",
+    extractVariables: (signal) => {
+      const txMatch = signal.reason?.match(/All\s+(\d+)/);
+      const fpMatch = signal.reason?.match(/by\s+(\d+)/);
+      return {
+        txCount: txMatch?.[1] || signal.evidence.length || "?",
+        feePayerCount: fpMatch?.[1] || "1"
+      };
+    }
+  },
+  // Fee payer - external
+  {
+    pattern: "fee-payer-external",
+    category: "connections",
+    template: "I can see that {feePayerCount} external wallet(s) have paid transaction fees for this address. This creates a visible on-chain connection - if I identify any of these fee payers, I automatically link them to this wallet.",
+    extractVariables: (signal) => ({
+      feePayerCount: signal.evidence.length || 1
+    })
+  },
+  // Fee payer - multi signer
+  {
+    pattern: "fee-payer-multi-signer",
+    category: "connections",
+    template: "I have detected that certain fee payers are funding transactions for multiple different signers. This reveals a central operator controlling several wallets - I can now link all these wallets together under one entity.",
+    extractVariables: (signal) => ({
+      operatorCount: signal.evidence.length
+    })
+  },
+  // Signer repeated
+  {
+    pattern: "signer-repeated",
+    category: "connections",
+    template: "I observe that {signerCount} address(es) repeatedly sign transactions for this wallet. This is cryptographic proof that these wallets are connected.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+address/);
+      return {
+        signerCount: match?.[1] || signal.evidence.length || "1"
+      };
+    }
+  },
+  // Signer set reuse
+  {
+    pattern: "signer-set-reuse",
+    category: "connections",
+    template: "I can see that the same group of signers is used repeatedly across {patternCount} different transaction patterns. This combination acts as a unique fingerprint identifying your multi-sig setup.",
+    extractVariables: (signal) => ({
+      patternCount: signal.evidence.length
+    })
+  },
+  // Signer authority hub
+  {
+    pattern: "signer-authority-hub",
+    category: "connections",
+    template: 'I have identified {authorityCount} "authority" signer(s) that co-sign transactions with many different wallets. This reveals a central controller - I can map out the entire set of wallets under their control.',
+    extractVariables: (signal) => ({
+      authorityCount: signal.evidence.length
+    })
+  },
+  // ATA creator linkage
+  {
+    pattern: "ata-creator-linkage",
+    category: "connections",
+    template: "I can see that one wallet created token accounts for {ownerCount} different owners. Even though these wallets never send tokens to each other directly, they are permanently linked through their shared funding source.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/for\s+(\d+)\s+different/);
+      return {
+        ownerCount: match?.[1] || signal.evidence.length || "2"
+      };
+    }
+  },
+  // ATA funding pattern
+  {
+    pattern: "ata-funding-pattern",
+    category: "connections",
+    template: "I detected {burstCount} token accounts created within a short time window. This batch setup pattern tells me these wallets were prepared by the same operator.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+token\s+accounts/);
+      return {
+        burstCount: match?.[1] || signal.evidence.length || "3"
+      };
+    }
+  },
+  // Counterparty reuse
+  {
+    pattern: "counterparty-reuse",
+    category: "connections",
+    template: "I can map out this wallet's regular contacts - {counterpartyCount} address(es) appear repeatedly in transfers, revealing established relationships.",
+    extractVariables: (signal) => ({
+      counterpartyCount: signal.evidence.length || 1
+    })
+  },
+  // PDA reuse
+  {
+    pattern: "pda-reuse",
+    category: "connections",
+    template: "I can track this wallet's repeated interactions with {pdaCount} program-derived account(s). Each visit to these accounts links those transactions together, revealing a complete activity timeline.",
+    extractVariables: (signal) => ({
+      pdaCount: signal.evidence.length
+    })
+  }
+];
+var BEHAVIOR_TEMPLATES = [
+  // Timing burst
+  {
+    pattern: "timing-burst",
+    category: "behavior",
+    template: "I detected a burst of {txCount} transactions within {timeSpan}. This concentrated activity stands out and could correlate with real-world events or identify this wallet among others.",
+    extractVariables: (signal) => {
+      const txMatch = signal.reason?.match(/(\d+)\s+transaction/);
+      const timeMatch = signal.reason?.match(/within\s+([^\.]+)/);
+      return {
+        txCount: txMatch?.[1] || signal.evidence.length || "?",
+        timeSpan: timeMatch?.[1] || "a short period"
+      };
+    }
+  },
+  // Timing regular interval
+  {
+    pattern: "timing-regular-interval",
+    category: "behavior",
+    template: "I can see transactions happening at regular intervals. This clock-like precision tells me this is likely automated, revealing either a bot or a fixed personal schedule.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)[- ]?(minute|hour|day)/i);
+      return {
+        interval: match ? `${match[1]} ${match[2]}` : "predictable"
+      };
+    }
+  },
+  // Timing timezone
+  {
+    pattern: "timing-timezone-pattern",
+    category: "behavior",
+    template: "I can determine that {concentration}% of transactions happen during specific hours ({activeHours} UTC). This reveals the user's timezone and daily schedule, narrowing down their geographic location.",
+    extractVariables: (signal) => {
+      const concMatch = signal.reason?.match(/(\d+)%/);
+      const hoursMatch = signal.reason?.match(/during\s+(\d+:\d+.*?)\s*UTC/i);
+      return {
+        concentration: concMatch?.[1] || "40",
+        activeHours: hoursMatch?.[1] || "consistent hours"
+      };
+    }
+  },
+  // Priority fee consistent
+  {
+    pattern: "priority-fee-consistent",
+    category: "behavior",
+    template: "I notice that many transactions use consistent priority fees. This pattern acts as a signature linking these transactions together.",
+    extractVariables: (signal) => {
+      const concMatch = signal.reason?.match(/(\d+)%/);
+      const feeMatch = signal.reason?.match(/(\d+)\s*lamports/);
+      return {
+        concentration: concMatch?.[1] || "50",
+        feeAmount: feeMatch?.[1] || "specific amounts"
+      };
+    }
+  },
+  // Compute budget fingerprint
+  {
+    pattern: "compute-budget-fingerprint",
+    category: "behavior",
+    template: "I can identify a distinctive compute unit pattern in {concentration}% of transactions. This consistency helps identify transactions from the same source.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)%/);
+      return {
+        concentration: match?.[1] || "60"
+      };
+    }
+  },
+  // Instruction sequence pattern
+  {
+    pattern: "instruction-sequence-pattern",
+    category: "behavior",
+    template: "I can identify {sequenceCount} repeated instruction sequence(s). Even across different wallets, this operational fingerprint could link them together.",
+    extractVariables: (signal) => ({
+      sequenceCount: signal.evidence.length || 1
+    })
+  },
+  // Program usage profile
+  {
+    pattern: "program-usage-profile",
+    category: "behavior",
+    template: "I have profiled this wallet's program usage - they regularly interact with {programCount} distinctive programs. This combination creates a behavioral fingerprint that could identify this user across wallets.",
+    extractVariables: (signal) => ({
+      programCount: signal.evidence.length
+    })
+  },
+  // Program reuse
+  {
+    pattern: "program-reuse",
+    category: "behavior",
+    template: "I can see this wallet repeatedly uses the same {programCount} program(s). This pattern of protocol preferences helps identify the user's DeFi strategy and habits.",
+    extractVariables: (signal) => ({
+      programCount: signal.evidence.length
+    })
+  },
+  // Instruction PDA reuse
+  {
+    pattern: "instruction-pda-reuse",
+    category: "behavior",
+    template: "I can track repeated interactions with {pdaCount} program-derived account(s) at the instruction level, creating a detailed activity trail.",
+    extractVariables: (signal) => ({
+      pdaCount: signal.evidence.length
+    })
+  },
+  // Instruction type patterns (dynamic)
+  {
+    pattern: /^instruction-type-/,
+    category: "behavior",
+    template: "I see a specific operation type being used {count} times. This repetitive behavior pattern distinguishes this wallet from normal users.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+times/);
+      return {
+        count: match?.[1] || "many"
+      };
+    }
+  },
+  // Stake delegation pattern
+  {
+    pattern: "stake-delegation-pattern",
+    category: "behavior",
+    template: "I can see staking activity concentrated on {validatorCount} validator(s). This choice reveals preferences that could help identify the staker, especially if using uncommon validators.",
+    extractVariables: (signal) => ({
+      validatorCount: signal.evidence.length
+    })
+  },
+  // Stake timing correlation
+  {
+    pattern: "stake-timing-correlation",
+    category: "behavior",
+    template: "I detect staking operations at regular intervals. This schedule reveals either automation or habitual behavior patterns.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)[- ]?hour/);
+      return {
+        interval: match?.[1] || "regular"
+      };
+    }
+  },
+  // Address high diversity
+  {
+    pattern: "address-high-diversity",
+    category: "behavior",
+    template: "I can see this single wallet is used for {activityCount} different types of activity. This makes it easy to build a complete profile of the owner's interests and habits.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+different/);
+      return {
+        activityCount: match?.[1] || "4"
+      };
+    }
+  },
+  // Address moderate diversity
+  {
+    pattern: "address-moderate-diversity",
+    category: "behavior",
+    template: "I can see this wallet is used for multiple activity types. These activities are now connected to the same identity.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+activity/);
+      return {
+        activityCount: match?.[1] || "3"
+      };
+    }
+  },
+  // Address long-term usage
+  {
+    pattern: "address-long-term-usage",
+    category: "behavior",
+    template: "I have access to {dayCount} days of transaction history with {txCount} transactions on this wallet. This extended timeline provides a detailed view of the owner's behavior over time.",
+    extractVariables: (signal) => {
+      const dayMatch = signal.reason?.match(/(\d+)\s*days/);
+      const txMatch = signal.reason?.match(/(\d+)\s*transaction/);
+      return {
+        dayCount: dayMatch?.[1] || "many",
+        txCount: txMatch?.[1] || "many"
+      };
+    }
+  }
+];
+var EXPOSURE_TEMPLATES = [
+  // Memo PII exposure (critical)
+  {
+    pattern: "memo-pii-exposure",
+    category: "exposure",
+    template: "I found personal information directly embedded in {memoCount} transaction memo(s). This data - including possible email addresses, phone numbers, or names - is permanently visible on the blockchain and directly links this wallet to a real identity.",
+    detailTemplates: ['Memo content found: "{content}"'],
+    extractVariables: (signal) => ({
+      memoCount: signal.evidence.length
+    })
+  },
+  // Memo descriptive content
+  {
+    pattern: "memo-descriptive-content",
+    category: "exposure",
+    template: "I can read {memoCount} descriptive memo(s) containing URLs, payment references, or descriptions. This context reveals the purpose of transactions and provides additional identifying information.",
+    extractVariables: (signal) => ({
+      memoCount: signal.evidence.length
+    })
+  },
+  // Memo usage (low severity)
+  {
+    pattern: "memo-usage",
+    category: "exposure",
+    template: "I see that {txCount} transaction(s) include memo data. While the current content may seem harmless, any memo adds extra context that observers can use to understand this wallet's activity.",
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)\s+transaction/);
+      return {
+        txCount: match?.[1] || signal.evidence.length || "?"
+      };
+    }
+  },
+  // Token account churn
+  {
+    pattern: "token-account-churn",
+    category: "exposure",
+    template: 'I can trace {closeCount} closed token account(s) through their rent refunds sent back to the owner. This reveals which wallets own the "throwaway" accounts.',
+    extractVariables: (signal) => {
+      const match = signal.reason?.match(/(\d+)/);
+      return {
+        closeCount: match?.[1] || signal.evidence.length || "?"
+      };
+    }
+  },
+  // Token account short-lived
+  {
+    pattern: "token-account-short-lived",
+    category: "exposure",
+    template: "I detected {accountCount} token account(s) that were created and closed within an hour. This throwaway pattern still leaves a trail through the rent refunds.",
+    extractVariables: (signal) => ({
+      accountCount: signal.evidence.length
+    })
+  },
+  // Token account common owner
+  {
+    pattern: "token-account-common-owner",
+    category: "exposure",
+    template: "I can see that {ownerCount} wallet(s) own multiple token accounts. Since ownership is public, I can link all these accounts to their common owners.",
+    extractVariables: (signal) => ({
+      ownerCount: signal.evidence.length
+    })
+  },
+  // Rent refund clustering
+  {
+    pattern: "rent-refund-clustering",
+    category: "exposure",
+    template: "I traced rent refunds from multiple closed accounts back to the same address(es). This exposes the full scope of their token holdings.",
+    extractVariables: (signal) => ({
+      recipientCount: signal.evidence.length
+    })
+  },
+  // Known entity other
+  {
+    pattern: "known-entity-other",
+    category: "exposure",
+    template: "I can see interactions with {entityCount} known service(s). These public landmarks in the transaction history reveal which protocols and services this wallet uses.",
+    extractVariables: (signal) => ({
+      entityCount: signal.evidence.length
+    })
+  },
+  // Counterparty-program combo
+  {
+    pattern: "counterparty-program-combo",
+    category: "exposure",
+    template: "I identified {comboCount} distinctive counterparty-program combination(s) used repeatedly. This specific pairing is highly identifying - much more so than either element alone.",
+    extractVariables: (signal) => ({
+      comboCount: signal.evidence.length
+    })
+  }
+];
+var ALL_TEMPLATES = [
+  ...IDENTITY_TEMPLATES,
+  ...CONNECTIONS_TEMPLATES,
+  ...BEHAVIOR_TEMPLATES,
+  ...EXPOSURE_TEMPLATES
+];
+function findTemplate(signalId) {
+  for (const template of ALL_TEMPLATES) {
+    if (typeof template.pattern === "string") {
+      if (template.pattern === signalId) return template;
+    } else {
+      if (template.pattern.test(signalId)) return template;
+    }
+  }
+  return void 0;
+}
+
+// src/narrative/categories.ts
+var CATEGORY_DEFINITIONS = {
+  identity: {
+    id: "identity",
+    title: "Identity Linkage",
+    description: "Direct connections to real-world identity",
+    openingPhrases: [
+      "Starting with the most critical findings - I can potentially identify who owns this wallet.",
+      "The most serious privacy concerns involve direct identity linkage.",
+      "I have found clear paths to identifying the wallet owner."
+    ],
+    closingPhrases: [
+      "These identity links are the most damaging because they connect on-chain activity to real-world identities.",
+      "Any of these pathways could lead to complete identification of the wallet owner."
+    ],
+    priority: 1
+  },
+  connections: {
+    id: "connections",
+    title: "Wallet Connections",
+    description: "Links between this wallet and other addresses",
+    openingPhrases: [
+      "I can map out a network of connected wallets.",
+      "This wallet is linked to other addresses in several ways.",
+      "The following connections reveal relationships between wallets."
+    ],
+    closingPhrases: [
+      "These connections form a web - identifying any one wallet helps identify the others.",
+      "Even without knowing the owner, I can see which wallets belong together."
+    ],
+    priority: 2
+  },
+  behavior: {
+    id: "behavior",
+    title: "Behavioral Fingerprints",
+    description: "Patterns that distinguish this wallet from others",
+    openingPhrases: [
+      "I can identify distinctive behavioral patterns.",
+      "This wallet has recognizable usage patterns.",
+      "The following behaviors create a unique fingerprint."
+    ],
+    closingPhrases: [
+      "These patterns help identify the same user across different wallets.",
+      "Behavioral consistency makes this wallet stand out from random users."
+    ],
+    priority: 3
+  },
+  exposure: {
+    id: "exposure",
+    title: "Information Exposure",
+    description: "Metadata and content that reveals information",
+    openingPhrases: [
+      "Additional information is exposed through transaction data.",
+      "I found metadata that provides extra context about this wallet.",
+      "The following data leaks provide additional insights."
+    ],
+    closingPhrases: [
+      "This exposed information adds context that helps in identification.",
+      "Each piece of exposed data contributes to a more complete profile."
+    ],
+    priority: 4
+  }
+};
+var SIGNAL_CATEGORY_MAP = {
+  // Identity - direct paths to real-world identity
+  "known-entity-exchange": "identity",
+  "known-entity-bridge": "identity",
+  "domain-name-linkage": "identity",
+  "nft-metadata-exposure": "identity",
+  // Connections - wallet relationships
+  "fee-payer-external": "connections",
+  "fee-payer-never-self": "connections",
+  "fee-payer-multi-signer": "connections",
+  "signer-repeated": "connections",
+  "signer-set-reuse": "connections",
+  "signer-authority-hub": "connections",
+  "ata-creator-linkage": "connections",
+  "ata-funding-pattern": "connections",
+  "counterparty-reuse": "connections",
+  "pda-reuse": "connections",
+  // Behavior - usage patterns
+  "timing-burst": "behavior",
+  "timing-regular-interval": "behavior",
+  "timing-timezone-pattern": "behavior",
+  "priority-fee-consistent": "behavior",
+  "compute-budget-fingerprint": "behavior",
+  "instruction-sequence-pattern": "behavior",
+  "program-usage-profile": "behavior",
+  "program-reuse": "behavior",
+  "instruction-pda-reuse": "behavior",
+  "stake-delegation-pattern": "behavior",
+  "stake-timing-correlation": "behavior",
+  "address-high-diversity": "behavior",
+  "address-moderate-diversity": "behavior",
+  "address-long-term-usage": "behavior",
+  // Exposure - information leaks
+  "memo-usage": "exposure",
+  "memo-pii-exposure": "exposure",
+  "memo-descriptive-content": "exposure",
+  "known-entity-other": "exposure",
+  "token-account-churn": "exposure",
+  "token-account-short-lived": "exposure",
+  "token-account-common-owner": "exposure",
+  "rent-refund-clustering": "exposure",
+  "counterparty-program-combo": "exposure"
+};
+function getSignalCategory(signalId) {
+  if (SIGNAL_CATEGORY_MAP[signalId]) {
+    return SIGNAL_CATEGORY_MAP[signalId];
+  }
+  if (signalId.startsWith("known-entity-frequent-")) return "identity";
+  if (signalId.startsWith("instruction-type-")) return "behavior";
+  return "exposure";
+}
+function getCategoriesInOrder() {
+  return ["identity", "connections", "behavior", "exposure"];
+}
+
+// src/narrative/transitions.ts
+var INTRA_CATEGORY_TRANSITIONS = {
+  additive: [
+    "Additionally,",
+    "Furthermore,",
+    "I also found that",
+    "Building on this,",
+    "On top of that,",
+    "Moreover,"
+  ],
+  amplifying: [
+    "More concerning,",
+    "Even more revealing,",
+    "This is compounded by the fact that",
+    "What makes this worse is that",
+    "Adding to this risk,"
+  ],
+  neutral: ["I can also see that", "Another observation:", "Looking further,", "In addition,"]
+};
+function selectTransition(currentSeverity, previousSeverity, index) {
+  const severityRank = { LOW: 1, MEDIUM: 2, HIGH: 3 };
+  if (index === 0) return "";
+  if (severityRank[currentSeverity] > severityRank[previousSeverity]) {
+    return INTRA_CATEGORY_TRANSITIONS.amplifying[index % INTRA_CATEGORY_TRANSITIONS.amplifying.length];
+  }
+  const transitions = index % 2 === 0 ? INTRA_CATEGORY_TRANSITIONS.additive : INTRA_CATEGORY_TRANSITIONS.neutral;
+  return transitions[index % transitions.length];
+}
+function getSeverityIndicator(severity) {
+  switch (severity) {
+    case "HIGH":
+      return "[!]";
+    case "MEDIUM":
+      return "[~]";
+    case "LOW":
+      return "[.]";
+  }
+}
+
+// src/narrative/conclusion.ts
+function determineIdentifiability(report) {
+  const { signals, overallRisk, summary } = report;
+  const hasExchangeInteraction = signals.some((s) => s.id === "known-entity-exchange");
+  const hasDomainLinkage = signals.some((s) => s.id === "domain-name-linkage");
+  const hasPIIInMemos = signals.some((s) => s.id === "memo-pii-exposure");
+  const hasNeverSelfPays = signals.some((s) => s.id === "fee-payer-never-self");
+  if (hasPIIInMemos && hasExchangeInteraction) {
+    return "fully-identified";
+  }
+  if (hasDomainLinkage && hasExchangeInteraction) {
+    return "fully-identified";
+  }
+  if (hasExchangeInteraction || hasDomainLinkage || hasPIIInMemos) {
+    return "identifiable";
+  }
+  const hasStrongLinkage = signals.some(
+    (s) => s.id === "fee-payer-never-self" || s.id === "signer-authority-hub" || s.id === "ata-creator-linkage"
+  );
+  if (hasStrongLinkage && summary.highRiskSignals >= 2) {
+    return "identifiable";
+  }
+  if (overallRisk === "HIGH" || overallRisk === "MEDIUM") {
+    return "pseudonymous";
+  }
+  if (summary.totalSignals > 0) {
+    return "pseudonymous";
+  }
+  return "anonymous";
+}
+function generateConclusion(report, statements, identifiability) {
+  const categoryCount = new Set(statements.map((s) => s.category)).size;
+  const highCount = statements.filter((s) => s.severity === "HIGH").length;
+  const conclusions = {
+    "fully-identified": [
+      `In summary, I can confidently identify the owner of this wallet. With direct exchange interactions combined with personal information exposure, the on-chain pseudonym is broken. The ${highCount} critical issues detected provide multiple pathways to real-world identification.`,
+      `This wallet is fully identified. Through ${categoryCount} categories of privacy leaks, I have established clear links between this on-chain address and real-world identity. The privacy damage is complete and permanent.`
+    ],
+    identifiable: [
+      `This wallet is identifiable through ${highCount} high-severity privacy issues. While I may not have a name yet, there are clear pathways - likely through exchange records or domain registration - that could reveal the owner's identity with minimal additional investigation.`,
+      `I can likely identify this wallet's owner. The patterns across ${categoryCount} categories create enough data points that, combined with external records, would reveal their identity. The wallet operates more like a named account than an anonymous one.`
+    ],
+    pseudonymous: [
+      `This wallet maintains pseudonymity but has revealing patterns. Across ${categoryCount} categories, I found behavioral fingerprints and connections that distinguish this user from others. While not immediately identifiable, these patterns could be used to link this wallet to other activities or narrow down the owner's identity.`,
+      `The wallet is pseudonymous - not anonymous. I cannot immediately identify the owner, but the ${statements.length} patterns detected create a profile that could be matched against other data sources or used to connect this wallet to the same owner's other activities.`
+    ],
+    anonymous: [
+      "This wallet maintains reasonable anonymity. While some minor patterns exist, there are no critical privacy issues that would allow identification. The owner practices good privacy hygiene.",
+      "I found no significant privacy leaks. This wallet blends in with normal activity and would be difficult to distinguish or identify from on-chain data alone."
+    ]
+  };
+  const options = conclusions[identifiability];
+  return options[report.summary.totalSignals % options.length];
+}
+function getIdentifiabilityDescription(level) {
+  const descriptions = {
+    "fully-identified": "Direct pathways to real-world identity exist through KYC exchanges and personal information exposure.",
+    identifiable: "Strong linkage to identity through exchanges, domains, or exposed personal information.",
+    pseudonymous: "Behavioral patterns exist that distinguish this wallet, but no direct identity link.",
+    anonymous: "Minimal distinguishing characteristics; wallet blends in with normal activity."
+  };
+  return descriptions[level];
+}
+
+// src/narrative/builder.ts
+var DEFAULT_OPTIONS = {
+  includeLowSeverity: true,
+  includeDetails: true,
+  maxStatementsPerCategory: 5,
+  format: "text"
+};
+function buildStatement(signal) {
+  const template = findTemplate(signal.id);
+  if (!template) {
+    return {
+      signalId: signal.id,
+      category: getSignalCategory(signal.id),
+      severity: signal.severity,
+      statement: `I can determine that: ${signal.reason}`,
+      details: signal.evidence.slice(0, 3).map((e) => e.description),
+      confidence: signal.confidence ?? 0.7
+    };
+  }
+  const variables = template.extractVariables(signal);
+  const statement = interpolate(template.template, variables);
+  const details = [];
+  if (template.detailTemplates && signal.evidence.length > 0) {
+    for (let i = 0; i < Math.min(signal.evidence.length, 3); i++) {
+      const ev = signal.evidence[i];
+      const detailVars = {
+        ...variables,
+        content: ev.description?.replace(/^"(.+)"$/, "$1") || "",
+        reference: ev.reference || ""
+      };
+      const detail = interpolate(template.detailTemplates[0], detailVars);
+      details.push(detail);
+    }
+  }
+  return {
+    signalId: signal.id,
+    category: template.category,
+    severity: signal.severity,
+    statement,
+    details,
+    confidence: signal.confidence ?? 0.7
+  };
+}
+function groupByCategory(statements) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const stmt of statements) {
+    if (!groups.has(stmt.category)) {
+      groups.set(stmt.category, []);
+    }
+    groups.get(stmt.category).push(stmt);
+  }
+  for (const [, stmts] of groups) {
+    stmts.sort((a, b) => {
+      const order = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+      return order[a.severity] - order[b.severity];
+    });
+  }
+  return groups;
+}
+function buildParagraph(category, statements, options) {
+  const def = CATEGORY_DEFINITIONS[category];
+  const limited = statements.slice(0, options.maxStatementsPerCategory);
+  const hasHigh = limited.some((s) => s.severity === "HIGH");
+  const openingIndex = hasHigh ? 0 : 1;
+  return {
+    category,
+    title: def.title,
+    opening: def.openingPhrases[openingIndex % def.openingPhrases.length],
+    statements: limited,
+    closing: def.closingPhrases[0]
+  };
+}
+function generateIntroduction(report) {
+  const { overallRisk, summary } = report;
+  if (overallRisk === "HIGH") {
+    return `Based on my analysis of ${summary.transactionsAnalyzed} transactions, I can build a detailed profile of this wallet's owner. There are ${summary.highRiskSignals} critical privacy issues that could lead to identification.`;
+  }
+  if (overallRisk === "MEDIUM") {
+    return `After analyzing ${summary.transactionsAnalyzed} transactions, I found several privacy patterns that reveal information about this wallet's owner. While not immediately identifiable, there are ${summary.totalSignals} concerns worth addressing.`;
+  }
+  return `My analysis of ${summary.transactionsAnalyzed} transactions reveals ${summary.totalSignals} minor privacy patterns. This wallet maintains reasonable privacy, though some behavioral fingerprints exist.`;
+}
+function formatAsText(narrative, options) {
+  const lines = [];
+  lines.push("");
+  lines.push("=".repeat(65));
+  lines.push("  WHAT DOES THE OBSERVER KNOW?");
+  lines.push("  An Adversary's Perspective");
+  lines.push("=".repeat(65));
+  lines.push("");
+  lines.push(narrative.introduction);
+  lines.push("");
+  for (let i = 0; i < narrative.paragraphs.length; i++) {
+    const para = narrative.paragraphs[i];
+    lines.push("-".repeat(65));
+    lines.push(`## ${para.title.toUpperCase()}`);
+    lines.push("-".repeat(65));
+    lines.push("");
+    lines.push(para.opening);
+    lines.push("");
+    for (let j = 0; j < para.statements.length; j++) {
+      const stmt = para.statements[j];
+      const prevSeverity = j > 0 ? para.statements[j - 1].severity : stmt.severity;
+      const transition = selectTransition(stmt.severity, prevSeverity, j);
+      const severityIcon = getSeverityIndicator(stmt.severity);
+      if (transition) {
+        lines.push(`${transition} ${severityIcon} ${stmt.statement}`);
+      } else {
+        lines.push(`${severityIcon} ${stmt.statement}`);
+      }
+      if (options.includeDetails && stmt.details.length > 0) {
+        for (const detail of stmt.details) {
+          lines.push(`    - ${detail}`);
+        }
+      }
+      lines.push("");
+    }
+    lines.push(para.closing);
+    lines.push("");
+  }
+  lines.push("=".repeat(65));
+  lines.push("## CONCLUSION");
+  lines.push("=".repeat(65));
+  lines.push("");
+  lines.push(narrative.conclusion);
+  lines.push("");
+  lines.push(`Identifiability Level: ${narrative.identifiabilityLevel.toUpperCase()}`);
+  lines.push("");
+  return lines.join("\n");
+}
+function generateNarrative(report, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let signals = report.signals;
+  if (!opts.includeLowSeverity) {
+    signals = signals.filter((s) => s.severity !== "LOW");
+  }
+  const statements = [];
+  for (const signal of signals) {
+    const stmt = buildStatement(signal);
+    if (stmt) {
+      statements.push(stmt);
+    }
+  }
+  const grouped = groupByCategory(statements);
+  const categoryOrder = getCategoriesInOrder();
+  const paragraphs = [];
+  for (const category of categoryOrder) {
+    const categoryStatements = grouped.get(category);
+    if (categoryStatements && categoryStatements.length > 0) {
+      paragraphs.push(buildParagraph(category, categoryStatements, opts));
+    }
+  }
+  const identifiability = determineIdentifiability(report);
+  const conclusion = generateConclusion(report, statements, identifiability);
+  return {
+    introduction: generateIntroduction(report),
+    paragraphs,
+    conclusion,
+    identifiabilityLevel: identifiability,
+    signalCount: signals.length,
+    timestamp: Date.now()
+  };
+}
+function generateNarrativeText(report, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const narrative = generateNarrative(report, opts);
+  return formatAsText(narrative, opts);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ALL_TEMPLATES,
+  CATEGORY_DEFINITIONS,
   DEFAULT_CONFIG,
+  FileNicknameProvider,
+  MemoryNicknameProvider,
   PERMISSIVE_CONFIG,
   PrivacyConfigSchema,
   RPCClient,
@@ -3678,7 +5220,10 @@ function getTestWallet(config) {
   collectTransactionData,
   collectWalletData,
   compareImplementations,
+  createAddressFormatter,
   createDefaultLabelProvider,
+  createFileNicknameProvider,
+  createMemoryNicknameProvider,
   detectATALinkage,
   detectAddressReuse,
   detectCounterpartyReuse,
@@ -3687,6 +5232,7 @@ function getTestWallet(config) {
   detectIdentityMetadataExposure,
   detectInstructionFingerprinting,
   detectKnownEntityInteraction,
+  detectLocationInference,
   detectMemoExposure,
   detectMemoPII,
   detectPriorityFeeFingerprinting,
@@ -3694,19 +5240,33 @@ function getTestWallet(config) {
   detectStakingDelegationPatterns,
   detectTimingPatterns,
   detectTokenAccountLifecycle,
+  determineIdentifiability,
+  displayAddress,
+  displayAddresses,
   evaluateHeuristics,
+  findTemplate,
+  generateConclusion,
+  generateNarrative,
+  generateNarrativeText,
   generateReport,
+  getAddressDisplayInfo,
+  getCategoriesInOrder,
   getEnvironmentConfig,
+  getIdentifiabilityDescription,
   getMemoRecommendations,
+  getSignalCategory,
   getTestWallet,
   groupIssuesByFile,
   loadConfig,
   normalizeProgramData,
   normalizeTransactionData,
   normalizeWalletData,
+  parseNicknameStore,
+  serializeNicknameStore,
   shouldEnforce,
   simulateTransactionFlow,
   simulateTransactionPrivacy,
-  sortIssues
+  sortIssues,
+  truncateAddress
 });
 //# sourceMappingURL=index.cjs.map