enigma-memory 0.1.18 → 0.1.22

package/packages/terminal-console/repl.mjs

@@ -0,0 +1,136 @@
+import readline from 'node:readline';
+import { renderTerminalBanner } from './banner.mjs';
+import { TerminalSession } from './commands.mjs';
+
+const KNOWN_COMMANDS = [
+  'quickstart',
+  'remember',
+  'context',
+  'doctor',
+  'tree',
+  'tui',
+  'dashboard',
+  'monitor',
+  'constellation',
+  'matrix',
+  'enclave cycle',
+  'enclave attest',
+  'enclave verify',
+  'swarm status',
+  'swarm graph',
+  'wallet',
+  'wallet connect',
+  'wallet status',
+  'wallet disconnect',
+  'solana status',
+  'solana stream',
+  'solana pulse',
+  'solana anchor-bundle',
+  'solana submit',
+  'solana verify-anchor',
+  'export',
+  'verify',
+  'token',
+  'ca',
+  'clear',
+  'cls',
+  'help',
+  'exit',
+  'quit',
+];
+
+export function createCompleter(session) {
+  return function completer(linePartial) {
+    const trimmed = linePartial.trimStart();
+    const hits = KNOWN_COMMANDS.filter((cmd) => cmd.startsWith(trimmed));
+    return [hits.length ? hits : KNOWN_COMMANDS, linePartial];
+  };
+}
+
+export async function runTerminalConsole({
+  bundlePath = '.enigma/bundle.json',
+  color = true,
+  execCommand = undefined,
+  interactive = true,
+  io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr },
+} = {}) {
+  const session = new TerminalSession({ bundlePath, color, io });
+
+  // If a one-shot command was provided via --exec, run it and return
+  if (execCommand) {
+    const exitCode = await session.executeCommand(execCommand);
+    return exitCode === 'EXIT' ? 0 : (exitCode || 0);
+  }
+
+  // If not interactive (e.g. CI without TTY), print banner and exit
+  if (!interactive || !io.stdin?.isTTY) {
+    io.stdout.write(renderTerminalBanner({ color }) + '\n');
+    return 0;
+  }
+
+  // Interactive REPL Loop
+  io.stdout.write('\x1b[2J\x1b[0;0H');
+  io.stdout.write(renderTerminalBanner({ color }) + '\n\n');
+
+  const rl = readline.createInterface({
+    input: io.stdin,
+    output: io.stdout,
+    completer: createCompleter(session),
+    terminal: true,
+  });
+
+  return new Promise((resolve) => {
+    let closed = false;
+    let commandQueue = Promise.resolve();
+
+    async function promptLoop() {
+      if (closed) return;
+      const promptStr = await session.renderPrompt();
+      rl.setPrompt(promptStr);
+      rl.prompt();
+    }
+
+    rl.on('line', (line) => {
+      commandQueue = commandQueue.then(async () => {
+        if (closed) return;
+        session.activeAbortController = new AbortController();
+        try {
+          const result = await session.executeCommand(line, { signal: session.activeAbortController.signal });
+          if (result === 'EXIT') {
+            closed = true;
+            io.stdout.write('\nExiting Enigma Terminal Console. Session closed.\n');
+            rl.close();
+            resolve(0);
+            return;
+          }
+        } catch (err) {
+          if (!session.activeAbortController?.signal?.aborted) {
+            io.stderr.write(`\nError: ${err.message}\n`);
+          }
+        } finally {
+          session.activeAbortController = null;
+        }
+        io.stdout.write('\n');
+        await promptLoop();
+      });
+    });
+
+    rl.on('SIGINT', () => {
+      if (session.activeAbortController) {
+        session.activeAbortController.abort();
+        io.stdout.write('\n^C\n');
+      } else {
+        closed = true;
+        io.stdout.write('\nExiting Enigma Terminal Console.\n');
+        rl.close();
+        resolve(0);
+      }
+    });
+    rl.on('close', () => {
+      closed = true;
+      resolve(0);
+    });
+
+    promptLoop();
+  });
+}

