@sage-protocol/cli 0.2.9 → 0.3.2

package/dist/cli/services/metaprompt/designer.js

@@ -57,7 +57,7 @@ class MetapromptDesigner {
     const history = this.path.join(base, 'history');
     try {
       this.fs.mkdirSync(history, { recursive: true });
-    } catch (_) {}
+    } catch (_) { }
     return history;
   }
 
@@ -103,7 +103,7 @@ class MetapromptDesigner {
       if (value.startsWith('[') && value.endsWith(']')) {
         try {
           value = JSON.parse(value.replace(/'/g, '"'));
-        } catch (_) {}
+        } catch (_) { }
       }
       meta[key] = value;
     });
@@ -197,9 +197,10 @@ class MetapromptDesigner {
       goal = 'Design a system prompt for an AI assistant that specialises in Sage Protocol development and prompt operations.',
       model = 'gpt-5',
       interviewStyle = 'one-question-at-a-time',
+      additionalInstructions = '',
     } = options;
 
-    return [
+    const lines = [
       'You are facilitating a metaprompt interview.',
       'Interview me one question at a time.',
       'Use each answer to decide the very next question.',
@@ -211,13 +212,19 @@ class MetapromptDesigner {
       'Offer optional follow-up artifacts (e.g., user prompt template, evaluation checklist).',
       'End by suggesting how to save or launch the prompt (e.g., via ChatGPT link).',
       `Interview cadence preference: ${interviewStyle}.`,
-    ].join('\n');
+    ];
+
+    if (additionalInstructions) {
+      lines.push(additionalInstructions);
+    }
+
+    return lines.join('\n');
   }
 
   saveTranscript(transcriptPath, payload) {
     try {
       this.fs.mkdirSync(this.path.dirname(transcriptPath), { recursive: true });
-    } catch (_) {}
+    } catch (_) { }
     this.fs.writeFileSync(transcriptPath, JSON.stringify(payload, null, 2));
   }
 }

package/dist/cli/services/skills/discovery.js

@@ -0,0 +1,99 @@
+const fs = require('fs');
+const path = require('path');
+
+function readFrontmatter(raw) {
+  const meta = { title: null, summary: null, tags: [], targets: [] };
+  if (!raw || typeof raw !== 'string') return { meta, body: raw || '' };
+  if (!raw.startsWith('---')) return { meta, body: raw };
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return { meta, body: raw };
+  const header = raw.slice(3, end).split(/\r?\n/);
+  for (const line of header) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const k = line.slice(0, idx).trim().toLowerCase();
+    let v = line.slice(idx + 1).trim();
+    if (!v) continue;
+    if (k === 'title' || k === 'name') {
+      meta.title = v;
+    } else if (k === 'summary' || k === 'description') {
+      meta.summary = v;
+    } else if (k === 'tags' || k === 'targets') {
+      try {
+        const arr = JSON.parse(v.replace(/'/g, '"'));
+        if (Array.isArray(arr)) meta[k] = arr;
+      } catch (_) {
+        const arr = String(v)
+          .split(/[,|\s]+/)
+          .filter(Boolean);
+        meta[k] = arr;
+      }
+    }
+  }
+  const body = raw.slice(end + 4);
+  return { meta, body };
+}
+
+function walk(dir, out) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+}
+
+function findWorkspaceSkills({ promptsDir = 'prompts' } = {}) {
+  const root = path.join(process.cwd(), promptsDir, 'skills');
+  const results = [];
+  if (!fs.existsSync(root)) return results;
+
+  const files = [];
+  walk(root, files);
+
+  for (const filePath of files) {
+    const relFromPrompts = path.relative(path.join(process.cwd(), promptsDir), filePath).replace(/\\/g, '/');
+    const isDirSkill = /\/SKILL\.md$/i.test(relFromPrompts) && /(^|\/)skills\//.test(relFromPrompts);
+    const isFlatMd = /(^|\/)skills\//.test(relFromPrompts) && filePath.toLowerCase().endsWith('.md') && !/\/skill\.md$/i.test(filePath);
+    if (!isDirSkill && !isFlatMd) continue;
+
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const { meta } = readFrontmatter(raw);
+    const nameGuess = isDirSkill
+      ? path.basename(path.dirname(filePath))
+      : path.basename(filePath, '.md');
+    const name = meta.title || nameGuess;
+    const summary = meta.summary || '';
+    const tags = Array.isArray(meta.tags) ? meta.tags : [];
+    const key = isDirSkill
+      ? relFromPrompts.replace(/\/SKILL\.md$/i, '')
+      : relFromPrompts.replace(/\.md$/i, '');
+    const baseDir = isDirSkill ? path.dirname(filePath) : path.dirname(filePath);
+    results.push({
+      key,
+      name,
+      summary,
+      tags,
+      path: filePath,
+      baseDir,
+      type: isDirSkill ? 'directory' : 'flat',
+    });
+  }
+  return results;
+}
+
+function resolveSkillFileByKey({ promptsDir = 'prompts', key }) {
+  const normalized = String(key || '').replace(/^\/+/, '').replace(/\.md$/i, '');
+  const flat = path.join(process.cwd(), promptsDir, `${normalized}.md`);
+  const dirSkill = path.join(process.cwd(), promptsDir, normalized, 'SKILL.md');
+  if (fs.existsSync(flat)) return { path: flat, baseDir: path.dirname(flat), type: 'flat' };
+  if (fs.existsSync(dirSkill)) return { path: dirSkill, baseDir: path.dirname(dirSkill), type: 'directory' };
+  return null;
+}
+
+module.exports = {
+  readFrontmatter,
+  findWorkspaceSkills,
+  resolveSkillFileByKey,
+};
+

