@ysv reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: all files reviewed, 5 unresolved discussions (waiting on @masihyeganeh and @miladz68)

x/pse/spec/README.md line 13 at r1 (raw file):

## Clearing Accounts

The PSE module manages six clearing account modules, each serving a specific purpose in the token distribution ecosystem:

six module clearing accounts

Code quote:

six clearing account modules

x/pse/spec/README.md line 29 at r1 (raw file):

- **Total Duration**: 84 months from the start date (December 1, 2025, 00:00:00 UTC)
- **Distribution Frequency**: Monthly distributions on the 1st of each month

start date & distribution date of month is not defined/finalized yet, right ?

Because it depends on upgrade date

Code quote:

- **Total Duration**: 84 months from the start date (December 1, 2025, 00:00:00 UTC)
- **Distribution Frequency**: Monthly distributions on the 1st of each month

x/pse/spec/README.md line 52 at r1 (raw file):

- `Time_Staked` is the duration in seconds that the tokens have been staked

The score accumulates over time and is tracked separately for each delegation to each validator. When delegations are modified (increased, decreased, or removed), the module:

over 1 month period.
Because it resets after each distribution

Code quote:

score accumulates over time

x/pse/spec/README.md line 416 at r1 (raw file):

- **Mainnet** (`core-1`): `core17pmq7hp4upvmmveqexzuhzu64v36re3w3447n7dt46uwp594wtps97qlm5`
- **Testnet** (`core-testnet-1`): `testcore1dm4x48jqunpdh9h8sud30cwmtsghfuqascgqam`
- **Devnet** (`core-dev-1`): `devcore17we2jgjyxexcz8rg29dn622axt7s9l263fl0zt`

I don't think this should be mentioned. also all these addresses will be replaced

Code quote:

### 4. Clearing Account Mapping Initialization

Sets up default recipient mappings for non-Community clearing accounts. The recipient addresses are chain-specific:

- **Mainnet** (`core-1`): `core17pmq7hp4upvmmveqexzuhzu64v36re3w3447n7dt46uwp594wtps97qlm5`
- **Testnet** (`core-testnet-1`): `testcore1dm4x48jqunpdh9h8sud30cwmtsghfuqascgqam`
- **Devnet** (`core-dev-1`): `devcore17we2jgjyxexcz8rg29dn622axt7s9l263fl0zt`

x/pse/spec/README.md line 550 at r1 (raw file):

- If a smart contract is set as a recipient, ensure it can receive and handle tokens
- Smart contracts in excluded addresses will not accumulate Community scores
- Auto-delegation of Community rewards may fail if the recipient is a contract without delegation capability

I guess this README is mostly generated by AI (which is ok).
A few general comments from me:

• IMO readme has too many implementation details
• some parts are repeated multiple times
• in general size of this readme could be reduced significantly by keeping only important/relevant details

E.g this is repeated twice:

- Community: 40 billion tokens (40%)
- Foundation: 30 billion tokens (30%)
- Alliance: 20 billion tokens (20%)
- Partnership: 3 billion tokens (3%)
- Investors: 5 billion tokens (5%)
- Team: 2 billion tokens (2%)

Reviewable status: 0 of 1 files reviewed, 5 unresolved discussions (waiting on @masihyeganeh, @miladz68, and @ysv)

x/pse/spec/README.md line 13 at r1 (raw file):

Done

x/pse/spec/README.md line 29 at r1 (raw file):

Yes, with the change in other PR related to timing, it would be the upgrade date. changed accordingly.

x/pse/spec/README.md line 52 at r1 (raw file):

Done

x/pse/spec/README.md line 416 at r1 (raw file):

Rephrased and cleaned

x/pse/spec/README.md line 550 at r1 (raw file):

Yeah, The technical part is done by AI, i tried to have similar details as the rest of the readme files. do you still need think i need to make it smaller?
mainly technical parts i mean.

@ysv reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @masihyeganeh and @miladz68)

@miladz68 reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 14 unresolved discussions (waiting on @masihyeganeh)

x/pse/spec/README.md line 5 at r2 (raw file):

## Abstract

