Pallet readme updates

toolkit/pallets/address-associations/README.md

@@ -0,0 +1,84 @@
+# Address Associations Pallet
+
+## Overview
+
+The Address Associations pallet provides functionality to associate mainchain (e.g., Cardano) stake public keys with partner chain addresses. This forms a critical link between the main chain and the partner chain, enabling cross-chain identity verification and operations.
+
+## Purpose
+
+This pallet serves several purposes:
+- Establishes verifiable links between mainchain identities and partner chain addresses
+- Enables cross-chain validation of key ownership through cryptographic signatures
+- Provides a foundation for permission-based operations that require mainchain identity verification
+- Supports cross-chain governance and validator selection processes
+
+## Configuration
+
+The pallet uses the following configuration traits:
+
+```rust
+#[pallet::config]
+pub trait Config: frame_system::Config {
+    /// The overarching event type.
+    type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
+
+    /// Type representing the partner chain address.
+    type PartnerChainAddress: Parameter + Member + MaxEncodedLen + Copy + TypeInfo;
+
+    /// Type representing the mainchain stake public key.
+    type StakePublicKey: Parameter + Member + MaxEncodedLen + TypeInfo;
+}
+```
+
+## Storage
+
+The pallet maintains two main storage maps:
+
+1. `StakePublicKeyToPartnerChainAddress`: Maps from a mainchain stake public key to a partner chain address
+2. `PartnerChainAddressToStakePublicKey`: Maps from a partner chain address to a mainchain stake public key
+
+## API Specification
+
+### Extrinsics
+
+- **associate_address**: Associates a mainchain public key with a partner chain address
+
+### Public Functions (API)
+
+- **get_version**: Returns the current pallet version
+- **get_all_address_associations**: Returns an iterator over all mainchain-partnerchain address associations
+- **get_partner_chain_address_for**: Returns the partner chain address for a given mainchain public key if it exists
+
+### Inherent Data
+
+This pallet does not use inherent data.
+
+### Events
+
+- `AddressAssociated(T::StakePublicKey, T::PartnerChainAddress)`: Emitted when a mainchain public key is successfully associated with a partner chain address
+
+### Errors
+
+- `AddressAlreadyAssociated`: The partner chain address is already associated with a different stake public key
+- `StakePublicKeyAlreadyAssociated`: The stake public key is already associated with a different partner chain address
+- `InvalidSignature`: The provided signature is invalid and cannot prove ownership of the stake key
+
+## Usage
+
+To associate a mainchain stake public key with a partner chain address, the caller must:
+
+1. Generate a signature using their mainchain stake key
+2. Submit the `associate_address` extrinsic with their partner chain address, the signature, and their stake public key
+
+The pallet verifies the signature to ensure the caller owns both the mainchain stake key and the partner chain address before creating the association.
+
+## Dependencies
+
+- frame_system
+- frame_support
+
+## Security Considerations
+
+- Signatures are verified cryptographically to prevent unauthorized associations
+- Once created, associations cannot be modified without governance intervention
+- The pallet ensures one-to-one mappings between stake public keys and partner chain addresses

toolkit/pallets/block-participation/README.md

@@ -1,4 +1,135 @@
 # Block Participation Pallet
 