package/packages/terminal-console/signer-store.mjs

@@ -0,0 +1,130 @@
+// Enigma Sovereign AI Memory — SignerStore Interface
+// Manages secure automation signer key custody with strict zero-plaintext boundaries.
+// Integrates with Electron safeStorage (OS DPAPI on Windows / Keychain on macOS) and host-bound AES-256-GCM.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import { encodeBase58 } from './phantom-bridge.mjs';
+
+function deriveHostBoundKey(salt = 'enigma-auto-anchor-dpapi-salt-v1') {
+  const hostIdentity = [
+    os.hostname() || 'localhost',
+    os.userInfo()?.username || 'user',
+    os.platform() || 'win32',
+    os.arch() || 'x64',
+  ].join(':');
+  return crypto.scryptSync(hostIdentity, salt, 32);
+}
+
+export function zeroizeBuffer(buf) {
+  if (Buffer.isBuffer(buf)) {
+    try {
+      buf.fill(0);
+    } catch {}
+  }
+}
+
+export class SignerStore {
+  constructor({ signerPath = '.enigma/auto-anchor/signer.enc.json', safeStorage = undefined, customKey = undefined } = {}) {
+    this.signerPath = resolve(signerPath);
+    this.safeStorage = safeStorage;
+    this.customKey = customKey;
+  }
+
+  hasSigner() {
+    return existsSync(this.signerPath);
+  }
+
+  getPublicKey() {
+    if (!this.hasSigner()) return null;
+    try {
+      const data = JSON.parse(readFileSync(this.signerPath, 'utf8'));
+      return data.publicKeyBase58 || null;
+    } catch {
+      return null;
+    }
+  }
+
+  generateKeypair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const rawPubBytes = publicKey.export({ type: 'spki', format: 'der' }).subarray(-32);
+    const rawPrivBytes = privateKey.export({ type: 'pkcs8', format: 'der' }).subarray(-32);
+    const fullSecretKey = Buffer.concat([rawPrivBytes, rawPubBytes]);
+    const publicKeyBase58 = encodeBase58(rawPubBytes);
+    return {
+      publicKeyBase58,
+      publicKeyBuffer: rawPubBytes,
+      secretKeyBuffer: fullSecretKey,
+    };
+  }
+
+  saveSignerSecretKey(secretKeyBuffer, { publicKeyBase58 }) {
+    if (!Buffer.isBuffer(secretKeyBuffer) || secretKeyBuffer.length !== 64) {
+      throw new Error('Signer secret key must be a valid 64-byte Buffer');
+    }
+    if (!publicKeyBase58 || typeof publicKeyBase58 !== 'string') {
+      throw new Error('Missing valid publicKeyBase58');
+    }
+
+    const dir = dirname(this.signerPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    if (this.safeStorage && typeof this.safeStorage.encryptString === 'function') {
+      const encryptedBuffer = this.safeStorage.encryptString(secretKeyBuffer.toString('hex'));
+      const manifest = {
+        schema: 'enigma.encrypted_signer_safestorage.v1',
+        publicKeyBase58,
+        encryptedHex: encryptedBuffer.toString('hex'),
+        storage: 'electron-safestorage-dpapi',
+        created_at: new Date().toISOString(),
+      };
+      writeFileSync(this.signerPath, JSON.stringify(manifest, null, 2), 'utf8');
+      return true;
+    }
+
+    // Host-bound AES-256-GCM encryption fallback
+    const key = this.customKey || deriveHostBoundKey();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(secretKeyBuffer), cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    const manifest = {
+      schema: 'enigma.encrypted_signer_hostbound.v1',
+      publicKeyBase58,
+      iv: iv.toString('hex'),
+      tag: tag.toString('hex'),
+      data: encrypted.toString('hex'),
+      storage: 'host-bound-aes-256-gcm',
+      created_at: new Date().toISOString(),
+    };
+    writeFileSync(this.signerPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return true;
+  }
+
+  loadSignerSecretKey() {
+    if (!this.hasSigner()) throw new Error('Signer store is empty');
+    const data = JSON.parse(readFileSync(this.signerPath, 'utf8'));
+
+    if (data.schema === 'enigma.encrypted_signer_safestorage.v1') {
+      if (!this.safeStorage || typeof this.safeStorage.decryptString !== 'function') {
+        throw new Error('Cannot decrypt safeStorage payload outside active Electron session');
+      }
+      const decryptedHex = this.safeStorage.decryptString(Buffer.from(data.encryptedHex, 'hex'));
+      return Buffer.from(decryptedHex, 'hex');
+    }
+
+    if (data.schema === 'enigma.encrypted_signer_hostbound.v1') {
+      const key = this.customKey || deriveHostBoundKey();
+      const iv = Buffer.from(data.iv, 'hex');
+      const tag = Buffer.from(data.tag, 'hex');
+      const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(Buffer.from(data.data, 'hex')), decipher.final()]);
+    }
+
+    throw new Error(`Unsupported signer storage schema: ${data.schema}`);
+  }
+}

