Module levelwise 

LevelWise sync types (CIP Appendix B - Protocol Selection Matrix).

Types for level-by-level breadth-first synchronization, optimized for wide, shallow trees with scattered changes.

When to Use

• max_depth <= 2 (shallow trees)
• avg_children_per_level > 10 (wide trees)
• Changes scattered across siblings

Protocol Flow

Initiator                          Responder
    │                                   │
    │ ──── LevelWiseRequest ──────────► │
    │      { level: 0 }                 │
    │                                   │
    │ ◄──── LevelWiseResponse ───────── │
    │      { nodes at level 0 }         │
    │                                   │
    │ (Compare hashes, identify diff)   │
    │                                   │
    │ ──── LevelWiseRequest ──────────► │
    │      { level: 1, parent_ids }     │
    │                                   │

Trade-offs

Aspect	HashComparison	LevelWise
Round trips	O(depth)	O(depth)
Messages/round	1	Batched by level
Best for	Deep trees	Wide shallow trees

Validation

All types have is_valid() methods that should be called after deserializing from untrusted sources to prevent resource exhaustion attacks.

Security Note: DoS Protection Limitations

The current validation model has a known limitation: is_valid() checks occur after borsh deserialization, meaning a malicious peer could send an oversized array that gets fully allocated before validation rejects it.

Mitigations:

• Transport layer: Message size limits should be enforced at the network layer
• Defense in depth: is_valid() still catches logical violations

Future work: Consider transport-level message size limits or streaming deserialization with early termination. Borsh field-level max_length attributes don’t prevent the underlying allocation during deserialization.

Structs

LevelCompareResult

Result of comparing nodes at a level.

LevelNode

A node in the level-wise traversal.

LevelWiseRequest

Request for level-wise breadth-first synchronization.

LevelWiseResponse

Response containing nodes at a specific level.

Constants

MAX_LEVELWISE_DEPTH

Maximum depth for level-wise sync traversal.

MAX_NODES_PER_LEVEL

Maximum number of nodes in a single response.

MAX_PARENTS_PER_REQUEST

Maximum number of parent IDs in a single request.

MAX_REQUESTS_PER_SESSION

Maximum number of requests allowed per sync session.

Functions

compare_level_nodes

Compare local and remote nodes at a level.

should_use_levelwise

Check if LevelWise sync is appropriate for a tree.