package/dist/cli/services/subdao/applier.js

@@ -0,0 +1,229 @@
+const fs = require('fs');
+const path = require('path');
+const SubDAOManager = require('../../subdao-manager');
+const IpfsManager = require('../../ipfs-manager');
+const { ethers } = require('ethers');
+const FactoryABI = require('../../utils/factory-abi');
+const { resolveArtifact } = require('../../utils/artifacts');
+
+async function applyPlan(planOrPath) {
+    let plan;
+    if (typeof planOrPath === 'string') {
+        const content = fs.readFileSync(planOrPath, 'utf8');
+        plan = JSON.parse(content);
+    } else {
+        plan = planOrPath;
+    }
+
+    console.log(`Applying Plan: ${plan.config.name} (${plan.playbook.name})`);
+
+    // Instantiate manager
+    const manager = new SubDAOManager();
+    const WalletManager = require('../../wallet-manager');
+    const wm = new WalletManager();
+    await wm.connect();
+    manager.signer = wm.getSigner();
+    manager.walletManager = wm;
+    await manager.initialize();
+    const provider = wm.getProvider();
+
+    // Idempotency Check: Check if SubDAO with this name is already registered in Factory
+    // Or locally in subdao store.
+    const store = require('../../utils/subdao-store');
+    const existing = (store.listFavorites?.() || []).find(f => (f.alias || '').toLowerCase() === String(plan.config.name || '').toLowerCase());
+    if (existing) {
+        console.warn(`⚠️  SubDAO with name "${plan.config.name}" already exists locally (${existing.address}).`);
+        // We proceed but warn.
+    }
+
+    // Stamping: Pin Playbook to IPFS
+    console.log('📌 Stamping Playbook to IPFS...');
+    let playbookCid = '';
+    try {
+        const ipfs = new IpfsManager();
+        const res = await ipfs.uploadJson(plan.playbook, 'playbook');
+        playbookCid = res;
+        console.log(`   CID: ${playbookCid}`);
+    } catch (e) {
+        console.warn(`⚠️  Failed to pin playbook: ${e.message}`);
+        // Fail fast if provenance is critical? User said "No IPFS stamping... Fix: Stamping".
+        // We should probably fail or retry.
+    }
+
+    // Convert accessModel string to int
+    const accessMap = { 'free': 0, 'governance': 1, 'hybrid': 2 };
+    const accessModel = accessMap[plan.config.accessModel || 'governance'] || 1;
+
+    // Creation options
+    const creationOpts = {
+        quorumPercentage: plan.config.quorumBps ? BigInt(plan.config.quorumBps) / 100n : 4n,
+        votingPeriodBlocks: plan.config.votingPeriodBlocks,
+        proposalThreshold: plan.config.proposalThreshold || '0',
+        forkingPolicy: plan.config.forkingPolicy || 'gov_only',
+        membershipPolicy: plan.playbook.governance === 'operator' ? 'admin' : 'stake',
+        profileCid: playbookCid // Stamp CID into profileCid field of SubDAO
+    };
+
+    if (plan.playbook.governance === 'operator') {
+        console.log('🏗️  Creating Operator/Team SubDAO...');
+
+        const factory = new ethers.Contract(manager.factoryAddress, FactoryABI, manager.signer);
+
+        // Validate Factory Support (ABI check)
+        if (typeof factory.createSubDAOOperator !== 'function') {
+            throw new Error('Factory does not support createSubDAOOperator. Upgrade factory or use Community playbook.');
+        }
+
+        // Resolve Executor (Safe)
+        let executor = plan.config.owners;
+        if (!executor) executor = await manager.signer.getAddress();
+
+        // If comma separated, warn and pick first.
+        if (executor.includes(',')) {
+            console.warn('⚠️  Multiple owners provided. Operator mode requires a SINGLE executor address (Safe or EOA).');
+            const parts = executor.split(',');
+            executor = parts[0].trim();
+            console.warn(`   Using first address: ${executor}`);
+        }
+
+        // Enforce Safe (Code Check)
+        const code = await provider.getCode(executor);
+        if (code === '0x') {
+            // EOA.
+            console.warn('⚠️  Executor is an EOA (External Account), not a Safe Contract.');
+            console.warn('   "Squad" playbook implies a Safe. Ensure you trust this single key.');
+            // User requirement: "Require a Safe address... or a created Safe".
+            // If playbook is 'squad', we MUST have a Safe.
+            if (plan.playbook.id === 'squad') {
+                throw new Error('Squad playbook requires a Safe contract address. Use "sage safe create" (if available) or create at app.safe.global and provide via --owners.');
+            }
+        } else {
+            console.log('✅ Executor is a Contract (Likely Safe).');
+        }
+
+        console.log(`   Executor: ${executor}`);
+
+        try {
+            // Check for createSubDAOOperatorWithParams (Prioritize Factory Path)
+            const hasNewOperatorCreate = factory.interface.fragments.some(
+                f => f.name === 'createSubDAOOperatorWithParams'
+            );
+
+            let tx;
+            if (hasNewOperatorCreate) {
+                console.log('✨ Using factory.createSubDAOOperatorWithParams (stamping supported)...');
+                tx = await factory.createSubDAOOperatorWithParams(
+                    plan.config.name,
+                    plan.config.description,
+                    accessModel,
+                    executor, // executor
+                    executor, // admin
+                    plan.config.minStake || 0,
+                    plan.config.burnAmount || 0,
+                    playbookCid || ''
+                );
+            } else {
+                console.log('⚠️  Factory does not support atomic stamping. Using legacy createSubDAOOperator...');
+                tx = await factory.createSubDAOOperator(
+                    plan.config.name,
+                    plan.config.description,
+                    accessModel,
+                    executor, // executor
+                    executor, // admin
+                    plan.config.minStake || 0,
+                    plan.config.burnAmount || 0
+                );
+            }
+
+            console.log('⏳ Waiting for tx:', tx.hash);
+            const receipt = await tx.wait();
+
+            // Parse logs to find SubDAO address
+            let subdaoAddr = null;
+            for (const log of receipt.logs) {
+                try {
+                    const parsed = factory.interface.parseLog(log);
+                    if (parsed.name === 'SubDAOCreated') {
+                        subdaoAddr = parsed.args[0];
+                        break;
+                    }
+                } catch (e) { }
+            }
+
+            if (subdaoAddr) {
+                console.log(`✅ SubDAO created: ${subdaoAddr}`);
+
+                // Post-Create Stamping (only if NOT stamped via params)
+                if (playbookCid && !hasNewOperatorCreate) {
+                    console.log('📌 Applying Playbook Stamp (Profile CID)...');
+
+                    const subdao = new ethers.Contract(subdaoAddr, ['function setProfileCid(string)'], manager.signer);
+
+                    try {
+                        // Check if we are the admin (executor)
+                        const myAddr = await manager.signer.getAddress();
+                        if (executor.toLowerCase() === myAddr.toLowerCase()) {
+                            // We are admin
+                            console.log('   Directly calling setProfileCid...');
+                            const tx2 = await subdao.setProfileCid(playbookCid);
+                            await tx2.wait();
+                            console.log('✅ Stamped.');
+                        } else {
+                            console.warn('⚠️  Cannot stamp profileCid automatically (Admin is Safe/Other).');
+
+                            // Generate Safe Payload (Post-Create Fallback)
+                            const iface = new ethers.Interface(['function setProfileCid(string)']);
+                            const calldata = iface.encodeFunctionData('setProfileCid', [playbookCid]);
+
+                            const safeBatch = {
+                                version: "1.0",
+                                chainId: (await provider.getNetwork()).chainId.toString(),
+                                createdAt: Date.now(),
+                                meta: { name: "Stamp Playbook CID", description: `Set profileCid to ${playbookCid}` },
+                                transactions: [{
+                                    to: subdaoAddr,
+                                    value: "0",
+                                    data: calldata,
+                                    operation: 0 // Call
+                                }]
+                            };
+
+                            const filename = `safe-tx-stamp-${Date.now()}.json`;
+                            fs.writeFileSync(filename, JSON.stringify(safeBatch, null, 2));
+
+                            console.log(`\n📋 Safe Transaction Payload saved to ${filename}`);
+                            console.log(JSON.stringify(safeBatch, null, 2));
+                            console.log('\n   Use this JSON in the Safe Transaction Builder to stamp the playbook.');
+                        }
+                    } catch (e) {
+                        console.warn('⚠️  Failed to stamp profileCid:', e.message);
+                        console.warn('   This SubDAO contract version might not support setProfileCid.');
+                    }
+                }
+            }
+
+        } catch (e) {
+            console.error('❌ Operator creation failed:', e.message);
+            throw e;
+        }
+
+    } else {
+        // Token Governance (Community)
+        // Community playbook uses createSubDAO (legacy) or createSubDAOWithParams (new) logic.
+        // If token mode, we usually rely on `createSubDAO` which calls internal logic.
+        // But check if we can stamp there too.
+        // The `creationOpts` already has `profileCid`. 
+        // If SubDAOManager.createSubDAO supports it, we are good.
+        
+        await manager.createSubDAO(
+            plan.config.name,
+            plan.config.description,
+            accessModel,
+            plan.config.minStake || '0',
+            plan.config.burnAmount || '0',
+            creationOpts // Ensure manager uses this
+        );
+    }
+}
+
+module.exports = { applyPlan };

