# Detailed explanation of the shareholder system

## Overview

MemeDice’s shareholder system adopts **Vault-style global accumulator mode**This is a proven DeFi design pattern that can **with O(1) gas cost** handle deposit and withdrawal operations, regardless of the number of shareholders.

***

## Core mechanism

### Shares vs Tokens

The core of the shareholder system is to separate **the number of tokens** from **the number of shares** :

* **Tokens**: the actual amount of Token tokens in the pool, which changes with game profits and losses
* **Shares**: represents the shareholder’s proportion in the pool and does not change after deposit due to game profits or losses

```
Your actual value = total pool tokens × (your shares / total shares)
```

### Deposit: Tokens → Shares

When you deposit tokens, the system calculates the number of shares you receive based on the current **token/share ratio** to calculate the number of shares you receive:

```
Shares received = number of tokens deposited × (current total shares / current total pool tokens)
```

**Special case**: if the pool is empty (the first deposit), then `shares = number of tokens`(1:1 ratio).

#### Example

| Scenario             | Pool tokens | Total shares | Deposit tokens | Shares received |
| -------------------- | ----------- | ------------ | -------------- | --------------- |
| First deposit        | 0           | 0            | 1,000          | 1,000           |
| After pool growth    | 2,000       | 1,000        | 1,000          | 500             |
| After pool shrinkage | 500         | 1,000        | 1,000          | 2,000           |

### Withdrawal: Shares → Tokens

When withdrawing, the system converts your **entire shares** back into tokens:

```
Tokens withdrawn = total pool tokens × (your shares / total shares) - fee
```

> ⚠️ **Note**: withdrawals are only available as a full withdrawal; partial withdrawals are not supported. After withdrawal, your shares are reset to zero.

***

## Profit and loss propagation mechanism

### Players lose money → shareholders make money

```mermaid
sequenceDiagram
    participant P as player
    participant Pool as Pool
    participant S as shareholders

    P->>Pool: Bet 100 tokens
    Note over Pool: Random number verdict: player loses
    Pool->>Pool: Pool +100 (after fees)
    Note over S: Shares remain unchanged, but the number of tokens<br/>represented by each share increases
    S-->>S: 📈 Shares appreciate
```

### Players win money → shareholders lose money

```mermaid
sequenceDiagram
    participant P as player
    participant Pool as Pool
    participant S as shareholders

    P->>Pool: Bet 100 tokens
    Note over Pool: Random number verdict: player wins
    Pool->>P: Pay bonus
    Note over Pool: Pool decreases
    Note over S: Shares remain unchanged, but the number of tokens<br/>represented by each share decreases
    S-->>S: 📉 Shares depreciate
```

***

## Complete lifecycle example

Here is a complete example of the investment lifecycle:

### Step 1: Alice deposits 1,000 USDT

| Status       | value        |
| ------------ | ------------ |
| Pool tokens  | 1,000 USDT   |
| Total shares | 1,000        |
| Alice shares | 1,000 (100%) |
| Alice value  | 1,000 USDT   |

### Step 2: Bob deposits 1,000 USDT

| Status       | value       |
| ------------ | ----------- |
| Pool tokens  | 2,000 USDT  |
| Total shares | 2,000       |
| Alice shares | 1,000 (50%) |
| Bob shares   | 1,000 (50%) |

### Step 3: Players lost 200 USDT

| Status       | value                                   |
| ------------ | --------------------------------------- |
| Pool tokens  | 2,200 USDT                              |
| Total shares | 2,000 (unchanged)                       |
| Alice value  | 2,200 × 1,000/2,000 = **1,100 USDT** 📈 |
| Bob value    | 2,200 × 1,000/2,000 = **1,100 USDT** 📈 |

### Step 4: Charlie deposits 1,100 USDT at this point

```
Charlie receives shares = 1,100 × (2,000 / 2,200) = 1,000
```

| Status        | value                                |
| ------------- | ------------------------------------ |
| Pool tokens   | 3,300 USDT                           |
| Total shares  | 3,000                                |
| Alice value   | 3,300 × 1,000/3,000 = **1,100 USDT** |
| Bob value     | 3,300 × 1,000/3,000 = **1,100 USDT** |
| Charlie value | 3,300 × 1,000/3,000 = **1,100 USDT** |

> 💡 Note: Charlie deposits 1,100 USDT and receives 1,000 shares, because each share is worth 1.1 USDT at this time. This ensures that Charlie does not dilute the gains of Alice and Bob.