package/packages/terminal-console/solana-rpc.mjs

@@ -0,0 +1,214 @@
+import { OFFICIAL_TOKEN_CA } from './banner.mjs';
+import { ANSI } from '../terminal-tui/merkle-tree-renderer.mjs';
+
+export const SOLANA_RPC_CLUSTERS = Object.freeze({
+  'mainnet-beta': 'https://api.mainnet-beta.solana.com',
+  'devnet': 'https://api.devnet.solana.com',
+  'testnet': 'https://api.testnet.solana.com',
+  'localnet': 'http://127.0.0.1:8899',
+});
+
+function isCustomRpcUrl(rpcUrl) {
+  return typeof rpcUrl === 'string' && rpcUrl.length > 0;
+}
+
+function redactRpcText(value, resolvedUrl) {
+  let text = String(value ?? '');
+  if (resolvedUrl) text = text.split(resolvedUrl).join('<custom-rpc>');
+  return text.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s/@]+:[^\s/@]+@[^\s)]+/giu, '<custom-rpc>');
+}
+
+export async function probeSolanaRpc({
+  cluster = 'mainnet-beta',
+  rpcUrl = undefined,
+  timeoutMs = 4000,
+  fetchFn = globalThis.fetch,
+} = {}) {
+  const customRpc = isCustomRpcUrl(rpcUrl);
+  const resolvedUrl = customRpc ? rpcUrl : SOLANA_RPC_CLUSTERS[cluster] || SOLANA_RPC_CLUSTERS['mainnet-beta'];
+  const displayedUrl = customRpc ? '<custom-rpc>' : resolvedUrl;
+  const started = Date.now();
+
+  const payload = {
+    jsonrpc: '2.0',
+    id: 'enigma-probe',
+    method: 'getHealth',
+  };
+
+  try {
+    let timer;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    if (controller) {
+      timer = setTimeout(() => controller.abort(), timeoutMs);
+    }
+
+    const response = await fetchFn(resolvedUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: controller?.signal,
+    });
+
+    clearTimeout(timer);
+    const latencyMs = Date.now() - started;
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        cluster,
+        rpc_url: displayedUrl,
+        error: redactRpcText(`HTTP ${response.status}: ${response.statusText}`, customRpc ? resolvedUrl : undefined),
+        latency_ms: latencyMs,
+      };
+    }
+
+    const data = await response.json();
+    const isHealthy = data?.result === 'ok' || data?.result === true || (!data?.error && data?.result !== undefined);
+
+    return {
+      ok: isHealthy,
+      cluster,
+      rpc_url: displayedUrl,
+      health: data?.result ?? (data?.error ? 'error' : 'ok'),
+      latency_ms: latencyMs,
+      error: data?.error?.message ? redactRpcText(data.error.message, customRpc ? resolvedUrl : undefined) : null,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      cluster,
+      rpc_url: displayedUrl,
+      error: err.name === 'AbortError' ? `RPC probe timed out after ${timeoutMs}ms` : redactRpcText(err.message, customRpc ? resolvedUrl : undefined),
+      latency_ms: Date.now() - started,
+    };
+  }
+}
+
+export async function fetchSolanaStreamMetrics({
+  cluster = 'mainnet-beta',
+  rpcUrl = undefined,
+  timeoutMs = 4000,
+  fetchFn = globalThis.fetch,
+} = {}) {
+  const customRpc = isCustomRpcUrl(rpcUrl);
+  const resolvedUrl = customRpc ? rpcUrl : SOLANA_RPC_CLUSTERS[cluster] || SOLANA_RPC_CLUSTERS['mainnet-beta'];
+  const displayedUrl = customRpc ? '<custom-rpc>' : resolvedUrl;
+  const started = Date.now();
+
+  const payload = [
+    { jsonrpc: '2.0', id: 'probe-health', method: 'getHealth' },
+    { jsonrpc: '2.0', id: 'probe-slot', method: 'getSlot' },
+    { jsonrpc: '2.0', id: 'probe-epoch', method: 'getEpochInfo' },
+    { jsonrpc: '2.0', id: 'probe-version', method: 'getVersion' },
+  ];
+
+  try {
+    let timer;
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    if (controller) {
+      timer = setTimeout(() => controller.abort(), timeoutMs);
+    }
+
+    const response = await fetchFn(resolvedUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: controller?.signal,
+    });
+
+    clearTimeout(timer);
+    const latencyMs = Date.now() - started;
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        cluster,
+        rpc_url: displayedUrl,
+        latency_ms: latencyMs,
+        error: redactRpcText(`HTTP ${response.status}: ${response.statusText}`, customRpc ? resolvedUrl : undefined),
+      };
+    }
+
+    const data = await response.json();
+    const results = Array.isArray(data) ? data : [data];
+    const healthRes = results.find((r) => r.id === 'probe-health')?.result ?? data?.result;
+    const slotRes = results.find((r) => r.id === 'probe-slot')?.result;
+    const epochRes = results.find((r) => r.id === 'probe-epoch')?.result;
+    const versionRes = results.find((r) => r.id === 'probe-version')?.result;
+
+    const isHealthy = healthRes === 'ok' || healthRes === true || (slotRes !== undefined && slotRes !== null) || data?.result === 'ok' || data?.result === true;
+
+    return {
+      ok: isHealthy,
+      cluster,
+      rpc_url: displayedUrl,
+      latency_ms: latencyMs,
+      slot: typeof slotRes === 'number' ? slotRes : (typeof epochRes?.absoluteSlot === 'number' ? epochRes.absoluteSlot : null),
+      block_height: typeof epochRes?.blockHeight === 'number' ? epochRes.blockHeight : null,
+      epoch: typeof epochRes?.epoch === 'number' ? epochRes.epoch : null,
+      slot_index: typeof epochRes?.slotIndex === 'number' ? epochRes.slotIndex : null,
+      slots_in_epoch: typeof epochRes?.slotsInEpoch === 'number' ? epochRes.slotsInEpoch : null,
+      transaction_count: typeof epochRes?.transactionCount === 'number' ? epochRes.transactionCount : null,
+      solana_core_version: versionRes?.['solana-core'] ?? (typeof versionRes === 'string' ? versionRes : 'N/A'),
+      error: null,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      cluster,
+      rpc_url: displayedUrl,
+      latency_ms: Date.now() - started,
+      slot: null,
+      block_height: null,
+      epoch: null,
+      error: err.name === 'AbortError' ? `RPC probe timed out after ${timeoutMs}ms` : redactRpcText(err.message, customRpc ? resolvedUrl : undefined),
+    };
+  }
+}
+
+export function formatSolanaStatusReport(probeResult, { color = true } = {}) {
+  const c = (text, code) => (color ? `${code}${text}${ANSI.reset}` : text);
+
+  const statusBadge = probeResult.ok
+    ? `${c('● CONNECTED', `${ANSI.bold}${ANSI.green}`)} (${probeResult.latency_ms}ms)`
+    : `${c('○ UNREACHABLE / OFFLINE', `${ANSI.bold}${ANSI.yellow}`)} (${probeResult.error || 'no response'})`;
+
+  const lines = [
+    `  ${c('ENIGMA SOLANA CONTEXT LAYER & RPC STATUS', `${ANSI.bold}${ANSI.amber}`)}`,
+    `  ${c('Cluster:', ANSI.dimText)}           ${probeResult.cluster} (${probeResult.rpc_url})`,
+    `  ${c('RPC Connection:', ANSI.dimText)}    ${statusBadge}`,
+    `  ${c('Token Mint CA:', ANSI.dimText)}     ${c(OFFICIAL_TOKEN_CA, `${ANSI.bold}${ANSI.white}`)}`,
+    `  ${c('Proof Anchoring:', ANSI.dimText)}   Solana Memo Program (MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr)`,
+    `  ${c('Anchor Contracts:', ANSI.dimText)}  enigma_nullifier, enigma_context_escrow (in development)`,
+    `  ${c('Settlement Model:', ANSI.dimText)}  M2M context micro-escrows with receipt-hash release`,
+    `  ${c('Architecture:', ANSI.dimText)}      100% offline standalone vaults; optional on-chain proof anchoring`,
+  ];
+
+  return lines.join('\n') + '\n';
+}
+
+export function formatSolanaAnchorVerificationReport(report, { color = true } = {}) {
+  const c = (text, code) => (color ? `${code}${text}${ANSI.reset}` : text);
+  const verified = report?.ok === true && report?.verified_on_chain === true;
+  const status = verified
+    ? c('● VERIFIED', `${ANSI.bold}${ANSI.green}`)
+    : c('○ NOT VERIFIED', `${ANSI.bold}${ANSI.yellow}`);
+  const confirmation = report?.confirmation_status
+    ? `${report.confirmation_status}${report.confirmation_depth === null || report.confirmation_depth === undefined ? '' : ` (${report.confirmation_depth} confirmations)`}`
+    : 'unknown';
+  const lines = [
+    `  ${c('ENIGMA SOLANA ANCHOR VERIFICATION', `${ANSI.bold}${ANSI.amber}`)}`,
+    `  ${c('Status:', ANSI.dimText)}              ${status}`,
+    `  ${c('Cluster:', ANSI.dimText)}             ${report?.cluster ?? 'unknown'}`,
+    `  ${c('Signature:', ANSI.dimText)}           ${report?.signature ?? 'unknown'}`,
+    `  ${c('Slot / block time:', ANSI.dimText)}  ${report?.slot ?? 'unknown'} / ${report?.block_time ?? 'unknown'}`,
+    `  ${c('Confirmation:', ANSI.dimText)}        ${confirmation}`,
+    `  ${c('Slot depth:', ANSI.dimText)}          ${report?.slot_depth ?? 'unknown'}`,
+    `  ${c('Artifact hash:', ANSI.dimText)}      ${report?.artifact_hash ?? 'unknown'}`,
+    `  ${c('Proof commitment:', ANSI.dimText)}   ${report?.proof_commitment ?? 'unknown'}`,
+    `  ${c('Verification state:', ANSI.dimText)} ${report?.verification_status ?? 'unknown'}`,
+    ...(report?.error?.message ? [`  ${c('Error:', ANSI.dimText)}              ${report.error.message}`] : []),
+    `  ${c('Boundary:', ANSI.dimText)}           public commitment only; no factual-truth, hallucination, provider-deletion, or physical-deletion claim`,
+  ];
+  return lines.join('\n') + '\n';
+}

