Positions codec

Hyperliquid level runs and footprint minutes use one small binary codec, both on the wire (the answers of /v1/hl/levels and /v1/hl/footprint) and on disk (the recorder’s .levels and .fp day files). The reference implementation is flowscope_engine::positions::codec.

Principles

• Little-endian, no padding.
• Self-delimiting: a payload’s length follows from its counts.
• Checksummed: every payload ends with an FNV-1a 32-bit hash of its own bytes.
• Appendable: a day file is payloads written one after another. A reader decodes payloads until the first truncated or damaged one and ignores the rest, so a crash mid-write loses only the last append.
• Versioned: both payload types are at version 1.

Levels payload

"FSPL" u16 version u16 0  f64 bucket_px  i64 latest  i64 from  i64 to
u8 coin_len  coin  u32 n  n × (i64 start  u32 dur  i32 bucket  u8 kind  f32 notional)  u32 fnv

Header

In an API answer, from is the requested start or later when nothing is recorded before it. In a day file, from and to are the day’s bounds.

Run record

21 bytes each.

Kinds 0–1 make up the take-profit map, 2–3 the stop-loss map and 4–5 the liquidation map.

Trailer

Total size: 45 + coin_len + 21 × n + 4 bytes.

Footprint payload

"FSPF" u16 version u16 0  f64 row_px  i64 latest  i64 from  u8 coin_len  coin  u32 n
n × (i64 minute  f32 oi mark tracked_long tracked_short volume taker_known both_known  u32 cells
     cells × (i32 row  f32 d_oi nl ns volume))  u32 fnv

Header

There is no to: the footprint payload covers minutes from from on.

Minute record

40 bytes, followed by its cells.

Cell record

20 bytes each, directly after their minute record.

Trailer

A u32 FNV-1a 32 of every byte of the payload before it, from the magic on.

Checksum

Both payload types use the same 32-bit FNV-1a as day segments: offset basis 0x811C9DC5, prime 0x01000193, applied byte by byte.

fn fnv1a(bytes: &[u8]) -> u32 {
    bytes.iter().fold(0x811c_9dc5u32, |h, b| (h ^ u32::from(*b)).wrapping_mul(0x0100_0193))
}

Decoding

A reader checks, per payload:

To read a day file, decode payloads from offset 0 until the end of the file or the first error. Everything before the error is valid; anything after is a torn tail.

In Rust

use flowscope_engine::positions::codec::{decode_levels, decode_footprint, decode_levels_file};

// One payload from the API.
let levels = decode_levels(&std::fs::read("btc.levels")?)?;
let footprint = decode_footprint(&std::fs::read("eth.fp")?)?;

// A recorder day file: every intact payload and the bytes they cover.
let (payloads, good) = decode_levels_file(&std::fs::read("flowscope-data/hl/BTC/2026-10-04.levels")?);

decode_footprint_file does the same for .fp files.