pandora-cli-skills 1.1.66 → 1.1.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +8 -0
  2. package/README_FOR_SHARING.md +14 -0
  3. package/SKILL.md +37 -16
  4. package/cli/lib/agent_contract_registry.cjs +402 -34
  5. package/cli/lib/mcp_tool_registry.cjs +363 -1
  6. package/cli/lib/mirror_command_service.cjs +3 -3
  7. package/cli/lib/mirror_handlers/deploy.cjs +2 -2
  8. package/cli/lib/parsers/mirror_deploy_flags.cjs +3 -2
  9. package/cli/lib/parsers/mirror_go_flags.cjs +3 -2
  10. package/cli/lib/parsers/sports_flags.cjs +4 -2
  11. package/cli/lib/shared/poll_categories.cjs +109 -0
  12. package/cli/lib/sports_creation_service.cjs +2 -1
  13. package/package.json +1 -1
  14. package/scripts/create_market_launcher.ts +13 -1
  15. package/scripts/create_polymarket_clone_and_bet.ts +13 -1
package/README.md CHANGED
@@ -78,6 +78,14 @@ pandora --output json lifecycle status --id <lifecycle-id>
78
78
  pandora --output json lifecycle resolve --id <lifecycle-id> --confirm
79
79
  ```
80
80
 
81
+ ### Mirror Operator Notes
82
+
83
+ - `mirror plan` computes a sports-aware suggested `targetTimestamp`; do not assume a generic `+1h` close buffer. Use `--target-timestamp <unix|iso>` only when you intentionally want to override the suggested close time.
84
+ - Fresh `mirror deploy` / `mirror go` runs need at least two independent public resolution URLs from different hosts in `--sources`. Polymarket, Gamma, and CLOB URLs are source-market discovery inputs and are not valid resolution sources.
85
+ - Validation is payload-exact: run `pandora --output json agent market validate ...` on the final `question`, `rules`, `sources`, and `targetTimestamp` before execute mode. CLI mirror execute reruns use `--validation-ticket`; MCP execute/live reruns use `agentPreflight`.
86
+ - For sports deploy/create flows, `--category Sports` (or `--category 1`) maps to the on-chain `PollCategory.Sports` enum.
87
+ - Poll category ids: `Politics=0`, `Sports=1`, `Finance=2`, `Crypto=3`, `Culture=4`, `Technology=5`, `Science=6`, `Entertainment=7`, `Health=8`, `Environment=9`, `Other=10`.
88
+
81
89
  ## Risk Controls
82
90
 
83
91
  - Inspect/engage panic lock:
package/README_FOR_SHARING.md CHANGED
@@ -72,6 +72,18 @@ Prerequisite: Node.js `>=18`.
72
72
  - `pandora --output json risk panic --clear`
73
73
  - semantic note: `max_daily_loss_usd` and `max_open_markets` are enforced as daily live-notional / daily operation counters in current implementation.
74
74
 
75
+ ## Mirror operator guidance
76
+ - `mirror plan` computes a sports-aware suggested `targetTimestamp`; mirror deploy/go do not use a generic `+1h` buffer. Use `--target-timestamp <unix|iso>` only when you intentionally want to override the suggested close time.
77
+ - Fresh `mirror deploy` / `mirror go` runs require at least two independent public resolution URLs from different hosts in `--sources`.
78
+ - Polymarket, Gamma, and CLOB URLs are discovery inputs only and are not valid `--sources`.
79
+ - Poll category ids: `Politics=0`, `Sports=1`, `Finance=2`, `Crypto=3`, `Culture=4`, `Technology=5`, `Science=6`, `Entertainment=7`, `Health=8`, `Environment=9`, `Other=10`.
80
+ - Validation is exact-payload:
81
+ - run `pandora --output json agent market validate --question "<final question>" --rules "<final rules>" --target-timestamp <unix-seconds> --sources <url1> <url2>`
82
+ - rerun CLI mirror execute with `--validation-ticket <ticket>`
83
+ - rerun MCP execute/live with `agentPreflight = { validationTicket, validationDecision: "PASS", validationSummary }`
84
+ - `sports create run` does not expose a CLI `--validation-ticket`; agent-controlled execute paths use `agentPreflight` / `PANDORA_AGENT_PREFLIGHT`.
85
+ - In the packaged sports/mirror examples, use `--category Sports` (or `--category 1`) for the on-chain `PollCategory.Sports` enum.
86
+
75
87
  ## New CLI capabilities
76
88
  - Global machine-readable output:
77
89
  - `pandora --output json doctor`
@@ -207,6 +219,8 @@ Mirror advanced flags (for operator tuning):
207
219
  - `--sync-interval-ms <ms>` on `mirror go` to control auto-sync tick cadence.
208
220
  - `--oracle <address>` / `--factory <address>` on `mirror deploy` and `mirror go` for explicit contract overrides.
209
221
  - `--rules "<text>"` on `mirror deploy` for direct rules override without a plan file.
222
+ - `--target-timestamp <unix|iso>` on `mirror deploy|go` for explicit close-time override when the suggested sports-safe target is not sufficient.
223
+ - `--validation-ticket <ticket>` on `mirror deploy|go` for CLI execute reruns after `agent market validate`.
210
224
  - `--distribution-yes-pct <0-100>` / `--distribution-no-pct <0-100>` on `mirror deploy|go` as percentage alternatives to raw 1e9 part hints.
211
225
  - `--max-imbalance <n>` now accepts the full uint24 range, including `0` for "no guard".
212
226
  - `--polymarket-gamma-mock-url <url>` on `mirror browse|plan|verify|go|sync|status` for deterministic mock-source testing.
package/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: pandora-cli-skills
3
3
  summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
4
- version: 1.1.66
4
+ version: 1.1.67
5
5
  ---
6
6
 
7
7
  # Pandora CLI & Skills
@@ -14,11 +14,15 @@ Use this skill to launch Parimutuel or AMM markets with explicit market paramete
14
14
  ## Safety & Resolution Rules (enforced)
15
15
  - At least **2 public source URLs** are required (`http/https` only).
16
16
  - `--rules` must include explicit **Yes/No** outcomes and edge-case handling (cancel/postpone/abandoned/unresolved cases).
17
- - `--target-timestamp` uses a `+1h` buffer by default (`--target-timestamp-offset-hours` to override).
17
+ - `mirror plan|deploy|go` do **not** assume a generic `+1h` buffer. They use a sports-aware suggested `targetTimestamp`; use explicit `--target-timestamp <unix|iso>` only when intentionally overriding that suggestion.
18
+ - `mirror deploy|go` require at least **2 independent public resolution URLs from different hosts** in `--sources`. Polymarket / Gamma / CLOB URLs are discovery inputs only and are not valid `--sources`.
19
+ - Manual `launch` / `clone-bet` still expose `--target-timestamp-offset-hours`; that legacy script flag is not the mirror timing model.
18
20
  - `deadline` must be in the future (12h+ window strongly recommended).
19
21
  - `distribution-yes + distribution-no = 1_000_000_000`.
20
22
  - `--liquidity` minimum is **10 USDC**.
21
23
  - `--arbiter` cannot be zero-address.
24
+ - Poll category ids:
25
+ - `Politics=0`, `Sports=1`, `Finance=2`, `Crypto=3`, `Culture=4`, `Technology=5`, `Science=6`, `Entertainment=7`, `Health=8`, `Environment=9`, `Other=10`
22
26
 
23
27
  ## Setup
24
28
  ```bash
