my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Percolator
#2
#3	EDUCATIONAL RESEARCH PROJECT — NOT PRODUCTION READY. NOT AUDITED. Do NOT use with real funds.
#4
#5	A predictable alternative to ADL queues.
#6
#7	If you want the `xy = k` of perpetual futures risk engines -- something you can reason about, audit, and run without human intervention -- the cleanest move is simple: stop treating profit like money. Treat it like what it really is in a stressed exchange: a junior claim on a shared balance sheet.
#8
#9	> No user can ever withdraw more value than actually exists on the exchange balance sheet.
#10
#11	## Two Problems, Two Mechanisms
#12
#13	A perp exchange has two fairness problems:
#14
#15	1. Exit fairness: when the vault is stressed, who gets paid and how much?
#16	2. Overhang clearing: when positions go bankrupt, how does the opposing side absorb the residual without deadlocking the market?
#17
#18	Percolator solves them with two independent mechanisms that compose cleanly:
#19
#20	- H (the haircut ratio) keeps all exits fair.
#21	- A/K (the lazy side indices) keeps all residual overhang clearing fair, and guarantees markets always return to healthy.
#22
#23	---
#24
#25	## H: Fair Exits
#26
#27	Capital is senior. Profit is junior. A single global ratio determines how much profit is real.
#28
#29	```
#30	Residual = max(0, V - C_tot - I)
#31
#32	min(Residual, PNL_matured_pos_tot)
#33	h = ----------------------------------
#34	PNL_matured_pos_tot
#35	```
#36
#37	If fully backed, `h = 1`. If stressed, `h < 1`. Every profitable account sees the same fraction of its released profit:
#38
#39	```
#40	ReleasedPos_i = max(PNL_i, 0) - R_i
#41	effective_pnl_i = floor(ReleasedPos_i * h)
#42	```
#43
#44	Fresh profit sits in a per-account reserve `R_i` and converts to released (matured) profit through a warmup period. Only matured profit enters the haircut denominator (`PNL_matured_pos_tot`) and the per-account effective PnL. This is the core oracle-manipulation defense — an attacker who spikes a price sees their unrealized gain locked in `R_i`, excluded from both the ratio and their withdrawable amount, until the warmup window passes.
#45
#46	No rankings, no queue priority, no first-come advantage. The floor rounding is conservative — the sum of all effective PnL never exceeds what exists in the vault.
#47
#48	When the system is stressed, `h` falls and less converts. When losses settle or buffers recover, `h` rises. Self-healing.
#49
#50	Flat accounts are always protected — `h` only gates profit extraction, never touches deposited capital.
#51
#52	---
#53
#54	## A/K: Fair Overhang Clearing
#55
#56	When a leveraged account goes bankrupt, two things need to happen: remove the position quantity from open interest, and distribute any uncovered deficit across the opposing side.
#57
#58	Traditional ADL queues pick specific counterparties and force-close them. Percolator replaces the queue with two global coefficients per side:
#59
#60	- A scales everyone's effective position equally.
#61	- K accumulates all PnL events (mark, funding, deficit socialization) into one index.
#62
#63	```
#64	effective_pos(i) = floor(basis_i * A / a_basis_i)
#65	pnl_delta(i) = floor(\|basis_i\| * (K - k_snap_i) / (a_basis_i * POS_SCALE))
#66	```
#67
#68	When a liquidation reduces OI, `A` decreases — every account on that side shrinks by the same ratio. When a deficit is socialized, `K` shifts — every account absorbs the same per-unit loss.
#69
#70	No account is singled out. Settlement is O(1) per account and order-independent.
#71
#72	### Markets Always Return to Healthy
#73
#74	A/K guarantees forward progress through a deterministic cycle:
#75
#76	DrainOnly — when `A` drops below a precision threshold, no new OI can be added. Positions can only close.
#77
#78	ResetPending — when OI reaches zero, the engine snapshots `K`, increments the epoch, and resets `A` back to 1. Remaining accounts settle their residual PnL exactly once when next touched.
#79
#80	Normal — once all stale accounts have settled and OI is confirmed zero, the side reopens for trading with full precision.
#81
#82	No admin intervention. No governance vote. The state machine always makes progress.
#83
#84	---
#85
#86	## How They Compose
#87
#88	\| \| H \| A/K \|
#89	\|---\|---\|---\|
#90	\| Solves \| Exit fairness \| Overhang clearing \|
#91	\| Math \| Pro-rata profit scaling \| Pro-rata position/deficit scaling \|
#92	\| Triggered by \| Withdrawal or conversion \| Bankrupt liquidation \|
#93	\| Recovery \| Automatic as Residual improves \| Deterministic three-phase reset \|
#94
#95	Together:
#96	- No user can withdraw more than exists.
#97	- No user is singled out for forced closure.
#98	- Markets always recover.
#99	- Flat accounts keep their deposits.
#100
#101	A/K fairness is exact for open-position economics. H fairness is exact only for the currently stored realized claim set, not for the economically "true" claim set you would get after globally cranking everyone.
#102
#103	---
#104
#105	## Open Source
#106
#107	Fork it, test it, send bug reports. Percolator is open research under Apache-2.0.
#108
#109	```bash
#110	cargo install --locked kani-verifier
#111	cargo kani setup
#112	cargo kani
#113	```
#114
#115	## References
#116
#117	- Tarun Chitra, Autodeleveraging: Impossibilities and Optimization, arXiv:2512.01112, 2025. https://arxiv.org/abs/2512.01112
#118

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public