-This pallet provides configuration and runtime-level support for the block participation inherent data producing
-logic defined in `toolkit/primitives/block-participation`.
+## Overview
+
+The Block Participation pallet manages and tracks validator participation in the block production process across the network. It establishes a systematic mechanism for recording when and how validators contribute to consensus, which is essential for maintaining network security, fairness, and proper incentive distribution.
+
+In the context of partner chains, "block participation" refers to the record of which validators have successfully produced blocks at which slots in the blockchain's history. This information is crucial for several reasons:
+
+1. **Consensus Integrity**: By tracking participation, the system can verify that the consensus rules are being properly followed, and that block production responsibilities are correctly assigned and fulfilled.
+
+2. **Performance Monitoring**: The participation data enables the network to monitor the performance of validators over time, identifying those who consistently meet their obligations and those who don't.
+
+3. **Rewards and Slashing**: Accurate participation records provide the foundation for fairly distributing rewards to validators who contribute to network security, and potentially applying penalties to those who fail to meet their obligations.
+
+4. **Historical Analysis**: Participation data offers valuable insights into network health and validator behavior patterns over time, which can inform governance decisions and protocol improvements.
+
+5. **Slot Finality**: By knowing when participation data has been processed up to a certain slot, the system can make determinations about when certain slots can be considered "finalized" from a participation tracking perspective.
+
+The pallet provides a time-windowed approach to participation tracking, where data is processed up to specific slots, and historical data beyond a configured slack window can be safely released to optimize storage usage. This creates an efficient balance between maintaining necessary historical records and managing chain state growth.
+
+Additionally, it integrates with the inherent data mechanism of Substrate, allowing participation processing to be included automatically in blocks when appropriate, rather than requiring explicit extrinsic calls for every update.
+
+By separating the concerns of recording participation (typically handled by the block production log pallet) and processing that participation data (handled by this pallet), the system achieves a clean architectural separation that enhances maintainability and allows for more flexible reward and governance mechanisms.
+
+## Purpose
+
+This pallet serves several important purposes in the partner chain ecosystem:
+
+- Tracks the processing progress of block participation data
+- Determines when historical block production data should be released
+- Helps maintain a record of validator participation in the consensus process
+- Supports reward mechanisms based on participation history
+- Enables other pallets to query if participation data is ready to be released or processed
+
+## Primitives
+
+The Block Participation pallet utilizes several primitive types and structures defined in the `toolkit/primitives/block-participation` crate.
+
+## Configuration
+
+The pallet uses the following configuration traits:
+
+```rust
+#[pallet::config]
+pub trait Config: frame_system::Config {
+    /// The overarching event type.
+    type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
+
+    /// The slot type
+    type Slot: Member + Parameter + AtLeast32BitUnsigned + Default + Copy + TypeInfo;
+
+    /// The slack window, in number of slots, that determines how long to wait before releasing block
+    /// production data.
+    #[pallet::constant]
+    type SlackWindow: Get<u32>;
+}
+```
+
+## Storage
+
+The pallet maintains one main storage item:
+
+- `ProcessedUpToSlot`: Records the slot up to which participation data has been processed
+
+## API Specification
+
+### Extrinsics
+
+- **note_processing**: Records that block participation data has been processed up to a specific slot
+
+### Public Functions (API)
+
+- **should_release_data**: Returns the slot up to which block production data should be released, or None
+
+### Inherent Data
+
+#### Inherent Identifier
+```rust
+pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"partcptn";
+```
+
+#### Data Type
+`Slot` - A specific slot boundary up to which block participation data should be processed
+
+#### Inherent Required
+Yes, when participation data needs to be processed. The runtime verifies this inherent data by checking:
+- If a previous inherent was already processed in the same block
+- Whether the slot value is greater than the last processed slot
+
+### Events
+
+- `Processed(T::Slot)`: Emitted when block participation data has been processed up to a specific slot
+
+### Errors
+
+- `ProcessingInvalidPreviousSlot`: The processing operation would move the processed slot boundary backwards, which is not allowed
+- `AlreadyProcessedInBlock`: Block participation data has already been processed in the current block
+
+## Usage
+
+This pallet works in conjunction with other pallets that track block production and validator participation. To use it:
+
+1. At regular intervals (typically determined by epoch boundaries), submit the `note_processing` extrinsic to record that participation data has been processed up to a specific slot.
+
+2. Other pallets can call `should_release_data` to determine if historical participation data can be released for a given slot, based on the slack window configuration.
+
+## Integration with Block Production Log
+
+This pallet is typically used in conjunction with the Block Production Log pallet, which records the actual block production data. Together, they provide a complete system for:
+
+1. Recording which validators produced blocks in which slots
+2. Tracking when this data has been processed (e.g., for rewards calculation)
+3. Determining when historical data can be safely released to reclaim storage
+
+## Configuration Examples
+
+A typical configuration might use a slack window of 100 slots:
+
+```rust
+parameter_types! {
+    pub const ParticipationSlackWindow: u32 = 100;
+}
+
+impl pallet_block_participation::Config for Runtime {
+    type RuntimeEvent = RuntimeEvent;
+    type Slot = u64;
+    type SlackWindow = ParticipationSlackWindow;
+}
+```
+
+## Dependencies
+
+- frame_system
+- frame_support
+- sp_block_participation (for inherent data handling)

toolkit/pallets/block-production-log/README.md

