1const ErrSpoofedRealm = "rlm does not match the current crossing frame"

1const (
2	StoreKeyPositions      StoreKey = "positions"      // Positions
3	StoreKeyPositionNextID StoreKey = "positionNextID" // Position next ID
4)

1func CollectFee(
2	cur realm,
3	positionId uint64,
4) (uint64, string, string, string, string, string)

1func DecreaseLiquidity(
2	cur realm,
3	positionId uint64,
4	liquidityStr string,
5	amount0MinStr string,
6	amount1MinStr string,
7	deadline int64,
8) (uint64, string, string, string, string, string, string)

1func GetImplementationPackagePath() string

1func GetPositionFeeGrowthInside0LastX128(positionId uint64) (string, error)

1func GetPositionFeeGrowthInside1LastX128(positionId uint64) (string, error)

1func GetPositionFeeGrowthInsideLastX128(positionId uint64) (string, string, error)

1func GetPositionLiquidity(positionId uint64) (string, error)

1func GetPositionPoolKey(positionId uint64) (string, error)

1func GetPositionTickLower(positionId uint64) (int32, error)

1func GetPositionTickUpper(positionId uint64) (int32, error)

1func GetPositionTicks(positionId uint64) (int32, int32, error)

1func GetPositionToken0Balance(positionId uint64) (int64, error)

1func GetPositionToken1Balance(positionId uint64) (int64, error)

1func GetPositionTokenBalances(positionId uint64) (int64, int64, error)

1func GetPositionTokensOwed(positionId uint64) (int64, int64, error)

1func GetPositionTokensOwed0(positionId uint64) (int64, error)

1func GetPositionTokensOwed1(positionId uint64) (int64, error)

1func GetPositions() *rotree.ReadOnlyTree

1func GetUnclaimedFee(positionId uint64) (string, string, error)

1func IncreaseLiquidity(
2	cur realm,
3	positionId uint64,
4	amount0DesiredStr string,
5	amount1DesiredStr string,
6	amount0MinStr string,
7	amount1MinStr string,
8	deadline int64,
9) (uint64, string, string, string, string)

1func IsBurned(positionId uint64) (bool, error)

1func IsInRange(positionId uint64) (bool, error)

 1func Mint(
 2	cur realm,
 3	token0 string,
 4	token1 string,
 5	fee uint32,
 6	tickLower int32,
 7	tickUpper int32,
 8	amount0Desired string,
 9	amount1Desired string,
10	amount0Min string,
11	amount1Min string,
12	deadline int64,
13	mintTo address,
14	referrer string,
15) (uint64, string, string, string)

1func NewPositionsTree() *bptree.BPTree

1func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, positionStore IPositionStore) IPosition)

1func Render(path string) string

 1func Reposition(
 2	cur realm,
 3	positionId uint64,
 4	tickLower int32,
 5	tickUpper int32,
 6	amount0DesiredStr string,
 7	amount1DesiredStr string,
 8	amount0MinStr string,
 9	amount1MinStr string,
10	deadline int64,
11) (uint64, string, int32, int32, string, string)

1func SetPositionOperator(
2	cur realm,
3	positionId uint64,
4	operator address,
5)

1func UpgradeImpl(cur realm, packagePath string)

1func NewPositionStore(kvStore store.KVStore) IPositionStore

 1func NewPosition(
 2	poolKey string,
 3	tickLower int32,
 4	tickUpper int32,
 5	liquidity string,
 6	feeGrowthInside0LastX128, feeGrowthInside1LastX128 string,
 7	tokensOwed0, tokensOwed1 int64,
 8	burned bool,
 9	operator address,
10) *Position

