JLP Protocol Specification

JLP (JeanLucPons protocol) is a binary protocol carried over TCP, optionally wrapped in TLS. It connects Pollard's Kangaroo workers to a pool server and handles authentication, work assignment, distinguished point (DP) submission, statistics, and solution broadcast. v3 (collider v1.5.0) is the current wire format; v1.4.x clients running v1 / v2 are refused at AUTH.

v4 adds proof-of-walk. Each worker commits a Merkle root over the checkpoint distances of its kangaroo walk (one checkpoint every 65,536 jumps) and attaches it to every distinguished point (DP_SUBMIT_V3). The server may then issue a CHALLENGE for a random subset of segments; the worker reveals the endpoint distances plus their Merkle proofs (CHALLENGE_RSP) and the server replays the forward jumps to confirm the segment links up. Because the challenge is random and issued after commitment, a grinder cannot fabricate a consistent checkpoint chain without actually walking — removing the advantage of submitting cheap off-walk points.

Backwards compatible. The pool runs in compatibility mode by default: existing v3 (v1.5.x) workers keep mining unchanged, while v4 workers additionally submit checkpoint commitments. Operators switch to strict (v4 required) once every worker has upgraded. Pre-v1.5 (v1.4.x) clients are refused in both modes.

The challenge check ships disabled (challenge_mode: off) and is turned on only after a v4 client is in the field and the walk step function is validated, so honest workers are never falsely penalized during the rollout.

In v1.4.x, a pool worker who happened to find the cross-collision computed the puzzle's private key locally and could sweep the funds before the pool ever saw the solution. v3 closes the window architecturally: each worker runs ONLY tame kangaroos OR ONLY wild kangaroos, the host-side cross-type hashtable is disabled in pool mode, and the pool server is the sole entity where TAME and WILD DPs aggregate.

Worker invariants

• WORK_ASN.kangaroo_type is 1 (TAME_ONLY) or 2 (WILD_ONLY). Value 0 (BOTH) is reserved and illegal in pool mode; standalone solo mode keeps BOTH.
• The worker host-side cross-type DP hashtable is disabled. DPs flow straight to the network.
• The report_solution codepath is removed from the client entirely. There is no client-to-server SOLUTION message in v3.
• A worker submitting a WILD DP under a TAME assignment (or vice versa) is unambiguous binary modification. The server bans the originating IP permanently on first occurrence, bypassing the rolling-window invalid-DP ladder.

Server flow on collision

1. Match incoming TAME DP against the WILD DP set (and vice versa).
2. Compute k = (d_tame - d_wild + HalfRange) mod n; verify k * G == Q.
3. Sign + broadcast the puzzle-funds sweep transaction via mempool
   provider PRIMARY.
4. Poll mempool provider FALLBACK until the sweep tx is observed
   (cross-provider attestation; hard timeout).
5. ONLY THEN broadcast SOLUTION to every connected worker.

Workers receive the recovered key inside a SOLUTION frame whose puzzle UTXOs are already moving (or already moved). They cannot win the race even by extracting the key from the SOLUTION payload.

Every JLP message starts with this fixed 8-byte header. The flags byte carries the negotiated protocol version (the layout itself is unchanged across v1/v2/v3 so a v1 receiver can at least read the type+length and emit a clean MSG_ERROR rather than crash).

+--------+--------+--------+--------+--------+--------+--------+--------+
|   'K'  |   'A'  |   'N'  |   'G'  |  TYPE  | FLAGS  |   LENGTH (u16)    |
+--------+--------+--------+--------+--------+--------+--------+--------+
|  0x4B  |  0x41  |  0x4E  |  0x47  |  0xNN  |  0xVV  |  LO     |  HI    |
+--------+--------+--------+--------+--------+--------+--------+--------+
|<-------- 4 bytes -------->|<- 1B ->|<- 1B ->|<------ 2 bytes -------->|
|         MAGIC "KANG"      |  TYPE  | flags  |   payload_size (LE)     |
                                       (= protocol_version)

DP_ACK (0x21) -- 4 bytes

struct DPAck {
    uint32_t count;             // Number of DPs accepted from the last DP_BATCH_V2
};