methodology_

Protocol solvency

Positions and risk

Traders

PAPER and stakers

Operations

Valuation inputs

Unconfirmed fields and the unnamed event

• PositionOpened: debtFunded name inferred (false on all samples)
• PositionClosed: debtFunded name inferred
• PositionsClosed: marginReturned, newBalance names inferred
• Liquidated: debtFunded name inferred
• Harvested: remaining name inferred
• StakerFeesClaimed: field names inferred
• StakerLpExcessDistributed: field 1 = amount per spec; fields 2,3 names inferred (2 == 1 and 3 == 0 on samples)
• DevFeesClaimed: field names inferred
• MarketOiCapsUpdated: cap names inferred
• Unstaked: found 15 Oct: topic0 0x0f5bb821… on PaperStaking hashes to this signature; not in spec v2
• BatchExecuted: word 4 unnamed
• 0x620c26bf… on PaperTokenomics fires once per close group (one per user per batch, after all of that group’s PositionClosed events). Words: lpLoss, lpGain, trackedLpBefore, trackedLpAfter, tailDelta, paperMinted. PAPER is allocated to the group’s positions in proportion to each position’s loss (−pnlAfterImpact − fee).
• On winning closes, trackedLpBefore equals trackedLpAfter in the event; the win has already been deducted when the event is emitted.
• 0x0bb3f42f… on Exchange: two words, no indexed fields, name not recovered. Not used.

Decisions log

# Decisions

Spec items that were ambiguous but did not change the data model. Each was decided here and the build continued (kickoff rule 9).

D-001 · ABI source. The companion `papertrade-events.json` was not supplied. `abi/papertrade-events.json` was rebuilt from the signatures in SPEC §3. Every event's keccak topic0 was matched against logs on chain, and every indexed and data word count was checked against a live sample (`scripts/recon/build-abi.mts`, `scripts/recon/idx.mts`). No signature was invented. Field names the spec does not give are marked "inferred" in the file.

D-002 · Unstake event. The spec says no unstake event exists. Topic0 `0x0f5bb821…` on PaperStaking hashes to `Unstaked(address,uint256)`, so it is indexed as `unstaked`.

D-003 · The close mint event is per group, not per position. The unnamed `0x620c26bf…` event fires once per user per close batch, after that group's PositionClosed events. Its lpGain equals Σ(−pnlAfterImpact − fee) over the group's losing closes, and its lpLoss equals Σ pnlAfterImpact over the group's wins. Each position stores its own lp_gain and lp_loss, computed from PositionClosed. The group's paperMinted and tailDelta are split across positions by loss share. The backfill found 3 groups out of 473,308 where the sums disagree by more than $0.0001, all at launch, and 0 unmatched groups.

D-004 · Storage. USD and PAPER amounts are stored as float8 decoded from 1e18 integers, and wallets are interned to int4 ids, to keep inside Neon's free 0.5 GB. Exact integer checks (the PnL formula, supply) run against chain in `scripts/qa.ts`, not against the DB.

D-005 · Timestamps. The backfill stores exact timestamps every 300 blocks (`blocks`) and interpolates linearly in between; HyperEVM runs at about 1.015 blocks/s, so the error is a few seconds at most. Live catch-up uses exact block timestamps.

D-006 · Topics not indexed on Day 1: CallExecuted, NonceUsed, PaperToken Transfer, PositionsClosed, SweepRequested, StakingRewardCredited, BatchExecuted. None feeds a Day 1 panel. The top strip's relayer count reads BatchExecuted live from chain. The fee split check needs PositionsClosed and is marked pending.

D-007 · Snapshot cadence. Every 300 blocks (about 5 minutes) instead of the spec's 500, so the "cap pin ratio" means what §4 says it means (share of 5-minute snapshots).

D-008 · Vercel cron. The project is on the Hobby plan, which allows only daily crons, so a one-minute cron is not available. Live ingest has three parts: (a) every API request that reads the DB schedules a catch-up through `after()` when the cursor is more than 8 s old, guarded by a 55 s lease in the `cursor` table; (b) `/api/catchup` protected by `CRON_SECRET`, on a daily Vercel cron and callable from any external minute scheduler; (c) the Alchemy Notify webhook on Day 2. On the Pro plan, set the cron in `vercel.json` to `* * * * *`.

