/share-allocation-fairness

name: "share-allocation-fairness"
description: "Trigger SHARE_ALLOCATION flag detected in pattern scan - Used by Breadth agents, depth-edge-case"

Skill: SHARE_ALLOCATION_FAIRNESS

> **Trigger**: SHARE_ALLOCATION flag detected in pattern scan > **Used by**: Breadth agents, depth-edge-case

Purpose

Analyze fairness of share/token allocation mechanisms where users receive shares proportional to deposits, contributions, or participation -- checking for late-entry advantages, queue-position gaming, and time-weighting omissions. Adapted for Aptos Move FungibleAsset-based accounting and resource model.

Methodology

STEP 1: Classify Allocation Mechanism

Identify which pattern the protocol uses:

| Type | Pattern | Key Risk | |------|---------|----------| | Pro-rata snapshot | Shares minted at fixed ratio at deposit time | Late depositors dilute early depositors accrued value | | Time-weighted | Shares accrue value based on duration held | Checkpoint manipulation, discrete vs continuous accrual | | Queue-based | Deposits processed in batch/queue order | Queue position gaming, front-running batch processing | | Epoch-based | Shares valued per epoch/period boundary | Cross-epoch timing arbitrage |

**Aptos-specific**: Identify whether shares are represented as:

• `FungibleAsset` with custom metadata (standard FA shares)
• `Coin<ShareType>` (legacy coin shares)
• Custom resource with balance field (non-standard)
• `Object<T>` with proportional ownership (object-based shares)

STEP 2: Late Entry Attack Model

For each allocation entry point:

1. **Identify accrual source**: What generates value for existing share holders? (yield, fees, rewards, appreciation) 2. **Trace timing**: When does accrued value become claimable vs when can new shares enter? 3. **Check for time-weighting**: Does allocation account for HOW LONG shares were held, or only THAT shares are held? 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 | |---------------|----------------|----------------|---------------------|--------|

**Aptos timing specifics**: Aptos block time is ~1 second. `timestamp::now_seconds()` granularity allows sub-epoch manipulation if epoch boundaries are timestamp-based. Check if the protocol uses `reconfiguration::last_reconfiguration_time()` or custom epoch tracking.

STEP 2c: Cross-Address Deposit Model

For each entry function accepting a beneficiary address or object parameter:

Check: what is the DEFAULT state for a never-before-seen beneficiary? Can depositing for a new address where that address has zero-initialized accounting unlock historical rewards, bypass cooldowns, or inherit accrued value?

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

**Aptos-specific**: When a new `FungibleStore` is created for an address via `primary_fungible_store::ensure_primary_store_exists`, is the associated accounting state also initialized? Or does the share accounting resource exist independently from the token store?

If beneficiary != caller enables reward capture the recipient did not earn -> FINDING (late-entry variant).

STEP 2d: Pre-Setter Timing Model

For each admin-settable reward/rate parameter: model the sequence user_deposits -> admin_sets_rate -> rewards_accrue. Does the user receive retroactive rewards for the period BEFORE the rate was set? Does a depositor after rate-setting receive the same, more, or less?

| Parameter Setter | Deposited-Before-Set? | Retroactive Rewards? | Fair? | |-----------------|----------------------|---------------------|-------|

If depositing before rate-setting yields unearned rewards or causes reward loss for post-set depositors -> FINDING (timing fairness).

STEP 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 module initialization sequence? List all `init_module` and manual configuration steps in order. 2. For each step: what functions are callable BEFORE this configuration completes? 3. Are there reward/share calculations that use unconfigured (zero/default) values? 4. Can a user deposit/stake before full configuration and receive outsized rewards/shares? 5. Is there a pause mechanism or `is_initialized` guard that prevents interaction before configuration completes?

**Aptos-specific**: `init_module` runs automatically on module publish. But additional configuration (setting rates, adding pools, registering tokens) often requires separate transactions. The window between `init_module` and full configuration is the attack surface.

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, arbitrary (admin-chosen), or manipulable? 2. **Partial processing**: Can operator process some deposits but not others within a batch? 3. **Cross-batch state**: Does processing order within a batch affect allocation ratios? 4. **Deposit splitting**: Can a user split one large deposit into many small ones for queue advantage?

**Aptos-specific**: Aptos transaction ordering within a block is determined by the validator. If batch processing reads from a `Table` or `SmartTable`, iteration order may not be deterministic or FIFO. Check if the protocol uses `SmartVector` with explicit ordering or `Table` with unordered access.

STEP 4: Share Redemption Symmetry

Check that entry and exit use c