Crate pallet_shards

Timechain Shards Pallet

The Shards pallet manages the lifecycle of shards in a decentralized network. It handles the creation, commitment, readiness, and offline status of shards, along with managing shard members and their state. The pallet ensures that the commitments of all members are valid and that they are ready before transitioning a shard to an online state. It also provides mechanisms for forcefully taking shards offline when needed. The main callable functions (commit, ready, and force_shard_offline) enable members and administrators to interact with the shards, while hooks like on_initialize ensure timely state updates and cleanup. Events are emitted to signal important state changes and actions taken on shards.

Call Functions

This graph represents the workflow of the commit, ready, and force_shard_offline call functions within the Shards pallet.

Commit Flow

The commit process begins with verifying that the request is from an authenticated user. It then checks the current status of the member to ensure they are eligible to commit. If the status is not as expected, the process returns an UnexpectedCommit error. Once the status is validated, the required commitment threshold is retrieved, and the length of the commitment is checked for appropriateness. The commitment is validated, and any invalid commitment results in an InvalidCommitment error. A valid commitment is stored, followed by a check to see if all necessary commitments have been received. Once all commitments are collected, they are aggregated into a group commitment, which is then stored. The shard state is updated based on these commitments, and the process concludes with the logging of a ShardCommitted event.

Force Shard Offline Flow

The force shard offline process starts with ensuring the request is from a root user. Upon confirmation, the system removes the shard. This involves removing the shard state, retrieving the network details, and scheduling the shard_offline task. The process also includes draining and removing shard members, removing members from the MemberShard, and concludes with logging the ShardOffline event.

Ready Flow

The ready process begins with ensuring the request is from an authenticated user. It checks the current status of the member to confirm they are in the correct state to be marked as ready. If the status is not appropriate, an UnexpectedReady error is returned. Once the status is validated, the system retrieves the network and commitment of the member. It is then marked as ready, and a check is performed to see if all members are ready. If all members are ready, the shard state is updated to Online, and the shard_online task is scheduled. The process ends with the logging of a ShardOnline event.

graph TD;
        X[commit] --> Y[Ensure signed];
        Y --> Z[Check member status];
        Z -->|No| AA[Error: UnexpectedCommit];
        Z -->|Yes| AB[Retrieve threshold];
        AB --> AC[Check commitment length];
        AC --> AD[Verify commitment validity];
        AD --> AE[Store member commitment];
        AE --> AF[Check all commitments];
        AF --> AG[Reduce commitments to group commitment];
        AG --> AH[Store group commitment];
        AG --> AI[Update shard state];
        AI --> AJ[Deposit ShardCommitted event];
        AJ[ShardCommitted];

        AD -->|Error: InvalidCommitment| AK[Handle commitment error];


        X2[force_shard_offline] --> Y2[Ensure root];
        Y2 --> Z2[Call remove_shard_offline];
        Z2 --> AA2[Remove shard state];
        AA2 --> AB2[Retrieve network];
        AB2 --> AC2[TaskScheduler: shard_offline];
        AA2 --> AD2[Drain and remove shard members];
        AD2 --> AE2[Remove member from MemberShard];
        AE2 --> AF2[Deposit ShardOffline event];

        X1[ready] --> Y1[Ensure signed];
        Y1 --> Z1[Check member status];
        Z1 -->|No| AA1[Error: UnexpectedReady];
        Z1 -->|Yes| AB1[Retrieve network];
        AB1 --> AC1[Retrieve commitment];
        AC1 --> AD1[Store member as ready];
        AD1 --> AE1[Check all members ready];
        AE1 --> AF1[Update shard state to Online];
        AE1 --> AG1[Deposit ShardOnline event];
        AF1 --> AH1[TaskScheduler: shard_online];





style X fill:#f9f,stroke:#333,stroke-width:2px;
style AK fill:#f96,stroke:#333,stroke-width:2px;
style AA fill:#f96,stroke:#333,stroke-width:2px;
style AJ fill:#bbf,stroke:#333,stroke-width:2px;
style X2 fill:#f9f,stroke:#333,stroke-width:2px;
style AF2 fill:#bbf,stroke:#333,stroke-width:2px;
style X1 fill:#f9f,stroke:#333,stroke-width:2px;
style AA1 fill:#f96,stroke:#333,stroke-width:2px;
style AG1 fill:#bbf,stroke:#333,stroke-width:2px;

on_initialize Hook

This graph illustrates the workflow of the on_initialize function within the Shards pallet. The on_initialize function is triggered at the beginning of each block and iterates over the DkgTimeout entries to identify any shards that have timed out. For each entry, the function checks if the timeout condition is met. If the condition is met, the function handles the timeout by either removing the DkgTimeout entry or marking the shard as offline. In the case where the shard is neither in a Created nor Committed state, the function removes the timeout entry. If the shard is in a Created or Committed state, it proceeds to handle the shard going offline. This involves removing the state and thresholds entrie of a shard, attempting to retrieve the associated network, and marking the shard as offline in the task scheduler. Additionally, the function drains the shard members, removes their entries, handles the shard going offline in the elections module, and finally emits the ShardOffline event.

graph TD;
    A[on_initialize] -->|Iterate DkgTimeout| B{Timeout check};
    B -->|Yes| C[Handle timeout];
    C --> D[Remove DkgTimeout];
    C --> E[Handle shard offline];
    E --> F[Remove shard state];
    F --> G[Remove shard threshold];
    F --> H[Retrieve network];
    H --> I[TaskScheduler: shard_offline];
    F --> J[Drain shard members];
    J --> K[Remove member from MemberShard];
    G -->|Elections: shard_offline| L[Handle shard offline event];
    L --> M[Deposit ShardOffline event];

 


style A fill:#f9f,stroke:#333,stroke-width:2px;
style M fill:#bbf,stroke:#333,stroke-width:2px;

Re-exports

• pub use pallet::*;

Modules

• benchmarking 🔒
• pallet
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.