plamentsv/share-allocation-fairness

Skill: Share Allocation Fairness (Sui)

Trigger Pattern: SHARE_ALLOCATION flag detected in pattern scan Inject Into: Breadth agents, depth-edge-case Finding prefix: [SAF-N] Rules referenced: R5, R10, R13, R14

shares|allocation|distribute|pro.rata|proportional|vest|reward.*per.*share|
balance::join|balance::split|coin::mint|reward_index|cumulative|epoch.*reward

Purpose

Analyze fairness of share/token allocation mechanisms on Sui where users receive Coin<T> shares or Balance<T> proportional to deposits, contributions, or participation -- checking for late-entry advantages, PTB-based timing exploitation, queue-position gaming, and time-weighting omissions.

Sui-specific share representations:

• Coin<ShareToken>: Fungible, freely transferable (has key + store). User holds as owned object.
• Balance<ShareToken> inside a position object: Non-transferable accounting. Locked within the protocol's object model.
• u64 field in a shared/owned struct: Simple numerical tracking, no token representation.
• Check which representation is used -- it affects transferability, composability, and gaming vectors.

---

Methodology

STEP 1: Classify Allocation Mechanism

Identify which pattern the protocol uses:

| Type | Sui Pattern | Key Risk | |------|------------|----------| | Pro-rata snapshot | Shares minted at fixed ratio via balance::split/coin::mint_balance at deposit time | Late depositors dilute early depositors' accrued value | | Time-weighted | Per-user owned object tracks reward_per_share_paid and accrued_rewards with clock::timestamp_ms() | Checkpoint manipulation, discrete vs continuous accrual | | Queue-based | Table/VecMap in shared object stores pending deposits | Queue position gaming, PTB-based front-running | | Epoch-based | Shares valued per Sui epoch boundary via tx_context::epoch() | Cross-epoch timing arbitrage at epoch transition |

STEP 2: Late Entry Attack Model

For each allocation entry function:

1. Identify accrual source: What generates value for existing share holders? (yield from external DeFi, fees collected in shared pool, token emissions via TreasuryCap)
2. Trace timing: When does accrued value become claimable vs when can new shares enter? Is there a separate crank/update function?
3. Check for time-weighting: Does allocation account for HOW LONG shares were held, or only THAT shares are held at checkpoint time?
4. Model attack: Can a depositor enter AFTER value accrues but BEFORE distribution, capturing value they did not earn?

| Entry Function | Accrual Source | Time-Weighted? | Late Entry Possible? | Impact | |---------------|----------------|----------------|---------------------|--------|

Sui timing model:

• clock::timestamp_ms() provides millisecond-precision timestamps (read from the Clock shared object)
• Timestamps advance per checkpoint (~0.5-2s), NOT per transaction
• Multiple transactions within the same checkpoint see the SAME timestamp
• Implication: time-weighted calculations based on clock::timestamp_ms() have ~0.5-2s granularity. An attacker can deposit and withdraw within the same checkpoint and see zero time elapsed, potentially capturing rewards with zero time commitment.

PTB-specific timing: With PTB composability, an attacker can compose multiple function calls in a single atomic transaction: [deposit] -> [trigger_distribution] -> [withdraw] within one PTB. This is more powerful than EVM flash loans for timing attacks because PTBs execute atomically with no inter-step cost.

STEP 2c: Cross-Address Deposit Model

For each entry function accepting a recipient address parameter:

| Entry Function | Accepts Recipient? | Default State for New Recipient | Exploitable? | Impact | |---------------|-------------------|-------------------------------|-------------|--------|

Check: When a new position object or dynamic field is created for a recipient:

• What is the DEFAULT state? (reward_per_share_paid = 0? last_deposit_epoch = 0?)
• If reward_per_share_paid starts at 0 while the global index is at N, the new position holder captures ALL historical rewards on their deposit -- FINDING
• Can deposit(recipient, coin) where recipient != sender create a position that captures historical rewards the recipient did not earn?
• On Sui, this may manifest as a new owned object created for the recipient (clean state -- typically safe) or a new dynamic field added to a shared object keyed by address (check default values).

STEP 2d: Pre-Setter Timing Model

For each admin-settable reward/rate parameter:

| Parameter Setter | Cap Required | Staked-Before-Set? | Retroactive Rewards? | Fair? | |-----------------|-------------|-------------------|---------------------|-------|

Model: user deposits (position created with current index) -> admin sets reward rate -> rewards accrue.

• Does the user receive retroactive rewards for the period BEFORE the rate was set?
• Is the global reward index updated atomically with the rate change in the same function call?

2e. Pre-Configuration State Analysis

For the allocation mechanism identified in Step 1:

| Configuration Step | Parameter Set | Functions Available Before Set | Exploitable Default? | |--------------------|-------------|-------------------------------|---------------------|

1. What is the deployment/initialization sequence? In Sui, init runs once at package publish. What configuration happens in init vs subsequent admin transactions?
2. For each step: what functions are callable BEFORE this configuration completes?
3. Are there reward/share calculations that use unconfigured (zero/default) values in shared objects?
4. Can a user deposit/stake before full configuration and receive outsized rewards/shares?
5. Is there a version flag or is_initialized check that gates user interactions?

Sui-specific: init() runs atomically at publish. If configuration requires MULTIPLE transactions (init -> configure_pool -> set_rates), there are windows between these transactions where the protocol is partially configured.

If users can interact during partial configuration AND default values create unfair advantage -> FINDING (minimum Medium, Rule 13: design gap).

STEP 3: Queue Position and Batch Processing

For protocols with batch/queue processing:

1. Ordering fairness: Is queue order FIFO (Table insertion order), arbitrary (admin-chosen), or manipulable (PTB composition order)?
2. Partial processing: Can admin process some deposits but not others within a batch? Does the batch function iterate with a limit?
3. Cross-batch state: Does processing order within a batch affect allocation ratios?
4. Deposit splitting: Can a user split one large Coin<T> into many small deposits (via coin::split in a PTB) for queue advantage or per-deposit limit bypass?

Sui-specific ordering:

• Transactions touching only owned objects are processed without consensus (fast path) -- no ordering manipulation
• Transactions touching shared objects go through consensus -- validator-influenced ordering within checkpoint
• PTB atomicity: all commands execute atomically, batch processing within a single PTB is all-or-nothing
• An attacker can use PTB to atomically: read queue state -> deposit at favorable position -> trigger processing -> claim

STEP 4: Share Redemption Symmetry

Check that entry and exit use consistent valuation:

1. Mint vs burn ratio: Are shares minted at the same exchange rate they can be burned? (check share price calculation in both deposit and withdraw)
2. Pending claims: Can unclaimed reward Balance<T> dilute active shares' value? (rewards already owed but counted in TVL)
3. Withdrawal queue: Does withdrawal ordering create unfair priority?

Sui-specific redemption:

• If shares are Coin<ShareToken>, user burns them via protocol function. Check: can user transfer shares to another address and redeem there to bypass cooldowns?
• If shares are Balance<ShareToken> inside position object, redemption requires the position object. Check: can position object be transferred (has store?) to bypass restrictions?
• First-depositor / last-withdrawer edge cases: what happens when total_supply == 0 and someone deposits? (division by zero in share calculation?)

TreasuryCap authority risks:

• Can TreasuryCap be used outside of deposit logic to inflate share supply?
• Is TreasuryCap stored in a shared object with access control? If store allows extraction from the wrapper -> unauthorized minting.
• If freeze authority pattern exists (rare on Sui): who controls it?

STEP 4b: Aggregate Constraint Coherence (Rule 14)

For independently-settable allocation rates/shares (e.g., per-pool weights, fee splits, distribution percentages):

| Rate/Weight Setter | Aggregate Constraint | Enforced On-Chain? | What if Sum Exceeds/Falls Short? | |-------------------|---------------------|-------------------|--------------------------------|

Sui-specific: If weights are stored as dynamic fields on a shared object (one field per pool), the setter function may not iterate all fields to validate the sum. Check: does the setter read all weight dynamic fields and validate the total?

If aggregate constraint NOT enforced and rates independently settable -> FINDING (Rule 14).

---

Output

For each finding, specify:

• Allocation mechanism type (pro-rata, time-weighted, queue, epoch)
• Whether time-weighting is present or missing
• Concrete attack sequence with numerical example (SUI/token amounts)
• Who benefits and who is harmed
• Whether the attack requires PTB composition or is achievable with single function calls
• Sui-specific timing factors (clock::timestamp_ms() granularity, checkpoint ordering)

Finding Template

**ID**: [SAF-N]
**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: (see checklist below)
**Rules Applied**: [R5:___, R10:___, R13:___, R14:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: sources/{module}.move:LineN
**Title**: {fairness violation type}
**Description**: {specific issue with numerical example}
**Impact**: {quantified at worst-state parameters -- who loses how much}

---

Step Execution Checklist (MANDATORY)

| Step | Required | Completed? | Notes | |------|----------|------------|-------| | 1. Classify Allocation Mechanism | YES | | | | 2. Late Entry Attack Model | YES | | PTB composition timing check | | 2c. Cross-Address Deposit Model | YES | | Check recipient != sender patterns | | 2d. Pre-Setter Timing Model | YES | | Model deposit-before-rate-set sequence | | 2e. Pre-Configuration State Analysis | YES | | Post-init() window + unconfigured defaults | | 3. Queue Position and Batch Processing | IF queue/batch detected | | Include PTB deposit splitting | | 4. Share Redemption Symmetry | YES | | Include TreasuryCap access check | | 4b. Aggregate Constraint Coherence | IF multiple settable weights | | Rule 14 enforcement check |

If any step skipped, document valid reason (N/A, no queue, single pool, no settable weights).