Skip to content

docs: add an Oracle page covering multi-source pricing and the internal price - #309

Merged
ogabrielides merged 5 commits into
mainfrom
docs/oracle-pricing-multi-source
Oct 16, 2026
Merged

ogabrielides merged 5 commits into
mainfrom
docs/oracle-pricing-multi-source

Conversation

@ogabrielides

@ogabrielides ogabrielides commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds doc/protocol/oracle.md, listed under Markets right after Order Book. It explains how a perp market's oracle price is picked on each batch, written for readers outside the team.

  • Multiple oracle sources: the 30-second staleness rule, measured against the batch deadline; median aggregation with worked examples; why a median is used instead of an average; how many bad sources a market can tolerate; and a batch-by-batch example of sources failing and coming back.
  • Internal price: what happens when every source is stale. It starts from the last real price and blends toward the order book over 30 minutes, staying inside a corridor. The corridor is sized so a position at maximum leverage can't be liquidated by the internal price alone.
  • Also covers funding during an outage, how new markets start, the trust model and limitations, and a parameters table.

Based on ADR 0038, checked against the current engine code where the ADR contradicts itself. Oracle providers are deliberately not named. Solver and wire-format details (submitSolutionsV2, source IDs, the V2 activation deadline) are left out.

Also: CI fix. test_Fork_BatchDeposit_WithUSDCPermit was failing on every branch. The test signs a USDC permit with key 0xA11CE, whose mainnet address now carries an EIP-7702 delegation. USDC therefore verifies the signature via ERC-1271, which reverts. The test now clears that code with vm.etch before signing (protocol/test/Bridge.fork.sol).

Test plan

  • Page renders in GitBook; {% hint %} blocks and tables display correctly
  • Links to perpetuals.md, margin.md and orderbook.md#solver resolve
  • forge test --mc BridgeForkTest passes against mainnet (9/9)

🤖 Generated with Claude Code

ogabrielides and others added 3 commits September 30, 2026 10:19
…al price

Adds an Oracle page under Markets, right after Order Book. It explains how
a perp market's oracle price is chosen: stale observations are dropped
against the batch deadline, the fresh ones are combined by median, and when
none are fresh the market falls back to a book-derived internal price
bounded by a margin-derived corridor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0xA11CE's address now carries an EIP-7702 delegation on mainnet, so USDC
routes the permit through ERC-1271 and rejects it. Etch the code away so
the test exercises the plain EOA permit path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread doc/protocol/oracle.md Outdated
Comment thread doc/protocol/oracle.md Outdated
ogabrielides and others added 2 commits October 16, 2026 13:06
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ogabrielides
ogabrielides merged commit ca1c47a into main Oct 16, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants