[codex] Add combined Binance and Polymarket oracle E2E

.agents/skills/gravity-oracle-demo/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: gravity-oracle-demo
+description: Use when the user asks how to run, demo, debug, or restart Gravity oracle tests, especially Binance index-kline price feeds, Polymarket settlement mirrors, or the combined frontend dashboard.
+---
+
+# Gravity Oracle Demo
+
+Use this skill for Gravity oracle demo and integration-test operations that span `gravity-sdk`,
+`gravity-reth`, `gravity_chain_core_contracts`, and the demo web app.
+
+## Safety
+
+- Ask before outbound public API/RPC requests unless the user has already
+  approved that exact live run.
+- Do not commit real RPC URLs, API keys, `.env` files, or absolute user-specific
+  paths in docs.
+- Prefer deterministic mock E2E for CI and review. Use live mode only for demos
+  or explicitly approved validation.
+- Do not stop a cluster unless the user asks or the running process was started
+  by the current task and is clearly part of cleanup.
+
+## Binance Price Feed Demo
+
+Default deterministic suite:
+
+```bash
+cd gravity-sdk
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh binance_price_feed --force-init
+```
+
+Long-running frontend backend with the local mock:
+
+```bash
+cd gravity-sdk
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh binance_price_feed \
+    --force-init \
+    --keep-running \
+    --demo-config-out ../gravity_price_feed_demo_web/public/demo-config.json \
+    --log-cli-level=INFO
+```
+
+Live Binance market-data demo:
+
+```bash
+cd gravity-sdk
+BINANCE_PRICE_FEED_MODE=live \
+BINANCE_PRICE_FEED_BASE_URL=https://testnet.binancefuture.com \
+BINANCE_PRICE_FEED_LAG_MINUTES=3 \
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh binance_price_feed \
+    --keep-running \
+    --demo-config-out ../gravity_price_feed_demo_web/public/demo-config.json \
+    --log-cli-level=INFO
+```
+
+Notes:
+
+- Production `https://fapi.binance.com` may return HTTP `451` from restricted
+  locations. For demos, `https://testnet.binancefuture.com` exposes the same
+  `indexPriceKlines` shape and worked for TSLAUSDT/NVDAUSDT.
+- `indexPriceKlines` is public market data; this implementation does not need
+  `BINANCE_API_KEY` or `BINANCE_SECRET_KEY`.
+- Live mode computes a recently closed 1-minute bucket, then continuous tasks
+  advance by delivery nonce: nonce `n` maps to bucket `start + (n - 1) * 1m`.
+- The default live task uses `graceMs=120000` and a three-minute lag so the
+  first requested bucket is already beyond that grace period.
+- A healthy demo shows `NativeOracle` nonce and resolver `roundId` increasing
+  every closed minute.
+
+Start or refresh the frontend:
+
+```bash
+cd gravity_price_feed_demo_web
+npm run dev
+```
+
+Open the URL printed by the dev server. The page reads `public/demo-config.json`
+and proxies `/rpc` to the Gravity devnet.
+
+Stop the backend:
+
+```bash
+cd gravity-sdk
+bash cluster/stop.sh --config gravity_e2e/cluster_test_cases/binance_price_feed/cluster.toml
+```
+
+If mock mode is still running, also stop the local mock server:
+
+```bash
+kill "$(cat gravity_e2e/cluster_test_cases/binance_price_feed/artifacts/mock_binance.pid)"
+```
+
+## Combined Price Feed + Polymarket Dashboard
+
+Use `oracle_demo` when the user wants one frontend showing both Binance price
+feeds and a Polymarket mirror in the same local Gravity cluster.
+
+Run the deterministic local backend:
+
+```bash
+cd gravity-sdk
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh oracle_demo \
+    --force-init \
+    --keep-running \
+    --demo-config-out ../gravity_price_feed_demo_web/public/demo-config.json \
+    --log-cli-level=INFO
+```
+
+Then start the dashboard:
+
+```bash
+cd gravity_price_feed_demo_web
+npm run dev
+```
+
+This suite sends no public internet requests. It starts:
+
+- a local Binance `indexPriceKlines` mock for `sourceType=3`
+- a local Polygon JSON-RPC mock for a Fed-style binary CTF settlement
+- one Gravity cluster that records both oracle lanes
+
+Stop it with:
+
+```bash
+cd gravity-sdk
+bash cluster/stop.sh --config gravity_e2e/cluster_test_cases/oracle_demo/cluster.toml
+kill "$(cat gravity_e2e/cluster_test_cases/oracle_demo/artifacts/mock_binance.pid)"
+```
+
+## Polymarket Mirror Demo
+
+Run the offline settlement rail first:
+
+```bash
+cd gravity-sdk
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh polymarket_mock --force-init
+```
+
+What it proves:
+
+- `sourceType=6` relayer reads a Polygon-like CTF `ConditionResolution` log.
+- Unsupported-JWK consensus carries canonical settlement bytes to
+  `NativeOracle`.
+- `PolymarketSettlementResolver` validates and stores the payout vector.
+- A Gravity market contract settles and releases claims from that resolver.
+
+For real Polymarket mirrors, do not infer a market from a Polygon log alone.
+Start from a reviewed manifest: slug/title/rules, `conditionId`, `questionId`,
+CTF address, outcome labels, `slotToOutcome`, source block range, and hashes of
+raw metadata snapshots. Then register exactly one `(sourceType=6, mirrorId)` per
+reviewed CTF condition.

