feat: GraphQL schema drift validator with CI and query fixes

.github/workflows/validate-graphql.yml

@@ -116,27 +116,47 @@ jobs:
             echo "🤖 Generated by [validate-graphql workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})"
           } > pr-body.md
 
-      - name: Create branch and PR
+      - name: Create or update PR
         if: steps.check-schema.outputs.changed == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          BRANCH="auto/schema-update-$(date +%Y%m%d-%H%M%S)"
+          BRANCH="auto/schema-update"
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
-          git checkout -b "$BRANCH"
-          git add scripts/graphql-schema-*.json
-          git commit -m "chore: update GraphQL schema snapshots
+
+          # Check if an open schema drift PR already exists
+          EXISTING_PR=$(gh pr list --state open --head "$BRANCH" --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING_PR" ]; then
+            # Update existing PR — force-push new schema to same branch
+            git checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null || git checkout -b "$BRANCH"
+            git add scripts/graphql-schema-*.json
+            git commit -m "chore: update GraphQL schema snapshots
 
           Schema drift detected from live endpoints.
           Trigger: ${{ github.event_name }}
 
           Co-authored-by: GitHub Actions <action@github.com>"
-          git push origin "$BRANCH"
-
-          gh pr create \
-            --title "Schema drift: GraphQL schema updated from live endpoints" \
-            --body-file pr-body.md \
-            --base main \
-            --head "$BRANCH" \
-            --draft
+            git push origin "$BRANCH" --force
+            gh pr edit "$EXISTING_PR" --body-file pr-body.md
+            echo "Updated existing PR #$EXISTING_PR"
+          else
+            # Create new branch and PR
+            git checkout -b "$BRANCH"
+            git add scripts/graphql-schema-*.json
+            git commit -m "chore: update GraphQL schema snapshots
+
+          Schema drift detected from live endpoints.
+          Trigger: ${{ github.event_name }}
+
+          Co-authored-by: GitHub Actions <action@github.com>"
+            git push origin "$BRANCH" --force
+
+            gh pr create \
+              --title "Schema drift: GraphQL schema updated from live endpoints" \
+              --body-file pr-body.md \
+              --base main \
+              --head "$BRANCH" \
+              --draft
+          fi

docs/_data/graphql-api/queries/leaderboard/account-rank.md

@@ -27,9 +27,9 @@ query GetAccountPnlRank {
     account_image
     rank
     percentile
-    total_pnl
+    total_pnl_formatted
     pnl_pct
-    total_volume
+    total_volume_formatted
     total_position_count
     win_rate
     total_accounts
@@ -55,9 +55,11 @@ query GetAccountPnlRank {
 | `account_image` | `String` | Profile image URL |
 | `rank` | `bigint` | Leaderboard rank position |
 | `percentile` | `numeric` | Percentile ranking (0-100) |
-| `total_pnl` | `numeric` | Total profit/loss |
+| `total_pnl_formatted` | `String` | Total profit/loss (formatted) |
+| `total_pnl_raw` | `numeric` | Total profit/loss (raw) |
 | `pnl_pct` | `numeric` | PnL percentage |
-| `total_volume` | `numeric` | Total trading volume |
+| `total_volume_formatted` | `String` | Total trading volume (formatted) |
+| `total_volume_raw` | `numeric` | Total trading volume (raw) |
 | `total_position_count` | `bigint` | Total number of positions |
 | `win_rate` | `numeric` | Win rate across positions |
 | `total_accounts` | `bigint` | Total accounts on the leaderboard |
@@ -79,7 +81,7 @@ export const rankQueries = [
     account_label
     rank
     percentile
-    total_pnl
+    total_pnl_formatted
     pnl_pct
     win_rate
     total_accounts
@@ -114,7 +116,7 @@ async function getAccountRank(accountId: string) {
       ) {
         rank
         percentile
-        total_pnl
+        total_pnl_formatted
         pnl_pct
         total_accounts
       }

docs/_data/graphql-api/queries/leaderboard/leaderboard-stats.md

@@ -26,11 +26,11 @@ query GetPnlLeaderboardStats {
     profitable_traders
     unprofitable_traders
     profitable_pct
-    total_pnl_sum
-    avg_pnl
-    median_pnl
-    total_volume
-    avg_volume
+    total_pnl_sum_formatted
+    avg_pnl_formatted
+    median_pnl_formatted
+    total_volume_formatted
+    avg_volume_formatted
   }
 }
 ```
@@ -50,11 +50,16 @@ query GetPnlLeaderboardStats {
 | `profitable_traders` | `bigint` | Number of traders with positive PnL |
 | `unprofitable_traders` | `bigint` | Number of traders with negative PnL |
 | `profitable_pct` | `numeric` | Percentage of profitable traders |
-| `total_pnl_sum` | `numeric` | Sum of all PnL across traders |
-| `avg_pnl` | `numeric` | Average PnL per trader |
-| `median_pnl` | `numeric` | Median PnL across traders |
-| `total_volume` | `numeric` | Total trading volume across all traders |
-| `avg_volume` | `numeric` | Average volume per trader |
+| `total_pnl_sum_formatted` | `String` | Sum of all PnL across traders (formatted) |
+| `total_pnl_sum_raw` | `numeric` | Sum of all PnL across traders (raw) |
+| `avg_pnl_formatted` | `String` | Average PnL per trader (formatted) |
+| `avg_pnl_raw` | `numeric` | Average PnL per trader (raw) |
+| `median_pnl_formatted` | `String` | Median PnL across traders (formatted) |
+| `median_pnl_raw` | `numeric` | Median PnL across traders (raw) |
+| `total_volume_formatted` | `String` | Total trading volume across all traders (formatted) |
+| `total_volume_raw` | `numeric` | Total trading volume across all traders (raw) |
+| `avg_volume_formatted` | `String` | Average volume per trader (formatted) |
+| `avg_volume_raw` | `numeric` | Average volume per trader (raw) |
 
 ## Interactive Example
 
@@ -68,11 +73,11 @@ export const statsQueries = [
     profitable_traders
     unprofitable_traders
     profitable_pct
-    total_pnl_sum
-    avg_pnl
-    median_pnl
-    total_volume
-    avg_volume
+    total_pnl_sum_formatted
+    avg_pnl_formatted
+    median_pnl_formatted
+    total_volume_formatted
+    avg_volume_formatted
   }
 }`,
     variables: {}
@@ -99,9 +104,9 @@ async function getProtocolStats() {
       get_pnl_leaderboard_stats(args: {}) {
         total_traders
         profitable_pct
-        avg_pnl
-        median_pnl
-        total_volume
+        avg_pnl_formatted
+        median_pnl_formatted
+        total_volume_formatted
       }
     }
   `

docs/_data/graphql-api/queries/leaderboard/vault-leaderboard.md

@@ -10,7 +10,7 @@ import GraphQLPlaygroundCustom from '@site/src/components/GraphQLPlaygroundCusto
 
 # Vault Leaderboard
 
-Rank accounts within specific vaults using `get_vault_leaderboard` and `get_vault_leaderboard_period`. Both return `pnl_leaderboard_entry` rows (same schema as the [PnL Leaderboard](./pnl-leaderboard)).
+Rank accounts within specific vaults using `get_vault_leaderboard` and `get_pnl_leaderboard_period`. Both return `pnl_leaderboard_entry` rows (same schema as the [PnL Leaderboard](./pnl-leaderboard)).
 
 ## Query Structure
 
@@ -51,11 +51,11 @@ query GetVaultLeaderboard {
 
 ## Period-Scoped {#period-scoped}
 
-Use `get_vault_leaderboard_period` to scope results to a specific date range:
+Use `get_pnl_leaderboard_period` to scope results to a specific date range:
 
 ```graphql
 query GetVaultLeaderboardPeriod {
-  get_vault_leaderboard_period(
+  get_pnl_leaderboard_period(
     args: {
       p_term_id: "0x57d94c..."
       p_curve_id: 1