types.gno
17.48 Kb · 430 lines
1package position
2
3import (
4 u256 "gno.land/p/gnoswap/uint256/v1"
5 rotree "gno.land/p/nt/bptree/rotree/v0"
6 bptree "gno.land/p/nt/bptree/v0"
7)
8
9type IPosition interface {
10 IPositionManager
11 IPositionGetter
12 Render(path string) string
13}
14
15type IPositionManager interface {
16 // Mint creates a new liquidity position NFT.
17 //
18 // Parameters:
19 // - _: leading integer discriminator; callers pass 0
20 // - rlm: propagated realm context; implementations validate it as current before changing state
21 // - token0: path of the first token in the pool
22 // - token1: path of the second token in the pool
23 // - fee: pool fee tier used to identify the pool
24 // - tickLower: lower tick boundary of the position's price range
25 // - tickUpper: upper tick boundary of the position's price range
26 // - amount0Desired: desired amount of token0 to provide
27 // - amount1Desired: desired amount of token1 to provide
28 // - amount0Min: minimum acceptable token0 amount for slippage protection
29 // - amount1Min: minimum acceptable token1 amount for slippage protection
30 // - deadline: transaction expiration timestamp
31 // - mintTo: recipient address of the position NFT
32 // - referrer: referrer identifier used for reward tracking
33 //
34 // Returns:
35 // - positionId: newly minted position NFT token ID
36 // - liquidity: liquidity minted into the position, represented as a decimal string
37 // - amount0: actual amount of token0 added, represented as a decimal string
38 // - amount1: actual amount of token1 added, represented as a decimal string
39 Mint(
40 _ int,
41 rlm realm,
42 token0 string,
43 token1 string,
44 fee uint32,
45 tickLower int32,
46 tickUpper int32,
47 amount0Desired string,
48 amount1Desired string,
49 amount0Min string,
50 amount1Min string,
51 deadline int64,
52 mintTo address,
53 referrer string,
54 ) (uint64, string, string, string)
55
56 // IncreaseLiquidity adds liquidity to an existing position.
57 //
58 // Parameters:
59 // - _: leading integer discriminator; callers pass 0
60 // - rlm: propagated realm context; implementations validate it as current before changing state
61 // - positionId: position NFT token ID to increase
62 // - amount0DesiredStr: desired token0 amount, represented as a decimal string
63 // - amount1DesiredStr: desired token1 amount, represented as a decimal string
64 // - amount0MinStr: minimum acceptable token0 amount for slippage protection
65 // - amount1MinStr: minimum acceptable token1 amount for slippage protection
66 // - deadline: transaction expiration timestamp
67 //
68 // Returns:
69 // - positionId: position NFT token ID that received the liquidity
70 // - liquidity: liquidity amount added to the position (the delta), represented as a decimal string
71 // - amount0: actual token0 amount added, represented as a decimal string
72 // - amount1: actual token1 amount added, represented as a decimal string
73 // - poolKey: canonical pool key for the position
74 IncreaseLiquidity(
75 _ int,
76 rlm realm,
77 positionId uint64,
78 amount0DesiredStr string,
79 amount1DesiredStr string,
80 amount0MinStr string,
81 amount1MinStr string,
82 deadline int64,
83 ) (uint64, string, string, string, string)
84
85 // DecreaseLiquidity removes liquidity from a position.
86 //
87 // Parameters:
88 // - _: leading integer discriminator; callers pass 0
89 // - rlm: propagated realm context; implementations validate it as current before changing state
90 // - positionId: position NFT token ID to decrease
91 // - liquidityStr: liquidity amount to remove, represented as a decimal string
92 // - amount0MinStr: minimum acceptable token0 amount for slippage protection
93 // - amount1MinStr: minimum acceptable token1 amount for slippage protection
94 // - deadline: transaction expiration timestamp
95 //
96 // Returns:
97 // - positionId: position NFT token ID that had liquidity removed
98 // - liquidity: removed liquidity amount, represented as a decimal string
99 // - fee0: token0 fees collected, net of the withdrawal fee
100 // - fee1: token1 fees collected, net of the withdrawal fee
101 // - amount0: principal amount of token0 returned to the caller
102 // - amount1: principal amount of token1 returned to the caller
103 // - poolKey: canonical pool key for the position
104 DecreaseLiquidity(
105 _ int,
106 rlm realm,
107 positionId uint64,
108 liquidityStr string,
109 amount0MinStr string,
110 amount1MinStr string,
111 deadline int64,
112 ) (uint64, string, string, string, string, string, string)
113
114 // Reposition changes the tick range of an existing position.
115 //
116 // Parameters:
117 // - _: leading integer discriminator; callers pass 0
118 // - rlm: propagated realm context; implementations validate it as current before changing state
119 // - positionId: position NFT token ID to reposition
120 // - tickLower: new lower tick boundary of the position's price range
121 // - tickUpper: new upper tick boundary of the position's price range
122 // - amount0DesiredStr: desired token0 amount for the new range, represented as a decimal string
123 // - amount1DesiredStr: desired token1 amount for the new range, represented as a decimal string
124 // - amount0MinStr: minimum acceptable token0 amount for slippage protection
125 // - amount1MinStr: minimum acceptable token1 amount for slippage protection
126 // - deadline: transaction expiration timestamp
127 //
128 // Returns:
129 // - positionId: position NFT token ID that was repositioned
130 // - liquidity: new liquidity amount, represented as a decimal string
131 // - tickLower: lower tick boundary applied to the position
132 // - tickUpper: upper tick boundary applied to the position
133 // - amount0: actual token0 amount added to the new range, represented as a decimal string
134 // - amount1: actual token1 amount added to the new range, represented as a decimal string
135 Reposition(
136 _ int,
137 rlm realm,
138 positionId uint64,
139 tickLower int32,
140 tickUpper int32,
141 amount0DesiredStr string,
142 amount1DesiredStr string,
143 amount0MinStr string,
144 amount1MinStr string,
145 deadline int64,
146 ) (uint64, string, int32, int32, string, string)
147
148 // CollectFee collects accumulated fees from a position.
149 //
150 // Parameters:
151 // - _: leading integer discriminator; callers pass 0
152 // - rlm: propagated realm context; implementations validate it as current before changing state
153 // - positionId: position NFT token ID whose fees are collected
154 //
155 // Returns:
156 // - positionId: position NFT token ID whose fees were collected
157 // - tokensCollected0: token0 fees paid out to the caller, net of the withdrawal fee
158 // - tokensCollected1: token1 fees paid out to the caller, net of the withdrawal fee
159 // - poolKey: canonical pool key for the position
160 // - totalAmount0: token0 fees collected before the withdrawal fee
161 // - totalAmount1: token1 fees collected before the withdrawal fee
162 CollectFee(
163 _ int,
164 rlm realm,
165 positionId uint64,
166 ) (uint64, string, string, string, string, string)
167
168 // SetPositionOperator sets or removes the approved operator for a position.
169 //
170 // Parameters:
171 // - _: leading integer discriminator; callers pass 0
172 // - rlm: propagated realm context; implementations validate it as current before changing state
173 // - positionId: position NFT token ID whose operator is changed
174 // - operator: operator address to approve; the zero address removes the operator
175 SetPositionOperator(
176 _ int,
177 rlm realm,
178 positionId uint64,
179 operator address,
180 )
181}
182
183type IPositionGetter interface {
184 // GetPositions returns a read-only view of all positions.
185 //
186 // Returns:
187 // - positions: read-only tree keyed by decimal position ID
188 GetPositions() *rotree.ReadOnlyTree
189 // IsBurned reports whether a position's empty-position marker is set.
190 //
191 // Parameters:
192 // - positionId: position NFT token ID whose burned marker is queried
193 //
194 // Returns:
195 // - burned: true when the position's empty-position marker is set
196 // - err: non-nil when positionId cannot be resolved
197 IsBurned(positionId uint64) (bool, error)
198 // IsInRange reports whether a position's tick range contains the current pool tick.
199 //
200 // Parameters:
201 // - positionId: position NFT token ID whose range is checked
202 //
203 // Returns:
204 // - inRange: true when the current pool tick lies within the position's tick range
205 // - err: non-nil when positionId cannot be resolved or the associated pool tick cannot be read
206 IsInRange(positionId uint64) (bool, error)
207 // GetPositionOperator returns the approved operator address for a position.
208 //
209 // Parameters:
210 // - positionId: position NFT token ID whose operator is queried
211 //
212 // Returns:
213 // - operator: approved operator address; the zero address means no operator is set
214 // - err: non-nil when positionId cannot be resolved
215 GetPositionOperator(positionId uint64) (address, error)
216 // GetPositionPoolKey returns the pool key associated with a position.
217 //
218 // Parameters:
219 // - positionId: position NFT token ID whose pool is queried
220 //
221 // Returns:
222 // - poolKey: canonical pool key used by the position
223 // - err: non-nil when positionId cannot be resolved
224 GetPositionPoolKey(positionId uint64) (string, error)
225 // GetPositionTickLower returns the lower tick boundary of a position.
226 //
227 // Parameters:
228 // - positionId: position NFT token ID whose lower tick is queried
229 //
230 // Returns:
231 // - tickLower: lower tick boundary of the position's price range
232 // - err: non-nil when positionId cannot be resolved
233 GetPositionTickLower(positionId uint64) (int32, error)
234 // GetPositionTickUpper returns the upper tick boundary of a position.
235 //
236 // Parameters:
237 // - positionId: position NFT token ID whose upper tick is queried
238 //
239 // Returns:
240 // - tickUpper: upper tick boundary of the position's price range
241 // - err: non-nil when positionId cannot be resolved
242 GetPositionTickUpper(positionId uint64) (int32, error)
243 // GetPositionLiquidity returns the stored liquidity amount of a position.
244 //
245 // Parameters:
246 // - positionId: position NFT token ID whose liquidity is queried
247 //
248 // Returns:
249 // - liquidity: position liquidity represented as a decimal string
250 // - err: non-nil when positionId cannot be resolved
251 GetPositionLiquidity(positionId uint64) (string, error)
252 // GetPositionTokenBalances returns current token0 and token1 balances derived for a position.
253 //
254 // Parameters:
255 // - positionId: position NFT token ID whose balances are queried
256 //
257 // Returns:
258 // - balance0: current token0 balance derived from liquidity, ticks, and pool price
259 // - balance1: current token1 balance derived from liquidity, ticks, and pool price
260 // - err: non-nil when positionId cannot be resolved
261 GetPositionTokenBalances(positionId uint64) (int64, int64, error)
262 // GetPositionFeeGrowthInside0LastX128 returns the last fee-growth checkpoint inside a position's range for token0.
263 //
264 // Parameters:
265 // - positionId: position NFT token ID whose token0 fee-growth checkpoint is queried
266 //
267 // Returns:
268 // - feeGrowthInside0LastX128: token0 fee-growth checkpoint as a decimal string
269 // - err: non-nil when positionId cannot be resolved
270 GetPositionFeeGrowthInside0LastX128(positionId uint64) (string, error)
271 // GetPositionFeeGrowthInside1LastX128 returns the last fee-growth checkpoint inside a position's range for token1.
272 //
273 // Parameters:
274 // - positionId: position NFT token ID whose token1 fee-growth checkpoint is queried
275 //
276 // Returns:
277 // - feeGrowthInside1LastX128: token1 fee-growth checkpoint as a decimal string
278 // - err: non-nil when positionId cannot be resolved
279 GetPositionFeeGrowthInside1LastX128(positionId uint64) (string, error)
280 // GetPositionFeeGrowthInsideLastX128 returns the last fee-growth checkpoints inside a position's range for both tokens.
281 //
282 // Parameters:
283 // - positionId: position NFT token ID whose fee-growth checkpoints are queried
284 //
285 // Returns:
286 // - feeGrowthInside0LastX128: token0 fee-growth checkpoint as a decimal string
287 // - feeGrowthInside1LastX128: token1 fee-growth checkpoint as a decimal string
288 // - err: non-nil when positionId cannot be resolved
289 GetPositionFeeGrowthInsideLastX128(positionId uint64) (string, string, error)
290 // GetPositionTicks returns the lower and upper tick boundaries of a position.
291 //
292 // Parameters:
293 // - positionId: position NFT token ID whose tick range is queried
294 //
295 // Returns:
296 // - tickLower: lower tick boundary of the position's price range
297 // - tickUpper: upper tick boundary of the position's price range
298 // - err: non-nil when positionId cannot be resolved
299 GetPositionTicks(positionId uint64) (int32, int32, error)
300 // GetPositionTokensOwed0 returns the token0 amount accrued and owed to a position.
301 //
302 // Parameters:
303 // - positionId: position NFT token ID whose token0 debt is queried
304 //
305 // Returns:
306 // - tokensOwed0: token0 amount currently owed to the position
307 // - err: non-nil when positionId cannot be resolved
308 GetPositionTokensOwed0(positionId uint64) (int64, error)
309 // GetPositionTokensOwed1 returns the token1 amount accrued and owed to a position.
310 //
311 // Parameters:
312 // - positionId: position NFT token ID whose token1 debt is queried
313 //
314 // Returns:
315 // - tokensOwed1: token1 amount currently owed to the position
316 // - err: non-nil when positionId cannot be resolved
317 GetPositionTokensOwed1(positionId uint64) (int64, error)
318 // GetPositionTokensOwed returns token0 and token1 amounts accrued and owed to a position.
319 //
320 // Parameters:
321 // - positionId: position NFT token ID whose accrued token debt is queried
322 //
323 // Returns:
324 // - tokensOwed0: token0 amount currently owed to the position
325 // - tokensOwed1: token1 amount currently owed to the position
326 // - err: non-nil when positionId cannot be resolved
327 GetPositionTokensOwed(positionId uint64) (int64, int64, error)
328 // GetUnclaimedFee returns unclaimed fees for both tokens of a position.
329 //
330 // Parameters:
331 // - positionId: position NFT token ID whose unclaimed fees are queried
332 //
333 // Returns:
334 // - fee0: unclaimed token0 fee amount as a uint256 value
335 // - fee1: unclaimed token1 fee amount as a uint256 value
336 // - err: non-nil when positionId or the associated pool fee-growth data cannot be resolved
337 GetUnclaimedFee(positionId uint64) (*u256.Uint, *u256.Uint, error)
338 // GetPositionOwner returns the owner address of a position NFT.
339 //
340 // Parameters:
341 // - positionId: position NFT token ID whose owner is queried
342 //
343 // Returns:
344 // - owner: address that owns the position NFT
345 // - err: non-nil when the NFT owner lookup fails
346 GetPositionOwner(positionId uint64) (address, error)
347}
348
349type IPositionStore interface {
350 // HasPositionsStoreKey reports whether the positions tree exists in storage.
351 //
352 // Returns:
353 // - exists: true when the positions storage key is present
354 HasPositionsStoreKey() bool
355 // GetPositions returns the mutable positions tree.
356 //
357 // Returns:
358 // - positions: positions tree keyed by decimal position ID
359 GetPositions() *bptree.BPTree
360 // SetPositions stores the complete positions tree.
361 //
362 // Parameters:
363 // - _: leading integer discriminator; callers pass 0
364 // - rlm: propagated realm context; implementations require it to be current for storage writes
365 // - positions: positions tree to persist, keyed by decimal position ID
366 //
367 // Returns:
368 // - err: nil when the tree is stored; non-nil when the realm is spoofed or the write fails
369 SetPositions(_ int, rlm realm, positions *bptree.BPTree) error
370
371 // HasPositionNextIDStoreKey reports whether the next-position-ID value exists.
372 //
373 // Returns:
374 // - exists: true when the next-position-ID storage key is present
375 HasPositionNextIDStoreKey() bool
376 // GetPositionNextID returns the next position NFT ID to allocate.
377 //
378 // Returns:
379 // - nextID: next position ID stored for minting
380 GetPositionNextID() uint64
381 // SetPositionNextID stores the next position NFT ID.
382 //
383 // Parameters:
384 // - _: leading integer discriminator; callers pass 0
385 // - rlm: propagated realm context; implementations require it to be current for storage writes
386 // - nextID: next position ID to persist for the next mint
387 //
388 // Returns:
389 // - err: nil when nextID is stored; non-nil when the realm is spoofed or the write fails
390 SetPositionNextID(_ int, rlm realm, nextID uint64) error
391
392 // HasPosition reports whether an NFT ID is present in the positions tree.
393 //
394 // Parameters:
395 // - positionId: position NFT token ID to look up
396 //
397 // Returns:
398 // - exists: true when positionId has a stored position
399 HasPosition(positionId uint64) bool
400 // GetPosition loads a position by NFT ID.
401 //
402 // Parameters:
403 // - positionId: position NFT token ID to look up
404 //
405 // Returns:
406 // - position: stored position value, or the zero Position when absent
407 // - exists: true when positionId is present; false when no position is stored
408 GetPosition(positionId uint64) (Position, bool)
409 // SetPosition inserts or replaces a position in storage.
410 //
411 // Parameters:
412 // - _: leading integer discriminator; callers pass 0
413 // - rlm: propagated realm context; implementations require it to be current for storage writes
414 // - positionId: position NFT token ID used as the storage key
415 // - position: complete position value to persist
416 //
417 // Returns:
418 // - err: nil when the position tree is updated; non-nil when the realm is spoofed, storage is missing, or the write fails
419 SetPosition(_ int, rlm realm, positionId uint64, position Position) error
420 // RemovePosition deletes a position from storage.
421 //
422 // Parameters:
423 // - _: leading integer discriminator; callers pass 0
424 // - rlm: propagated realm context; implementations require it to be current for storage writes
425 // - positionId: position NFT token ID to remove
426 //
427 // Returns:
428 // - err: nil when the position tree is updated; non-nil when the realm is spoofed, storage is missing, or the write fails
429 RemovePosition(_ int, rlm realm, positionId uint64) error
430}