### Step 5: Players won 300 USDT

| Status        | value                                   |
| ------------- | --------------------------------------- |
| Pool tokens   | 3,000 USDT                              |
| Total shares  | 3,000 (unchanged)                       |
| Alice value   | 3,000 × 1,000/3,000 = **1,000 USDT** 📉 |
| Bob value     | **1,000 USDT** 📉                       |
| Charlie value | **1,000 USDT** 📉                       |

### Step 6: Alice withdraws

Alice withdraws all shares and receives 1,000 USDT (before fees).

| Status        | value                                |
| ------------- | ------------------------------------ |
| Pool tokens   | 2,000 USDT                           |
| Total shares  | 2,000                                |
| Bob value     | 2,000 × 1,000/2,000 = **1,000 USDT** |
| Charlie value | **1,000 USDT**                       |

***

## O(1) Gas efficiency

Traditional profit distribution methods require iterating over all shareholders to distribute returns, and gas costs grow linearly with the number of shareholders. MemeDice’s Vault mode achieves O(1) efficiency in the following way:

| Operation             | Traditional method                               | Vault mode                      |
| --------------------- | ------------------------------------------------ | ------------------------------- |
| Player bet settlement | Iterate over all shareholders to distribute O(n) | Only update the pool total O(1) |
| Deposit               | O(1)                                             | O(1)                            |
| Withdrawal            | O(1)                                             | O(1)                            |
| Query share value     | O(1)                                             | O(1)                            |

**Key insight**: At game settlement time, there is no need to update any shareholder data; only the total pool amount needs to be updated. Each shareholder’s actual value is calculated dynamically when queried.

***

## Pool limits

Game creators can set the following limits to control the pool:

| Parameter         | Description                      | Default value      |
| ----------------- | -------------------------------- | ------------------ |
| `minDeposit`      | Minimum deposit amount           | Set by the creator |
| `maxDeposit`      | Maximum deposit amount           | Set by the creator |
| `maxPoolCap`      | Maximum pool capacity            | Set by the creator |
| `maxShareholders` | Maximum number of shareholders   | Set by the creator |
| `depositEnabled`  | Whether new deposits are allowed | true               |

***

## Funds Locked for Settlement

To protect shareholder interests, the contract uses `pendingLockedAmount` mechanism:

* When a player places a bet, the potential maximum payout is **locked**
* The locked amount is not counted in the available pool balance
* This ensures that even if multiple players win at the same time, the pool has enough tokens to pay out

```
Available balance = total pool amount - locked amount pending settlement
```

***

## Admin operations

Game administrator (owner) has the following permissions over the shareholder system:

| Operation          | Description                                  | Risk level                    |
| ------------------ | -------------------------------------------- | ----------------------------- |
| Toggle deposits    | Control whether new deposits are allowed     | 🟢 Low                        |
| Remove shareholder | Force a shareholder’s shares to be withdrawn | 🔴 High (dangerous operation) |
| Pool withdrawal    | Withdraw tokens from the pool                | 🔴 High (dangerous operation) |

> ⚠️ If the game has **Decentralization**(owner set to the zero address), then the administrator cannot perform the above operations, and shareholder funds are fully protected by the contract.

For detailed admin operations, please refer to [Game management](/dapp.meme-en/manage-games/game-management-overview.md).

***

## Investment strategy recommendations

> 💡 The following are general suggestions only and do not constitute investment advice.

1. **Diversify investments**: Do not put all your funds into a single game
2. **Pay attention to pool size**: A larger pool is relatively less volatile
3. **Check game history**: Understand profit and loss trends through rankings and logs
4. **Pay attention to decentralization status**: Decentralized games are safer; the administrator cannot withdraw from the pool
5. **Understand fees**: Both deposits and withdrawals incur fees; frequent in-and-out transactions will increase costs

***

## Related links

* ⬅️ Back [Investment and equity overview](/dapp.meme-en/provide-liquidity-lp.md)
* 📊 View [Leaderboard](/dapp.meme-en/leaderboard-and-logs/leaderboard-and-logs-overview.md) the shareholder ranking in
* 🔒 Learn about [Game Security](/dapp.meme-en/technical-overview/game-security.md)
* 💸 Learn [Fee System](/dapp.meme-en/technical-overview/detailed-explanation-of-the-fee-system.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dapp.meme/dapp.meme-en/provide-liquidity-lp/detailed-explanation-of-the-shareholder-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.