LootX

HMP1 և HMP2 ֆորմատներ

Թարմացվել է 6 նոյեմբերի, 2026 թ. Այս էջը PDF-ով

Ջերմաքարտեզի երկուական ֆորմատը բայթ առ բայթ՝ վերնագիր, կադրեր, HMP2 ծավալի կոդեր և գների շարքեր՝ Python ապակոդավորիչով։

GET /v1/heatmap?format=hmp1 կամ format=hmp2 վերադարձնում է ջերմաքարտեզը ոչ թե աղյուսակով, այլ երկուական ձևաչափով. այն շատ անգամ ավելի կարճ է, գալիս է հոսքով և քեշավորվում է։ Այն հեշտ է պատկերել. կարելի է վերլուծել կադր առ կադր՝ առանց մարմնի ավարտին սպասելու։ Հարցման պարամետրերը նույնն են, ինչ աղյուսակինը։

format Ինչ կա ներսում Content-Type
hmp1 ծավալները ճշգրիտ ամբողջականներ application/octet-stream
hmp2 ծավալը 6–9 բիթանոց կոդով, ավելի կարճ, քան HMP1-ը; qbits՝ մանտիսի բիթ (6–9, լռելյայն 6), layout՝ 0 կադրեր կամ 1 շարքեր application/x-hmp2

format=hmp1|hmp2 այլ երթուղիներում՝ 400 bad_format; qbits կամ layout առանց format=hmp2-ի՝ 400 bad_request։ Սխալները գալիս են JSON-ով, ինչպես միշտ։

Քեշ և ծավալ

Վերնագիրը սահմանում է ջերմաքարտեզի աղբյուրը, դարպասը փոխանցում է այն անփոփոխ.

Cache-Control Երբ
no-store պատուհանն ավարտվում է վերջին րոպեում՝ կենդանի եզր
public, max-age=600 պատուհանի ավարտը 50 ժամից ոչ հին է. արխիվից վերանորոգումը դեռ կարող է լցնել անցքերը
public, max-age=86400, immutable ավելի հին է

Փակ միջակայքերն ունեն ETag։ If-None-Match: <ETag>-ով կրկնվող հարցումը ստանում է 304 Not Modified առանց մարմնի. այն օրական ծավալ չի ծախսում։ Ընդհատված ներբեռնումը ծախսում է այնքան բայթ, որքան հասցրել է ստանալ։

Վերնագիր

Little-endian, 48 բայթ.

Շեղում Չափ Դաշտ
0 4 magic՝ HMP1 կամ HMP2
4 2 version՝ 1 HMP1-ում, 2 HMP2-ում
6 2 flags
8 8 bucket_size (i64)՝ բջջի բարձրությունը price_scale միավորներով
16 1 price_scale (u8)
17 1 qty_scale (u8)
18 1 HMP1: 0; HMP2: qty_bits (6–9)
19 1 HMP1: 0; HMP2: layout (0՝ կադրեր, 1՝ շարքեր)
20 4 time_step_ms (u32)
24 8 from_ms (i64)
32 8 to_ms (i64)
40 4 frame_count (u32)՝ ժամանակային սյունակների քանակ
44 4 stream_id (u32), REST-ում 0

flags. բիթ 0՝ արժեքները ագրեգացված են առավելագույնով (հակառակ դեպքում՝ միջինով); բիթ 1՝ պատասխանը հասել է աղբյուրի մարմնի առաստաղին (16 ՄԲ) և կտրված է աջից ըստ ժամանակի։ Շարունակությունը՝ նույն հարցումը from = վերջին կադրի ժամանակ + time_step_ms։

Պատասխանը վերլուծեք ըստ վերնագրի (magic, version, layout), ոչ թե ձեր հարցման։

Բջջի գինը և ծավալը.

TEXT
price = idx * bucket_size / 10^price_scale     բջջի ստորին սահմանը [price, price + քայլ)
qty   = q / 10^qty_scale                       մոնետաներով
քայլ   = bucket_size / 10^price_scale

Կադրեր՝ HMP1 և HMP2 layout=0-ով

Վերնագրից հետո՝ frame_count կադրեր անընդմեջ.

TEXT
varint  ts_delta_ms    նախորդ կադրի ts-ից; առաջինի մոտ՝ from_ms-ից
u8      kind           1 = KEY (լրիվ վիճակ), 0 = DELTA (փոփոխություններ)
zigzag  best_bid_d     տարբերություն նախորդ կադրի best_bid-ից; առաջինի մոտ՝ 0-ից
zigzag  best_ask_d     նույնը best_ask-ի համար
varint  bid_count
  bid_count անգամ.
    zigzag  idx_delta  նախորդ բջջի idx-ից; առաջինի մոտ՝ 0-ից
    varint  qty        բջջի ԲԱՑԱՐՁԱԿ ծավալը (HMP2-ում՝ կոդ); 0 = մակարդակն անհետացել է
varint  ask_count
  ask_count անգամ.     նույնը

varint՝ LEB128 առանց նշանի։ zigzag՝ LEB128 (n << 1) ^ (n >> 63)-ի վրա, ապակոդավորվում է որպես (u >> 1) ^ -(u & 1)։

Պահեք երկու բառարան idx → qty, bid-երի և ask-երի համար.

  • KEY՝ բառարանները փոխարինվում են կադրի բովանդակությամբ;
  • DELTA՝ վերադրվում է վերևից. qty > 0՝ վերագրել, qty == 0՝ ջնջել բանալին։

