> ## Documentation Index
> Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TrustCashLedger

> Non-fungible cash accounting segregated by source

## The Non-Fungible Cash Problem

In traditional accounting, all cash is fungible—any dollar can be used for any purpose. But **ESOP trust cash is different**. The source of cash determines how it can be legally used.

<Warning>
  Using restricted cash for the wrong purpose can result in ERISA violations, DOL audits, and plan disqualification.
</Warning>

## Model Structure

The `TrustCashLedger` segregates cash by source, each with different usage rules:

```python theme={null}
class TrustCashLedger(BaseModel):
    """
    Non-fungible cash ledger tracking cash by source.
    """
    # Individual participant cash balances
    participant_cash_accounts: Decimal = Field(ge=0)
    
    # Company contributions not yet allocated
    unallocated_company_contributions: Decimal = Field(ge=0)
    
    # Forfeitures not yet reallocated or used
    unallocated_forfeiture_cash: Decimal = Field(ge=0)
    
    def total_cash(self) -> Decimal:
        return (
            self.participant_cash_accounts +
            self.unallocated_company_contributions +
            self.unallocated_forfeiture_cash
        )
```

## Cash Sources Explained

<AccordionGroup>
  <Accordion title="Participant Cash Accounts" icon="user-dollar">
    **What It Is:** The sum of all cash held in individual employee accounts.

    **How It Gets There:**

    * Cash dividends on ESOP shares
    * Proceeds from diversification elections
    * Forfeitures reallocated as cash

    **Usage Restrictions:**

    * ✅ Can be used for distributions to that participant
    * ✅ Can fund repurchases per plan document
    * ❌ Cannot be used for plan expenses
    * ❌ Cannot be used for other participants

    ```python theme={null}
    # Example: Participant has $5,000 cash in account
    # Can be distributed to participant on termination
    # Or used to repurchase their shares (per plan rules)
    ```
  </Accordion>

  <Accordion title="Unallocated Company Contributions" icon="building">
    **What It Is:** Company contributions that have been received but not yet credited to individual participants.

    **How It Gets There:**

    * Annual company cash contributions
    * Loan proceeds (for leveraged ESOPs)

    **Usage Restrictions:**

    * ✅ Can be used for share purchases
    * ✅ Can fund repurchases (per plan document)
    * ✅ Can be allocated to participants
    * ✅ Flexible use per cash\_usage\_policy

    ```python theme={null}
    # Most flexible cash source
    # Temporary holding account before allocation
    ```

    <Note>
      **Timing Gap:** There's often a delay between when a contribution is made and when shares are allocated. This account bridges that gap.
    </Note>
  </Accordion>

  <Accordion title="Unallocated Forfeiture Cash" icon="rotate-left">
    **What It Is:** Cash from the non-vested accounts of terminated participants.

    **How It Gets There:**

    * Terminated participant had non-vested shares
    * Shares sold, proceeds held here

    **Usage Restrictions:**

    * ✅ Can reduce company contributions (most common)
    * ✅ Can be reallocated to remaining participants
    * ✅ Can fund administrative expenses (if plan allows)
    * ⚠️ Usage strictly governed by plan document

    ```python theme={null}
    # Example: Employee terminates with 40% vesting
    # Non-vested 60% becomes forfeiture
    # Shares sold → cash held here
    ```

    <Warning>
      **Highly Restricted:** Plan document specifies exactly how forfeitures can be used. Deviation can cause plan disqualification.
    </Warning>
  </Accordion>
</AccordionGroup>

## The Funding Waterfall

When the trust needs cash (e.g., for repurchases), it draws from sources in a specific order defined by `PlanRules.cash_usage_policy`:

```python theme={null}
# Example cash_usage_policy
cash_usage_policy = [
    "unallocated_company_contributions",  # Draw from here first
    "unallocated_forfeiture_cash",        # Then here
    "participant_cash_accounts"           # Last resort
]

# Process a $500,000 repurchase
ledger = TrustCashLedger(
    participant_cash_accounts=150_000,
    unallocated_contributions=200_000,
    unallocated_forfeitures=100_000
)

result = ledger.draw_cash(
    amount=500_000,
    sources=cash_usage_policy
)

# Execution:
# 1. Draw $200K from unallocated_contributions → $300K remaining
# 2. Draw $100K from unallocated_forfeitures → $200K remaining
# 3. Draw $200K from participant_cash → $0 remaining ✓
```

## Methods & Operations

