types.gno
42.47 Kb · 932 lines
1package pool
2
3import (
4 rotree "gno.land/p/nt/bptree/rotree/v0"
5 bptree "gno.land/p/nt/bptree/v0"
6
7 u256 "gno.land/p/gnoswap/uint256/v1"
8)
9
10// IPool interface defines all public methods that must be implemented by pool contract versions.
11// This interface serves as the contract between the proxy layer and implementation versions,
12// ensuring that all versions (v1, v2, v3, etc.) maintain the same public API.
13//
14// This design enables seamless upgrades while maintaining backwards compatibility.
15// When upgrading from v1 to v2, the proxy simply switches the implementation pointer
16// without changing the public interface, ensuring zero downtime and no breaking changes.
17type IPool interface {
18 IPoolManager
19 IPoolPosition
20 IPoolSwap
21 IPoolOracle
22 IPoolGetter
23 Render(path string) string
24}
25
26// IPoolManager interface defines pool management operations.
27// These methods handle pool creation and fee configuration.
28type IPoolManager interface {
29 // CreatePool creates a new concentrated liquidity pool.
30 // Parameters:
31 // - _: Noncrossing implementation-call discriminator; pass 0.
32 // - rlm: Current realm context forwarded unchanged by the pool proxy.
33 // - token0Path: Registered token contract path for token0.
34 // - token1Path: Registered token contract path for token1.
35 // - fee: Fee tier identifying the new pool and its tick spacing.
36 // - sqrtPriceX96: Initial token1/token0 square-root price encoded as a Q96 decimal string.
37 CreatePool(
38 _ int,
39 rlm realm,
40 token0Path string,
41 token1Path string,
42 fee uint32,
43 sqrtPriceX96 string,
44 )
45
46 // SetPoolCreationFee sets the pool creation fee.
47 // Parameters:
48 // - _: Noncrossing implementation-call discriminator; pass 0.
49 // - rlm: Current realm context forwarded unchanged by the pool proxy.
50 // - fee: Pool-creation fee amount to store for future pool creation operations.
51 SetPoolCreationFee(_ int, rlm realm, fee int64)
52}
53
54// IPoolPosition interface defines position management operations.
55// These methods handle liquidity provision and position management.
56type IPoolPosition interface {
57 // Mint adds liquidity to a pool position.
58 // Parameters:
59 // - _: Noncrossing implementation-call discriminator; pass 0.
60 // - rlm: Current realm context forwarded unchanged by the pool proxy.
61 // - token0Path: Registered token contract path for token0.
62 // - token1Path: Registered token contract path for token1.
63 // - fee: Fee tier identifying the pool.
64 // - tickLower: Lower inclusive tick of the position's price range; must align to pool spacing.
65 // - tickUpper: Upper exclusive tick of the position's price range; must align to pool spacing.
66 // - liquidityAmount: Positive decimal liquidity amount to add.
67 // - positionCaller: Position-contract address that provides tokens for the mint.
68 //
69 // Returns:
70 // - amount0: Token0 amount consumed, encoded as a decimal string.
71 // - amount1: Token1 amount consumed, encoded as a decimal string.
72 Mint(
73 _ int,
74 rlm realm,
75 token0Path string,
76 token1Path string,
77 fee uint32,
78 tickLower int32,
79 tickUpper int32,
80 liquidityAmount string,
81 positionCaller address,
82 ) (string, string)
83
84 // Burn removes liquidity and credits principal to the pool position entry;
85 // Collect later transfers that principal without a withdrawal fee.
86 // Parameters:
87 // - _: Noncrossing implementation-call discriminator; pass 0.
88 // - rlm: Current realm context forwarded unchanged by the pool proxy.
89 // - token0Path: Registered token contract path for token0.
90 // - token1Path: Registered token contract path for token1.
91 // - fee: Fee tier identifying the pool.
92 // - tickLower: Lower tick of the position's price range; must align to pool spacing.
93 // - tickUpper: Upper tick of the position's price range; must align to pool spacing.
94 // - liquidityAmount: Non-negative decimal liquidity amount to remove.
95 // - positionCaller: Position-contract address associated with the pool position.
96 //
97 // Returns:
98 // - amount0: Token0 principal credited to the position, encoded as a decimal string.
99 // - amount1: Token1 principal credited to the position, encoded as a decimal string.
100 Burn(
101 _ int,
102 rlm realm,
103 token0Path string,
104 token1Path string,
105 fee uint32,
106 tickLower int32,
107 tickUpper int32,
108 liquidityAmount string,
109 positionCaller address,
110 ) (string, string)
111
112 // CollectSwapFee pays accrued swap fees and applies the withdrawal fee;
113 // Collect pays principal owed by Burn without that fee.
114 // Parameters:
115 // - _: Noncrossing implementation-call discriminator; pass 0.
116 // - rlm: Current realm context forwarded unchanged by the pool proxy.
117 // - token0Path: Registered token contract path for token0.
118 // - token1Path: Registered token contract path for token1.
119 // - fee: Fee tier identifying the pool.
120 // - recipient: Nonzero address receiving collected tokens after any withdrawal fee.
121 // - tickLower: Lower tick of the position's price range.
122 // - tickUpper: Upper tick of the position's price range.
123 // - amount0Requested: Non-negative decimal amount of token0 requested; the int64 maximum requests all owed token0.
124 // - amount1Requested: Non-negative decimal amount of token1 requested; the int64 maximum requests all owed token1.
125 //
126 // Returns:
127 // - amount0: Token0 amount collected before withdrawal-fee deduction, as a decimal string.
128 // - amount1: Token1 amount collected before withdrawal-fee deduction, as a decimal string.
129 // - fee0: Withdrawal fee withheld from token0, as a decimal string.
130 // - fee1: Withdrawal fee withheld from token1, as a decimal string.
131 CollectSwapFee(
132 _ int,
133 rlm realm,
134 token0Path string,
135 token1Path string,
136 fee uint32,
137 recipient address,
138 tickLower int32,
139 tickUpper int32,
140 amount0Requested string,
141 amount1Requested string,
142 ) (amount0, amount1, fee0, fee1 string)
143
144 // Parameters:
145 // - _: Noncrossing implementation-call discriminator; pass 0.
146 // - rlm: Current realm context forwarded unchanged by the pool proxy.
147 // - token0Path: Registered token contract path for token0.
148 // - token1Path: Registered token contract path for token1.
149 // - fee: Fee tier identifying the pool.
150 // - recipient: Nonzero address receiving owed principal.
151 // - tickLower: Lower tick of the position's price range.
152 // - tickUpper: Upper tick of the position's price range.
153 // - amount0Requested: Non-negative decimal amount of token0 principal requested.
154 // - amount1Requested: Non-negative decimal amount of token1 principal requested.
155 //
156 // Returns:
157 // - amount0: Token0 principal transferred to recipient, as a decimal string.
158 // - amount1: Token1 principal transferred to recipient, as a decimal string.
159 Collect(
160 _ int,
161 rlm realm,
162 token0Path string,
163 token1Path string,
164 fee uint32,
165 recipient address,
166 tickLower int32,
167 tickUpper int32,
168 amount0Requested string,
169 amount1Requested string,
170 ) (amount0, amount1 string)
171
172 // Parameters:
173 // - _: Noncrossing implementation-call discriminator; pass 0.
174 // - rlm: Current realm context forwarded unchanged by the pool proxy.
175 // - fee: Withdrawal fee rate in basis points to apply to fee-bearing position payouts.
176 SetWithdrawalFee(_ int, rlm realm, fee uint64)
177}
178
179// IPoolSwap interface defines swap and protocol fee operations.
180// These methods handle token swaps and protocol fee management.
181type IPoolSwap interface {
182 // Parameters:
183 // - _: Noncrossing implementation-call discriminator; pass 0.
184 // - rlm: Current realm context forwarded unchanged by the pool proxy.
185 // - token0Path: Registered token contract path for token0.
186 // - token1Path: Registered token contract path for token1.
187 // - fee: Fee tier identifying the pool.
188 // - recipient: Nonzero address receiving swap output.
189 // - zeroForOne: Swap direction; true swaps token0 for token1, false swaps token1 for token0.
190 // - amountSpecified: Signed decimal amount; positive requests exact input and negative requests exact output.
191 // - sqrtPriceLimitX96: Q96-encoded decimal square-root price limit for the swap.
192 // - swapCallback: Callback that receives the current realm, signed token deltas, and marker, and must settle the input-token balance or return an error.
193 //
194 // Returns:
195 // - amount0: Signed token0 delta produced by the swap, encoded as a decimal string.
196 // - amount1: Signed token1 delta produced by the swap, encoded as a decimal string.
197 Swap(
198 _ int,
199 rlm realm,
200 token0Path string,
201 token1Path string,
202 fee uint32,
203 recipient address,
204 zeroForOne bool,
205 amountSpecified string,
206 sqrtPriceLimitX96 string,
207 swapCallback func(cur realm, amount0Delta, amount1Delta int64, callbackMarker *CallbackMarker) error,
208 ) (string, string)
209
210 // Parameters:
211 // - token0Path: Registered token contract path for token0.
212 // - token1Path: Registered token contract path for token1.
213 // - fee: Fee tier identifying the pool.
214 // - zeroForOne: Swap direction; true swaps token0 for token1, false swaps token1 for token0.
215 // - amountSpecified: Signed decimal amount; positive requests exact input and negative requests exact output.
216 // - sqrtPriceLimitX96: Q96-encoded decimal square-root price limit for the simulated swap.
217 //
218 // Returns:
219 // - amount0: Signed token0 delta predicted by the simulation, encoded as a decimal string.
220 // - amount1: Signed token1 delta predicted by the simulation, encoded as a decimal string.
221 // - err: Non-nil when parsing or swap simulation validation fails; successful simulations return nil.
222 DrySwap(
223 token0Path string,
224 token1Path string,
225 fee uint32,
226 zeroForOne bool,
227 amountSpecified string,
228 sqrtPriceLimitX96 string,
229 ) (string, string, error)
230
231 // Parameters:
232 // - _: Noncrossing implementation-call discriminator; pass 0.
233 // - rlm: Current realm context forwarded unchanged by the pool proxy.
234 // - hook: Callback invoked after a swap with the current realm and pool path; a returned error aborts the swap.
235 SetSwapEndHook(_ int, rlm realm, hook func(cur realm, poolPath string) error)
236
237 // Parameters:
238 // - _: Noncrossing implementation-call discriminator; pass 0.
239 // - rlm: Current realm context forwarded unchanged by the pool proxy.
240 // - hook: Callback invoked before a swap with the current realm, pool path, and block timestamp.
241 SetSwapStartHook(_ int, rlm realm, hook func(cur realm, poolPath string, timestamp int64))
242
243 // Parameters:
244 // - _: Noncrossing implementation-call discriminator; pass 0.
245 // - rlm: Current realm context forwarded unchanged by the pool proxy.
246 // - hook: Callback invoked when a tick is crossed, receiving current realm, pool path, tick id, direction, and timestamp.
247 SetTickCrossHook(_ int, rlm realm, hook func(cur realm, poolPath string, tickId int32, zeroForOne bool, timestamp int64))
248
249 // Parameters:
250 // - _: Noncrossing implementation-call discriminator; pass 0.
251 // - rlm: Current realm context forwarded unchanged by the pool proxy.
252 // - token0Path: Registered token contract path for token0.
253 // - token1Path: Registered token contract path for token1.
254 // - fee: Fee tier identifying the pool.
255 // - recipient: Nonzero address receiving collected protocol fees.
256 // - amount0Requested: Non-negative decimal amount of token0 protocol fees requested, capped by availability.
257 // - amount1Requested: Non-negative decimal amount of token1 protocol fees requested, capped by availability.
258 //
259 // Returns:
260 // - amount0: Token0 protocol fees transferred to recipient, encoded as a decimal string.
261 // - amount1: Token1 protocol fees transferred to recipient, encoded as a decimal string.
262 CollectProtocol(
263 _ int,
264 rlm realm,
265 token0Path string,
266 token1Path string,
267 fee uint32,
268 recipient address,
269 amount0Requested string,
270 amount1Requested string,
271 ) (amount0, amount1 string)
272
273 // Parameters:
274 // - _: Noncrossing implementation-call discriminator; pass 0.
275 // - rlm: Current realm context forwarded unchanged by the pool proxy.
276 // - feeProtocol0: Protocol-fee denominator/configuration for token0 swaps.
277 // - feeProtocol1: Protocol-fee denominator/configuration for token1 swaps.
278 SetFeeProtocol(_ int, rlm realm, feeProtocol0, feeProtocol1 uint8)
279}
280
281// IPoolOracle defines the pool's Uniswap V3-aligned oracle surface.
282//
283// Its public methods mirror the relevant Uniswap V3 pool-state, derived-state,
284// and action specifications, adapted for GnoSwap's singleton pool realm: every
285// operation identifies its pool with poolPath, and uint values cross the public
286// boundary using GnoSwap types or decimal strings rather than the EVM ABI.
287//
288// ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolState.sol#L21-L32
289// ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolDerivedState.sol#L18-L39
290type IPoolOracle interface {
291 // GetSlot0 returns a safe copy of a pool's price, tick, protocol-fee, lock,
292 // and oracle cursor/capacity state, corresponding to Uniswap V3 slot0().
293 //
294 // ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolState.sol#L21-L32
295 // Parameters:
296 // - poolPath: Canonical path identifying the pool whose slot0 state is read.
297 //
298 // Returns:
299 // - slot0: Safe copy of the pool's price, tick, protocol-fee, lock, and oracle cursor/capacity state.
300 GetSlot0(poolPath string) Slot0
301
302 // GetObservationAt returns the observation stored at index, corresponding to
303 // Uniswap V3 observations(uint256). An in-range uninitialized slot returns a
304 // zero observation; an out-of-range index returns an error.
305 //
306 // ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolState.sol#L99-L115
307 // Parameters:
308 // - poolPath: Canonical path identifying the pool containing the observation.
309 // - index: uint16 observation-buffer index to read.
310 //
311 // Returns:
312 // - observation: Stored observation, or the zero observation for an in-range uninitialized slot.
313 // - err: Non-nil when poolPath is unknown or index is outside the pool's observation buffer.
314 GetObservationAt(poolPath string, index uint16) (Observation, error)
315
316 // Observe returns tick and seconds-per-liquidity cumulatives for every
317 // requested lookback, corresponding to Uniswap V3 observe(uint32[]).
318 //
319 // ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolDerivedState.sol#L18-L21
320 // Parameters:
321 // - poolPath: Canonical path identifying the pool whose oracle data is read.
322 // - secondsAgos: Lookback durations in seconds; one cumulative pair is returned for each entry in order.
323 //
324 // Returns:
325 // - tickCumulatives: Signed cumulative ticks corresponding to each requested lookback.
326 // - secondsPerLiquidityCumulativesX128: Q128-scaled seconds-per-liquidity cumulatives as decimal strings, in request order.
327 // - err: Non-nil when the pool or requested lookback cannot be served by its observations.
328 Observe(poolPath string, secondsAgos []uint32) ([]int64, []string, error)
329
330 // SnapshotCumulativesInside returns accumulators accrued while the pool price
331 // was inside [tickLower, tickUpper), corresponding to Uniswap V3
332 // snapshotCumulativesInside(int24,int24).
333 //
334 // ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolDerivedState.sol#L23-L39
335 // Parameters:
336 // - poolPath: Canonical path identifying the pool whose inside accumulators are read.
337 // - tickLower: Lower boundary of the half-open tick range [tickLower, tickUpper).
338 // - tickUpper: Upper boundary of the half-open tick range [tickLower, tickUpper).
339 //
340 // Returns:
341 // - tickCumulativeInside: Signed tick accumulator while the price was inside the range.
342 // - secondsPerLiquidityInsideX128: Q128-scaled seconds-per-liquidity accumulator inside the range.
343 // - secondsInside: Number of seconds for which the price was inside the range.
344 // - err: Non-nil when poolPath or the requested tick range is invalid or unavailable.
345 SnapshotCumulativesInside(
346 poolPath string,
347 tickLower int32,
348 tickUpper int32,
349 ) (int64, *u256.Uint, uint32, error)
350
351 // OracleConsult returns the arithmetic mean tick and harmonic mean liquidity
352 // over secondsAgo, following Uniswap V3 periphery's OracleLibrary.consult.
353 //
354 // ref: https://github.com/Uniswap/v3-periphery/blob/0682387198a24c7cd63566a2c58398533860a5d1/contracts/libraries/OracleLibrary.sol#L16-L41
355 // Parameters:
356 // - poolPath: Canonical path identifying the pool consulted for the time-weighted oracle values.
357 // - secondsAgo: Lookback duration in seconds over which the arithmetic mean tick and harmonic mean liquidity are calculated.
358 //
359 // Returns:
360 // - arithmeticMeanTick: Time-weighted arithmetic mean tick over secondsAgo.
361 // - harmonicMeanLiquidity: Harmonic mean liquidity over secondsAgo, represented as a u256 value.
362 // - err: Non-nil when poolPath is unknown or the requested history is unavailable.
363 OracleConsult(poolPath string, secondsAgo uint32) (int32, *u256.Uint, error)
364
365 // IncreaseObservationCardinalityNext schedules growth of the circular
366 // observation buffer, corresponding to Uniswap V3
367 // increaseObservationCardinalityNext(uint16).
368 //
369 // ref: https://github.com/Uniswap/v3-core/blob/e3589b192d0be27e100cd0daaf6c97204fdb1899/contracts/interfaces/pool/IUniswapV3PoolActions.sol#L98-L102
370 // Parameters:
371 // - _: Noncrossing implementation-call discriminator; pass 0.
372 // - rlm: Current realm context forwarded unchanged by the pool proxy.
373 // - token0Path: Registered token contract path for token0.
374 // - token1Path: Registered token contract path for token1.
375 // - fee: Fee tier identifying the pool.
376 // - cardinalityNext: Requested next observation-buffer capacity; must not exceed the implementation maximum.
377 IncreaseObservationCardinalityNext(
378 _ int,
379 rlm realm,
380 token0Path string,
381 token1Path string,
382 fee uint32,
383 cardinalityNext uint16,
384 )
385}
386
387// IPoolGetter interface defines data retrieval operations.
388// These methods provide read-only access to pool state and data.
389type IPoolGetter interface {
390 // Parameters:
391 // - poolPath: Canonical pool path to test in the pool registry.
392 //
393 // Returns:
394 // - exists: True when a pool is registered at poolPath.
395 ExistsPoolPath(poolPath string) bool
396
397 // Parameters:
398 // - poolPath: Canonical path identifying the pool whose token0 balance is read.
399 //
400 // Returns:
401 // - balanceToken0: Current internal token0 balance recorded for the pool.
402 // - err: Non-nil when poolPath does not identify a registered pool.
403 GetBalanceToken0(poolPath string) (int64, error)
404
405 // Parameters:
406 // - poolPath: Canonical path identifying the pool whose token1 balance is read.
407 //
408 // Returns:
409 // - balanceToken1: Current internal token1 balance recorded for the pool.
410 // - err: Non-nil when poolPath does not identify a registered pool.
411 GetBalanceToken1(poolPath string) (int64, error)
412
413 // Parameters:
414 // - poolPath: Canonical path identifying the pool whose fee tier is read.
415 //
416 // Returns:
417 // - fee: Configured fee tier for the pool.
418 // - err: Non-nil when poolPath does not identify a registered pool.
419 GetFee(poolPath string) (uint32, error)
420
421 // Parameters:
422 // - fee: Fee tier whose configured tick spacing is requested.
423 //
424 // Returns:
425 // - spacing: Tick interval associated with fee.
426 // - err: Non-nil when no tick spacing is configured for fee.
427 GetFeeAmountTickSpacing(fee uint32) (spacing int32, err error)
428
429 // Parameters:
430 // - poolPath: Canonical path identifying the pool whose token0 fee growth is read.
431 //
432 // Returns:
433 // - feeGrowthGlobal0X128: Token0 global fee-growth accumulator scaled by 2^128.
434 // - err: Non-nil when poolPath does not identify a registered pool.
435 GetFeeGrowthGlobal0X128(poolPath string) (*u256.Uint, error)
436
437 // Parameters:
438 // - poolPath: Canonical path identifying the pool whose token1 fee growth is read.
439 //
440 // Returns:
441 // - feeGrowthGlobal1X128: Token1 global fee-growth accumulator scaled by 2^128.
442 // - err: Non-nil when poolPath does not identify a registered pool.
443 GetFeeGrowthGlobal1X128(poolPath string) (*u256.Uint, error)
444
445 // Parameters:
446 // - poolPath: Canonical path identifying the pool whose fee growth is read.
447 //
448 // Returns:
449 // - feeGrowthGlobal0X128: Token0 global fee-growth accumulator scaled by 2^128.
450 // - feeGrowthGlobal1X128: Token1 global fee-growth accumulator scaled by 2^128.
451 // - err: Non-nil when poolPath does not identify a registered pool.
452 GetFeeGrowthGlobalX128(poolPath string) (*u256.Uint, *u256.Uint, error)
453
454 // Parameters:
455 // - poolPath: Canonical path identifying the pool whose active liquidity is read.
456 //
457 // Returns:
458 // - liquidity: Current active liquidity as a u256 value.
459 // - err: Non-nil when poolPath does not identify a registered pool.
460 GetLiquidity(poolPath string) (*u256.Uint, error)
461
462 // Returns:
463 // - pendingProtocolFees: Map from token contract path to pending protocol-fee amount.
464 GetPendingProtocolFees() map[string]int64
465
466 // Returns:
467 // - poolCreationFee: Configured fee amount charged when creating a pool.
468 GetPoolCreationFee() int64
469
470 // Parameters:
471 // - poolPath: Canonical path identifying the pool containing the position.
472 // - key: Encoded position key identifying the position's tick range.
473 //
474 // Returns:
475 // - feeGrowthInside0LastX128: Token0 inside-fee-growth checkpoint as a decimal Q128-scaled string.
476 // - err: Non-nil when poolPath or key cannot be resolved.
477 GetPositionFeeGrowthInside0LastX128(poolPath, key string) (string, error)
478
479 // Parameters:
480 // - poolPath: Canonical path identifying the pool containing the position.
481 // - key: Encoded position key identifying the position's tick range.
482 //
483 // Returns:
484 // - feeGrowthInside1LastX128: Token1 inside-fee-growth checkpoint as a decimal Q128-scaled string.
485 // - err: Non-nil when poolPath or key cannot be resolved.
486 GetPositionFeeGrowthInside1LastX128(poolPath, key string) (string, error)
487
488 // Parameters:
489 // - poolPath: Canonical path identifying the pool containing the position.
490 // - key: Encoded position key identifying the position's tick range.
491 //
492 // Returns:
493 // - feeGrowthInside0LastX128: Token0 inside-fee-growth checkpoint as a decimal Q128-scaled string.
494 // - feeGrowthInside1LastX128: Token1 inside-fee-growth checkpoint as a decimal Q128-scaled string.
495 // - err: Non-nil when poolPath or key cannot be resolved.
496 GetPositionFeeGrowthInsideLastX128(poolPath, key string) (string, string, error)
497
498 // Parameters:
499 // - poolPath: Canonical path identifying the pool containing the position.
500 // - key: Encoded position key identifying the position's tick range.
501 //
502 // Returns:
503 // - liquidity: Position liquidity as a decimal string.
504 // - err: Non-nil when poolPath or key cannot be resolved.
505 GetPositionLiquidity(poolPath, key string) (string, error)
506
507 // Parameters:
508 // - poolPath: Canonical path identifying the pool containing the position.
509 // - key: Encoded position key identifying the position's tick range.
510 //
511 // Returns:
512 // - tokensOwed0: Token0 amount owed to the position in the pool ledger.
513 // - err: Non-nil when poolPath or key cannot be resolved.
514 GetPositionTokensOwed0(poolPath, key string) (int64, error)
515
516 // Parameters:
517 // - poolPath: Canonical path identifying the pool containing the position.
518 // - key: Encoded position key identifying the position's tick range.
519 //
520 // Returns:
521 // - tokensOwed1: Token1 amount owed to the position in the pool ledger.
522 // - err: Non-nil when poolPath or key cannot be resolved.
523 GetPositionTokensOwed1(poolPath, key string) (int64, error)
524
525 // Parameters:
526 // - poolPath: Canonical path identifying the pool whose protocol fees are read.
527 //
528 // Returns:
529 // - protocolFeesToken0: Accrued token0 protocol-fee amount.
530 // - err: Non-nil when poolPath does not identify a registered pool.
531 GetProtocolFeesToken0(poolPath string) (int64, error)
532
533 // Parameters:
534 // - poolPath: Canonical path identifying the pool whose protocol fees are read.
535 //
536 // Returns:
537 // - protocolFeesToken1: Accrued token1 protocol-fee amount.
538 // - err: Non-nil when poolPath does not identify a registered pool.
539 GetProtocolFeesToken1(poolPath string) (int64, error)
540
541 // Parameters:
542 // - poolPath: Canonical path identifying the pool's slot0 protocol fee configuration.
543 //
544 // Returns:
545 // - feeProtocol: Token-direction protocol-fee denominator/configuration stored in slot0.
546 // - err: Non-nil when poolPath does not identify a registered pool.
547 GetSlot0FeeProtocol(poolPath string) (uint8, error)
548
549 // Parameters:
550 // - poolPath: Canonical path identifying the pool's current square-root price.
551 //
552 // Returns:
553 // - sqrtPriceX96: Current square-root price encoded as a u256 Q96 value.
554 // - err: Non-nil when poolPath does not identify a registered pool.
555 GetSlot0SqrtPriceX96(poolPath string) (*u256.Uint, error)
556
557 // Parameters:
558 // - poolPath: Canonical path identifying the pool whose current tick is read.
559 //
560 // Returns:
561 // - tick: Current signed price tick.
562 // - err: Non-nil when poolPath does not identify a registered pool.
563 GetSlot0Tick(poolPath string) (int32, error)
564
565 // Parameters:
566 // - poolPath: Canonical path identifying the pool whose lock state is read.
567 //
568 // Returns:
569 // - unlocked: True when the pool is available for another state-changing operation.
570 // - err: Non-nil when poolPath does not identify a registered pool.
571 GetSlot0Unlocked(poolPath string) (bool, error)
572
573 // Parameters:
574 // - poolPath: Canonical path identifying the pool containing the tick.
575 // - tick: Signed tick whose outside cumulative is requested.
576 //
577 // Returns:
578 // - tickCumulativeOutside: Signed cumulative tick value stored outside tick.
579 // - err: Non-nil when poolPath or tick cannot be resolved.
580 GetTickCumulativeOutside(poolPath string, tick int32) (int64, error)
581
582 // Parameters:
583 // - poolPath: Canonical path identifying the pool containing the tick.
584 // - tick: Signed tick whose token0 fee-growth outside value is requested.
585 //
586 // Returns:
587 // - feeGrowthOutside0X128: Token0 fee-growth outside tick, encoded as a decimal Q128-scaled string.
588 // - err: Non-nil when poolPath or tick cannot be resolved.
589 GetTickFeeGrowthOutside0X128(poolPath string, tick int32) (string, error)
590
591 // Parameters:
592 // - poolPath: Canonical path identifying the pool containing the tick.
593 // - tick: Signed tick whose token1 fee-growth outside value is requested.
594 //
595 // Returns:
596 // - feeGrowthOutside1X128: Token1 fee-growth outside tick, encoded as a decimal Q128-scaled string.
597 // - err: Non-nil when poolPath or tick cannot be resolved.
598 GetTickFeeGrowthOutside1X128(poolPath string, tick int32) (string, error)
599
600 // Parameters:
601 // - poolPath: Canonical path identifying the pool containing the tick.
602 // - tick: Signed tick whose outside fee growth is requested.
603 //
604 // Returns:
605 // - feeGrowthOutside0X128: Token0 fee-growth outside tick, encoded as a decimal Q128-scaled string.
606 // - feeGrowthOutside1X128: Token1 fee-growth outside tick, encoded as a decimal Q128-scaled string.
607 // - err: Non-nil when poolPath or tick cannot be resolved.
608 GetTickFeeGrowthOutsideX128(poolPath string, tick int32) (string, string, error)
609
610 // Parameters:
611 // - poolPath: Canonical path identifying the pool containing the tick.
612 // - tick: Signed tick whose initialization state is requested.
613 //
614 // Returns:
615 // - initialized: True when tick has initialized liquidity/fee-growth state.
616 // - err: Non-nil when poolPath or tick cannot be resolved.
617 GetTickInitialized(poolPath string, tick int32) (bool, error)
618
619 // Parameters:
620 // - poolPath: Canonical path identifying the pool containing the tick.
621 // - tick: Signed tick whose gross liquidity is requested.
622 //
623 // Returns:
624 // - liquidityGross: Gross liquidity associated with tick, encoded as a decimal string.
625 // - err: Non-nil when poolPath or tick cannot be resolved.
626 GetTickLiquidityGross(poolPath string, tick int32) (string, error)
627
628 // Parameters:
629 // - poolPath: Canonical path identifying the pool containing the tick.
630 // - tick: Signed tick whose net liquidity is requested.
631 //
632 // Returns:
633 // - liquidityNet: Signed net liquidity change at tick, encoded as a decimal string.
634 // - err: Non-nil when poolPath or tick cannot be resolved.
635 GetTickLiquidityNet(poolPath string, tick int32) (string, error)
636
637 // Parameters:
638 // - poolPath: Canonical path identifying the pool containing the tick.
639 // - tick: Signed tick whose elapsed outside time is requested.
640 //
641 // Returns:
642 // - secondsOutside: Seconds elapsed outside tick's range.
643 // - err: Non-nil when poolPath or tick cannot be resolved.
644 GetTickSecondsOutside(poolPath string, tick int32) (uint32, error)
645
646 // Parameters:
647 // - poolPath: Canonical path identifying the pool containing the tick.
648 // - tick: Signed tick whose outside seconds-per-liquidity value is requested.
649 //
650 // Returns:
651 // - secondsPerLiquidityOutsideX128: Outside seconds-per-liquidity accumulator encoded as a decimal Q128-scaled string.
652 // - err: Non-nil when poolPath or tick cannot be resolved.
653 GetTickSecondsPerLiquidityOutsideX128(poolPath string, tick int32) (string, error)
654
655 // Parameters:
656 // - poolPath: Canonical path identifying the pool whose tick spacing is read.
657 //
658 // Returns:
659 // - tickSpacing: Configured signed tick interval for the pool.
660 // - err: Non-nil when poolPath does not identify a registered pool.
661 GetTickSpacing(poolPath string) (int32, error)
662
663 // Parameters:
664 // - poolPath: Canonical path identifying the pool whose token0 path is read.
665 //
666 // Returns:
667 // - token0Path: Registered token contract path assigned to token0.
668 // - err: Non-nil when poolPath does not identify a registered pool.
669 GetToken0Path(poolPath string) (string, error)
670
671 // Parameters:
672 // - poolPath: Canonical path identifying the pool whose token1 path is read.
673 //
674 // Returns:
675 // - token1Path: Registered token contract path assigned to token1.
676 // - err: Non-nil when poolPath does not identify a registered pool.
677 GetToken1Path(poolPath string) (string, error)
678
679 // Returns:
680 // - withdrawalFeeBPS: Configured withdrawal fee in basis points.
681 GetWithdrawalFee() uint64
682
683 // Returns:
684 // - pools: Read-only tree containing registered pool entries.
685 GetPools() *rotree.ReadOnlyTree
686 // Returns:
687 // - feeAmountTickSpacings: Map from fee tier to configured tick spacing.
688 GetFeeAmountTickSpacings() map[uint32]int32
689
690 // Parameters:
691 // - poolPath: Canonical path identifying the pool whose positions are viewed.
692 //
693 // Returns:
694 // - positions: Read-only tree containing position entries for poolPath, or nil when poolPath is not registered.
695 GetPoolPositions(poolPath string) *rotree.ReadOnlyTree
696
697 // Parameters:
698 // - poolPath: Canonical path identifying the pool to scan.
699 // - tickLower: Inclusive lower tick bound for the requested range.
700 // - tickUpper: Exclusive upper tick bound for the requested range.
701 //
702 // Returns:
703 // - ticks: Initialized ticks in [tickLower, tickUpper), ordered by tick.
704 // - err: Non-nil when poolPath or the requested range is invalid.
705 GetInitializedTicksInRange(poolPath string, tickLower, tickUpper int32) ([]int32, error)
706
707 // Parameters:
708 // - poolPath: Canonical path identifying the pool containing the tick.
709 // - tick: Signed tick whose complete state is requested.
710 //
711 // Returns:
712 // - info: Tick state including initialization, liquidity, fee-growth, and oracle accumulators.
713 // - err: Non-nil when poolPath or tick cannot be resolved.
714 GetTickInfo(poolPath string, tick int32) (TickInfo, error)
715 // Parameters:
716 // - poolPath: Canonical path identifying the pool whose bitmap is read.
717 // - wordPos: Signed bitmap word position containing 256 tick-initialization bits.
718 //
719 // Returns:
720 // - bitmap: Decimal-encoded bitmap word for wordPos.
721 // - err: Non-nil when poolPath or wordPos cannot be resolved.
722 GetTickBitmaps(poolPath string, wordPos int16) (string, error)
723}
724
725// IPoolStore interface defines the storage abstraction for pool data.
726// This interface provides a clean separation between business logic and storage,
727// allowing different implementations to use the same storage interface.
728//
729// All pool implementations (v1, v2, etc.) use this interface to access
730// and modify pool state, ensuring data consistency across versions.
731type IPoolStore interface {
732 // Returns:
733 // - exists: True when the backing pool registry tree has been initialized.
734 HasPools() bool
735 // Returns:
736 // - pools: Stored B+tree containing pool state entries; the implementation panics if the KV value is unreadable, wrongly typed, or nil.
737 GetPools() *bptree.BPTree
738 // Parameters:
739 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
740 // - rlm: Propagated realm context; the setter rejects a context that is not current.
741 // - pools: B+tree replacing the stored pool registry.
742 //
743 // Returns:
744 // - err: Nil after storing pools; non-nil for a non-current rlm or an underlying KV-store write failure.
745 SetPools(_ int, rlm realm, pools *bptree.BPTree) error
746
747 // Returns:
748 // - exists: True when the backing observation registry tree has been initialized.
749 HasObservations() bool
750 // Returns:
751 // - observations: Stored B+tree containing pool observation trees; the implementation panics if the KV value is unreadable, wrongly typed, or nil.
752 GetObservations() *bptree.BPTree
753 // Parameters:
754 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
755 // - rlm: Propagated realm context; the setter rejects a context that is not current.
756 // - observations: B+tree replacing the stored observation registry.
757 //
758 // Returns:
759 // - err: Nil after storing observations; non-nil for a non-current rlm or an underlying KV-store write failure.
760 SetObservations(_ int, rlm realm, observations *bptree.BPTree) error
761
762 // Returns:
763 // - exists: True when the fee-to-tick-spacing map has been initialized.
764 HasFeeAmountTickSpacing() bool
765 // Returns:
766 // - feeAmountTickSpacing: Stored fee-tier to tick-spacing map; the implementation panics if the KV value is unreadable, wrongly typed, or nil.
767 GetFeeAmountTickSpacing() map[uint32]int32
768 // Parameters:
769 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
770 // - rlm: Propagated realm context; the setter rejects a context that is not current.
771 // - feeAmountTickSpacing: Map replacing the configured fee-tier to tick-spacing values.
772 //
773 // Returns:
774 // - err: Nil after storing the mapping; non-nil for a non-current rlm or an underlying KV-store write failure.
775 SetFeeAmountTickSpacing(_ int, rlm realm, feeAmountTickSpacing map[uint32]int32) error
776
777 // Returns:
778 // - exists: True when the slot0 protocol-fee configuration has been initialized.
779 HasSlot0FeeProtocol() bool
780 // Returns:
781 // - slot0FeeProtocol: Stored packed protocol-fee denominator configuration; the implementation panics if the KV value is unreadable or wrongly typed.
782 GetSlot0FeeProtocol() uint8
783 // Parameters:
784 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
785 // - rlm: Propagated realm context; the setter rejects a context that is not current.
786 // - slot0FeeProtocol: Protocol-fee denominator/configuration to store in slot0.
787 //
788 // Returns:
789 // - err: Nil after storing the value; non-nil for a non-current rlm or an underlying KV-store write failure.
790 SetSlot0FeeProtocol(_ int, rlm realm, slot0FeeProtocol uint8) error
791
792 // Returns:
793 // - exists: True when a pool-creation fee has been initialized.
794 HasPoolCreationFee() bool
795 // Returns:
796 // - poolCreationFee: Stored pool-creation charge in the chain's smallest currency unit; the implementation panics if the KV value is unreadable or wrongly typed.
797 GetPoolCreationFee() int64
798 // Parameters:
799 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
800 // - rlm: Propagated realm context; the setter rejects a context that is not current.
801 // - poolCreationFee: Pool-creation fee amount to store.
802 //
803 // Returns:
804 // - err: Nil after storing the fee; non-nil for a non-current rlm or an underlying KV-store write failure.
805 SetPoolCreationFee(_ int, rlm realm, poolCreationFee int64) error
806
807 // Returns:
808 // - exists: True when the pending protocol-fee map has been initialized.
809 HasPendingProtocolFees() bool
810 // Returns:
811 // - pendingProtocolFees: Stored token-path map of pending protocol-fee amounts in the chain's smallest currency unit; the implementation panics if the KV value is unreadable or wrongly typed.
812 GetPendingProtocolFees() map[string]int64
813 // Parameters:
814 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
815 // - rlm: Propagated realm context; the setter rejects a context that is not current.
816 // - pendingProtocolFees: Map replacing all pending protocol-fee balances.
817 //
818 // Returns:
819 // - err: Nil after storing the map; non-nil for a non-current rlm or an underlying KV-store write failure.
820 SetPendingProtocolFees(_ int, rlm realm, pendingProtocolFees map[string]int64) error
821 // Parameters:
822 // - tokenPath: Registered token contract path whose pending protocol fee is read.
823 //
824 // Returns:
825 // - amount: Pending protocol-fee amount recorded for tokenPath, or zero when none is stored.
826 GetPendingProtocolFee(tokenPath string) int64
827 // Parameters:
828 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
829 // - rlm: Propagated realm context; the setter rejects a context that is not current.
830 // - tokenPath: Registered token contract path whose pending fee is updated.
831 // - amount: Pending protocol-fee amount to store for tokenPath.
832 //
833 // Returns:
834 // - err: Nil after storing the amount; non-nil for a non-current rlm, unauthorized code-realm write, or underlying authorization failure.
835 SetPendingProtocolFee(_ int, rlm realm, tokenPath string, amount int64) error
836 // Parameters:
837 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
838 // - rlm: Propagated realm context; the setter rejects a context that is not current.
839 // - tokenPath: Registered token contract path whose pending fee entry is removed.
840 //
841 // Returns:
842 // - err: Nil after removing the entry; non-nil for a non-current rlm, unauthorized code-realm write, or underlying authorization failure.
843 RemovePendingProtocolFee(_ int, rlm realm, tokenPath string) error
844
845 // Returns:
846 // - exists: True when a withdrawal-fee basis-point value has been initialized.
847 HasWithdrawalFeeBPS() bool
848 // Returns:
849 // - withdrawalFeeBPS: Stored withdrawal fee in basis points.
850 GetWithdrawalFeeBPS() uint64
851 // Parameters:
852 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
853 // - rlm: Propagated realm context; the setter rejects a context that is not current.
854 // - withdrawalFeeBPS: Withdrawal fee rate in basis points to store.
855 //
856 // Returns:
857 // - err: Nil after storing the rate; non-nil for a non-current rlm or an underlying KV-store write failure.
858 SetWithdrawalFeeBPS(_ int, rlm realm, withdrawalFeeBPS uint64) error
859
860 // Returns:
861 // - exists: True when the pool unlocked flag has been initialized.
862 HasUnlocked() bool
863 // Returns:
864 // - unlocked: Persisted global reentrancy-lock state; true means pool operations may proceed without the lock, and malformed/missing storage panics.
865 GetUnlocked() bool
866 // Parameters:
867 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
868 // - rlm: Propagated realm context; the setter rejects a context that is not current.
869 // - unlocked: Lock flag to store; false marks the pool as locked.
870 //
871 // Returns:
872 // - err: Nil after storing the flag; non-nil for a non-current rlm or an underlying KV-store write failure.
873 SetUnlocked(_ int, rlm realm, unlocked bool) error
874
875 // Returns:
876 // - exists: True when a swap-start hook has been initialized.
877 HasSwapStartHook() bool
878 // Returns:
879 // - swapStartHook: Stored callback receiving current realm, pool path, and timestamp; callers should check HasSwapStartHook before retrieving it.
880 GetSwapStartHook() func(cur realm, poolPath string, timestamp int64)
881 // Parameters:
882 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
883 // - rlm: Propagated realm context; the setter rejects a context that is not current.
884 // - swapStartHook: Callback invoked with current realm, pool path, and timestamp before swaps.
885 //
886 // Returns:
887 // - err: Nil after storing the hook; non-nil for a non-current rlm or an underlying KV-store write failure.
888 SetSwapStartHook(_ int, rlm realm, swapStartHook func(cur realm, poolPath string, timestamp int64)) error
889
890 // Returns:
891 // - exists: True when a swap-end hook has been initialized.
892 HasSwapEndHook() bool
893 // Returns:
894 // - swapEndHook: Stored callback receiving current realm and pool path and returning a hook error; callers should check HasSwapEndHook before retrieving it.
895 GetSwapEndHook() func(cur realm, poolPath string) error
896 // Parameters:
897 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
898 // - rlm: Propagated realm context; the setter rejects a context that is not current.
899 // - swapEndHook: Callback invoked with current realm and pool path after swaps; it may return an error.
900 //
901 // Returns:
902 // - err: Nil after storing the hook; non-nil for a non-current rlm or an underlying KV-store write failure.
903 SetSwapEndHook(_ int, rlm realm, swapEndHook func(cur realm, poolPath string) error) error
904
905 // Returns:
906 // - exists: True when a tick-cross hook has been initialized.
907 HasTickCrossHook() bool
908 // Returns:
909 // - tickCrossHook: Stored callback receiving current realm, pool path, crossed tick, direction, and timestamp; callers should check HasTickCrossHook before retrieving it.
910 GetTickCrossHook() func(cur realm, poolPath string, tickId int32, zeroForOne bool, timestamp int64)
911 // Parameters:
912 // - _: Leading integer discriminator forwarded to the storage setter; pass 0.
913 // - rlm: Propagated realm context; the setter rejects a context that is not current.
914 // - tickCrossHook: Callback invoked with current realm, pool path, crossed tick, direction, and timestamp.
915 //
916 // Returns:
917 // - err: Nil after storing the hook; non-nil for a non-current rlm or an underlying KV-store write failure.
918 SetTickCrossHook(_ int, rlm realm, tickCrossHook func(cur realm, poolPath string, tickId int32, zeroForOne bool, timestamp int64)) error
919}
920
921type CallbackMarker struct{}
922
923// NewCallbackMarker allocates a CallbackMarker in the pool realm.
924// Construction must happen here because /r/-declared types can only be
925// allocated in their owning realm (interrealm v2 checkConstructionTime).
926// Callers in other realms (e.g. pool/v1 impl) borrow into pool via
927// borrow rule #1 (function defined in /r/ package).
928// Returns:
929// - marker: New marker value allocated in the pool realm for swap-callback validation.
930func NewCallbackMarker() *CallbackMarker {
931 return &CallbackMarker{}
932}