pandora-cli-skills 1.1.16 → 1.1.18

package/README.md

@@ -0,0 +1,40 @@
+# Pandora CLI & Skills
+
+Production CLI for Pandora prediction markets with mirror + hedge tooling.
+
+## Install
+
+```bash
+npm i -g pandora-cli-skills
+pandora --help
+```
+
+Or run without installing:
+
+```bash
+npx pandora-cli-skills@latest --help
+```
+
+## Core commands
+
+- `pandora markets list|get`
+- `pandora quote`
+- `pandora trade`
+- `pandora history`
+- `pandora export`
+- `pandora arbitrage`
+- `pandora autopilot run|once`
+- `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
+- `pandora polymarket check|approve|preflight|trade`
+
+## Mirror economics commands
+
+- `pandora mirror lp-explain --liquidity-usdc 10000 --source-yes-pct 58`
+- `pandora mirror hedge-calc --reserve-yes-usdc 8 --reserve-no-usdc 12 --excess-no-usdc 2 --polymarket-yes-pct 60`
+- `pandora mirror simulate --liquidity-usdc 10000 --source-yes-pct 58 --target-yes-pct 58 --volume-scenarios 1000,5000,10000`
+
+## Notes
+
+- Node.js `>=18` required.
+- Full operational and JSON contract documentation is in
+  [`README_FOR_SHARING.md`](./README_FOR_SHARING.md).

package/README_FOR_SHARING.md

@@ -96,7 +96,8 @@ Prerequisite: Node.js `>=18`.
   - `pandora leaderboard --metric profit|volume|win-rate`
   - `pandora analyze --market-address <0x...> --provider <name>`
   - `pandora suggest --wallet <0x...> --risk low|medium|high --budget <amount>`
-  - ABI-gated placeholders: `pandora resolve`, `pandora lp`
+  - `pandora resolve`
+  - `pandora lp add|remove|positions`
 
 ## Read-only examples
 - `pandora markets list --limit 20 --order-by createdAt --order-direction desc`
@@ -235,8 +236,8 @@ Prerequisite: Node.js `>=18`.
 - `suggest`:
   - envelope is `ok=true`, `command="suggest"`, with ranked suggestions, sizing, and risk notes.
 
-## ABI-gated commands
-- `resolve` and `lp` are intentionally gated and return `ABI_READY_REQUIRED` until verified ABI signatures/events and integration tests are committed.
+## Resolve/LP commands
+- `resolve` and `lp` are active command paths with strict flag validation, runtime preflight checks, and decoded on-chain revert reporting.
 
 ## Pandora Mainnet Reference
 - PredictionOracle (Factory): `0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442`
@@ -282,8 +283,8 @@ Prerequisite: Node.js `>=18`.
   - `pandora leaderboard`
   - `pandora analyze`
   - `pandora suggest`
-  - `pandora resolve` (ABI-gated)
-  - `pandora lp` (ABI-gated)
+  - `pandora resolve`
+  - `pandora lp add|remove|positions`
   - `pandora polls list|get`
   - `pandora events list|get`
   - `pandora positions list`

package/SKILL.md

@@ -45,12 +45,13 @@ npm link
   - `pandora export`
   - `pandora arbitrage`
   - `pandora autopilot run|once`
-  - `pandora mirror browse|plan|deploy|verify|go|sync|status|close`
+  - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
   - `pandora webhook test`
   - `pandora leaderboard`
   - `pandora analyze`
   - `pandora suggest`
-  - ABI-gated placeholders: `pandora resolve`, `pandora lp`
+  - `pandora resolve`
+  - `pandora lp add|remove|positions`
 - Doctor checks:
   - env presence + format validation
   - RPC reachability and chain id match
@@ -100,6 +101,9 @@ pandora --output json arbitrage --venues pandora,polymarket --min-spread-pct 3 -
 pandora --output json autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper
 pandora --output json mirror browse --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10
 pandora --output json mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity
+pandora --output json mirror lp-explain --liquidity-usdc 10000 --source-yes-pct 58
+pandora --output json mirror hedge-calc --reserve-yes-usdc 8 --reserve-no-usdc 12 --excess-no-usdc 2 --polymarket-yes-pct 60
+pandora --output json mirror simulate --liquidity-usdc 10000 --source-yes-pct 58 --target-yes-pct 58 --volume-scenarios 1000,5000,10000
 pandora --output json mirror go --polymarket-slug <slug> --liquidity-usdc 10 --paper
 pandora --output json mirror verify --pandora-market-address <0x...> --polymarket-market-id <id> --include-similarity
 pandora --output json mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper --hedge-ratio 1.0
@@ -168,6 +172,9 @@ pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --inclu
 - `mirror browse`: Polymarket candidate discovery with optional Pandora mirror hints.
 - `mirror deploy`: dry-run/execute Pandora AMM deployment from mirror plan inputs, with execute-time wallet preflight and trust-manifest persistence.
 - `mirror verify`: explicit question/rules similarity endpoint for AI-subagent validation, with optional `--trust-deploy` manifest bypass for similarity.
+- `mirror lp-explain`: complete-set liquidity walkthrough (minted YES/NO, seeded pool reserves, returned excess inventory).
+- `mirror hedge-calc`: reserve/excess-driven hedge sizing (`deltaTotalUsdc`, target hedge leg, break-even volume).
+- `mirror simulate`: planning-grade LP + hedge scenario simulation with customizable `--volume-scenarios`.
 - `mirror go`: one-command orchestration for plan → deploy → verify, with optional auto-sync start.
 - `mirror sync`: paper-first delta-neutral loop with strict gates, state persistence, and optional live hedging (`--hedge-ratio <n>`, `--no-hedge`).
   - live hedge env: `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_FUNDER`, `POLYMARKET_API_KEY`, `POLYMARKET_API_SECRET`, `POLYMARKET_API_PASSPHRASE`, `POLYMARKET_HOST`.
@@ -184,7 +191,7 @@ pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --inclu
   - invalid indexer aggregates are sanitized (win-rate capped to 0-100%) and emitted in diagnostics.
 - `analyze`: provider-agnostic market analysis interface (fails with structured error when provider is not configured).
 - `suggest`: risk/budget-ranked opportunities seeded from arbitrage output and wallet history.
-- `resolve` and `lp`: intentionally return `ABI_READY_REQUIRED` until ABI readiness sign-off.
+- `resolve` and `lp`: enabled command paths with strict flag/runtime validation and decoded on-chain revert reporting.
 
 ## Pandora mainnet deployment reference
 - PredictionOracle (Factory): `0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442`

package/cli/lib/mirror_econ_service.cjs

@@ -37,7 +37,6 @@ function rawUsdcToNumber(rawValue) {
 function toPercent(value) {
   const numeric = toNumber(value);
   if (numeric === null) return null;
-  if (numeric >= 0 && numeric <= 1) return round(numeric * 100, 6);
   if (numeric >= 0 && numeric <= 100) return round(numeric, 6);
   return null;
 }
@@ -71,7 +70,7 @@ function resolveDistribution(options = {}) {
     };
   }
 
-  const distribution = computeDistributionHint(sourceYesPct === null ? 50 : sourceYesPct);
+  const distribution = computeDistributionHint(sourceYesPct === null ? 0.5 : sourceYesPct / 100);
   if (sourceYesPct === null) {
     diagnostics.push('No source YES probability supplied; defaulted to balanced 50/50 distribution hint.');
   }

package/cli/lib/mirror_service.cjs

@@ -65,9 +65,18 @@ function buildPlanDigest(planData) {
     sourceMarket: {
       marketId: planData.sourceMarket && planData.sourceMarket.marketId,
       slug: planData.sourceMarket && planData.sourceMarket.slug,
+      question: planData.sourceMarket && planData.sourceMarket.question,
+      description: planData.sourceMarket && planData.sourceMarket.description,
       yesPct: planData.sourceMarket && planData.sourceMarket.yesPct,
       closeTimestamp: planData.sourceMarket && planData.sourceMarket.closeTimestamp,
     },
+    rules: planData.rules
+      ? {
+          sourceRules: planData.rules.sourceRules || null,
+          proposedPandoraRules: planData.rules.proposedPandoraRules || null,
+          sourceCount: planData.rules.sourceCount || null,
+        }
+      : null,
     liquidityRecommendation: planData.liquidityRecommendation,
     distributionHint: planData.distributionHint,
   }));

package/cli/lib/mirror_sync_service.cjs

@@ -449,17 +449,30 @@ async function runMirrorSync(options, deps = {}) {
           saveState(loaded.filePath, state);
 
           if (snapshotMetrics.driftTriggered && plannedRebalanceUsdc > 0) {
+            let rebalanceResultOk = true;
             if (options.executeLive) {
-              const rebalanceResult = await rebalanceFn({
-                marketAddress: options.pandoraMarketAddress,
-                side: rebalanceSide,
-                amountUsdc: plannedRebalanceUsdc,
-              });
+              let rebalanceResult;
+              try {
+                rebalanceResult = await rebalanceFn({
+                  marketAddress: options.pandoraMarketAddress,
+                  side: rebalanceSide,
+                  amountUsdc: plannedRebalanceUsdc,
+                });
+              } catch (err) {
+                rebalanceResult = {
+                  ok: false,
+                  error: {
+                    code: err && err.code ? String(err.code) : null,
+                    message: err && err.message ? String(err.message) : String(err),
+                  },
+                };
+              }
               action.rebalance = {
                 side: rebalanceSide,
                 amountUsdc: plannedRebalanceUsdc,
                 result: rebalanceResult,
               };
+              rebalanceResultOk = Boolean(rebalanceResult && rebalanceResult.ok !== false);
             } else {
               action.rebalance = {
                 side: rebalanceSide,
@@ -467,10 +480,22 @@ async function runMirrorSync(options, deps = {}) {
                 result: { status: 'simulated' },
               };
             }
-            actualRebalanceUsdc = plannedRebalanceUsdc;
-
-            state.cumulativeLpFeesApproxUsdc =
-              round((toNumber(state.cumulativeLpFeesApproxUsdc) || 0) + plannedRebalanceUsdc * 0.003, 6) || 0;
+            if (rebalanceResultOk) {
+              actualRebalanceUsdc = plannedRebalanceUsdc;
+              state.cumulativeLpFeesApproxUsdc =
+                round((toNumber(state.cumulativeLpFeesApproxUsdc) || 0) + plannedRebalanceUsdc * 0.003, 6) || 0;
+            } else {
+              action.status = 'failed';
+              const rebalanceError =
+                action.rebalance && action.rebalance.result && action.rebalance.result.error
+                  ? action.rebalance.result.error
+                  : { message: 'Pandora rebalance execution failed.' };
+              action.error = {
+                code: 'REBALANCE_EXECUTION_FAILED',
+                message: rebalanceError.message || 'Pandora rebalance execution failed.',
+                details: rebalanceError,
+              };
+            }
           }
 
           if (hedgeTriggered && plannedHedgeUsdc > 0) {
@@ -539,8 +564,8 @@ async function runMirrorSync(options, deps = {}) {
 
           const actualSpendUsdc = round(actualRebalanceUsdc + actualHedgeUsdc, 6) || 0;
           state.dailySpendUsdc = round((toNumber(state.dailySpendUsdc) || 0) + actualSpendUsdc, 6) || 0;
-          const executedLegCount = (action.rebalance ? 1 : 0) + (action.hedge ? 1 : 0);
-          state.tradesToday += executedLegCount || 1;
+          const executedLegCount = (actualRebalanceUsdc > 0 ? 1 : 0) + (actualHedgeUsdc > 0 ? 1 : 0);
+          state.tradesToday += executedLegCount;
           state.lastExecution = action;
 
           snapshot.action = action;

package/cli/lib/polymarket_trade_adapter.cjs

@@ -113,6 +113,12 @@ function resolveSignatureType(options = {}) {
   return options.funder ? POLYMARKET_SIG_TYPE_PROXY : POLYMARKET_SIG_TYPE_EOA;
 }
 
+function hashSensitiveCachePart(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
 function buildTradingCacheKey(host, chain, options = {}) {
   const signatureType = resolveSignatureType(options);
   return [
@@ -120,10 +126,10 @@ function buildTradingCacheKey(host, chain, options = {}) {
     String(chain || ''),
     String(signatureType),
     String(options.funder || ''),
-    String(options.privateKey || ''),
-    String(options.apiKey || ''),
-    String(options.apiSecret || ''),
-    String(options.apiPassphrase || ''),
+    hashSensitiveCachePart(options.privateKey),
+    hashSensitiveCachePart(options.apiKey),
+    hashSensitiveCachePart(options.apiSecret),
+    hashSensitiveCachePart(options.apiPassphrase),
   ].join('|');
 }
 
@@ -142,7 +148,7 @@ function responseContainsError(response) {
 }
 
 function responseIndicatesSuccess(response) {
-  if (!response || typeof response !== 'object') return true;
+  if (!response || typeof response !== 'object') return false;
   if (Object.prototype.hasOwnProperty.call(response, 'success')) {
     return Boolean(response.success) && !responseContainsError(response);
   }
@@ -990,7 +996,7 @@ async function browsePolymarketMarkets(options = {}) {
 
 function readTradingCredsFromEnv(env = process.env) {
   const creds = {
-    privateKey: env.POLYMARKET_PRIVATE_KEY || env.PRIVATE_KEY || null,
+    privateKey: env.POLYMARKET_PRIVATE_KEY || null,
     funder: env.POLYMARKET_FUNDER || null,
     apiKey: env.POLYMARKET_API_KEY || null,
     apiSecret: env.POLYMARKET_API_SECRET || null,

package/cli/pandora.cjs

@@ -854,6 +854,16 @@ function parseAddressFlag(value, flagName) {
   return value.toLowerCase();
 }
 
+function parsePrivateKeyFlag(value, flagName = '--private-key') {
+  if (!isValidPrivateKey(value)) {
+    throw new CliError(
+      'INVALID_FLAG_VALUE',
+      `${flagName} must be a valid private key (0x + 64 hex chars). Received: "${value}"`,
+    );
+  }
+  return value;
+}
+
 function parsePositionsOrderBy(value) {
   if (!POSITIONS_ORDER_BY_FIELD_SET.has(value)) {
     throw new CliError(
@@ -1497,7 +1507,7 @@ function parseTradeFlags(args) {
     }
 
     if (token === '--private-key') {
-      options.privateKey = requireFlagValue(args, i, '--private-key');
+      options.privateKey = parsePrivateKeyFlag(requireFlagValue(args, i, '--private-key'), '--private-key');
       i += 1;
       continue;
     }
@@ -3450,7 +3460,7 @@ function parseMirrorSyncFlags(args) {
       continue;
     }
     if (token === '--private-key') {
-      options.privateKey = requireFlagValue(rest, i, '--private-key');
+      options.privateKey = parsePrivateKeyFlag(requireFlagValue(rest, i, '--private-key'), '--private-key');
       i += 1;
       continue;
     }
@@ -3855,7 +3865,7 @@ function parseMirrorGoFlags(args) {
       continue;
     }
     if (token === '--private-key') {
-      options.privateKey = requireFlagValue(args, i, '--private-key');
+      options.privateKey = parsePrivateKeyFlag(requireFlagValue(args, i, '--private-key'), '--private-key');
       i += 1;
       continue;
     }
@@ -5277,6 +5287,17 @@ function formatTimestamp(raw) {
   return date.toISOString();
 }
 
+function formatUnixTimestampIfLikely(raw) {
+  if (raw === null || raw === undefined || raw === '') return '';
+  const numeric = Number(raw);
+  if (!Number.isFinite(numeric)) return String(raw);
+  if (numeric <= 0) return String(raw);
+  const seconds = numeric > 1e12 ? numeric / 1000 : numeric;
+  // Guard against block-number-like values rendered as 1970 dates.
+  if (seconds < 946684800) return String(raw); // 2000-01-01T00:00:00Z
+  return formatTimestamp(raw);
+}
+
 function valueToCell(value) {
   if (value === null || value === undefined) return '';
   if (typeof value === 'object') return JSON.stringify(value);
@@ -5538,7 +5559,7 @@ function renderPollsListTable(data) {
       short(item.id, 18),
       item.status,
       short(item.creator, 16),
-      formatTimestamp(item.deadlineEpoch),
+      formatUnixTimestampIfLikely(item.deadlineEpoch),
       short(item.question, 56),
     ]),
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pandora-cli-skills",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "Pandora CLI & Skills",
   "main": "cli/pandora.cjs",
   "bin": {
@@ -16,6 +16,7 @@
     "references/contracts.md",
     "references/creation-script.md",
     "SKILL.md",
+    "README.md",
     "README_FOR_SHARING.md",
     "tsconfig.json"
   ],