pandora-cli-skills 1.0.3 → 1.1.3

package/README_FOR_SHARING.md

@@ -78,6 +78,16 @@ Prerequisite: Node.js `>=18`.
   - `pandora portfolio --wallet <0x...> [--chain-id <id>] [--limit <n>] [--include-events|--no-events]`
   - `pandora watch --wallet <0x...> --iterations 10 --interval-ms 5000`
   - `pandora watch --market-address <0x...> --side yes --amount-usdc 10 --iterations 5 --alert-yes-above 65 --fail-on-alert`
+- Phase 4 intelligence and automation:
+  - `pandora history --wallet <0x...> --limit 50`
+  - `pandora export --wallet <0x...> --format csv --year 2026 --out ./trades-2026.csv`
+  - `pandora arbitrage --venues pandora,polymarket --min-spread-pct 3`
+  - `pandora autopilot run|once ...`
+  - `pandora webhook test ...`
+  - `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`
 
 ## Read-only examples
 - `pandora markets list --limit 20 --order-by createdAt --order-direction desc`
@@ -91,6 +101,14 @@ Prerequisite: Node.js `>=18`.
 - `pandora trade --dry-run --market-address <0x...> --side no --amount-usdc 25 --max-amount-usdc 30 --min-probability-pct 20`
 - `pandora portfolio --wallet <0x...> --chain-id 1`
 - `pandora watch --wallet <0x...> --iterations 3 --interval-ms 1000 --alert-net-liquidity-below -100`
+- `pandora history --wallet <0x...> --limit 50`
+- `pandora export --wallet <0x...> --format csv --out ./trades.csv`
+- `pandora arbitrage --venues pandora,polymarket --min-spread-pct 2`
+- `pandora autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper`
+- `pandora webhook test --webhook-url https://example.com/hook`
+- `pandora leaderboard --metric volume --limit 20`
+- `pandora analyze --market-address <0x...> --provider mock`
+- `pandora suggest --wallet <0x...> --risk medium --budget 50 --include-venues pandora`
 - `pandora polls list --status 1 --category 3`
 - `pandora events list --type all --wallet <0x...> --limit 25`
 - `pandora positions list --wallet <0x...> --limit 50`
@@ -139,6 +157,45 @@ Prerequisite: Node.js `>=18`.
 - `watch` polls on an interval and is intended for terminal monitoring, not background daemonization.
 - `--fail-on-alert` exits non-zero when any configured threshold is hit.
 
+## Phase 4 JSON contracts
+- `history`:
+  - envelope is `ok=true`, `command="history"`, with `data.schemaVersion`, `data.summary`, and per-trade `data.items[]`.
+  - P&L fields are analytics-grade approximations with row diagnostics where precision is limited.
+- `export`:
+  - envelope is `ok=true`, `command="export"`, with `data.format`, `data.columns`, `data.count`, optional `data.outPath`, and materialized `data.content`.
+- `arbitrage`:
+  - envelope is `ok=true`, `command="arbitrage"`, with `data.parameters`, `data.sources`, and `data.opportunities[]`.
+  - source failures are emitted in diagnostics instead of hard crashes.
+- `autopilot`:
+  - envelope is `ok=true`, `command="autopilot"`, with `data.strategyHash`, `data.stateFile`, `data.snapshots[]`, and `data.actions[]`.
+  - paper mode is default; live mode requires explicit caps (`--max-amount-usdc`, `--max-open-exposure-usdc`, `--max-trades-per-day`).
+- `webhook test`:
+  - envelope is `ok=true`, `command="webhook.test"`, with per-target delivery and retry metadata.
+- `leaderboard`:
+  - envelope is `ok=true`, `command="leaderboard"`, with ranked rows for selected metric.
+  - inconsistent indexer aggregates are sanitized (win-rate capped to 0-100%) and exposed in diagnostics.
+- `analyze`:
+  - envelope is `ok=true`, `command="analyze"`, with provider/model metadata, market context, and `{ fairYesPct, confidence, rationale }`.
+  - provider-agnostic interface; missing provider returns `ANALYZE_PROVIDER_NOT_CONFIGURED`.
+- `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.
+
+## Pandora Mainnet Reference
+- PredictionOracle (Factory): `0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442`
+- PredictionPoll (Implementation): `0xC49c177736107fD8351ed6564136B9ADbE5B1eC3`
+- MarketFactory: `0xaB120F1FD31FB1EC39893B75d80a3822b1Cd8d0c`
+- OutcomeToken (Implementation): `0x15AF9A6cE764a7D2b6913e09494350893436Ab3d`
+- PredictionAMM (Implementation): `0x7D45D4835001347B31B722Fb830fc1D9336F09f4`
+- PredictionPariMutuel (Implementation): `0x5CaF2D85f17A8f3b57918d54c8B138Cacac014BD`
+- Initial collateral (USDC): `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
+- Platform treasury: `0x8789F22a0456FEddaf9074FF4cEE55E4122095f0`
+- Protocol fee rate: `20000` (`2%`)
+- Indexer URL: `https://pandoraindexer.up.railway.app/`
+- Full deployment notes: `references/contracts.md`
+
 ## Release and verified install
 - CI workflow: `.github/workflows/ci.yml` runs on Linux/macOS/Windows and covers install, lint/typecheck, full tests, and `npm pack --dry-run`.
 - Release workflow: `.github/workflows/release.yml` runs on pushed `v*` tags, runs tests, builds `npm pack`, generates `checksums.sha256`, and uploads both workflow artifacts + GitHub Release assets.
