This doc is closed!

Pls comment on and refer to https://hackmd.io/@lido/csm-v2-internal

Priority Queues in CSM v2

Preface

For CSM v2, finding a way for likely independent operators to be deposited before other permissionless operators is required. The notion of a priority queue was introduced—a queue where deposit data is requested first. It also became clear that multiple types of node operators can participate in CSM, and it makes sense to prioritize deposits to those differently. To achieve this, the idea is to introduce several prioritized queues with different priorities.

Tech design

CSModule keeps track of a predefined list of priority queues. Every queue is identified by its index, which also serves as its priority indicator. A queue with an index of 0 has the maximum priority. The module has a fixed amount of queues, limited by the LOWEST_PRIORITY deploy-time constant. As a result, the module can work with any queue in the range [0; LOWEST_PRIORITY], where LOWEST_PRIORITY is reserved to be used as a default queue.

CSM v2 introduces a separate contract to the module composition called CSParametersRegistry, so the configuration for separate priority queues is stored in the registry. Queue configuration looks like this:

struct QueueConfig {
    uint8 priority;
    uint32 maxDeposits;
}

In this structure, priority indicates which queue to use, and maxDeposits shows the maximum number of validator keys a node operator can get deposited using the priority queue.

A node operator can be assigned to a group identified by its curveID, so every curveID has its priority queue configuration. The configuration is not limited to using specific queues except for reserved ones. We can imagine the following setup:

curveID    QueueConfig
0          (p0, 10)
1          (p1, 10)
2          (p0, 50)
3          (p3, 10)
...

Adding keys to the queue(s)

The mechanic of adding new keys by a node operator looks like this:

1. Get the QueueConfig associated with the node operator's curveID.
2. Check if there are non-deposited and non-queued keys below QueueConfig.maxDeposits limit that can be put into the queue with priority QueueConfig.priority.
3. Add as many keys as possible to the priority queue with the priority QueueConfig.priority and the rest to the default one, i.e., with LOWEST_PRIORITY.

Note that a node operator can get up to maxDepositsusing its priority queue. In other words, the following scenario is actual:

1. NO uploads 10 (maxDeposits) keys and puts them in the priority queue.
2. NO changes their mind and removes all the keys.
3. NO's batch in the priority queue is skipped.
4. NO uploads 10 keys again and puts them in the priority queue since they have not received any deposits from the queue yet.

Getting deposit data from the queues

The mechanic is simple. CSModule goes over the queues in the order of their priority (0 -> LOWEST_PRIORITY) and processes batches from the queues sequentially: when one queue is exhausted, the next one is used to fetch batches.

Queue(s) cleanup

The cleanup mechanic works similarly to deposit data retrieval. Queues are ordered and processed by their priority, and the batches that cannot be deposited are removed from the queue where they were found.

Migration from the old scheme

To migrate the current queue to the new mechanic, a separate priority is dedicated to the queue and can't be used by any curveID. LEGACY_QUEUE_PRIORITY is set to LOWEST_PRIORITY - 1. As a result, we have the following range of free priorities: [0; LOWEST_PRIORITY-2]. Eventually, the legacy queue will be entirely deposited, and the reserved priority will be released for use in the next release of CSM (v3).