position.gno

  1package position
  2
  3import bptree "gno.land/p/nt/bptree/v0"
  4
  5// Position represents a liquidity position in a pool.
  6// Each position tracks liquidity, fee-growth checkpoints, tokens owed, and a
  7// burned marker for the position NFT.
  8// All uint256 fields are stored as decimal strings to reduce realm object overhead.
  9type Position struct {
 10	operator  address // address that is approved for spending this token
 11	poolKey   string  // poolPath of the pool which this has lp token
 12	tickLower int32   // the lower tick of the position, bounds are included
 13	tickUpper int32   // the upper tick of the position
 14	liquidity string  // liquidity of the position
 15
 16	// fee growth of the aggregate position as of the last action on the individual position
 17	feeGrowthInside0LastX128 string
 18	feeGrowthInside1LastX128 string
 19
 20	// how many uncollected tokens are owed to the position, as of the last computation
 21	tokensOwed0 int64
 22	tokensOwed1 int64
 23
 24	burned bool // empty-position marker; the NFT itself is not burned
 25}
 26
 27// PoolKey returns the pool identifier associated with the position.
 28//
 29// Returns:
 30//   - poolKey: pool key encoding the position's token pair and fee tier
 31func (p *Position) PoolKey() string {
 32	return p.poolKey
 33}
 34
 35// SetPoolKey stores the pool identifier associated with the position.
 36//
 37// Parameters:
 38//   - poolKey: pool key encoding the position's token pair and fee tier
 39func (p *Position) SetPoolKey(poolKey string) {
 40	p.poolKey = poolKey
 41}
 42
 43// Liquidity returns the position's stored liquidity amount.
 44//
 45// Returns:
 46//   - liquidity: decimal-encoded liquidity currently held by the position
 47func (p *Position) Liquidity() string {
 48	return p.liquidity
 49}
 50
 51// SetLiquidity stores the position's liquidity amount.
 52//
 53// Parameters:
 54//   - liquidity: decimal string representing the position's liquidity
 55func (p *Position) SetLiquidity(liquidity string) {
 56	p.liquidity = liquidity
 57}
 58
 59// TickLower returns the lower tick boundary of the position's range.
 60//
 61// Returns:
 62//   - tickLower: lower tick boundary, inclusive in range checks
 63func (p *Position) TickLower() int32 {
 64	return p.tickLower
 65}
 66
 67// SetTickLower stores the lower tick boundary of the position's range.
 68//
 69// Parameters:
 70//   - tickLower: lower tick boundary used for the position's range
 71func (p *Position) SetTickLower(tickLower int32) {
 72	p.tickLower = tickLower
 73}
 74
 75// TickUpper returns the upper tick boundary of the position's range.
 76//
 77// Returns:
 78//   - tickUpper: upper tick boundary, used as the exclusive end in range checks
 79func (p *Position) TickUpper() int32 {
 80	return p.tickUpper
 81}
 82
 83// SetTickUpper stores the upper tick boundary of the position's range.
 84//
 85// Parameters:
 86//   - tickUpper: upper tick boundary used for the position's range
 87func (p *Position) SetTickUpper(tickUpper int32) {
 88	p.tickUpper = tickUpper
 89}
 90
 91// TokensOwed0 returns the stored amount of token0 owed to the position.
 92//
 93// Returns:
 94//   - tokensOwed0: accrued token0 amount awaiting collection, in token units
 95func (p *Position) TokensOwed0() int64 {
 96	return p.tokensOwed0
 97}
 98
 99// SetTokensOwed0 stores the amount of token0 owed to the position.