@@ -0,0 +1,140 @@
+# Block Production Log Pallet
+
+## Overview
+
+The Block Production Log pallet records and maintains the historical data of which validators have produced blocks at specific slots throughout the blockchain's lifetime. This chronological record serves as the source of truth for validator participation in the network's consensus process.
+
+Unlike many other pallets that focus on state management, the Block Production Log specializes in historical record-keeping - capturing the essential relationship between time (slots) and validator activity. This historical data forms the empirical basis for several critical network functions:
+
+1. **Validator Performance Assessment**: By maintaining an accurate log of which validators successfully produced blocks when scheduled, the system can evaluate the reliability and performance of validators over time. This assessment is crucial for governance decisions regarding validator selection and rewards.
+
+2. **Reward Distribution Fairness**: Rewards in proof-of-stake networks are typically distributed based on validator participation. The block production log provides the verifiable data needed to ensure rewards are distributed fairly according to actual contributions.
+
+3. **Network Liveness Analysis**: The record of block production over time enables analysis of network liveness and the effectiveness of the validator set in maintaining consistent block production.
+
+4. **Consensus Mechanism Verification**: The block production log provides evidence that the consensus mechanism is functioning as expected, with validators producing blocks according to the protocol rules.
+
+5. **Delegator Information**: For delegated proof-of-stake systems, the log informs delegators about validator performance, helping them make informed decisions about delegation.
+
+The pallet implements an efficient storage strategy by supporting three key operations:
+- Appending new block production records
+- Retrieving historical records up to a specified slot
+- Removing (pruning) historical records that are no longer needed
+
+This approach balances the need for historical record-keeping with efficient storage management. By allowing controlled pruning of old data once it has been processed (typically for reward calculations), the pallet prevents unbounded state growth while ensuring all necessary historical data is available when needed.
+
+The Block Production Log pallet works seamlessly with the Block Participation pallet, which determines when historical data has been fully processed and can safely be pruned from storage.
+
+## Purpose
+
+This pallet serves several important purposes in the partner chain ecosystem:
+
+- Maintains a chronological record of block production by validators
+- Provides historical data for reward calculations
+- Supports analysis of validator performance over time
+- Enables efficient pruning of historical data to manage state growth
+- Forms the foundation for fair reward distribution based on participation
+
+## Primitives
+
+The Block Production Log pallet relies on primitives defined in the `toolkit/primitives/block-production-log` crate.
+
+## Configuration
+
+The pallet uses the following configuration traits:
+
+```rust
+#[pallet::config]
+pub trait Config: frame_system::Config {
+    /// The overarching event type.
+    type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
+
+    /// Type representing a block producer ID, which is recorded in the block production log.
+    type BlockProducerId: Parameter + Member + Copy + MaybeSerializeDeserialize + Debug + MaxEncodedLen
+        + TypeInfo + Ord;
+
+    /// Type representing a block slot.
+    type Slot: Parameter + Member + Copy + AtLeast32BitUnsigned + MaybeSerializeDeserialize
+        + Default + Debug + TypeInfo + Ord;
+}
+```
+
+## Storage
+
+The pallet maintains several storage items:
+
+1. `BlockProductionLogEntries`: A map of slots to block producers who created blocks at those slots
+2. `BlockProductionLogBoundary`: Optional slot boundary marking the earliest slot in the log
+
+## API Specification
+
+### Extrinsics
+
+- **append**: Appends the block producer to the production log
+
+### Public Functions (API)
+
+- **take_prefix**: Returns and removes block production data up to the given slot
+- **peek_prefix**: Returns an iterator of block production data up to the given slot without removing it
+- **drop_prefix**: Removes block production data up to the given slot
+
+### Inherent Data
+
+#### Inherent Identifier
+```rust
+pub const INHERENT_IDENTIFIER: InherentIdentifier = *b"blprdlog";
+```
+
+#### Data Type
+`T::BlockProducerId` - The ID of the block producer who created the current block
+
+#### Inherent Required
+Yes, when a block is produced. The pallet verifies this inherent data to ensure blocks include information about who produced them.
+
+### Events
+
+- `Appended(T::BlockProducerId, T::Slot)`: Emitted when a block producer is appended to the log for a specific slot
+- `Dropped(T::Slot)`: Emitted when production data is dropped up to a specific slot
+
+### Errors
+
+- `NoBlocksToTake`: Attempted to take blocks but no blocks were available in the specified range
+- `InvalidSlotBoundary`: Attempted to set an invalid slot boundary in the block production log
+
+## Usage
+
+The Block Production Log pallet is typically used in conjunction with the consensus mechanism and block participation tracking. The typical usage flow is:
+
+1. For each block, the `append` function is called (usually via inherent data) to record which validator produced the block at the current slot.
+
+2. Periodically, other pallets (such as a rewards pallet) can call `peek_prefix` to examine historical block production data without removing it.
+
+3. After historical data has been fully processed (typically determined by the Block Participation pallet), the `drop_prefix` function can be called to prune old data and manage storage growth.
+
+4. The `take_prefix` function combines retrieval and pruning in a single operation for cases where data will be processed immediately and then no longer needed.
+
+## Integration with Block Participation
+
+This pallet is designed to work closely with the Block Participation pallet:
+
+1. The Block Production Log pallet maintains the raw history of block production.
+2. The Block Participation pallet tracks when this history has been processed (e.g., for rewards).
+3. Once processed, the Block Participation pallet signals that historical data can be pruned via the `drop_prefix` function.
+
+This separation of concerns creates a clean architecture that separates record-keeping from record processing.
+
+## Configuration Example
+
+```rust
+impl pallet_block_production_log::Config for Runtime {
+    type RuntimeEvent = RuntimeEvent;
+    type BlockProducerId = AccountId;
+    type Slot = u64;
+}
+```
+
+## Dependencies
+
+- frame_system
+- frame_support
+- sp_block_production_log (for inherent data handling)