Module encoder 

Deterministic two-way encoder for Binance Link broker ID prefixing.

The Binance broker ID is automatically prefixed to all system-generated client order IDs for every order placed through the Binance adapter. This prefixing is transparent to strategies and requires no user configuration. Inbound order events are decoded back to the original ClientOrderId before reaching the trading system.

Binance’s Link and Trade program requires the newClientOrderId parameter to start with x-{BROKER_ID} for order attribution. Binance enforces a 36-character limit on this field with the regex ^[\.A-Z\:/a-z0-9_-]{1,36}$.

Internal Nautilus ClientOrderId values (O-format: 23+ chars, UUID: 32-36 chars) exceed the 36-char limit when combined with the broker prefix. This module provides compact, deterministic, two-way encoding via pure functions.

Wire format

x-TD67BGP9-{signal}{base62_payload}
|-- prefix -||- encoded component -|

The prefix x-{BROKER_ID}- is 11 chars (for an 8-char broker ID), leaving 25 chars for the encoded component. Spot and Futures use separate broker IDs defined in consts.

Signal chars

The first character after the prefix identifies the original format so the decoder can reconstruct the exact original ClientOrderId string.

Signal	Original format	Payload length	Total
T	O-format with hyphens	13 base62	25
t	O-format without hyphens	13 base62	25
U	UUID with hyphens	22 base62	34
u	UUID without hyphens	22 base62	34
R	Raw passthrough	variable	<= 36

O-format packing (72 bits -> 13 base62 chars)

The O-format ClientOrderId O-YYYYMMDD-HHMMSS-TTT-SSS-CCC is packed into a 72-bit integer:

bits [71:40] (32 bits): seconds since 2020-01-01 epoch
bits [39:30] (10 bits): trader tag (0-1023)
bits [29:20] (10 bits): strategy tag (0-1023)
bits [19:0]  (20 bits): count (0-1048575)

UUID packing (128 bits -> 22 base62 chars)

The UUID is parsed from hex into a 128-bit integer and base62-encoded.

Decoding

If the encoded string starts with the broker prefix, the decoder strips it, reads the signal char, and reconstructs the original ClientOrderId. Strings without the prefix are returned as-is for backward compatibility with orders placed before broker ID support.

Performance

Encoding adds sub-microsecond overhead per order operation, negligible compared to network round-trip latency (typically 1-10 ms). Measured on AMD Ryzen 9 7950X (release build, 100k iterations):

Operation	ns/op
encode O-format	~70
decode O-format	~178
encode UUID	~208
decode UUID	~46
encode raw	~14
decode raw	~14
decode passthrough	~13

Uses stack-allocated base62 output, manual civil time arithmetic (no chrono), and direct byte-level hex/digit parsing to avoid heap allocations on the hot path.

Note: cargo bench cannot currently run in this workspace due to a cdylib output filename collision (see https://github.com/rust-lang/cargo/issues/6313). Use cargo test --release -p nautilus-binance --lib -- bench_encode_decode_timing --nocapture to reproduce these numbers.

Functions

decode_broker_id

Decodes an encoded string back to the original ClientOrderId value.

encode_broker_id

Encodes a ClientOrderId into a Binance-compatible string with broker ID prefix.