@@ -78,8 +82,10 @@ npm link
78
82
  - `error.recovery = { action, command, retryable }`
79
83
  - Agent/MCP market creation policy:
80
84
  - Agent-drafted manual markets should start with `agent market autocomplete` when rules, sources, or timing still need to be generated/refined.
81
- - Execute/live MCP calls for `sports create run`, `mirror deploy`, and `mirror go` require a PASS attestation from `agent market validate`.
82
- - Dry-run outputs for those flows include the exact validation ticket that must be echoed back via `agentPreflight` on the execute call.
85
+ - `agent market validate` must run on the exact final payload (`question`, `rules`, `sources`, `targetTimestamp`) before agent-controlled execute mode for `sports create run`, `mirror deploy`, or `mirror go`.
86
+ - `mirror deploy --dry-run` and `mirror go --paper|--dry-run` return the exact mirror payload plus the required validation ticket for that payload.
87
+ - CLI mirror execute reruns pass `--validation-ticket <ticket>`. MCP execute/live reruns pass `agentPreflight = { validationTicket, validationDecision: "PASS", validationSummary }`.
88
+ - `sports create run` has no CLI `--validation-ticket` flag; agent-controlled execute paths use `agentPreflight` / `PANDORA_AGENT_PREFLIGHT`.
83
89
  - Doctor checks:
84
90
  - env presence + format validation
85
91
  - RPC reachability and chain id match
@@ -180,19 +186,26 @@ pandora clone-bet [--dotenv-path <path>] [--skip-dotenv] [script args...]
180
186
  Mirror subcommand detail:
181
187
 
182
188
  ```text
183
- browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
184
- plan --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
185
- deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--distribution-yes-pct <0-100>] [--distribution-no-pct <0-100>] [--rules <text>] [--sources <url...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
189
+ browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>|--end-date-after <date|72h>] [--closes-before <date>|--end-date-before <date|72h>] [--question-contains <text>|--keyword <text>] [--slug <text>] [--category sports|crypto|politics|entertainment] [--exclude-sports] [--sort-by volume24h|liquidity|endDate] [--limit <n>] [--chain-id <id>] [--polymarket-tag-id <id>] [--polymarket-tag-ids <csv>] [--sport-tag-id <id>] [--sport-tag-ids <csv>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
190
+ plan --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
191
+ deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <id|name>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--distribution-yes-pct <0-100>] [--distribution-no-pct <0-100>] [--rules <text>] [--sources <url...>] [--validation-ticket <ticket>] [--target-timestamp <unix|iso>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
186
192
  verify --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--trust-deploy] [--manifest-file <path>] [--include-similarity] [--with-rules] [--allow-rule-mismatch] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
187
193
  lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>]
188
194
  hedge-calc [--reserve-yes-usdc <n> --reserve-no-usdc <n>] [--excess-yes-usdc <n>] [--excess-no-usdc <n>] [--polymarket-yes-pct <0-100>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--volume-scenarios <csv>] [--pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>] [--trust-deploy] [--manifest-file <path>]
189
195
  simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier <500-50000>] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--polymarket-yes-pct <0-100>]
190
- go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--distribution-yes-pct <0-100>] [--distribution-no-pct <0-100>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
196
+ go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <id|name>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--validation-ticket <ticket>] [--target-timestamp <unix|iso>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
191
197
  sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
192
198
  status --state-file <path>|--strategy-hash <hash> [--with-live] [--pandora-market-address <address>|--market-address <address>] [--polymarket-market-id <id>|--polymarket-slug <slug>]
193
199
  close --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>|--all --dry-run|--execute [--wallet <address>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--indexer-url <url>] [--timeout-ms <ms>]
194
200
  ```
195
201
 
202
+ Mirror operator rules:
203
+
204
+ - `mirror plan` computes a sports-aware suggested `targetTimestamp`. Keep that value unless you have a better close-time estimate; use `--target-timestamp <unix|iso>` only for explicit overrides.
205
+ - `mirror deploy` / `mirror go` require `--sources` with at least two independent public resolution URLs from different hosts. Do not pass Polymarket, Gamma, or CLOB URLs there.
206
+ - For a fresh deployment, run `mirror deploy --dry-run` or `mirror go --paper|--dry-run` first, validate the exact final payload with `agent market validate`, then rerun execute with `--validation-ticket` on CLI or `agentPreflight` over MCP.
207
+ - `--category` on deploy/create/go accepts either the enum id or canonical name. For sports flows, use `Sports` (or `1`) for `PollCategory.Sports`.
208
+
196
209
  Daemon selector detail:
197
210
 