1type IPosition interface {
2	IPositionManager
3	IPositionGetter
4	Render(path string) string
5}

  1type IPositionGetter interface {
  2	// GetPositions returns a read-only view of all positions.
  3	//
  4	// Returns:
  5	//   - positions: read-only tree keyed by decimal position ID
  6	GetPositions() *rotree.ReadOnlyTree
  7	// IsBurned reports whether a position's empty-position marker is set.
  8	//
  9	// Parameters:
 10	//   - positionId: position NFT token ID whose burned marker is queried
 11	//
 12	// Returns:
 13	//   - burned: true when the position's empty-position marker is set
 14	//   - err: non-nil when positionId cannot be resolved
 15	IsBurned(positionId uint64) (bool, error)
 16	// IsInRange reports whether a position's tick range contains the current pool tick.
 17	//
 18	// Parameters:
 19	//   - positionId: position NFT token ID whose range is checked
 20	//
 21	// Returns:
 22	//   - inRange: true when the current pool tick lies within the position's tick range
 23	//   - err: non-nil when positionId cannot be resolved or the associated pool tick cannot be read
 24	IsInRange(positionId uint64) (bool, error)
 25	// GetPositionOperator returns the approved operator address for a position.
 26	//
 27	// Parameters:
 28	//   - positionId: position NFT token ID whose operator is queried
 29	//
 30	// Returns:
 31	//   - operator: approved operator address; the zero address means no operator is set
 32	//   - err: non-nil when positionId cannot be resolved
 33	GetPositionOperator(positionId uint64) (address, error)
 34	// GetPositionPoolKey returns the pool key associated with a position.
 35	//
 36	// Parameters:
 37	//   - positionId: position NFT token ID whose pool is queried
 38	//
 39	// Returns:
 40	//   - poolKey: canonical pool key used by the position
 41	//   - err: non-nil when positionId cannot be resolved
 42	GetPositionPoolKey(positionId uint64) (string, error)
 43	// GetPositionTickLower returns the lower tick boundary of a position.
 44	//
 45	// Parameters:
 46	//   - positionId: position NFT token ID whose lower tick is queried
 47	//
 48	// Returns:
 49	//   - tickLower: lower tick boundary of the position's price range
 50	//   - err: non-nil when positionId cannot be resolved
 51	GetPositionTickLower(positionId uint64) (int32, error)
 52	// GetPositionTickUpper returns the upper tick boundary of a position.
 53	//
 54	// Parameters:
 55	//   - positionId: position NFT token ID whose upper tick is queried
 56	//
 57	// Returns:
 58	//   - tickUpper: upper tick boundary of the position's price range
 59	//   - err: non-nil when positionId cannot be resolved
 60	GetPositionTickUpper(positionId uint64) (int32, error)
 61	// GetPositionLiquidity returns the stored liquidity amount of a position.
 62	//
 63	// Parameters:
 64	//   - positionId: position NFT token ID whose liquidity is queried
 65	//
 66	// Returns:
 67	//   - liquidity: position liquidity represented as a decimal string
 68	//   - err: non-nil when positionId cannot be resolved
 69	GetPositionLiquidity(positionId uint64) (string, error)
 70	// GetPositionTokenBalances returns current token0 and token1 balances derived for a position.
 71	//
 72	// Parameters:
 73	//   - positionId: position NFT token ID whose balances are queried
 74	//
 75	// Returns:
 76	//   - balance0: current token0 balance derived from liquidity, ticks, and pool price
 77	//   - balance1: current token1 balance derived from liquidity, ticks, and pool price
 78	//   - err: non-nil when positionId cannot be resolved
 79	GetPositionTokenBalances(positionId uint64) (int64, int64, error)
 80	// GetPositionFeeGrowthInside0LastX128 returns the last fee-growth checkpoint inside a position's range for token0.
 81	//
 82	// Parameters:
 83	//   - positionId: position NFT token ID whose token0 fee-growth checkpoint is queried
 84	//
 85	// Returns:
 86	//   - feeGrowthInside0LastX128: token0 fee-growth checkpoint as a decimal string
 87	//   - err: non-nil when positionId cannot be resolved
 88	GetPositionFeeGrowthInside0LastX128(positionId uint64) (string, error)
 89	// GetPositionFeeGrowthInside1LastX128 returns the last fee-growth checkpoint inside a position's range for token1.
 90	//
 91	// Parameters:
 92	//   - positionId: position NFT token ID whose token1 fee-growth checkpoint is queried
 93	//
 94	// Returns:
 95	//   - feeGrowthInside1LastX128: token1 fee-growth checkpoint as a decimal string
 96	//   - err: non-nil when positionId cannot be resolved
 97	GetPositionFeeGrowthInside1LastX128(positionId uint64) (string, error)
 98	// GetPositionFeeGrowthInsideLastX128 returns the last fee-growth checkpoints inside a position's range for both tokens.
 99	//
100	// Parameters:
101	//   - positionId: position NFT token ID whose fee-growth checkpoints are queried
102	//
103	// Returns:
104	//   - feeGrowthInside0LastX128: token0 fee-growth checkpoint as a decimal string
105	//   - feeGrowthInside1LastX128: token1 fee-growth checkpoint as a decimal string
106	//   - err: non-nil when positionId cannot be resolved
107	GetPositionFeeGrowthInsideLastX128(positionId uint64) (string, string, error)
108	// GetPositionTicks returns the lower and upper tick boundaries of a position.
109	//
110	// Parameters:
111	//   - positionId: position NFT token ID whose tick range is queried
112	//
113	// Returns:
114	//   - tickLower: lower tick boundary of the position's price range
115	//   - tickUpper: upper tick boundary of the position's price range
116	//   - err: non-nil when positionId cannot be resolved
117	GetPositionTicks(positionId uint64) (int32, int32, error)
118	// GetPositionTokensOwed0 returns the token0 amount accrued and owed to a position.
119	//
120	// Parameters:
121	//   - positionId: position NFT token ID whose token0 debt is queried
122	//
123	// Returns:
124	//   - tokensOwed0: token0 amount currently owed to the position
125	//   - err: non-nil when positionId cannot be resolved
126	GetPositionTokensOwed0(positionId uint64) (int64, error)
127	// GetPositionTokensOwed1 returns the token1 amount accrued and owed to a position.
128	//
129	// Parameters:
130	//   - positionId: position NFT token ID whose token1 debt is queried
131	//
132	// Returns:
133	//   - tokensOwed1: token1 amount currently owed to the position
134	//   - err: non-nil when positionId cannot be resolved
135	GetPositionTokensOwed1(positionId uint64) (int64, error)
136	// GetPositionTokensOwed returns token0 and token1 amounts accrued and owed to a position.
137	//
138	// Parameters:
139	//   - positionId: position NFT token ID whose accrued token debt is queried
140	//
141	// Returns:
142	//   - tokensOwed0: token0 amount currently owed to the position
143	//   - tokensOwed1: token1 amount currently owed to the position
144	//   - err: non-nil when positionId cannot be resolved
145	GetPositionTokensOwed(positionId uint64) (int64, int64, error)
146	// GetUnclaimedFee returns unclaimed fees for both tokens of a position.
147	//
148	// Parameters:
149	//   - positionId: position NFT token ID whose unclaimed fees are queried
150	//
151	// Returns:
152	//   - fee0: unclaimed token0 fee amount as a uint256 value
153	//   - fee1: unclaimed token1 fee amount as a uint256 value
154	//   - err: non-nil when positionId or the associated pool fee-growth data cannot be resolved
155	GetUnclaimedFee(positionId uint64) (*u256.Uint, *u256.Uint, error)
156	// GetPositionOwner returns the owner address of a position NFT.
157	//
158	// Parameters:
159	//   - positionId: position NFT token ID whose owner is queried
160	//
161	// Returns:
162	//   - owner: address that owns the position NFT
163	//   - err: non-nil when the NFT owner lookup fails
164	GetPositionOwner(positionId uint64) (address, error)
165}

  1type IPositionManager interface {
  2	// Mint creates a new liquidity position NFT.
  3	//
  4	// Parameters:
  5	//   - _: leading integer discriminator; callers pass 0
  6	//   - rlm: propagated realm context; implementations validate it as current before changing state
  7	//   - token0: path of the first token in the pool
  8	//   - token1: path of the second token in the pool
  9	//   - fee: pool fee tier used to identify the pool
 10	//   - tickLower: lower tick boundary of the position's price range
 11	//   - tickUpper: upper tick boundary of the position's price range
 12	//   - amount0Desired: desired amount of token0 to provide
 13	//   - amount1Desired: desired amount of token1 to provide
 14	//   - amount0Min: minimum acceptable token0 amount for slippage protection
 15	//   - amount1Min: minimum acceptable token1 amount for slippage protection
 16	//   - deadline: transaction expiration timestamp
 17	//   - mintTo: recipient address of the position NFT
 18	//   - referrer: referrer identifier used for reward tracking
 19	//
 20	// Returns:
 21	//   - positionId: newly minted position NFT token ID
 22	//   - liquidity: liquidity minted into the position, represented as a decimal string
 23	//   - amount0: actual amount of token0 added, represented as a decimal string
 24	//   - amount1: actual amount of token1 added, represented as a decimal string
 25	Mint(
 26		_ int,
 27		rlm realm,
 28		token0 string,
 29		token1 string,
 30		fee uint32,
 31		tickLower int32,
 32		tickUpper int32,
 33		amount0Desired string,
 34		amount1Desired string,
 35		amount0Min string,
 36		amount1Min string,
 37		deadline int64,
 38		mintTo address,
 39		referrer string,
 40	) (uint64, string, string, string)
 41
 42	// IncreaseLiquidity adds liquidity to an existing position.
 43	//
 44	// Parameters:
 45	//   - _: leading integer discriminator; callers pass 0
 46	//   - rlm: propagated realm context; implementations validate it as current before changing state
 47	//   - positionId: position NFT token ID to increase
 48	//   - amount0DesiredStr: desired token0 amount, represented as a decimal string
 49	//   - amount1DesiredStr: desired token1 amount, represented as a decimal string
 50	//   - amount0MinStr: minimum acceptable token0 amount for slippage protection
 51	//   - amount1MinStr: minimum acceptable token1 amount for slippage protection
 52	//   - deadline: transaction expiration timestamp
 53	//
 54	// Returns:
 55	//   - positionId: position NFT token ID that received the liquidity
 56	//   - liquidity: liquidity amount added to the position (the delta), represented as a decimal string
 57	//   - amount0: actual token0 amount added, represented as a decimal string
 58	//   - amount1: actual token1 amount added, represented as a decimal string
 59	//   - poolKey: canonical pool key for the position
 60	IncreaseLiquidity(
 61		_ int,
 62		rlm realm,
 63		positionId uint64,
 64		amount0DesiredStr string,
 65		amount1DesiredStr string,
 66		amount0MinStr string,
 67		amount1MinStr string,
 68		deadline int64,
 69	) (uint64, string, string, string, string)
 70
 71	// DecreaseLiquidity removes liquidity from a position.
 72	//
 73	// Parameters:
 74	//   - _: leading integer discriminator; callers pass 0
 75	//   - rlm: propagated realm context; implementations validate it as current before changing state
 76	//   - positionId: position NFT token ID to decrease
 77	//   - liquidityStr: liquidity amount to remove, represented as a decimal string
 78	//   - amount0MinStr: minimum acceptable token0 amount for slippage protection
 79	//   - amount1MinStr: minimum acceptable token1 amount for slippage protection
 80	//   - deadline: transaction expiration timestamp
 81	//
 82	// Returns:
 83	//   - positionId: position NFT token ID that had liquidity removed
 84	//   - liquidity: removed liquidity amount, represented as a decimal string
 85	//   - fee0: token0 fees collected, net of the withdrawal fee
 86	//   - fee1: token1 fees collected, net of the withdrawal fee
 87	//   - amount0: principal amount of token0 returned to the caller
 88	//   - amount1: principal amount of token1 returned to the caller
 89	//   - poolKey: canonical pool key for the position
 90	DecreaseLiquidity(
 91		_ int,
 92		rlm realm,
 93		positionId uint64,
 94		liquidityStr string,
 95		amount0MinStr string,
 96		amount1MinStr string,
 97		deadline int64,
 98	) (uint64, string, string, string, string, string, string)
 99
100	// Reposition changes the tick range of an existing position.
101	//
102	// Parameters:
103	//   - _: leading integer discriminator; callers pass 0
104	//   - rlm: propagated realm context; implementations validate it as current before changing state
105	//   - positionId: position NFT token ID to reposition
106	//   - tickLower: new lower tick boundary of the position's price range
107	//   - tickUpper: new upper tick boundary of the position's price range
108	//   - amount0DesiredStr: desired token0 amount for the new range, represented as a decimal string
109	//   - amount1DesiredStr: desired token1 amount for the new range, represented as a decimal string
110	//   - amount0MinStr: minimum acceptable token0 amount for slippage protection
111	//   - amount1MinStr: minimum acceptable token1 amount for slippage protection
112	//   - deadline: transaction expiration timestamp
113	//
114	// Returns:
115	//   - positionId: position NFT token ID that was repositioned
116	//   - liquidity: new liquidity amount, represented as a decimal string
117	//   - tickLower: lower tick boundary applied to the position
118	//   - tickUpper: upper tick boundary applied to the position
119	//   - amount0: actual token0 amount added to the new range, represented as a decimal string
120	//   - amount1: actual token1 amount added to the new range, represented as a decimal string
121	Reposition(
122		_ int,
123		rlm realm,
124		positionId uint64,
125		tickLower int32,
126		tickUpper int32,
127		amount0DesiredStr string,
128		amount1DesiredStr string,
129		amount0MinStr string,
130		amount1MinStr string,
131		deadline int64,
132	) (uint64, string, int32, int32, string, string)
133
134	// CollectFee collects accumulated fees from a position.
135	//
136	// Parameters:
137	//   - _: leading integer discriminator; callers pass 0
138	//   - rlm: propagated realm context; implementations validate it as current before changing state
139	//   - positionId: position NFT token ID whose fees are collected
140	//
141	// Returns:
142	//   - positionId: position NFT token ID whose fees were collected
143	//   - tokensCollected0: token0 fees paid out to the caller, net of the withdrawal fee
144	//   - tokensCollected1: token1 fees paid out to the caller, net of the withdrawal fee
145	//   - poolKey: canonical pool key for the position
146	//   - totalAmount0: token0 fees collected before the withdrawal fee
147	//   - totalAmount1: token1 fees collected before the withdrawal fee
148	CollectFee(
149		_ int,
150		rlm realm,
151		positionId uint64,
152	) (uint64, string, string, string, string, string)
153
154	// SetPositionOperator sets or removes the approved operator for a position.
155	//
156	// Parameters:
157	//   - _: leading integer discriminator; callers pass 0
158	//   - rlm: propagated realm context; implementations validate it as current before changing state
159	//   - positionId: position NFT token ID whose operator is changed
160	//   - operator: operator address to approve; the zero address removes the operator
161	SetPositionOperator(
162		_ int,
163		rlm realm,
164		positionId uint64,
165		operator address,
166	)
167}

 1type IPositionStore interface {
 2	// HasPositionsStoreKey reports whether the positions tree exists in storage.
 3	//
 4	// Returns:
 5	//   - exists: true when the positions storage key is present
 6	HasPositionsStoreKey() bool
 7	// GetPositions returns the mutable positions tree.
 8	//
 9	// Returns:
10	//   - positions: positions tree keyed by decimal position ID
11	GetPositions() *bptree.BPTree
12	// SetPositions stores the complete positions tree.
13	//
14	// Parameters:
15	//   - _: leading integer discriminator; callers pass 0
16	//   - rlm: propagated realm context; implementations require it to be current for storage writes
17	//   - positions: positions tree to persist, keyed by decimal position ID
18	//
19	// Returns:
20	//   - err: nil when the tree is stored; non-nil when the realm is spoofed or the write fails
21	SetPositions(_ int, rlm realm, positions *bptree.BPTree) error
22
23	// HasPositionNextIDStoreKey reports whether the next-position-ID value exists.
24	//
25	// Returns:
26	//   - exists: true when the next-position-ID storage key is present
27	HasPositionNextIDStoreKey() bool
28	// GetPositionNextID returns the next position NFT ID to allocate.
29	//
30	// Returns:
31	//   - nextID: next position ID stored for minting
32	GetPositionNextID() uint64
33	// SetPositionNextID stores the next position NFT ID.
34	//
35	// Parameters:
36	//   - _: leading integer discriminator; callers pass 0
37	//   - rlm: propagated realm context; implementations require it to be current for storage writes
38	//   - nextID: next position ID to persist for the next mint
39	//
40	// Returns:
41	//   - err: nil when nextID is stored; non-nil when the realm is spoofed or the write fails
42	SetPositionNextID(_ int, rlm realm, nextID uint64) error
43
44	// HasPosition reports whether an NFT ID is present in the positions tree.
45	//
46	// Parameters:
47	//   - positionId: position NFT token ID to look up
48	//
49	// Returns:
50	//   - exists: true when positionId has a stored position
51	HasPosition(positionId uint64) bool
52	// GetPosition loads a position by NFT ID.
53	//
54	// Parameters:
55	//   - positionId: position NFT token ID to look up
56	//
57	// Returns:
58	//   - position: stored position value, or the zero Position when absent
59	//   - exists: true when positionId is present; false when no position is stored
60	GetPosition(positionId uint64) (Position, bool)
61	// SetPosition inserts or replaces a position in storage.
62	//
63	// Parameters:
64	//   - _: leading integer discriminator; callers pass 0
65	//   - rlm: propagated realm context; implementations require it to be current for storage writes
66	//   - positionId: position NFT token ID used as the storage key
67	//   - position: complete position value to persist
68	//
69	// Returns:
70	//   - err: nil when the position tree is updated; non-nil when the realm is spoofed, storage is missing, or the write fails
71	SetPosition(_ int, rlm realm, positionId uint64, position Position) error
72	// RemovePosition deletes a position from storage.
73	//
74	// Parameters:
75	//   - _: leading integer discriminator; callers pass 0
76	//   - rlm: propagated realm context; implementations require it to be current for storage writes
77	//   - positionId: position NFT token ID to remove
78	//
79	// Returns:
80	//   - err: nil when the position tree is updated; non-nil when the realm is spoofed, storage is missing, or the write fails
81	RemovePosition(_ int, rlm realm, positionId uint64) error
82}

 1type Position struct {
 2	operator  address // address that is approved for spending this token
 3	poolKey   string  // poolPath of the pool which this has lp token
 4	tickLower int32   // the lower tick of the position, bounds are included
 5	tickUpper int32   // the upper tick of the position
 6	liquidity string  // liquidity of the position
 7
 8	// fee growth of the aggregate position as of the last action on the individual position
 9	feeGrowthInside0LastX128 string
10	feeGrowthInside1LastX128 string
11
12	// how many uncollected tokens are owed to the position, as of the last computation
13	tokensOwed0 int64
14	tokensOwed1 int64
15
16	burned bool // empty-position marker; the NFT itself is not burned
17}

1type StoreKey string