<Tabs>
  <Tab title="Drawing Cash">
    ```python theme={null}
    def draw_cash(
        self,
        amount: Decimal,
        sources: List[str]
    ) -> CashDrawResult:
        """
        Draw cash following the waterfall sequence.
        """
        remaining_need = amount
        transactions = []
        
        for source in sources:
            if remaining_need <= 0:
                break
            
            available = getattr(self, source)
            amount_to_draw = min(available, remaining_need)
            
            if amount_to_draw > 0:
                # Deduct from source
                setattr(self, source, available - amount_to_draw)
                remaining_need -= amount_to_draw
                
                transactions.append(
                    CashTransaction(
                        source=source,
                        amount=amount_to_draw
                    )
                )
        
        return CashDrawResult(
            requested=amount,
            drawn=amount - remaining_need,
            shortfall=remaining_need,
            transactions=transactions
        )
    ```
  </Tab>

  <Tab title="Depositing Cash">
    ```python theme={null}
    def deposit_cash(
        self,
        amount: Decimal,
        source: str
    ):
        """
        Add cash to a specific source.
        """
        current = getattr(self, source)
        setattr(self, source, current + amount)

    # Example usage
    ledger.deposit_cash(
        amount=500_000,
        source="unallocated_company_contributions"
    )
    ```
  </Tab>

  <Tab title="Transfers">
    ```python theme={null}
    def transfer(
        self,
        amount: Decimal,
        from_source: str,
        to_source: str
    ):
        """
        Move cash between sources (e.g., allocation).
        """
        # Validate sufficient funds
        available = getattr(self, from_source)
        if available < amount:
            raise InsufficientFundsError()
        
        # Execute transfer
        setattr(self, from_source, available - amount)
        current_dest = getattr(self, to_source)
        setattr(self, to_source, current_dest + amount)

    # Example: Allocate forfeitures
    ledger.transfer(
        amount=25_000,
        from_source="unallocated_forfeiture_cash",
        to_source="participant_cash_accounts"
    )
    ```
  </Tab>

  <Tab title="Validation">
    ```python theme={null}
    def validate(self) -> List[ValidationError]:
        """
        Ensure all cash balances are non-negative.
        """
        errors = []
        
        if self.participant_cash_accounts < 0:
            errors.append(ValidationError(
                "Negative participant cash",
                self.participant_cash_accounts
            ))
        
        if self.unallocated_company_contributions < 0:
            errors.append(ValidationError(
                "Negative unallocated contributions",
                self.unallocated_company_contributions
            ))
        
        if self.unallocated_forfeiture_cash < 0:
            errors.append(ValidationError(
                "Negative forfeiture cash",
                self.unallocated_forfeiture_cash
            ))
        
        return errors
    ```
  </Tab>
</Tabs>

## Real-World Example

Here's a complete annual cycle showing cash flow through the ledger:

<Steps>
  <Step title="Year Start">
    ```python theme={null}
    ledger = TrustCashLedger(
        participant_cash=125_000,
        unallocated_contributions=50_000,
        unallocated_forfeitures=25_000
    )
    # Total: $200,000
    ```
  </Step>

  <Step title="Company Contribution">
    ```python theme={null}
    ledger.deposit_cash(
        amount=500_000,
        source="unallocated_company_contributions"
    )
    # unallocated_contributions: 50K → 550K
    ```
  </Step>

  <Step title="Forfeiture Reallocation">
    ```python theme={null}
    # Reallocate forfeitures to participants
    ledger.transfer(
        amount=25_000,
        from_source="unallocated_forfeiture_cash",
        to_source="participant_cash_accounts"
    )
    # forfeitures: 25K → 0
    # participant_cash: 125K → 150K
    ```
  </Step>

  <Step title="Repurchase Obligation">
    ```python theme={null}
    # Need $400K for terminated participants
    result = ledger.draw_cash(
        amount=400_000,
        sources=[
            "unallocated_company_contributions",
            "unallocated_forfeiture_cash",
            "participant_cash_accounts"
        ]
    )

    # Execution:
    # Draw $400K from unallocated_contributions
    # unallocated_contributions: 550K → 150K
    ```
  </Step>

  <Step title="Year End">
    ```python theme={null}
    ledger = TrustCashLedger(
        participant_cash=150_000,
        unallocated_contributions=150_000,
        unallocated_forfeitures=0
    )
    # Total: $300,000
    ```
  </Step>
</Steps>

## Why This Matters

<CardGroup cols={2}>
  <Card title="Legal Compliance" icon="gavel">
    Proper segregation ensures ERISA compliance and prevents DOL issues
  </Card>

  <Card title="Audit Trail" icon="file-lines">
    Clear source tracking makes audits straightforward
  </Card>

  <Card title="Planning Accuracy" icon="bullseye">
    Knowing what cash is available for what purpose improves forecasting
  </Card>

  <Card title="Fiduciary Protection" icon="shield">
    Demonstrates prudent management of plan assets
  </Card>
</CardGroup>

## Common Mistakes to Avoid

<Warning>
  **Don't:**

  * ❌ Use participant cash for other participants
  * ❌ Use forfeiture cash without checking plan rules
  * ❌ Ignore the cash\_usage\_policy waterfall
  * ❌ Allow negative balances in any account
</Warning>

<Note>
  **Do:**

  * ✅ Follow the plan document's cash usage rules
  * ✅ Validate after every cash operation
  * ✅ Log all cash movements
  * ✅ Review cash sources before making decisions
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="ESOPTrust" icon="building-columns" href="/models/esop-trust">
    See how cash ledger fits into trust structure
  </Card>

  <Card title="Funding Waterfall" icon="water" href="/simulation/step-7-repurchase">
    Detailed repurchase processing logic
  </Card>
</CardGroup>