# JackpotLPManager

Manages liquidity provider (LP) deposits, withdrawals, and share accounting. LP funds back the prize pool and earn edge from ticket sales.

## State Variables

| Variable             | Type                                 | Description                            |
| -------------------- | ------------------------------------ | -------------------------------------- |
| `jackpot`            | `address`                            | Reference to the main Jackpot contract |
| `lpPoolCap`          | `uint256`                            | Maximum allowed LP pool size           |
| `lpDrawingState`     | `mapping(uint256 => LPDrawingState)` | LP pool state per drawing              |
| `lpInfo`             | `mapping(address => LP)`             | LP position data per address           |
| `drawingAccumulator` | `mapping(uint256 => uint256)`        | Share price accumulator per drawing    |

## Structs

### LP

```solidity
struct LP {
    uint256 consolidatedShares;    // Active LP shares (1e18 scale)
    DepositInfo lastDeposit;       // Most recent deposit details
    WithdrawalInfo pendingWithdrawal; // Active withdrawal request
    uint256 claimableWithdrawals;  // USDC ready to claim
}
```

### DepositInfo

```solidity
struct DepositInfo {
    uint256 amount;      // USDC amount deposited
    uint256 drawingId;   // Drawing when deposit was made
}
```

### WithdrawalInfo

```solidity
struct WithdrawalInfo {
    uint256 amountInShares;  // Shares pending withdrawal (1e18 scale)
    uint256 drawingId;       // Drawing when withdrawal was initiated
}
```

### LPDrawingState

```solidity
struct LPDrawingState {
    uint256 lpPoolTotal;        // Total LP pool value for drawing
    uint256 pendingDeposits;    // Deposits waiting to become active
    uint256 pendingWithdrawals; // Shares waiting to be withdrawn
}
```

### LPValueBreakdown

```solidity
struct LPValueBreakdown {
    uint256 activeDeposits;       // USDC value of active shares
    uint256 pendingDeposits;      // USDC waiting to become active
    uint256 pendingWithdrawals;   // USDC value of pending withdrawals
    uint256 claimableWithdrawals; // USDC ready to claim
}
```

## Events

### LPDeposit

```solidity
event LPDeposit(address indexed lpAddress, uint256 amount, uint256 drawingId);
```

### LPWithdrawalInitiated

```solidity
event LPWithdrawalInitiated(address indexed lpAddress, uint256 amountInShares, uint256 drawingId);
```

### LPWithdrawalFinalized

```solidity
event LPWithdrawalFinalized(address indexed lpAddress, uint256 amount, uint256 drawingId);
```

## Functions

### getLpInfo

Get complete LP position information for an address.

```solidity
function getLpInfo(address _lpAddress) external view returns (LP memory)
```

**Parameters:**

| Name         | Type      | Description                      |
| ------------ | --------- | -------------------------------- |
| `_lpAddress` | `address` | Address to query LP position for |

**Returns:**

| Type | Description                                                      |
| ---- | ---------------------------------------------------------------- |
| `LP` | Complete LP position including shares, deposits, and withdrawals |

**Example:**

```solidity
IJackpotLPManager.LP memory lpPosition = lpManager.getLpInfo(msg.sender);

uint256 activeShares = lpPosition.consolidatedShares;
uint256 pendingWithdrawShares = lpPosition.pendingWithdrawal.amountInShares;
uint256 claimable = lpPosition.claimableWithdrawals;
```

***

### getLPValueBreakdown

Get the USDC value breakdown of an LP's position.

```solidity
function getLPValueBreakdown(uint256 _drawingId, address _lpAddress) external view returns (LPValueBreakdown memory)
```

**Parameters:**

| Name         | Type      | Description                        |
| ------------ | --------- | ---------------------------------- |
| `_drawingId` | `uint256` | Drawing ID to calculate values for |
| `_lpAddress` | `address` | Address to query                   |

**Returns:**

| Type               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `LPValueBreakdown` | USDC values for active, pending deposits/withdrawals, and claimable |

**Example:**

```solidity
uint256 currentDrawing = jackpot.currentDrawingId();
IJackpotLPManager.LPValueBreakdown memory value =
    lpManager.getLPValueBreakdown(currentDrawing, msg.sender);

uint256 totalValue = value.activeDeposits +
                     value.pendingDeposits +
                     value.pendingWithdrawals +
                     value.claimableWithdrawals;
```

***

### getLPDrawingState

Get LP pool state for a specific drawing.

```solidity
function getLPDrawingState(uint256 _drawingId) external view returns (LPDrawingState memory)
```

**Parameters:**

| Name         | Type      | Description         |
| ------------ | --------- | ------------------- |
| `_drawingId` | `uint256` | Drawing ID to query |

**Returns:**

| Type             | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `LPDrawingState` | Pool totals, pending deposits, and pending withdrawals |

**Example:**

```solidity
uint256 currentDrawing = jackpot.currentDrawingId();
IJackpotLPManager.LPDrawingState memory state =
    lpManager.getLPDrawingState(currentDrawing);

uint256 totalPoolValue = state.lpPoolTotal;
```

***

### getDrawingAccumulator

Get the share price accumulator for a drawing.

```solidity
function getDrawingAccumulator(uint256 _drawingId) external view returns (uint256)
```

**Parameters:**

| Name         | Type      | Description         |
| ------------ | --------- | ------------------- |
| `_drawingId` | `uint256` | Drawing ID to query |

**Returns:**

| Type      | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `uint256` | Accumulator value (1e18 scale) used for share price calculations |

**Example:**

```solidity
uint256 accumulator = lpManager.getDrawingAccumulator(currentDrawing);
// Accumulator represents cumulative share price changes
// Higher accumulator = LPs have earned profits
```

## LP Share Economics

### How Shares Work

1. **Initial Deposit**: When you deposit USDC, you receive shares based on the current accumulator
2. **Share Value**: Share value increases when LPs earn edge from ticket sales
3. **Withdrawals**: Shares are converted back to USDC at the current accumulator rate

### Timing

* **Deposits**: Become active at the start of the next drawing
* **Withdrawals**: Must be initiated, then finalized after the drawing completes
* **Edge**: Earned proportionally to share holdings

### Example Flow

```solidity
// 1. Check current LP status
IJackpotLPManager.LP memory myPosition = lpManager.getLpInfo(msg.sender);

// 2. Check USDC value
IJackpotLPManager.LPValueBreakdown memory value =
    lpManager.getLPValueBreakdown(jackpot.currentDrawingId(), msg.sender);

// 3. Deposit more USDC (via Jackpot contract)
usdc.approve(address(jackpot), depositAmount);
jackpot.lpDeposit(depositAmount);

// 4. Initiate withdrawal (via Jackpot contract)
jackpot.initiateWithdraw(myPosition.consolidatedShares / 2);

// 5. After drawing completes, finalize
jackpot.finalizeWithdraw();
```