100//
101// Parameters:
102//   - tokensOwed0: accrued token0 amount awaiting collection, in token units
103func (p *Position) SetTokensOwed0(tokensOwed0 int64) {
104	p.tokensOwed0 = tokensOwed0
105}
106
107// TokensOwed1 returns the stored amount of token1 owed to the position.
108//
109// Returns:
110//   - tokensOwed1: accrued token1 amount awaiting collection, in token units
111func (p *Position) TokensOwed1() int64 {
112	return p.tokensOwed1
113}
114
115// SetTokensOwed1 stores the amount of token1 owed to the position.
116//
117// Parameters:
118//   - tokensOwed1: accrued token1 amount awaiting collection, in token units
119func (p *Position) SetTokensOwed1(tokensOwed1 int64) {
120	p.tokensOwed1 = tokensOwed1
121}
122
123// FeeGrowthInside0LastX128 returns the token0 fee-growth checkpoint.
124//
125// Returns:
126//   - feeGrowthInside0LastX128: decimal-encoded Q128 fee growth inside the position's range at its last update
127func (p *Position) FeeGrowthInside0LastX128() string {
128	return p.feeGrowthInside0LastX128
129}
130
131// SetFeeGrowthInside0LastX128 stores the token0 fee-growth checkpoint.
132//
133// Parameters:
134//   - feeGrowthInside0LastX128: decimal-encoded Q128 fee growth inside the position's range
135func (p *Position) SetFeeGrowthInside0LastX128(feeGrowthInside0LastX128 string) {
136	p.feeGrowthInside0LastX128 = feeGrowthInside0LastX128
137}
138
139// FeeGrowthInside1LastX128 returns the token1 fee-growth checkpoint.
140//
141// Returns:
142//   - feeGrowthInside1LastX128: decimal-encoded Q128 fee growth inside the position's range at its last update
143func (p *Position) FeeGrowthInside1LastX128() string {
144	return p.feeGrowthInside1LastX128
145}
146
147// SetFeeGrowthInside1LastX128 stores the token1 fee-growth checkpoint.
148//
149// Parameters:
150//   - feeGrowthInside1LastX128: decimal-encoded Q128 fee growth inside the position's range
151func (p *Position) SetFeeGrowthInside1LastX128(feeGrowthInside1LastX128 string) {
152	p.feeGrowthInside1LastX128 = feeGrowthInside1LastX128
153}
154
155// Burned reports the position's empty-position marker.
156//
157// Returns:
158//   - burned: true when the position is marked empty after its balances clear; the position NFT itself is not burned
159func (p *Position) Burned() bool {
160	return p.burned
161}
162
163// SetBurned stores the position's empty-position marker.
164//
165// Parameters:
166//   - burned: marker indicating whether the position is considered empty
167func (p *Position) SetBurned(burned bool) {
168	p.burned = burned
169}
170
171// Operator returns the address approved to operate on the position.
172//
173// Returns:
174//   - operator: approved operator address, or the empty address when no operator is set
175func (p *Position) Operator() address {
176	return p.operator
177}
178
179// SetOperator stores the address approved to operate on the position.
180//
181// Parameters:
182//   - operator: approved operator address; the empty address removes the operator
183func (p *Position) SetOperator(operator address) {
184	p.operator = operator
185}
186
187// IsClear reports whether liquidity and tokens owed are all zero; it does not
188// describe the burned marker.
189//
190// Returns:
191//   - clear: true when stored liquidity and both token-owed counters are zero, regardless of the burned marker
192func (p *Position) IsClear() bool {
193	return isZeroStr(p.liquidity) && p.tokensOwed0 == 0 && p.tokensOwed1 == 0
194}
195
196func isZeroStr(s string) bool {
197	return s == "" || s == "0"
198}
199
200// NewPosition constructs a position from its persisted pool, range, liquidity,
201// fee-growth, owed-token, marker, and operator values.
202//
203// Parameters:
204//   - poolKey: pool key encoding the position's token pair and fee tier
205//   - tickLower: lower tick boundary of the position's range
206//   - tickUpper: upper tick boundary of the position's range
207//   - liquidity: decimal string representing the position's liquidity
208//   - feeGrowthInside0LastX128: decimal-encoded Q128 token0 fee-growth checkpoint
209//   - feeGrowthInside1LastX128: decimal-encoded Q128 token1 fee-growth checkpoint
210//   - tokensOwed0: accrued token0 amount awaiting collection, in token units
211//   - tokensOwed1: accrued token1 amount awaiting collection, in token units
212//   - burned: empty-position marker to store
213//   - operator: approved operator address; the empty address means no operator
214//
215// Returns:
216//   - position: pointer to a position initialized with all supplied values
217func NewPosition(
218	poolKey string,
219	tickLower int32,
220	tickUpper int32,
221	liquidity string,
222	feeGrowthInside0LastX128, feeGrowthInside1LastX128 string,
223	tokensOwed0, tokensOwed1 int64,
224	burned bool,
225	operator address,
226) *Position {
227	return &Position{
228		poolKey:                  poolKey,
229		tickLower:                tickLower,
230		tickUpper:                tickUpper,
231		liquidity:                liquidity,
232		feeGrowthInside0LastX128: feeGrowthInside0LastX128,
233		feeGrowthInside1LastX128: feeGrowthInside1LastX128,
234		tokensOwed0:              tokensOwed0,
235		tokensOwed1:              tokensOwed1,
236		burned:                   burned,
237		operator:                 operator,
238	}
239}
240
241// NewPositionsTree allocates an empty BP-tree for position entries under the
242// position realm context.
243//
244// Returns:
245//   - positionsTree: empty position BP-tree allocated with fanout 16
246func NewPositionsTree() *bptree.BPTree {
247	return bptree.NewBPTreeN(16)
248}