package/dist/cli/services/subdao/planner.js

@@ -0,0 +1,142 @@
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const playbooksService = require('../governance/playbooks');
+const { ethers } = require('ethers');
+const config = require('../../config');
+
+function parseDurationToBlocks(durationStr, blockTimeSec = 12) {
+  if (!durationStr) return Math.ceil(3 * 24 * 3600 / blockTimeSec); // Default ~3 days
+  
+  const str = String(durationStr).toLowerCase().trim();
+  
+  // If already integer
+  if (/^\d+$/.test(str)) return parseInt(str, 10);
+  
+  const match = str.match(/^(\d+)\s*(d|days?|h|hours?|m|minutes?|blocks?)$/);
+  if (!match) return Math.ceil(3 * 24 * 3600 / blockTimeSec); // Fallback
+  
+  const val = parseInt(match[1], 10);
+  const unit = match[2];
+  
+  if (unit.startsWith('block')) return val;
+  
+  let seconds = 0;
+  if (unit.startsWith('d')) seconds = val * 24 * 3600;
+  else if (unit.startsWith('h')) seconds = val * 3600;
+  else if (unit.startsWith('m')) seconds = val * 60;
+  
+  return Math.ceil(seconds / blockTimeSec);
+}
+
+async function detectBlockTimeSec(rpcUrl) {
+  try {
+    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const latest = await provider.getBlockNumber();
+    const older = latest > 100 ? latest - 100 : (latest > 1 ? 1 : 0);
+    const [bLatest, bOlder] = await Promise.all([
+      provider.getBlock(latest),
+      provider.getBlock(older),
+    ]);
+    if (!bLatest || !bOlder || !bLatest.timestamp || !bOlder.timestamp) return 12;
+    const dt = Number(bLatest.timestamp) - Number(bOlder.timestamp);
+    if (dt <= 0) return 12;
+    const sec = Math.max(1, Math.round(dt / Math.max(1, latest - older)));
+    return sec;
+  } catch (_) {
+    return 12;
+  }
+}
+
+async function planSubDAO(options) {
+  // 1. Select Playbook
+  let playbookId = options.playbook;
+  if (!playbookId && !options.yes) {
+    const playbooks = playbooksService.listPlaybooks();
+    const choices = playbooks.map(p => ({
+      name: `${p.name} - ${p.description}`,
+      value: p.id
+    }));
+    
+    const ans = await inquirer.prompt([{
+      type: 'list',
+      name: 'playbookId',
+      message: 'Select a Governance Playbook:',
+      choices
+    }]);
+    playbookId = ans.playbookId;
+  }
+
+  if (!playbookId) throw new Error('Playbook is required');
+
+  const playbook = playbooksService.getPlaybook(playbookId);
+  if (!playbook) throw new Error(`Unknown playbook: ${playbookId}`);
+
+  console.log(`\nUsing Playbook: ${playbook.name} (${playbook.version})\n`);
+
+  // 2. Gather Inputs (merged with playbook defaults)
+  const questions = [];
+  if (!options.name) questions.push({ type: 'input', name: 'name', message: 'SubDAO Name:' });
+  if (!options.description) questions.push({ type: 'input', name: 'description', message: 'Description:' });
+
+  // Playbook specific inputs
+  if (playbook.governance === 'operator' && !options.owners) {
+    questions.push({ type: 'input', name: 'owners', message: 'Safe Owners (comma separated):', default: options.owners });
+    questions.push({ type: 'input', name: 'threshold', message: 'Safe Threshold:', default: '1' });
+  }
+  
+  // Token governance inputs
+  if (playbook.governance === 'token' && !options.minStake) {
+    questions.push({ type: 'input', name: 'minStake', message: 'Minimum Stake (SXXX):', default: '0' });
+  }
+
+  // Governance tuning (overrides) — prompt only in wizard mode or when overrides are missing
+  if (options.wizard) {
+    if (!options.votingPeriod) questions.push({ type: 'input', name: 'votingPeriod', message: 'Voting period (e.g., 7 days):', default: (playbook.params?.votingPeriod || '') });
+    if (!options.quorumBps) questions.push({ type: 'input', name: 'quorumBps', message: 'Quorum (bps, e.g., 200 = 2%):', default: (playbook.params?.quorumBps ?? '') });
+    if (!options.proposalThreshold) questions.push({ type: 'input', name: 'proposalThreshold', message: 'Proposal threshold (string/wei):', default: (playbook.params?.proposalThreshold || '') });
+  }
+
+  const answers = questions.length > 0 ? await inquirer.prompt(questions) : {};
+  
+  const merged = { ...options, ...answers };
+
+  // 3. Construct Plan
+  const plan = {
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    playbook: {
+      id: playbook.id,
+      version: playbook.version,
+      name: playbook.name,
+      governance: playbook.governance
+    },
+    config: {
+      name: merged.name,
+      description: merged.description,
+      accessModel: 'governance', 
+      minStake: merged.minStake || '0',
+      owners: merged.owners,
+      threshold: merged.threshold,
+      // Default to 1000 SXXX (minimum burn) if not provided
+      burnAmount: merged.burnAmount || '1000000000000000000000',
+      proposalThreshold: merged.proposalThreshold || playbook.params?.proposalThreshold || '0',
+      votingPeriod: merged.votingPeriod || playbook.params?.votingPeriod || '3 days',
+      quorumBps: merged.quorumBps != null && merged.quorumBps !== '' ? Number(merged.quorumBps) : (playbook.params?.quorumBps ?? 400),
+      forkingPolicy: 'gov_only',
+    }
+  };
+  
+  // Normalize voting period to blocks with override or auto-detect
+  let blockTime = 12;
+  if (options.blockTimeSec) blockTime = parseInt(options.blockTimeSec, 10);
+  else {
+    const rpc = config.resolveRpcUrl ? config.resolveRpcUrl() : (process.env.RPC_URL || 'https://base-sepolia.publicnode.com');
+    blockTime = await detectBlockTimeSec(rpc);
+  }
+  plan.config.votingPeriodBlocks = parseDurationToBlocks(plan.config.votingPeriod, blockTime).toString();
+
+  return plan;
+}
+
+module.exports = { planSubDAO, parseDurationToBlocks };