.agents/workflows/build-and-test.md

@@ -131,7 +131,61 @@ Genesis artifacts are cached in `cluster_test_cases/<suite>/artifacts/`. Use `--
 
 ---
 
-## 4. Bridge E2E Test Details
+## 4. Polymarket Mock Oracle E2E
+
+Suite directory: `gravity_e2e/cluster_test_cases/polymarket_mock/`
+
+This suite is the SDK-side integration proof for a Polymarket-like Gravity
+market. It does not hit Polygon. Instead, `hooks.py` starts
+`MockPolymarketPolygon` on localhost, `relayer_config.json` maps the configured
+Gravity oracle URI to that mock, and the test waits for the existing relayer plus
+unsupported-JWK/oracle consensus path to write a `sourceType=6` payload into
+`NativeOracle`.
+
+Run from the repository root:
+
+// turbo
+```bash
+PATH="$CONDA_PREFIX/bin:$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh polymarket_mock --force-init
+```
+
+If the shell already activated `gravity_e2e/.venv`, use:
+
+// turbo
+```bash
+PATH="$HOME/.foundry/bin:$PWD/target/quick-release:$PATH" \
+  ./gravity_e2e/run_test.sh polymarket_mock --force-init
+```
+
+Expected successful output includes:
+
+```text
+Released mock Polymarket settlement: winning_slot=<slot> payout=<vector>
+Polymarket match market resolved and claimed: marketId=1 winningSlot=<slot> totalPool=600000000000000000000
+PASSED
+Suite polymarket_mock PASSED
+All suites passed!
+```
+
+Product mapping:
+
+1. Gravity market creation stores the Polygon CTF reference.
+2. The relayer reads the CTF `ConditionResolution` log from the configured URI.
+3. Validators agree on canonical settlement bytes through the existing oracle
+   consensus path.
+4. `NativeOracle` records the agreed payload.
+5. Contract-side resolver logic validates the CTF metadata and stores the payout
+   vector.
+6. The market contract settles and pays the winner.
+
+This is intentionally a settlement-rail PoC. Dynamic request discovery can be
+layered on later with finalized request events, watermarks, deadlines, and typed
+pending/unknown/expired states.
+
+---
+
+## 5. Bridge E2E Test Details
 
 Suite directory: `gravity_e2e/cluster_test_cases/bridge/`
 
@@ -162,7 +216,7 @@ Suite directory: `gravity_e2e/cluster_test_cases/bridge/`
 
 ---
 
-## 5. Running Contract Unit Tests
+## 6. Running Contract Unit Tests
 
 Working directory: `gravity_chain_core_contracts`
 
@@ -179,4 +233,4 @@ forge test --match-path test/unit/integration/ConsensusEngineFlow.t.sol -vvv
 Run specific test function:
 ```bash
 forge test --match-test testBridgeFlow -vvv
-```
+```

.gitignore

@@ -112,6 +112,7 @@ lib/
 
 # Hardhat (if ever used)
 artifacts/
+mock_polymarket_metadata.json
 cache/
 typechain-types/