@@ -161,6 +218,16 @@ Prerequisite: Node.js `>=18`.
   - `pandora trade`
   - `pandora portfolio`
   - `pandora watch`
+  - `pandora history`
+  - `pandora export`
+  - `pandora arbitrage`
+  - `pandora autopilot`
+  - `pandora webhook test`
+  - `pandora leaderboard`
+  - `pandora analyze`
+  - `pandora suggest`
+  - `pandora resolve` (ABI-gated)
+  - `pandora lp` (ABI-gated)
   - `pandora polls list|get`
   - `pandora events list|get`
   - `pandora positions list`

package/SKILL.md

@@ -40,6 +40,16 @@ npm link
 - Phase 3 analytics command: `pandora portfolio`
 - Phase 3 monitoring command: `pandora watch`
 - Phase 3 watch alerts: `--alert-yes-*`, `--alert-net-liquidity-*`, `--fail-on-alert`
+- Phase 4 commands:
+  - `pandora history`
+  - `pandora export`
+  - `pandora arbitrage`
+  - `pandora autopilot run|once`
+  - `pandora webhook test`
+  - `pandora leaderboard`
+  - `pandora analyze`
+  - `pandora suggest`
+  - ABI-gated placeholders: `pandora resolve`, `pandora lp`
 - Doctor checks:
   - env presence + format validation
   - RPC reachability and chain id match
@@ -83,6 +93,14 @@ pandora --output json quote --market-address <0x...> --side yes --amount-usdc 10
 pandora --output json trade --dry-run --market-address <0x...> --side no --amount-usdc 10 --max-amount-usdc 20
 pandora --output json portfolio --wallet <0x...> --chain-id 1
 pandora --output json watch --wallet <0x...> --iterations 3 --interval-ms 1000 --alert-net-liquidity-above 1000 --fail-on-alert