Առաջին կադրը միշտ KEY է, հետագայում KEY-ը կրկնվում է յուրաքանչյուր 512 կադրը մեկ։ ts, best_bid, best_ask հաշվիչներն ապրում են մեկ պատասխանի սահմաններում։ Բառարանների վիճակը կադրից հետո՝ ջերմաքարտեզի մեկ սյունակ։

Python
import struct

def uvarint(b, p):
    out = shift = 0
    while True:
        x = b[p]; p += 1
        out |= (x & 0x7F) << shift
        if x < 0x80:
            return out, p
        shift += 7

def svarint(b, p):
    u, p = uvarint(b, p)
    return (u >> 1) ^ -(u & 1), p

def columns(b):
    """HMP1 -> [(ts, {price: qty} bid-եր, {price: qty} ask-եր)]."""
    assert b[:4] == b"HMP1"
    bucket, ps, qs = struct.unpack_from("<qBB", b, 8)
    step_ms, from_ms, _to, frames = struct.unpack_from("<IqqI", b, 20)
    if frames == 0:
        return []
    bid, ask, out, p, ts = {}, {}, [], 48, from_ms
    for _ in range(frames):
        d, p = uvarint(b, p); ts += d
        kind = b[p]; p += 1
        _, p = svarint(b, p); _, p = svarint(b, p)        # best_bid_d, best_ask_d
        for book in (bid, ask):
            n, p = uvarint(b, p)
            cells, idx = [], 0
            for _ in range(n):
                di, p = svarint(b, p); idx += di
                q, p = uvarint(b, p)
                cells.append((idx, q))
            if kind == 1:
                book.clear()
                book.update((i, q) for i, q in cells if q > 0)
            else:
                for i, q in cells:
                    if q: book[i] = q
                    else: book.pop(i, None)
        price = lambda i: i * bucket / 10**ps
        out.append((ts,
                    {price(i): q / 10**qs for i, q in sorted(bid.items())},
                    {price(i): q / 10**qs for i, q in sorted(ask.items())}))
    assert p == len(b), "կադրերից հետո բայթեր են մնացել"
    return out

format=json աղյուսակը հենց այս վերլուծությունն է՝ տող յուրաքանչյուր ոչ զրոյական բջջի համար յուրաքանչյուր սյունակում։

HMP2. ծավալը կոդով

Կադրերը layout=0-ով՝ բայթ առ բայթ ինչպես HMP1-ում, բայց varint qty-ի փոխարեն կանգնած է varint code.

  • code = 0՝ մակարդակ չկա (DELTA-ում՝ «մակարդակն անհետացավ»);
  • հակառակ դեպքում code-ը բջջի ծավալն է մոնետաներով՝ m = qty_bits մանտիսի բիթերով ձևաչափով։

DELTA-ն համեմատում է կոդերը. բջիջը, որի կոդը չի փոխվել, DELTA-ում չի ընկնում, նույնիսկ եթե հում ծավալը մի փոքր շարժվել է։

Ապակոդավորում (d = 23 − m). code = 0 → 0, հակառակ դեպքում v = from_bits(((code + (64 << m)) << d) as u32) որպես float32՝ ծավալը մոնետաներով, qty_scale-ն այլևս չի կիրառվում։ m = 9-ի դեպքում սխալը 2⁻¹⁰-ից ոչ ավելի է, միջակայքը՝ 2⁻⁶³-ից մինչև 2⁶⁵ մոնետա։

Python
import struct

def hmp2_qty(code, m):
    if code == 0:
        return 0.0
    bits = (code + (64 << m)) << (23 - m)
    return struct.unpack("<f", struct.pack("<I", bits))[0]

Վեկտորներ՝ ձեր իրականացումը ստուգելու համար.

Ծավալ Կոդ m=9 Հակառակ Կոդ m=6 Հակառակ
1e-8 18607 9.997166e-9 2326 1.0011718e-8
0.001 27148 0.0009994507 3394 0.0010070801
0.5 31744 0.5 3968 0.5
1 32256 1 4032 1
1023 37375 1023 4672 1024
12345.678 39172 12352 4896 12288

HMP2, layout=1. գների շարքեր

Նույն վերնագիրը 19-րդ բայթ = 1։ Մարմինը՝ չորս հոսք անընդմեջ, առանց kind-ի և կադրի հաշվիչների.

  1. Ժամանակ. frame_count անգամ varint ts_delta, zigzag best_bid_d, zigzag best_ask_d՝ ինչպես կադրում։
  2. Շարքեր. bid-երի, ապա ask-երի համար՝ varint R, հետո R անգամ zigzag idx_delta (առաջինը՝ 0-ից, հետագաները՝ այդ կողմի նախորդ շարքի idx-ից, խիստ աճման կարգով) և varint run_count։
  3. Երկարություններ. բոլոր bid-երի, ապա ask-երի շարքերը, յուրաքանչյուր սերիայի համար varint (len − 1)։ Շարքի երկարությունների գումարը = frame_count։
  4. Կոդեր. նույն հերթականությամբ յուրաքանչյուր սերիայի համար zigzag(code − prev), prev = 0 յուրաքանչյուր շարքի սկզբում։ code = 0՝ մակարդակ չկա այդ սյունակներում։

Շարքը, որը ոչ մի ոչ զրոյական կոդ չունի, չի գրվում։ Շարքերի սյունակը չի կարելի առանձին կարդալ ամբողջ մարմնից՝ հոսքային պատկերման համար վերցրեք layout=0։