D-009 · Bust price. Fitted per side as |bust − entry| / entry = a/lev − b over all liquidations (73,709 at QA): long a = 1.00043, b = 4.785 bps, R² 0.9999993 (43,266 rows); short a = 0.99945, b = 4.782 bps, R² 0.9999972 (30,443 rows). The live fit is recomputed every 10 minutes and shown on the Ladder page.

D-010 · Reconciliation deltas against the spec's §1 table. Archive reads at block 48,549,415 reproduce treasury $61.45M, balances $44.98M, locked margin $11.65M, LP $4.82M, tail $154.35M, supply 7.408B and staked 7.352B. Differences:
- nextPositionId − 1 = 662,267, against the spec's 662,279.
- Accrued fees not yet pushed read staker $81 and dev $73, against the spec's $95.4k and $87.4k. These accumulators are pushed often, so the spec's read was probably taken at a different moment.
- Queue: 3 Enqueued events totalling $22.87 at 1e18 scaling, against the spec's "$22.9k". All other amounts on this event family are consistent with 1e18 scaling.
- §5.1 "stakers' cumulative sweep $150M+": Σ StakerLpExcessDistributed since launch is $37.9M. The $154M figure is the tail high-water mark (gross losses past $2M), not the sweep. The Loop shows $37.9M.
- §1 "Treasury … down from $137.9M pre-launch": treasury() was $0 at the block before the first deposit (47,920,889). The waterfall reconciles Σ Swept − Σ CoreWithdrawal to Δ treasury with a residual of −$101 (0.0002%).

D-011 · Loss inflow follows §4: Σ lpGain + Σ liquidated margin. lpGain on closes is already net of the 2% fee while the liquidation term is gross; this is stated on the methodology page.

D-012 · OI caps. MarketOiCapsUpdated fires about 90 times per 2,000 blocks, so the caps are dynamic. Their units are not confirmed (raw ÷ 1e18 gives about 2,289 for BTC long), so "OI vs caps" stays pending until the units are matched to open notional.

D-013 · Next.js 15 is kept as the spec asks. `npm audit` flags the PostCSS bundled inside Next for build-time CSS stringify and source-map issues. The app only processes its own CSS, so this is not reachable at runtime. Next 16 fixes it and is a later upgrade.

D-014 · Local development without DATABASE_URL uses an embedded Postgres (PGlite socket server on port 5433, `.localdb/`). Production uses Neon through the Vercel Marketplace.

D-015 · Distributed word order. §4 says "Σ Distributed.amount" without naming the word. On chain, word 2 equals StakerFeesClaimed.amount + StakerLpExcessDistributed.amount in the same tx (checked on tx 0x5c12f925…: 4,772.90 + 145,066.0 = 149,838.9). Word 1 tracks rewardReserve after the push. Word 2 is therefore the USDC amount. Lifetime: $40.89M = $37.90M LP sweep + $2.98M fees.

D-016 · Struct layout of Exchange.positions(uint256), confirmed on 100 random ids at a pinned block: [owner, instrumentId, entryPrice, margin 1e18, leverage, openTimestamp, isLong, unknown, isOpen]. Word 7 matches isLong in only 52 of 100, so it is something else; not used.

D-017 · Lint. `@typescript-eslint/no-explicit-any` is off. JSON-RPC payloads and decoded logs are untyped at the boundary, and `tsc --strict` still runs on every build. `scripts/` is excluded from the Next type-check and run with tsx.

D-018 · Live-edge reconciliation (OPEN ISSUE). Reconciliation is exact (margin Δ $0.00, supply Δ 0.16 PAPER, waterfall $0.00) for any block 200 or more behind the cursor. Within the last ~200 blocks after a catch-up, sums disagree even though every open and close id is present, and the gap heals on later passes. The working hypothesis is a lagging RPC node or partially indexed recent blocks. Mitigation for now: catch-up stays 20 blocks behind head and re-scans the last 300 blocks on every pass. QA should pin at least 200 blocks behind the cursor (QA_LAG=200) until the root cause is found.

