feat: record the Ref pool's bid side over time
ci / gate (push) Successful in 4m7s
deploy / validate (push) Skipped
deploy / build (push) Successful in 8m55s
deploy / deploy-web (push) Successful in 5s
deploy / deploy-api (push) Successful in 18s

Each pool read now writes a snapshot — totals, swap volumes, and what
selling 10, 100, 1,000 and 5,000 of the asset would fetch from the
pool's own `quote` view — and the order book whenever it changed
(migration 0014). `/v1/chains/{chain}/ref/bids` turns that into the
series #41 asks for: posted orders, money held otherwise, net swapped
in, the quotes; the book now against N hours ago; and every level
change, classified by `dcl::level_changes` — a shrink the pool's payout
in the same minute accounts for is "taken by a swap" (consistent with
one, not proof), the rest "withdrawn", allocated nearest the price
first. The `ref-dcl` page shows it as four one-hue sparkline tiles and
two tables, never one chart in several colours.

Also records in CLAUDE.md why three deploys were cancelled: Gitea
cancels runs by commit when a branch at that commit is deleted.

Refs #41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pkwBsR54NRmZyU4QVhvfj
This commit is contained in:
2026-10-06 18:17:11 +03:00
co-authored by Claude Opus 5.5
parent 1d25689e3d
commit 5361dec713
21 changed files with 1479 additions and 4 deletions
+28
View File
@@ -0,0 +1,28 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* A change to one bid level between two reads of the book.
*/
export type BidChange = {
/**
* When the book showing it was read.
*/
at: string,
/**
* The level's price.
*/
price: number,
/**
* `added`, `raised`, `filled` or `cancelled`. A fill is a shrink that the
* pool's payout in the interval accounts for — consistent with a swap, not
* proof of one.
*/
kind: string,
/**
* Counter token bid there before, whole units.
*/
before: number,
/**
* And after.
*/
after: number, };
+18
View File
@@ -0,0 +1,18 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* One limit-order bid level.
*/
export type BidLevel = {
/**
* The asset's price there, in the counter.
*/
price: number,
/**
* Counter token bid, whole units.
*/
counter: number,
/**
* The asset it absorbs, whole units, before the pool's fee.
*/
absorbs: number, };
+55
View File
@@ -0,0 +1,55 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { BidChange } from "./BidChange";
import type { BidLevel } from "./BidLevel";
import type { BidSidePoint } from "./BidSidePoint";
/**
* A Ref DCL pool's bid side over time: what a seller of the asset can be
* paid, and how that has been changing (blackbeard/observer#41).
*/
export type BidSide = {
/**
* `token_x|token_y|fee`.
*/
pool_id: string,
/**
* The asset's symbol.
*/
asset_symbol: string | null,
/**
* The counter token's symbol.
*/
counter_symbol: string | null,
/**
* Hours the series covers.
*/
hours: number,
/**
* When this observer first read the pool: no history exists before it,
* whatever `hours` asks for.
*/
recorded_since: string | null,
/**
* Amounts of the asset whose sale is quoted, whole units.
*/
quote_sizes: Array<number>,
/**
* The series, oldest first, thinned to at most a few hundred points.
*/
points: Array<BidSidePoint>,
/**
* The bid book now, best price first.
*/
book_now: Array<BidLevel>,
/**
* The book as it stood `hours` ago, or at `recorded_since` if later.
*/
book_then: Array<BidLevel>,
/**
* When `book_then` was in force.
*/
book_then_at: string | null,
/**
* Every level change in the span, newest first.
*/
changes: Array<BidChange>, };
+30
View File
@@ -0,0 +1,30 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* One moment of a pool's bid side, in whole units of the counter token
* (blackbeard/observer#41).
*/
export type BidSidePoint = {
/**
* When the pool was read.
*/
at: string,
/**
* Counter token in open limit orders: posted bids, cancellable at will.
*/
posted: number,
/**
* Counter token held outside orders — liquidity, buyers' payments and
* uncollected fees. Moves only by swaps or a provider withdrawing.
*/
held: number,
/**
* Net counter token swapped in since the pool opened: buyers' payments
* less what sellers were paid. Falling means sellers outpace buyers.
*/
net_swapped: number,
/**
* Average price a seller of each [`BidSide::quote_sizes`] amount would
* get, in the counter per asset, same order; `None` where unanswered.
*/
quotes: Array<number | null>, };
+14
View File
@@ -6,6 +6,7 @@
* Pushing it to every connected tab would be strictly worse.
*/
import type { BidSide } from './generated/BidSide'
import type { AccountDetail } from './generated/AccountDetail'
import type { AccountEvent } from './generated/AccountEvent'
import type { AccountRow } from './generated/AccountRow'
@@ -328,6 +329,19 @@ export async function fetchIntentsSeries(
)
}
/** A Ref DCL pool's bid side over the last `hours` (blackbeard/observer#41). */
export async function fetchRefBids(
chain: string,
poolId: string,
hours: number,
signal?: AbortSignal,
): Promise<BidSide> {
return get<BidSide>(
`/chains/${chain}/ref/bids?pool_id=${encodeURIComponent(poolId)}&hours=${hours}`,
signal,
)
}
/** The asset's price in its Ref DCL pools against one counter token. */
export async function fetchRefSeries(
chain: string,
+288
View File
@@ -0,0 +1,288 @@
/**
* A Ref DCL pool's bid side over time: what a seller of the asset can be paid,
* and how that is changing (blackbeard/observer#41).
*
* The ladder above says what is bid now. This says where it came from and
* where it is going, which is the part a seller deciding *when* to sell needs:
*
* - **Posted** is limit-order money. It is most of the bid side and its owner
* can take it back at any moment, so it is shown apart from everything else.
* - **Held otherwise** moves only by swaps or a provider withdrawing.
* - **Net swapped in** is buyers' payments less what sellers were paid: falling
* means sellers are outpacing buyers.
* - **Selling N fetches** is the pool's own `quote` view at fixed sizes: a
* computation from pool state, never an offer — the solver's spread and the
* pool's fee come on top.
*
* Every chart is one series in one hue (CLAUDE.md "Charts"): four tiles, each
* its own sparkline, rather than one chart with four colours. The book then and
* now, and every level change, are tables.
*/
import { useEffect, useState } from 'react'
import type { BidSide } from '../api/generated/BidSide'
import { RequestFailed, fetchRefBids } from '../api/rest'
import { price as fmtPrice, utc, when } from '../lib/format'
import type { SparkPoint } from './Sparkline'
import { TrendStat } from './StatBar'
/** Spans offered, in hours. */
const SPANS: [number, string][] = [
[6, '6 h'],
[24, '24 h'],
[24 * 7, '7 d'],
]
const REFRESH_MS = 60_000
/** Whole units, compact. */
function amount(v: number, places = 0): string {
return v.toLocaleString('en-US', { maximumFractionDigits: places })
}
/** How each kind of change reads. */
const CHANGE: Record<string, string> = {
added: 'posted',
raised: 'raised',
filled: 'taken by a swap',
cancelled: 'withdrawn',
}
export function BidSidePanel({
chain,
poolId,
refresh,
}: {
chain: string
poolId: string
/** Changes when the pools were re-read, so the panel follows them. */
refresh: string
}) {
const [hours, setHours] = useState(24)
const [size, setSize] = useState(0)
const [data, setData] = useState<BidSide | null>(null)
const [error, setError] = useState<string | null>(null)
useEffect(() => {
const controller = new AbortController()
const load = () =>
fetchRefBids(chain, poolId, hours, controller.signal)
.then((d) => {
setData(d)
setError(null)
})
.catch((e: unknown) => {
if (controller.signal.aborted) return
setError(e instanceof RequestFailed ? e.message : 'Could not reach the observer.')
})
load()
const id = window.setInterval(load, REFRESH_MS)
return () => {
window.clearInterval(id)
controller.abort()
}
}, [chain, poolId, hours, refresh])
const asset = data?.asset_symbol ?? 'the asset'
const counter = data?.counter_symbol ?? 'the counter token'
const points = data?.points ?? []
const last = points[points.length - 1]
const spark = (
pick: (p: (typeof points)[number]) => number | null,
fmt: (v: number) => string,
) =>
points.length > 1
? points.map<SparkPoint>((p) => {
const v = pick(p)
return { value: v, label: v === null ? `— · ${when(p.at)}` : `${fmt(v)} · ${when(p.at)}` }
})
: null
const sizes = data?.quote_sizes ?? []
const quoteAt = (p: (typeof points)[number] | undefined) => p?.quotes[size] ?? null
// The book now against then, one row per price either side has.
const levels = new Map<number, { now: number; then: number; absorbs: number }>()
for (const l of data?.book_then ?? [])
levels.set(l.price, { now: 0, then: l.counter, absorbs: 0 })
for (const l of data?.book_now ?? []) {
const row = levels.get(l.price) ?? { now: 0, then: 0, absorbs: 0 }
levels.set(l.price, { ...row, now: l.counter, absorbs: l.absorbs })
}
const depth = [...levels.entries()].sort((a, b) => b[0] - a[0])
return (
<section className="panel" style={{ marginBottom: 26 }}>
<div className="panel-head">
<h2 className="panel-title">Bid side</h2>
<span className="eyebrow">
what a {asset} seller can be paid
{data?.recorded_since ? ` · recorded since ${when(data.recorded_since)}` : ''}
</span>
</div>
<div className="pager" style={{ justifyContent: 'flex-start' }}>
{SPANS.map(([h, label]) => (
<button
key={h}
className="segmented panel-button"
aria-pressed={hours === h}
onClick={() => setHours(h)}
>
{label}
</button>
))}
</div>
{error && <p className="empty">{error}</p>}
{!error && !data && <p className="empty">Reading the bid side…</p>}
{data && points.length === 0 && (
<p className="empty">
Nothing recorded yet. The pool is read once a minute, and its history starts with the
first read.
</p>
)}
{data && last && (
<>
<div className="stats">
<TrendStat
label="Posted bids"
value={`${amount(last.posted)} ${counter}`}
note="limit orders — cancellable at any moment"
points={spark(
(p) => p.posted,
(v) => `${amount(v)} ${counter}`,
)}
/>
<TrendStat
label="Held otherwise"
value={`${amount(last.held, 2)} ${counter}`}
note="liquidity, buyers' payments and fees"
points={spark(
(p) => p.held,
(v) => `${amount(v, 2)} ${counter}`,
)}
/>
<TrendStat
label="Net swapped in"
value={`${amount(last.net_swapped, 2)} ${counter}`}
note="bought in less sold out, since the pool opened"
points={spark(
(p) => p.net_swapped,
(v) => `${amount(v, 2)} ${counter}`,
)}
/>
<TrendStat
label={
sizes.length ? `Selling ${amount(sizes[size] ?? 0)} ${asset} fetches` : 'Quote'
}
value={quoteAt(last) === null ? '—' : `${fmtPrice(quoteAt(last))} ${counter} each`}
note="the pool's own quote — not an offer"
points={spark(
(p) => quoteAt(p),
(v) => `${fmtPrice(v)} ${counter} each`,
)}
/>
</div>
<div className="pager" style={{ justifyContent: 'flex-start' }}>
<span className="eyebrow">quote for selling</span>{' '}
{sizes.map((s, i) => (
<button
key={s}
className="segmented panel-button"
aria-pressed={size === i}
onClick={() => setSize(i)}
>
{amount(s)} {asset}
</button>
))}
</div>
</>
)}
{data && depth.length > 0 && (
<div className="scroll-x">
<table className="board">
<caption className="visually-hidden">
The limit-order bids now and {data.hours} hours ago
</caption>
<thead>
<tr>
<th scope="col" className="left">
Price of {asset}
</th>
<th scope="col">
Bid {data.book_then_at ? `at ${when(data.book_then_at)}` : 'then'}
</th>
<th scope="col">Bid now</th>
<th scope="col">Change</th>
<th scope="col">{asset} it absorbs now</th>
</tr>
</thead>
<tbody>
{depth.map(([p, l]) => (
<tr key={p}>
<td className="left numeral">{fmtPrice(p)}</td>
<td className="numeral">{l.then ? amount(l.then) : '—'}</td>
<td className="numeral">{l.now ? amount(l.now) : '—'}</td>
<td className="numeral">
{l.now === l.then
? '—'
: `${l.now > l.then ? '+' : '−'}${amount(Math.abs(l.now - l.then))}`}
</td>
<td className="numeral">{l.absorbs ? amount(l.absorbs, 1) : '—'}</td>
</tr>
))}
</tbody>
</table>
</div>
)}
{data && data.changes.length > 0 && (
<div className="scroll-x">
<table className="board">
<caption className="visually-hidden">Changes to the bid levels, newest first</caption>
<thead>
<tr>
<th scope="col" className="left">
When
</th>
<th scope="col" className="left">
Price of {asset}
</th>
<th scope="col" className="left">
What happened
</th>
<th scope="col">Before</th>
<th scope="col">After</th>
</tr>
</thead>
<tbody>
{data.changes.map((c, i) => (
<tr key={`${c.at}-${c.price}-${c.kind}-${i}`}>
<td className="left numeral" title={utc(c.at)}>
{when(c.at)}
</td>
<td className="left numeral">{fmtPrice(c.price)}</td>
<td className="left">{CHANGE[c.kind] ?? c.kind}</td>
<td className="numeral">{amount(c.before)}</td>
<td className="numeral">{amount(c.after)}</td>
</tr>
))}
</tbody>
</table>
</div>
)}
<p className="panel-note">
Read from the pool contract once a minute and recorded from the first read, so no history
exists before it. &ldquo;Taken by a swap&rdquo; means a bid shrank by no more than the pool
paid out in {counter} in the same minute — consistent with a seller filling it, though the
views cannot prove which swap; a shrink beyond that is &ldquo;withdrawn&rdquo;. The quote is
the pool&apos;s own computation from its state, not anyone&apos;s offer: a seller going
through NEAR Intents also pays a solver&apos;s spread, and every swap pays the pool&apos;s
fee.
</p>
</section>
)
}
+10
View File
@@ -33,6 +33,7 @@ import {
} from '../lib/format'
import { href } from '../lib/routes'
import { Field } from './Field'
import { BidSidePanel } from './BidSidePanel'
import { SeriesBody } from './PriceChart'
const EXPLORER = 'https://nearblocks.io/txns/'
@@ -252,6 +253,15 @@ export function RefDclMarket({
)
})}
{pools?.pools.map((p) => (
<BidSidePanel
key={`bids-${p.pool_id}`}
chain={chain}
poolId={p.pool_id}
refresh={pools.checked_at}
/>
))}
{pools?.pools.map((p) => (
<RefPriceChart
key={`chart-${p.pool_id}`}
+1 -1
View File
@@ -73,7 +73,7 @@ function Stat({
* place the reader is already looking, costs no layout, and falls back to the
* caption the moment the pointer leaves.
*/
function TrendStat({
export function TrendStat({
label,
value,
note,