Startup equity distribution

ails. The architecture follows an event-sourcing pattern where every grant, vesting event, cancellation, or dilution trigger is an immutable record. Calculations are pure functions with no side effects, ensuring deterministic outputs across environments.

Architecture Decisions and Rationale

1. Event-Sourced Ledger: Cap table mutations are recorded as sequential events (GrantIssued, VestingAccrued, DilutionApplied, GrantCancelled). This enables time-travel debugging, full audit compliance, and rollback capabilities without state corruption.
2. Pure Calculation Functions: Vesting, dilution, and option pool math are isolated from database I/O. Functions accept typed inputs and return deterministic outputs, simplifying unit testing and regulatory validation.
3. Strict Type Boundaries: Securities (Common, Preferred, Options, RSUs) are modeled as distinct types with separate validation rules. This prevents accidental cross-security calculations that violate term sheet structures.
4. UTC-Only Timestamps: Vesting accrual and cliff calculations use UTC to eliminate timezone drift across distributed teams and global hires.
5. Idempotent Grant Issuance: Each grant carries a unique grantId and issueDate. Repeated API calls with identical payloads return the same state without double-issuing shares.

TypeScript Implementation

// types/equity.types.ts
export type SecurityType = 'COMMON' | 'PREFERRED' | 'OPTION' | 'RSU';
export type VestingSchedule = 'STANDARD' | 'ACCELERATED' | 'CUSTOM';

export interface Grant {
  grantId: string;
  recipientId: string;
  securityType: SecurityType;
  totalShares: number;
  strikePriceCents: number;
  issueDate: Date;
  vestingSchedule: VestingSchedule;
  monthlyVestingPercent: number;
  cliffMonths: number;
  accelerationMonths?: number;
}

export interface VestingSnapshot {
  grantId: string;
  asOfDate: Date;
  vestedShares: number;
  unvestedShares: number;
  cliffMet: boolean;
}

// calculations/vesting.ts
export function calculateVesting(
  grant: Grant,
  asOfDate: Date = new Date()
): VestingSnapshot {
  const utcNow = new Date(Date.UTC(asOfDate.getUTCFullYear(), asOfDate.getUTCMonth(), asOfDate.getUTCDate()));
  const utcIssue = new Date(Date.UTC(grant.issueDate.getUTCFullYear(), grant.issueDate.getUTCMonth(), grant.issueDate.getUTCDate()));
  
  const elapsedMonths = (utcNow.getUTCFullYear() - utcIssue.getUTCFullYear()) * 12 + 
                        (utcNow.getUTCMonth() - utcIssue.getUTCMonth());
  
  const cliffMet = elapsedMonths >= grant.cliffMonths;
  const vestingMonths = cliffMet ? Math.min(elapsedMonths, 48) : 0;
  const vestedShares = Math.floor(grant.totalShares * (grant.monthlyVestingPercent / 100) * vestingMonths);
  
  return {
    grantId: grant.grantId,
    asOfDate: utcNow,
    vestedShares,
    unvestedShares: grant.totalShares - vestedShares,
    cliffMet
  };
}

// calculations/dilution.ts
export interface DilutionModel {
  preMoneyValuation: number;
  investmentAmount: number;
  existingShares: number;
  optionPoolSize: number;
}

export function calculatePostMoneyDilution(model: DilutionModel) {
  const preMoneyShares = model.existingShares;
  const newSharesForInvestors = Math.floor(
    (model.investmentAmount / model.preMoneyValuation) * preMoneyShares
  );
  const postMoneyShares = preMoneyShares + newSharesForInvestors + model.optionPoolSize;
  const investorOwnershipPercent = (newSharesForInvestors / postMoneyShares) * 100;
  const fullyDilutedShares = postMoneyShares;
  
  return {
    newSharesForInvestors,
    postMoneyShares,
    investorOwnershipPercent: Number(investorOwnershipPercent.toFixed(2)),
    fullyDilutedShares,
    optionPoolPercent: Number(((model.optionPoolSize / postMoneyShares) * 100).toFixed(2))
  };
}

The vesting calculator uses UTC-normalized dates to prevent timezone-related accrual errors. The cliffMet guard ensures zero vesting before the threshold, matching standard 1-year cliff structures. The dilution model separates pre-money valuation math from option pool creation, reflecting actual term sheet mechanics where pools are typically added pre-money but calculated post-money for ownership percentages.

Production Integration Pattern

// engine/equity-engine.ts
import { Grant, VestingSnapshot, DilutionModel } from '../types/equity.types';
import { calculateVesting, calculatePostMoneyDilution } from '../calculations';

export class EquityEngine {
  private grants: Map<string, Grant> = new Map();
  private events: Array<{ type: string; payload: any; timestamp: Date }> = [];

  public issueGrant(grant: Grant): void {
    if (this.grants.has(grant.grantId)) {
      throw new Error(`Grant ${grant.grantId} already exists. Idempotency violation.`);
    }
    this.grants.set(grant.grantId, grant);
    this.events.push({ type: 'GRANT_ISSUED', payload: grant, timestamp: new Date() });
  }

  public getVestingSnapshot(grantId: string, asOfDate: Date): VestingSnapshot {
    const grant = this.grants.get(grantId);
    if (!grant) throw new Error(`Grant ${grantId} not found`);
    return calculateVesting(grant, asOfDate);
  }

  public simulateDilution(model: DilutionModel) {
    return calculatePostMoneyDilution(model);
  }

  public getAuditTrail() {
    return [...this.events];
  }
}

The engine wraps pure functions with state management and audit logging. Every mutation is recorded as an event, enabling regulatory compliance and founder scenario testing. The architecture supports horizontal scaling by externalizing state to a relational database while keeping calculation logic stateless.

Pitfall Guide

1. Hardcoding Vesting Percentages Instead of Date-Based Accrual Spreadsheets often use static monthly percentages that ignore actual grant dates, leap years, and partial-month accruals. Production systems must calculate elapsed time from issueDate to asOfDate using UTC timestamps. Partial months should be prorated or rounded down depending on legal jurisdiction requirements.

2. Ignoring 409A Valuation Impact on Strike Prices Option strike prices must align with the latest 409A fair market value. Engineering teams that hardcode strike prices or allow manual overrides without validation create tax compliance risks. Implement price validation against a FairMarketValue service that tracks quarterly appraisal dates.

3. Miscalculating Fully Diluted Shares Founders frequently calculate ownership using issued shares only, omitting unissued option pools, convertible notes, or outstanding warrants. A production engine must maintain a fullyDilutedCapTable that aggregates all security types, including reserved but ungranted shares.

4. Treating Equity as a Single Ledger Common stock, preferred stock, ISOs, NSOs, and RSUs have distinct tax treatments, voting rights, and liquidation preferences. Modeling them as a unified shares array causes calculation drift during exit scenarios. Use strict type separation and security-specific validation rules.

5. Missing Idempotency in Grant Issuance Retries, webhook duplicates, or UI double-clicks can trigger multiple grant issuances. Every issueGrant call must check for existing grantId and return the original state without creating duplicates. Implement database-level unique constraints and application-level guards.

6. Overlooking Acceleration Clauses Single-trigger and double-trigger acceleration modify vesting schedules during acquisitions or leadership changes. Engines that ignore acceleration parameters will under-vest employees during exit events. Model acceleration as a separate modifier function that overrides base vesting when triggered.

7. Failing to Version Control Cap Table Snapshots Cap tables change with every financing round, grant, or cancellation. Without versioned snapshots, teams cannot reconstruct historical ownership percentages for investor reporting or tax filings. Implement daily snapshot exports with cryptographic hashes to prove immutability.

Best Practices from Production:

