ESOPTrust

# Process a share repurchase
def repurchase_shares(
    self,
    participant_id: str,
    shares: Decimal,
    cash_sources: List[str]
) -> RepurchaseTransaction:
    repurchase_amount = shares * self.current_share_price
    
    # Draw cash from specified sources (waterfall)
    cash_drawn = self.cash_ledger.draw_cash(
        amount=repurchase_amount,
        sources=cash_sources
    )
    
    # Remove shares from circulation
    self.allocated_shares -= shares
    self.total_shares_outstanding -= shares
    
    return RepurchaseTransaction(...)

# Receive company contribution
def receive_contribution(
    self,
    cash_amount: Decimal,
    stock_shares: Decimal = 0
):
    self.cash_ledger.unallocated_company_contributions += cash_amount
    self.unallocated_shares += stock_shares
    self.total_shares_outstanding += stock_shares

# Process annual loan payment and release shares
def process_loan_payment(
    self,
    loan_id: str,
    principal_payment: Decimal,
    interest_payment: Decimal
) -> Decimal:
    loan = self.get_loan(loan_id)
    
    # Calculate shares to release
    release_percentage = principal_payment / loan.original_principal
    shares_to_release = loan.suspense_shares * release_percentage
    
    # Release shares from suspense
    loan.suspense_shares -= shares_to_release
    loan.principal_balance -= principal_payment
    
    # Add to allocable pool
    self.unallocated_shares += shares_to_release
    
    # Pay interest from cash
    self.cash_ledger.unallocated_company_contributions -= interest_payment
    
    return shares_to_release

# Validate trust state consistency
def validate(self) -> List[ValidationError]:
    errors = []
    
    # Check share conservation
    total_calculated = (
        self.allocated_shares + 
        self.unallocated_shares + 
        self.total_suspense_shares()
    )
    if total_calculated != self.total_shares_outstanding:
        errors.append(ValidationError(
            "Share conservation violated",
            f"Expected {self.total_shares_outstanding}, got {total_calculated}"
        ))
    
    # Check cash non-negativity
    if self.cash_ledger.total_cash() < 0:
        errors.append(ValidationError(
            "Negative cash balance",
            f"Total cash: {self.cash_ledger.total_cash()}"
        ))
    
    # Check loan balances
    for loan in self.loans:
        if loan.principal_balance < 0:
            errors.append(ValidationError(
                f"Negative loan balance: {loan.loan_id}"
            ))
    
    return errors