+pandora --output json history --wallet <0x...> --limit 50
+pandora --output json export --wallet <0x...> --format csv --out ./trades.csv
+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 webhook test --webhook-url https://example.com/hook
+pandora --output json leaderboard --metric profit --limit 20
+pandora --output json analyze --market-address <0x...> --provider mock
+pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --include-venues pandora
 ```
 
 ## Phase 1 JSON contracts
@@ -129,6 +147,31 @@ pandora --output json watch --wallet <0x...> --iterations 3 --interval-ms 1000 -
 - `watch` is polling-based and terminal-oriented, not a long-running background service manager.
 - `--fail-on-alert` exits non-zero when any configured threshold triggers.
 
+## Phase 4 contracts
+- `history`: analytics-grade trade journal with per-trade approximate P&L and diagnostics.
+- `export`: deterministic CSV/JSON materialization from history rows.
+- `arbitrage`: duplicate/correlated market spread detection across Pandora + Polymarket.
+- `autopilot`: paper-first trigger loop with persisted local state and idempotency.
+- `webhook test`: channel validation for generic, Telegram, and Discord payload delivery.
+- `leaderboard`: ranked user aggregates by profit/volume/win-rate.
+  - 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.
+
+## Pandora mainnet deployment reference
+- PredictionOracle (Factory): `0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442`
+- PredictionPoll (Implementation): `0xC49c177736107fD8351ed6564136B9ADbE5B1eC3`
+- MarketFactory: `0xaB120F1FD31FB1EC39893B75d80a3822b1Cd8d0c`
+- OutcomeToken (Implementation): `0x15AF9A6cE764a7D2b6913e09494350893436Ab3d`
+- PredictionAMM (Implementation): `0x7D45D4835001347B31B722Fb830fc1D9336F09f4`
+- PredictionPariMutuel (Implementation): `0x5CaF2D85f17A8f3b57918d54c8B138Cacac014BD`
+- Initial collateral (USDC): `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
+- Platform treasury: `0x8789F22a0456FEddaf9074FF4cEE55E4122095f0`
+- Protocol fee rate: `20000` (`2%`)
+- Indexer URL: `https://pandoraindexer.up.railway.app/`
+- Source of truth doc: `references/contracts.md`
+
 ## Release verification
 - CI coverage includes Linux, macOS, and Windows.
 - Release artifacts are signed keylessly with cosign in the release workflow.

package/cli/lib/analyze_provider.cjs

@@ -0,0 +1,76 @@
+const ANALYZE_SCHEMA_VERSION = '1.0.0';
+
+class AnalyzeProviderError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'AnalyzeProviderError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function getProviderName(options = {}) {
+  const explicit = options.provider ? String(options.provider).trim().toLowerCase() : '';
+  const envProvider = process.env.PANDORA_ANALYZE_PROVIDER ? String(process.env.PANDORA_ANALYZE_PROVIDER).trim().toLowerCase() : '';
+  return explicit || envProvider || 'none';
+}
+
+async function evaluateWithMock(context) {
+  const raw = process.env.PANDORA_ANALYZE_MOCK_RESPONSE;
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      return {
+        fairYesPct: parsed.fairYesPct,
+        confidence: parsed.confidence,
+        rationale: parsed.rationale || 'Mocked analyze response.',
+        caveats: Array.isArray(parsed.caveats) ? parsed.caveats : [],
+      };
+    } catch {
+      // Ignore malformed mock payload and fall through to deterministic default.
+    }
+  }
+
+  const marketYes = Number(context && context.market && context.market.yesPct);
+  const fair = Number.isFinite(marketYes) ? Math.max(1, Math.min(99, marketYes * 0.9)) : 50;
+  return {
+    fairYesPct: fair,
+    confidence: 0.42,
+    rationale: 'Mock provider generated a conservative fair-value estimate for local/testing workflows.',
+    caveats: ['Mock analysis provider is enabled; no external model call was executed.'],
+  };
+}
+
+async function evaluateMarket(context, options = {}) {
+  const provider = getProviderName(options);
+  if (provider === 'none') {
+    throw new AnalyzeProviderError(
+      'ANALYZE_PROVIDER_NOT_CONFIGURED',
+      'No analyze provider configured. Set --provider or PANDORA_ANALYZE_PROVIDER.',
+      {
+        supportedProviders: ['mock'],
+      },
+    );
+  }
+
+  if (provider === 'mock') {
+    const result = await evaluateWithMock(context);
+    return {
+      schemaVersion: ANALYZE_SCHEMA_VERSION,
+      provider,
+      model: options.model || 'mock-v1',
+      result,
+    };
+  }
+
+  throw new AnalyzeProviderError('ANALYZE_PROVIDER_UNSUPPORTED', `Unsupported analyze provider: ${provider}`, {
+    supportedProviders: ['mock'],
+  });
+}
+
+module.exports = {
+  ANALYZE_SCHEMA_VERSION,
+  AnalyzeProviderError,
+  getProviderName,
+  evaluateMarket,
+};