package/dist/cli/subdao-manager.js

@@ -15,6 +15,7 @@ const GAS_FLAGS = '--legacy --gas-limit 3000000 --gas-price 2gwei';
 const { resolvePermitOrApprove, normalizePermit, zeroPermit } = require('./utils/permit');
 const { ethers } = require('ethers');
 const FactoryABI = require('./utils/factory-abi');
+const { decodeContractError } = require('./utils/contract-error-decoder');
 
 const DEFAULT_TIMELOCK_MIN_DELAY = process.env.SAGE_TIMELOCK_MIN_DELAY_SECONDS || '1';
 const DEFAULT_TIMELOCK_DELAY_FLOOR =
@@ -31,6 +32,19 @@ function toBigInt(value) {
 
 function formatFactoryCreationError(err) {
 	if (!err) return 'Unknown error';
+
+    // Try precise decoding first
+    try {
+        const iface = new ethers.Interface(FactoryABI);
+        const decoded = decodeContractError(err, iface);
+        if (decoded && decoded !== 'Unknown Error' && !decoded.startsWith('Transaction failed')) {
+            const reason = decoded;
+            if (reason.includes('BurnOutOfBounds')) return `${reason} (Burn amount is outside the allowed range)`;
+            if (reason.includes('InsufficientSXXXBalance')) return `${reason} (Check SXXX balance and allowance)`;
+            return reason;
+        }
+    } catch (_) {}
+
 	const name = err.error?.errorName || err.errorName || '';
 	const reason = err.reason || err.shortMessage || err.message || '';
 	const details = reason || name;

package/dist/cli/utils/aliases.js

@@ -19,6 +19,7 @@ const COMMAND_CATALOG = {
     needsSubcommand: true,
     subcommands: [
       'create',
+      'create-playbook',
       'create-template',
       'list',
       'list-all',
@@ -50,14 +51,20 @@ const COMMAND_CATALOG = {
       'info',
       'list',
       'vote',
+      'vote-with-reason',
       'queue',
       'execute',
       'status',
       'inspect',
       'watch',
       'power',
+      'preflight',
       'doctor',
-      'propose'
+      'propose',
+      'propose-custom',
+      'list-all-subdaos',
+      'wait',
+      'wizard'
     ],
     subcommandAliases: {
       ls: 'list',
@@ -71,18 +78,33 @@ const COMMAND_CATALOG = {
     needsSubcommand: true,
     subcommands: [
       'push',
-      'propose',
-      'status',
+      'template',
+      'add-prompt',
+      'preview',
+      'examples',
+      'propose-import',
       'cache',
       'check',
-      'lint',
+      'check',
+      'doctor',
       'diff',
-      'doctor'
+      'execute',
+      'latest-prompts',
+      'lint',
+      'list',
+      'propose',
+      'search',
+      'status',
+      'sync-alt',
+      'view-prompts'
     ],
     subcommandAliases: {
       ls: 'status',
       status: 'status',
-      propose: 'propose'
+      tpl: 'template',
+      add: 'add-prompt',
+      view: 'preview',
+      ex: 'examples'
     }
   },
   prompt: {

package/dist/cli/utils/contract-error-decoder.js

@@ -0,0 +1,61 @@
+const { ethers } = require('ethers');
+
+/**
+ * Attempts to decode a contract error using provided interfaces.
+ * @param {Error} error - The error object caught from ethers.js
+ * @param {ethers.Interface|ethers.Contract|Array<ethers.Interface|ethers.Contract>} contractsOrInterfaces - Context to decode against
+ * @returns {string} - Human readable error message or original message
+ */
+function decodeContractError(error, contractsOrInterfaces = []) {
+  if (!error) return 'Unknown Error';
+
+  // Normalize inputs
+  const contexts = Array.isArray(contractsOrInterfaces) ? contractsOrInterfaces : [contractsOrInterfaces];
+  const interfaces = contexts.map(c => {
+    if (c instanceof ethers.Interface) return c;
+    if (c.interface instanceof ethers.Interface) return c.interface;
+    return null;
+  }).filter(Boolean);
+
+  // Extract data
+  // Ethers v6 often puts the revert data in error.data, error.info.error.data, or error.revert.data
+  let data = error.data;
+  if (!data && error.info?.error?.data) data = error.info.error.data;
+  if (!data && error.revert?.data) data = error.revert.data;
+  if (!data && typeof error.message === 'string') {
+     // Sometimes it's buried in the message string: "execution reverted: ..." or hex
+     // But parsing message is brittle.
+  }
+
+  // If we have data, try to decode
+  if (data && data !== '0x') {
+    for (const iface of interfaces) {
+      try {
+        const parsed = iface.parseError(data);
+        if (parsed) {
+          // Format: "ErrorName(arg1, arg2)"
+          const args = parsed.args ? Array.from(parsed.args).join(', ') : '';
+          return `Reverted: ${parsed.name}(${args})`;
+        }
+      } catch (e) {
+        // Ignore parse errors, try next interface
+      }
+    }
+  }
+
+  // Fallback: check for string revert reasons in the error object
+  if (error.reason) return `Reverted: ${error.reason}`;
+  if (error.shortMessage) return `Error: ${error.shortMessage}`;
+  if (error.message) {
+      // Clean up common noise
+      if (error.message.includes('execution reverted')) {
+          return error.message.split('execution reverted')[1].trim() || 'Execution Reverted';
+      }
+      return error.message;
+  }
+
+  return 'Transaction failed with unknown error';
+}
+
+module.exports = { decodeContractError };
+