198
211
  ```text
@@ -317,7 +330,7 @@ pandora trade --dry-run --market-address <0x...> --side no --amount-usdc 25 --ma
317
330
  pandora portfolio --wallet <0x...> --chain-id 1
318
331
  pandora watch --wallet <0x...> --iterations 5 --interval-ms 2000 --alert-net-liquidity-below -100
319
332
 
320
- pandora polls list --status 1 --category 3
333
+ pandora polls list --status 1 --category Sports
321
334
  pandora polls get --id <poll-id>
322
335
 
323
336
  pandora events list --type all --wallet <0x...> --limit 25
@@ -472,14 +485,20 @@ pandora --output json schema
472
485
  ## Mirror workflow guide
473
486
  1. Plan:
474
487
  - `pandora mirror plan --source polymarket --polymarket-slug <slug> --with-rules --include-similarity`
475
- 2. Deploy:
476
- - `pandora mirror deploy --polymarket-slug <slug> --liquidity-usdc 10 --dry-run|--execute`
477
- 3. Verify:
488
+ 2. Prepare operator inputs:
489
+ - choose at least two independent public resolution URLs from different hosts for `--sources`
490
+ - keep the plan's suggested `targetTimestamp`, or set `--target-timestamp <unix|iso>` explicitly if you need to override it
491
+ 3. Validate the exact final payload:
492
+ - `pandora --output json agent market validate --question "<final question>" --rules "<final rules>" --target-timestamp <unix-seconds> --sources <url1> <url2>`
493
+ 4. Deploy:
494
+ - `pandora mirror deploy --polymarket-slug <slug> --liquidity-usdc 10 --sources <url1> <url2> --dry-run`
495
+ - rerun execute with `--validation-ticket <ticket>` after validation passes
496
+ 5. Verify:
478
497
  - `pandora mirror verify --market-address <pandora-market> --polymarket-slug <slug> --include-similarity --with-rules`
479
- 4. Run sync:
498
+ 6. Run sync:
480
499
  - `pandora mirror sync run --market-address <pandora-market> --polymarket-slug <slug> --paper`
481
500
  - live: `--execute-live --max-open-exposure-usdc <n> --max-trades-per-day <n>`
482
- 5. Inspect status:
501
+ 7. Inspect status:
483
502
  - `pandora mirror status --state-file <path> --with-live`
484
503
 
485
504
  Mode aliases:
@@ -653,7 +672,7 @@ pandora clone-bet \
653
672
  --target-timestamp 1772323200 \
654
673
  --target-timestamp-offset-hours 1 \
655
674
  --arbiter 0x0D7B957C47Da86c2968dc52111D633D42cb7a5F7 \
656
- --category 3 \
675
+ --category Sports \
657
676
  --liquidity 10 \
658
677
  --curve-flattener 7 \
659
678
  --curve-offset 30000 \
@@ -663,6 +682,7 @@ pandora clone-bet \
663
682
 
664
683
  For live execution, replace `--dry-run` with `--execute`.
665
684
  If `pandora` is not linked yet, use `node cli/pandora.cjs clone-bet ...`.
685
+ In this example, `--category Sports` maps to `PollCategory.Sports` (`1`).
666
686
 
667
687
  Default arbiter (whitelisted): `0x0D7B957C47Da86c2968dc52111D633D42cb7a5F7`
668
688
 
@@ -676,12 +696,13 @@ pandora launch \
676
696
  --sources "https://coinmarketcap.com/currencies/bitcoin/" "https://www.coingecko.com/en/coins/bitcoin" \
677
697
  --target-timestamp 1798675200 \
678
698
  --target-timestamp-offset-hours 1 \
679
- --category 3 \
699
+ --category Sports \
680
700
  --liquidity 100 \
681
701
  --fee-tier 3000 \
682
702
  --distribution-yes 600000000 \
683
703
  --distribution-no 400000000
684
704
  ```
705
+ In this example, `--category Sports` maps to `PollCategory.Sports` (`1`).
685
706
 
686
707
  If `pandora` is not linked yet, use `node cli/pandora.cjs launch ...`.
687
708