@sage-protocol/cli 0.3.0 → 0.3.3

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

@@ -7,211 +7,223 @@ 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.
-  // The Factory doesn't expose `isSubDAO(name)`. It exposes `isSubDAO(address)`.
-  // But we can't know address until we deploy.
-  // Best effort: check local profiles for name collision?
-  // Or rely on user?
-  // "Preflight: if a SubDAO with same name/owner exists, skip create" - User Requirement
-  // Factory events scan is too slow. 
-  // We will warn if we see a similar entry in .sage/subdaos.json.
-  // And/Or if user passed --subdao override? No, create generates one.
-  // We will skip this heavy scan and rely on "check-then-set" via create2 if possible, but Factory uses create.
-  // For Operator mode, we can check if the Safe is already an admin of a SubDAO? Hard.
-  // Let's implement a simple check: if file "subdao-plan-<timestamp>.json" exists? No.
-  // User: "if a SubDAO with same name/owner exists".
-  // We will skip if we find a local alias with same name.
-  const SubDAOStore = require('../../utils/subdao-store');
-  const store = new SubDAOStore();
-  const existing = store.list().find(s => s.alias === plan.config.name);
-  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.upload(plan.playbook);
-      playbookCid = res.cid;
-      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,
-    forkingPolicy: plan.config.forkingPolicy,
-    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.');
+    let plan;
+    if (typeof planOrPath === 'string') {
+        const content = fs.readFileSync(planOrPath, 'utf8');
+        plan = JSON.parse(content);
+    } else {
+        plan = planOrPath;
     }
 
-    // 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}`);
-    }
+    console.log(`Applying Plan: ${plan.config.name} (${plan.playbook.name})`);
 
-    // 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).');
+    // 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.
     }
 
-    console.log(`   Executor: ${executor}`);
-    
+    // Stamping: Pin Playbook to IPFS
+    console.log('📌 Stamping Playbook to IPFS...');
+    let playbookCid = '';
     try {
-         // Stamping? createSubDAOOperator arguments:
-         // name, desc, accessModel, executor, admin, minStake, burnAmount
-         // It lacks profileCid.
-         // We must call setProfileCid AFTER creation if factory doesn't support it.
-         // OR use createSubDAOOperatorWithParams if available?
-         // Assuming standard factory.
-         
-         const tx = await factory.createSubDAOOperator(
-             plan.config.name,
-             plan.config.description,
-             accessModel,
-             executor, // executor (Timelock role)
-             executor, // admin (SubDAO 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
-         // Event: SubDAOCreated(address indexed subDAO, ...)
-         // We reuse SubDAOManager logic or parse manually
-         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 (if CID exists)
-             if (playbookCid) {
-                 console.log('📌 Applying Playbook Stamp (Profile CID)...');
-                 // We need to call setProfileCid via the Admin.
-                 // If WE (signer) are not the admin (Safe is), we can't directly set it.
-                 // We must PROPOSE it to the Safe if we are an owner.
-                 // Or assume user will do it.
-                 // "Fix: ...stamp the playbook manifest CID into SubDAO metadata."
-                 // If executor == Safe, we can't easily set it now synchronously.
-                 // We warn and output the instruction.
-                 
-                 // Check if setProfileCid exists on SubDAO contract
-                 const subdao = new ethers.Contract(subdaoAddr, ['function setProfileCid(string)'], manager.signer);
-                 // Checking function existence without call is hard on ethers v6 without ABI check or call.
-                 // We can try to estimateGas or call static. 
-                 // Or check code? No.
-                 // Check if ABI fragment matches?
-                 // If standard SubDAO doesn't have it, we skip.
-                 // Let's try to see if `setProfileCid` is in the contract by calling it? No, that reverts.
-                 // We rely on the artifact/ABI we used.
-                 // If the artifact has it, we try. If it reverts (method missing), we catch.
-                 
-                 try {
-                     if (typeof subdao.setProfileCid === 'function') {
-                          if (executor.toLowerCase() === (await manager.signer.getAddress()).toLowerCase()) {
-                             // We are admin
-                             const tx2 = await subdao.setProfileCid(playbookCid);
-                             await tx2.wait();
-                             console.log('✅ Stamped.');
-                         } else {
-                             console.warn('⚠️  Cannot stamp profileCid automatically (Admin is Safe/Other).');
-                             console.warn(`   Please propose call: setProfileCid("${playbookCid}") on ${subdaoAddr}`);
-                         }
-                     } else {
-                         console.warn('⚠️  SubDAO contract does not support setProfileCid.');
-                     }
-                 } catch (e) {
-                     console.warn('⚠️  Failed to stamp profileCid (likely not supported by contract):', e.message);
-                 }
-             }
-         }
-
+        const ipfs = new IpfsManager();
+        const res = await ipfs.uploadJson(plan.playbook, 'playbook');
+        playbookCid = res;
+        console.log(`   CID: ${playbookCid}`);
     } catch (e) {
-        console.error('❌ Operator creation failed:', e.message);
-        throw 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.
     }
 
-  } else {
-    // Token Governance (Community)
-    await manager.createSubDAO(
-        plan.config.name,
-        plan.config.description,
-        accessModel,
-        plan.config.minStake || '0',
-        plan.config.burnAmount || '0',
-        creationOpts
-    );
-  }
+    // 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

@@ -2,6 +2,8 @@ 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
@@ -27,6 +29,25 @@ function parseDurationToBlocks(durationStr, blockTimeSec = 12) {
   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;
@@ -69,6 +90,13 @@ async function planSubDAO(options) {
     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 };
@@ -87,18 +115,25 @@ async function planSubDAO(options) {
       name: merged.name,
       description: merged.description,
       accessModel: 'governance', 
-      minStake: merged.minStake,
+      minStake: merged.minStake || '0',
       owners: merged.owners,
       threshold: merged.threshold,
-      proposalThreshold: playbook.params.proposalThreshold,
-      votingPeriod: playbook.params.votingPeriod, 
-      quorumBps: playbook.params.quorumBps,
+      // 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
-  const blockTime = options.blockTimeSec ? parseInt(options.blockTimeSec, 10) : 12;
+  // 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;

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,6 +78,11 @@ const COMMAND_CATALOG = {
     needsSubcommand: true,
     subcommands: [
       'push',
+      'template',
+      'add-prompt',
+      'preview',
+      'examples',
+      'propose-import',
       'cache',
       'check',
       'check',
@@ -89,7 +101,10 @@ const COMMAND_CATALOG = {
     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 };
+