> ## 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.

# InitialState Guide

> A deep dive into the InitialState object, the snapshot of your ESOP at the start of a simulation.

## Overview

The `InitialState` object is a snapshot of your ESOP at the beginning of a simulation. It contains all the necessary data about your participants, trust assets, and ESOP loans.

<Info>
  **Source of Truth:** Your TPA's annual report, census data, trust statements, and loan documents.
</Info>

## Complete Field Reference

Below is a detailed walkthrough of each field in the `InitialState` object.

### `census_year`

* **Type:** `integer`
* **Required:** Yes
* **Description:** The year of the census data.
* **Example:** `2024`

### `participants`

* **Type:** `array` of objects
* **Required:** Yes
* **Description:** An array of all current ESOP participants. Each object in the array represents one participant.

<AccordionGroup>
  <Accordion title="Participant Object Fields">
    - **`id`**: `string` (Required) - A unique identifier for the employee.
    - **`age`**: `integer` (Required) - The participant's age.
    - **`service_years`**: `integer` (Required) - The participant's years of service for vesting purposes.
    - **`compensation`**: `number` (Required) - The participant's annual compensation.
    - **`allocated_shares`**: `number` (Required) - The number of shares allocated to the participant's account.
    - **`vested_percentage`**: `number` (Optional) - The participant's current vested percentage. If not provided, it will be calculated based on the `vesting_schedule`.
    - **`cash_balance`**: `number` (Optional) - The cash balance in the participant's account.
  </Accordion>
</AccordionGroup>

### `trust_cash`

* **Type:** `object`
* **Required:** Yes
* **Description:** The cash balances in the ESOP trust, segregated by source.

<AccordionGroup>
  <Accordion title="`participant_cash_accounts`">
    - **Type:** `number`
    - **Description:** Cash that has been segregated for participants who have terminated but have not yet been paid out.
  </Accordion>

  <Accordion title="`unallocated_company_contributions`">
    * **Type:** `number`
    * **Description:** Cash from company contributions that has not yet been used.
  </Accordion>

  <Accordion title="`unallocated_forfeiture_cash`">
    * **Type:** `number`
    * **Description:** Cash from forfeited (unvested) shares of terminated participants.
  </Accordion>
</AccordionGroup>

### `esop_loans`

* **Type:** `array` of objects
* **Required:** No
* **Description:** An array of all outstanding ESOP loans.

<AccordionGroup>
  <Accordion title="Loan Object Fields">
    - **`loan_id`**: `string` (Required) - A unique identifier for the loan.
    - **`principal_balance`**: `number` (Required) - The outstanding principal balance.
    - **`interest_rate`**: `number` (Required) - The annual interest rate.
    - **`years_remaining`**: `integer` (Required) - The number of years left on the loan.
    - **`suspense_shares`**: `number` (Required) - The number of shares held as collateral for this loan.
  </Accordion>
</AccordionGroup>

## Complete Example

```json theme={null}
{
  "census_year": 2024,
  "participants": [
    {
      "id": "EMP001",
      "age": 45,
      "service_years": 8,
      "compensation": 120000,
      "allocated_shares": 1000,
      "vested_percentage": 0.80
    },
    {
      "id": "EMP002",
      "age": 35,
      "service_years": 5,
      "compensation": 80000,
      "allocated_shares": 500,
      "vested_percentage": 0.60
    }
  ],
  "trust_cash": {
    "participant_cash_accounts": 50000,
    "unallocated_company_contributions": 25000,
    "unallocated_forfeiture_cash": 10000
  },
  "esop_loans": [
    {
      "loan_id": "LOAN_2020",
      "principal_balance": 2000000,
      "interest_rate": 0.065,
      "years_remaining": 8,
      "suspense_shares": 20000
    }
  ]
}
```