111 lines
2.9 KiB
TypeScript
111 lines
2.9 KiB
TypeScript
/**
|
|
* Type definitions for Threshold-Based Flow Funding
|
|
* These types model the academic paper's mathematical concepts
|
|
*/
|
|
|
|
export type AccountStatus = 'deficit' | 'minimum' | 'healthy' | 'overflow'
|
|
|
|
/**
|
|
* FlowFundingAccount represents a participant in the network
|
|
* Each account has:
|
|
* - balance: current funds held
|
|
* - minThreshold: minimum viable funding (survival level)
|
|
* - maxThreshold: overflow point (beyond which funds redistribute)
|
|
*/
|
|
export interface FlowFundingAccount {
|
|
// Identity
|
|
id: string
|
|
name: string
|
|
|
|
// Financial State
|
|
balance: number
|
|
minThreshold: number
|
|
maxThreshold: number
|
|
|
|
// Visual Position (for canvas rendering)
|
|
x: number
|
|
y: number
|
|
width: number
|
|
height: number
|
|
|
|
// Computed properties (derived from balance vs thresholds)
|
|
status: AccountStatus
|
|
shortfall: number // max(0, minThreshold - balance)
|
|
capacity: number // max(0, maxThreshold - balance)
|
|
overflow: number // max(0, balance - maxThreshold)
|
|
}
|
|
|
|
/**
|
|
* Allocation represents where overflow goes
|
|
* When source account exceeds maxThreshold, overflow flows to target
|
|
* based on allocation percentage
|
|
*/
|
|
export interface Allocation {
|
|
id: string
|
|
sourceAccountId: string
|
|
targetAccountId: string
|
|
percentage: number // 0.0 to 1.0 (e.g., 0.5 = 50%)
|
|
|
|
// Visual (calculated dynamically from account positions)
|
|
x1?: number
|
|
y1?: number
|
|
x2?: number
|
|
y2?: number
|
|
}
|
|
|
|
/**
|
|
* FlowFundingNetwork represents the complete system
|
|
*/
|
|
export interface FlowFundingNetwork {
|
|
name: string
|
|
accounts: FlowFundingAccount[]
|
|
allocations: Allocation[]
|
|
|
|
// Computed network-level properties
|
|
totalFunds: number
|
|
totalShortfall: number
|
|
totalCapacity: number
|
|
totalOverflow: number
|
|
}
|
|
|
|
/**
|
|
* FlowParticle represents an animated particle flowing along an allocation
|
|
* Used to visualize fund transfers during redistribution
|
|
*/
|
|
export interface FlowParticle {
|
|
allocationId: string
|
|
progress: number // 0.0 to 1.0 along the path
|
|
amount: number // Funds being transferred
|
|
startTime: number // timestamp when particle was created
|
|
duration: number // milliseconds for animation
|
|
}
|
|
|
|
/**
|
|
* RedistributionStep captures one iteration of the overflow redistribution process
|
|
*/
|
|
export interface RedistributionStep {
|
|
iteration: number
|
|
overflows: Array<{ accountId: string; amount: number }>
|
|
deltas: Record<string, number> // accountId -> balance change
|
|
flowParticles: FlowParticle[]
|
|
}
|
|
|
|
/**
|
|
* FundingStep represents a step in the funding round process
|
|
* Used for animation/visualization callbacks
|
|
*/
|
|
export type FundingStep =
|
|
| { type: 'initial-distribution'; amount: number }
|
|
| { type: 'overflow-redistribution' }
|
|
| { type: 'redistribution-step'; iteration: number; flowParticles: FlowParticle[] }
|
|
| { type: 'complete' }
|
|
|
|
/**
|
|
* ValidationResult for network validation
|
|
*/
|
|
export interface ValidationResult {
|
|
valid: boolean
|
|
errors: string[]
|
|
warnings: string[]
|
|
}
|