This document specifies the `pse` module (Proof of Stake Extension). The module is responsible for managing scheduled token distributions from clearing accounts to designated recipients based on a predefined allocation schedule. The Community clearing account uses a special score-based distribution mechanism that rewards stakers proportionally to their staking duration and amount. This module was introduced in the v6 upgrade of TX Blockchain.

(Proof of Support Emission)

Code quote:

(Proof of Stake Extension)

x/pse/spec/README.md line 154 at r2 (raw file):

- A Community distribution is processed (reset to zero for the next month)

### AllocationSchedule

we are no longer using this name. use ScheduledDistribution

Code quote:

AllocationSchedule

x/pse/spec/README.md line 174 at r2 (raw file):

The PSE module provides a keeper with methods for:

### Distribution Processing

this is just copied code and seems redundant.

x/pse/spec/README.md line 185 at r2 (raw file):

Score Management

this is just copied code and seems redundant.

x/pse/spec/README.md line 199 at r2 (raw file):

Schedule Management

this is just copied code and seems redundant.

x/pse/spec/README.md line 212 at r2 (raw file):

Parameter Management

this is just copied code and seems redundant.

x/pse/spec/README.md line 225 at r2 (raw file):

Query Helpers

this is just copied code and seems redundant.

x/pse/spec/README.md line 418 at r2 (raw file):

This ensures that stakers who delegated before the upgrade are not disadvantaged and start accumulating scores immediately.

## Parameters

did we not discuss it previously ? can we merge the 2 sections ?

x/pse/spec/README.md line 451 at r2 (raw file):

- No duplicate clearing accounts across mappings

## Integration with Other Modules

seems redundant to me @ysv What do you think ?

x/pse/spec/README.md line 495 at r2 (raw file):

- The module processes distributions in chronological order based on timestamp

### Token Economics

did we not already discuss it ? merge the 2 sections or remove one if it is a duplicate.

x/pse/spec/README.md line 530 at r2 (raw file):

### Score Manipulation Prevention

- Scores are calculated automatically by the protocol, not user-submitted

seems redundant and obvious.

x/pse/spec/README.md line 531 at r2 (raw file):

- Scores are calculated automatically by the protocol, not user-submitted
- Delegation changes trigger immediate score updates

repeated.

x/pse/spec/README.md line 532 at r2 (raw file):

- Scores are calculated automatically by the protocol, not user-submitted
- Delegation changes trigger immediate score updates
- Excluded addresses list prevents gaming through exchange deposits

this is not ture strictly speaking.

x/pse/spec/README.md line 533 at r2 (raw file):

- Delegation changes trigger immediate score updates
- Excluded addresses list prevents gaming through exchange deposits
- Score reset after each distribution prevents accumulation gaming

again not true.

Reviewable status: all files reviewed, 14 unresolved discussions (waiting on @masihyeganeh and @miladz68)

x/pse/spec/README.md line 5 at r2 (raw file):

Done

x/pse/spec/README.md line 154 at r2 (raw file):

The name is AllocationSchedule in the code, do we have a plan to remove them? this section is state, and we have many usage of AllocationSchedule in the code.

x/pse/spec/README.md line 174 at r2 (raw file):

Replaced with a brief

x/pse/spec/README.md line 185 at r2 (raw file):

Replaced with a brief

x/pse/spec/README.md line 199 at r2 (raw file):

Replaced with a brief

x/pse/spec/README.md line 212 at r2 (raw file):

Replaced with a brief

x/pse/spec/README.md line 225 at r2 (raw file):

Replaced with a brief

x/pse/spec/README.md line 418 at r2 (raw file):

I don't remember, merging Parameters with which section?

x/pse/spec/README.md line 495 at r2 (raw file):

Do you mean merging this to params?

x/pse/spec/README.md line 530 at r2 (raw file):

Done

x/pse/spec/README.md line 531 at r2 (raw file):

Done

x/pse/spec/README.md line 532 at r2 (raw file):

Done

x/pse/spec/README.md line 533 at r2 (raw file):

Done

@miladz68 reviewed 1 of 1 files at r3, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @masihyeganeh)

x/pse/spec/README.md line 154 at r2 (raw file):

marked as resolved.

@ysv reviewed 1 of 1 files at r3, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @masihyeganeh)