D-019 · Hourly rollup and insight cache (15 Oct, depth pass). Request handlers never scan raw events: `hourly` (one row per UTC hour, 40 measures) is materialised by `refreshHourly`, called from the catch-up for the hours it touched; `kv` holds the heavy aggregates (concentration, survival, cohorts, fee split, flows) as JSON, refreshed by the catch-up when older than 5 minutes. Cold computation is about 20 s; serving is one row read.

D-020 · No `Upgraded` events. None of the five proxies has emitted ERC1967 `Upgraded(address)` since deployment, so the protocol-changes feed shows InstrumentAdded only. Upgrade detection relies on polling the implementation slot and diffing against the launch-block value (parameters panel).

D-021 · Time-series charts start at launch. Pre-launch hours (the $137.9M of deposits between 6 and 10 Oct) are excluded from every hourly chart so the axis is not dominated by one bar; lifetime totals that need them (waterfall, net flow since first deposit) read the full `flows` table.

D-022 · `Distributed` on PaperStaking: word 2 is the USDC amount (see D-015). Hourly `staker_usdc` sums it; the fee share vs LP sweep split in the staker chart uses `StakerFeesClaimed` and `StakerLpExcessDistributed` from the same hours.

D-023 · Liquidation map (15 Oct). The Ladder hero is a time × price map: every open position is a wall at its fitted bust price from the block it opened to now (width and opacity by notional), confirmed liquidations are dots at (close time, liquidation price), the price path is Hyperliquid 1-minute closes joined to the live BBO mid. A depth profile on the same price axis (2 bp buckets, longs left, shorts right) replaces the earlier stand-alone ladder, and the top eight buckets are labelled. Default view: ±1% of mid, 6 h, notional ≥ $100k; the "$10k+" chip is the floor the liquidation feed is capped at (8,000 rows). The §4 bucket scheme (1 bp near mid, 5 bp, 25 bp) is kept in the CSV/table view; on a linear price axis uniform 2 bp buckets draw more honestly.

D-024 · 26 Oct, pre-launch pass. The indexer had fallen 690k blocks behind because the request-triggered catch-up moved 6,000 blocks per page view and the Hobby cron runs once a day; it now moves 30,000 blocks per pass (routes that trigger it declare maxDuration 60). The gap was closed with the backfill script. Neon's free project limit was hit at 468 MB; the installation moved to the Launch plan (usage-based, $0.35 per GB-month storage). Two recon-only indexes on `positions` were dropped (open_block, (close_type, close_block)).

D-025 · Local Node connects to Neon only with `--no-network-family-autoselection`: Node 24's happy-eyeballs aborts the ~430 ms IPv4 connect. Scripts and the local dev server set NODE_OPTIONS accordingly; Vercel is unaffected.

D-026 · Upsert ordering. Concurrent backfill windows deadlocked on `wallets` and `positions`; every chunk is now sorted (addresses, then position ids) so transactions take row locks in one order. Concurrency 2.

D-027 · HyperCore preview. Alchemy's docs mark the market-data reads (candles, asset contexts, mids) "documented but not yet callable"; the HyperCore JSON-RPC host returns 401 for this key. Candles and 24h change stay on Hyperliquid's public API, labelled. The `/info` subset on the EVM host (spotClearinghouseState, clearinghouseState) keeps working.

D-028 · Revenue page. Adds the narrative layer: staker income per UTC day split into fee share (StakerFeesClaimed) and overflow (StakerLpExcessDistributed), take in bp of volume, the live overflow regime, the top-25 stakers' trading PnL vs staking rewards (live stakedBalance and pendingReward via Multicall3), cost per PAPER by first-trade cohort, OI history by side from the hourly rollup, and a valuation calculator with measured defaults. The reference price ($0.0263, Paragon's 19 Oct settlement) is a manual input and says so.

D-029 · Performance after the gap (2.1M positions). `positions` gained `open_ts` and `close_ts` indexes; trailing-window and recent-liquidation queries use them. Lifetime totals read the hourly rollup instead of scanning positions. Launch-block parameter reads are cached in `kv` for a day. The heavy aggregates are split into six `kv` keys (insightsA/B/C, flowsInsights, house, cohortCost) and the catch-up refreshes the stalest one per pass, so no single pass approaches the 60 s function limit.