• Isolate calculation logic from storage. Use pure functions for math, event stores for state.
• Enforce UTC across all timestamps. Convert local times at the UI boundary only.
• Validate inputs against securities law constraints before calculation. Fail fast on invalid grants.
• Maintain separate calculation paths for ISO vs NSO tax treatment.
• Run deterministic unit tests against known cap table scenarios (e.g., YC standard, Series A term sheet).
• Expose equity data through versioned APIs with rate limiting and role-based access control.

Production Bundle

Action Checklist

• Initialize event-sourced ledger: Set up immutable event storage with append-only writes and cryptographic hashing for audit compliance.
• Implement pure calculation modules: Isolate vesting, dilution, and option pool math into stateless functions with comprehensive unit test coverage.
• Enforce strict security typing: Model Common, Preferred, Options, and RSUs as distinct types with separate validation and tax rule sets.
• Add idempotency guards: Require unique grantId per issuance and implement duplicate detection at both application and database layers.
• Integrate 409A validation service: Connect strike price assignment to quarterly appraisal dates and block grants below fair market value.
• Build scenario simulator: Expose dilution and vesting APIs for founder dashboards, enabling real-time term sheet modeling without production state mutation.
• Schedule daily snapshot exports: Generate hashed cap table snapshots with version tags for legal, tax, and investor reporting.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Seed stage (<20 employees, pre-funding)	Programmatic Engine (lightweight)	Prevents spreadsheet drift during early hiring; scales to Series A without refactor	Low engineering cost, high long-term compliance savings
Series A ready (50+ employees, term sheet pending)	Full Event-Sourced Engine + Audit API	Real-time dilution modeling required for investor negotiations; audit trail mandatory	Medium engineering cost, eliminates legal retrospective fees
Late stage / Pre-IPO (200+ employees, multiple security classes)	Enterprise Equity Platform + Custom Calculators	Regulatory complexity demands segregated ledgers, tax event tracking, and board reporting	High initial investment, reduces IPO readiness timeline by 3-6 months
Acquisition target	Snapshot-Only Engine + Export Module	Buyers require immutable historical cap tables; live calculation less critical than provenance	Low cost, accelerates due diligence by 40%

Configuration Template

equity_plan:
  version: "2.1"
  jurisdiction: "US_DE"
  409a_service:
    endpoint: "/api/v1/409a/latest"
    refresh_interval_days: 90
    strict_strike_validation: true

  security_classes:
    - type: "COMMON"
      voting_rights: true
      liquidation_preference: 1.0
      max_issuance: 10000000
    - type: "PREFERRED_SERIES_A"
      voting_rights: false
      liquidation_preference: 1.0
      max_issuance: 5000000
    - type: "OPTION_ISO"
      tax_treatment: "ISO"
      exercise_window_days: 90
      max_issuance: 2000000
    - type: "OPTION_NSO"
      tax_treatment: "NSO"
      exercise_window_days: 365
      max_issuance: 1000000

  vesting_defaults:
    schedule: "STANDARD"
    cliff_months: 12
    monthly_percent: 1.6667
    max_vesting_months: 48
    acceleration:
      single_trigger: false
      double_trigger_months: 24

  dilution_model:
    option_pool_pre_money: true
    calculate_fully_diluted: true
    rounding_rule: "FLOOR"

Quick Start Guide

1. Initialize the engine: Clone the repository, install dependencies, and run npm run setup. The script creates the event store schema and loads default configuration from equity.config.yaml.
2. Load your cap table baseline: Use the /api/v1/import endpoint to upload existing grants as JSON. The validator checks for duplicate IDs, valid security types, and 409A strike compliance before persisting events.
3. Run a dilution simulation: Call POST /api/v1/simulate/dilution with your pre-money valuation, investment amount, and option pool size. The engine returns post-money ownership percentages without mutating live state.
4. Generate audit snapshot: Execute npm run snapshot:export -- --date 2024-06-01. The command produces a hashed CSV of vested/unvested shares, ready for legal review or investor reporting.
5. Integrate with internal dashboards: Expose vesting and ownership data via /api/v1/grants/:id/vesting. Apply role-based middleware to restrict access to HR, legal, and executive roles.