Skip to main content

​
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.
Source of Truth: Your TPA’s annual report, census data, trust statements, and loan documents.

​
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.
  • 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.

​
trust_cash

  • Type: object
  • Required: Yes
  • Description: The cash balances in the ESOP trust, segregated by source.
  • Type: number
  • Description: Cash that has been segregated for participants who have terminated but have not yet been paid out.
  • Type: number
  • Description: Cash from company contributions that has not yet been used.
  • Type: number
  • Description: Cash from forfeited (unvested) shares of terminated participants.

​
esop_loans

  • Type: array of objects
  • Required: No
  • Description: An array of all outstanding ESOP loans.
  • 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.

​
Complete Example

{
  "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
    }
  ]
}