package/packages/terminal-console/solana-transport.mjs

@@ -0,0 +1,189 @@
+// Enigma Sovereign AI Memory — Solana Transport Layer
+// Enforces Mainnet genesis verification, dynamic fee computation with 5,000 lamport clamp,
+// SPL Memo program allowlisting, parsed transaction confirmation, and secret key zeroization.
+
+import { SOLANA_MAINNET_RPC } from './phantom-bridge.mjs';
+import { sha256Json, PROOF_NETWORK_ANCHOR_BATCH_SCHEMA } from '../proof-network/src/index.js';
+
+export const SOLANA_MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
+export const SOLANA_MAINNET_GENESIS_HASH = '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d';
+export const MAX_AUTO_ANCHOR_FEE_LAMPORTS = 5000;
+
+export function createSolanaProofMemoRef(schema, artifact, cluster = 'mainnet-beta') {
+  const artifactHash = sha256Json(artifact);
+  const proofCommitment = sha256Json({
+    rail: 'solana-memo-v1',
+    cluster,
+    artifact_type: schema,
+    artifact_hash: artifactHash,
+  });
+  return {
+    v: 1,
+    protocol: 'enigma-proof-network',
+    rail: 'solana-memo',
+    cluster,
+    artifact_type: schema,
+    artifact_hash: artifactHash,
+    proof_commitment: proofCommitment,
+  };
+}
+
+export class SolanaTransport {
+  constructor({
+    rpcUrl = SOLANA_MAINNET_RPC,
+    cluster = 'mainnet-beta',
+    fetchFn = globalThis.fetch,
+    maxFeeLamports = MAX_AUTO_ANCHOR_FEE_LAMPORTS,
+  } = {}) {
+    this.rpcUrl = rpcUrl;
+    this.cluster = cluster;
+    this.fetchFn = fetchFn;
+    this.maxFeeLamports = maxFeeLamports;
+  }
+
+  async verifyGenesisHash() {
+    const res = await this.fetchFn(this.rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 'genesis-check', method: 'getGenesisHash' }),
+    });
+    const data = await res.json();
+    const hash = data?.result;
+    if (this.cluster === 'mainnet-beta' && hash !== SOLANA_MAINNET_GENESIS_HASH) {
+      throw new Error(`Solana RPC genesis mismatch: got ${hash}, expected ${SOLANA_MAINNET_GENESIS_HASH}`);
+    }
+    return hash;
+  }
+
+  async getBalance(publicKeyBase58) {
+    const res = await this.fetchFn(this.rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 'bal-check', method: 'getBalance', params: [publicKeyBase58] }),
+    });
+    const data = await res.json();
+    const lamports = Number(data?.result?.value ?? 0);
+    return { lamports, balanceSol: (lamports / 1e9).toFixed(4) };
+  }
+
+  async broadcastMemo({ payerSecretKey, memoRef }) {
+    if (!Buffer.isBuffer(payerSecretKey) || payerSecretKey.length !== 64) {
+      throw new Error('payerSecretKey must be a 64-byte Buffer');
+    }
+    if (!memoRef || typeof memoRef !== 'object') {
+      throw new Error('Invalid memoRef payload');
+    }
+
+    await this.verifyGenesisHash();
+
+    // Dynamically load Solana web3 SDK
+    const web3 = await import('@solana/web3.js');
+    const { Connection, Keypair, PublicKey, Transaction, TransactionInstruction, sendAndConfirmTransaction } = web3;
+
+    let payer;
+    try {
+      payer = Keypair.fromSecretKey(payerSecretKey);
+    } finally {
+      // Memory safety: Zeroize volatile secret key buffer copy after keypair creation
+      try {
+        payerSecretKey.fill(0);
+      } catch {}
+    }
+
+    const connection = new Connection(this.rpcUrl, 'confirmed');
+    const memoBytes = Buffer.from(JSON.stringify(memoRef), 'utf8');
+
+    const instruction = new TransactionInstruction({
+      keys: [],
+      programId: new PublicKey(SOLANA_MEMO_PROGRAM_ID),
+      data: memoBytes,
+    });
+
+    const { blockhash } = await connection.getLatestBlockhash('confirmed');
+    const transaction = new Transaction({ feePayer: payer.publicKey, recentBlockhash: blockhash }).add(instruction);
+
+    // Dynamic Fee Query & Clamp Verification
+    const message = transaction.compileMessage();
+    const feeRes = await connection.getFeeForMessage(message, 'confirmed');
+    const estimatedFee = Number(feeRes?.value ?? 5000);
+
+    if (estimatedFee > this.maxFeeLamports) {
+      throw new Error(`Estimated transaction fee (${estimatedFee} lamports) exceeds maximum auto-anchor fee policy (${this.maxFeeLamports} lamports)`);
+    }
+
+    // Submit and confirm
+    const signature = await sendAndConfirmTransaction(connection, transaction, [payer], { commitment: 'confirmed' });
+
+    return await this.verifyTransactionOnChain(connection, signature, memoRef, estimatedFee);
+  }
+
+  async verifyTransactionOnChain(connection, signature, expectedMemoRef, fee = 5000) {
+    if (!expectedMemoRef || typeof expectedMemoRef !== 'object') {
+      throw new Error('expectedMemoRef must be a canonical memoRef object');
+    }
+
+    const parsedTx = await connection.getParsedTransaction(signature, {
+      commitment: 'confirmed',
+      maxSupportedTransactionVersion: 0,
+    });
+
+    if (!parsedTx || parsedTx.meta?.err !== null) {
+      throw new Error(`On-chain transaction execution failed: ${signature}`);
+    }
+
+    // Verify SPL Memo program ID and instruction presence
+    const memoIx = parsedTx.transaction?.message?.instructions?.find((ix) => {
+      const progId = ix.programId?.toBase58 ? ix.programId.toBase58() : String(ix.programId || '');
+      return progId === SOLANA_MEMO_PROGRAM_ID;
+    });
+
+    if (!memoIx) {
+      throw new Error(`Transaction ${signature} missing verified SPL Memo program instruction`);
+    }
+
+    // Extract memo text from parsed or data field
+    const rawMemoText = typeof memoIx.parsed === 'string'
+      ? memoIx.parsed
+      : (typeof memoIx.data === 'string' ? Buffer.from(memoIx.data, 'base64').toString('utf8') : '');
+
+    let observed;
+    try {
+      observed = JSON.parse(rawMemoText);
+    } catch {
+      throw new Error('On-chain memo payload is not valid JSON');
+    }
+
+    // Exact field-by-field equality checks against canonical memoRef contract
+    if (observed.v !== expectedMemoRef.v) {
+      throw new Error(`Memo version mismatch: got ${observed.v}, expected ${expectedMemoRef.v}`);
+    }
+    if (observed.protocol !== expectedMemoRef.protocol) {
+      throw new Error(`Memo protocol mismatch: got ${observed.protocol}, expected ${expectedMemoRef.protocol}`);
+    }
+    if (observed.rail !== expectedMemoRef.rail) {
+      throw new Error(`Memo rail mismatch: got ${observed.rail}, expected ${expectedMemoRef.rail}`);
+    }
+    if (observed.cluster !== expectedMemoRef.cluster) {
+      throw new Error(`Memo cluster mismatch: got ${observed.cluster}, expected ${expectedMemoRef.cluster}`);
+    }
+    if (observed.artifact_type !== expectedMemoRef.artifact_type) {
+      throw new Error(`Memo artifact_type mismatch: got ${observed.artifact_type}, expected ${expectedMemoRef.artifact_type}`);
+    }
+    if (observed.artifact_hash !== expectedMemoRef.artifact_hash) {
+      throw new Error(`Memo artifact_hash mismatch: got ${observed.artifact_hash}, expected ${expectedMemoRef.artifact_hash}`);
+    }
+    if (observed.proof_commitment !== expectedMemoRef.proof_commitment) {
+      throw new Error(`Memo proof_commitment mismatch: got ${observed.proof_commitment}, expected ${expectedMemoRef.proof_commitment}`);
+    }
+
+    return {
+      signature,
+      slot: parsedTx.slot,
+      blockTime: parsedTx.blockTime,
+      cluster: this.cluster,
+      solscanUrl: `https://solscan.io/tx/${signature}`,
+      feePaidLamports: parsedTx.meta?.fee ?? fee,
+      observedMemo: observed,
+    };
+  }
+}