D-030 · 61 close-mint events (150k PAPER in total, blocks 49.19M–49.56M) had no PositionClosed from the same user in the same transaction; they sit in `close_mints_unmatched` and count toward supply reconciliation (residual 99 PAPER, 0.000001%). Not yet investigated; most likely closes executed through a different path than the relayer batch.

D-031 · QA at block 49,562,444 (26 Oct): waterfall residual $0.00; Σ mints vs totalSupply 99.31 PAPER; open set Σ margin equals totalLockedMargin to $0.00 over 1,333 positions; 100/100 random positions match `positions(id)`; losses formula exact in wei 525/525; fee 2% 524/525 losses (one rounding), 463/463 wins; ladder next-hour precision 70.5%, recall 100%.

D-032 · Cost per PAPER is shown as net trading loss (losses minus wins) ÷ PAPER minted, which is what a wallet actually paid in cash; gross losses ÷ PAPER (what minted) is in the CSV. The net figure reproduces the 22 Oct thread's $0.0064 for the top 10 (dashboard: $0.0065).

D-033 · Silent upgrade on 21 Oct. The Exchange and PaperTokenomics implementations changed in block 49,169,385 (21 Oct 22:00:02 UTC), two days after the non-transferability post. No `Upgraded` event was emitted; the implementation-slot poll (parameters panel) caught it and the block was found by bisecting `eth_getStorageAt`. Checked after the upgrade: close fee still 2.000% of loss and of pnlAfterImpact; realised mint rate 9.81 PAPER/$ equals r(H) = 100 × (120M / (120M + 263M))², so the curve parameters and formula are unchanged. Two things did change: (a) 61 close-mint events since block 49,190,341 have no PositionClosed in the same transaction, carry round `lpGain` amounts ($500, $1,000), tailDelta 0 and a trackedLp increase equal to the amount, consistent with a direct "pay USDC, mint PAPER" path (150k PAPER so far; not yet confirmed from traces); (b) the mean pnlAfterImpact / pnlAfterDeadband ratio on winning closes fell from 0.553 to 0.473, which may be a heavier impact haircut or a different mix of moves; shown as observed, not explained.

D-034 · Candle source switched to settlement prints (26 Oct). The price path on the Ladder, the 24 h change in the strip and the MAE/MFE approximation now come from Papertrade's own prints: every PositionOpened entry and every PositionClosed / Liquidated exit, which are the exact HyperCore BBO prices the Exchange settled at (indexed from HyperEVM logs via Alchemy). Checked against Hyperliquid's public 1-minute closes: 1,434 of 1,440 minutes covered, mean |diff| 0.28 bp. Hyperliquid's public API is kept only as a fallback when a window has no prints, and the response carries its source. The print queries filter on the open_ts / close_ts indexes.

D-035 · QA at block 49,569,232 (26 Oct, after the prints switch): waterfall residual $0.00; Σ mints vs totalSupply 99.31 PAPER; open set equals totalLockedMargin to $0.00 over 1,379 positions; 100/100 positions match `positions(id)`; losses formula exact in wei 542/542; fee 2% 542/542 and 443/443; ladder next-hour precision 71.4%, recall 100%. MAE/MFE from prints on 1,199 sampled positions: wins close at a median MAE of 0 bp and MFE 6.9 bp; losses MAE 4.0 bp; liquidations MAE 6.6 bp with a median MFE of 2.8 bp, i.e. most liquidated positions had a small profitable exit they did not take.

D-036 · Rebrand to PAPERNOMICS (27 Oct). paperscope.xyz and papertrail.xyz were both taken by the time of launch; papernomics.xyz was free ($1.99 first year, $13/year after) and fits the Revenue angle. The product, wordmark, page titles, CSV filenames and article brief use the new name; the Vercel project, repo folder and internal identifiers keep `paperscope`. The purchase itself had to be made by the author: Vercel's CLI refuses domain purchases from agents by policy.