types.gno
8.83 Kb · 223 lines
1package dca
2
3import (
4 rotree "gno.land/p/nt/bptree/rotree/v0"
5 bptree "gno.land/p/nt/bptree/v0"
6)
7
8// These interfaces are the contract between the proxy realm
9// gno.land/r/gnoswap/order/dca and its implementations.
10// Keeping them in an immutable package lets every implementation version
11// compile against the same definitions.
12
13// IDCAOrder is the implementation interface behind the order/dca proxy.
14type IDCAOrder interface {
15 IDCAOrderManager
16 IDCAOrderExecutor
17 IDCAOrderAdmin
18 IDCAOrderGetter
19}
20
21// IDCAOrderManager covers owner-facing order operations.
22type IDCAOrderManager interface {
23 // CreateOrder escrows amountPerExecution*executionCount of inputToken,
24 // and joins the (inputToken, outputToken, interval, slotOffset) group.
25 CreateOrder(
26 _ int,
27 rlm realm,
28 inputToken string,
29 outputToken string,
30 interval int64,
31 slotOffset int64,
32 amountPerExecution int64,
33 executionCount int64,
34 ) uint64
35
36 // CancelOrder pays accrued output, refunds unsold input,
37 // and closes the order. Owner only.
38 CancelOrder(_ int, rlm realm, orderID uint64) (refundedAmount int64, claimedAmount int64)
39
40 // Claim pays accrued output to the order owner. Anyone may call it.
41 Claim(_ int, rlm realm, orderID uint64) (claimedAmount int64)
42}
43
44// IDCAOrderExecutor covers keeper-authorized execution and cancellation,
45// and public batch-claim entry points.
46type IDCAOrderExecutor interface {
47 // ExecuteGroup sells the group's per-round input with a pool swap,
48 // on the pool with the best quote, and credits the output to the orders;
49 // each order's execution fee is deducted when it is paid out.
50 // amountOutMin (0 disables it) is the pool output floor
51 // quoted for expectedAmountIn.
52 // If the group orderAmount differs from expectedAmountIn,
53 // the round reverts so the keeper can quote again.
54 // Passing 0 for both runs the round without a floor.
55 // Every order of the round must be credited at least
56 // max(1, minOrderAmountOut) of output after its own execution fee
57 // rate, or the round reverts.
58 ExecuteGroup(
59 _ int,
60 rlm realm,
61 groupID string,
62 expectedAmountIn int64,
63 amountOutMin int64,
64 minOrderAmountOut int64,
65 ) (executedAmountIn int64, executedAmountOut int64)
66
67 // ClaimGroupOrders pays accrued output to the owners of up to
68 // maxOrderCount orders of a group, after startAfterOrderID in ID order.
69 // It returns the number of orders paid or completed,
70 // and the cursor for the next call (0 when the group is done).
71 ClaimGroupOrders(_ int, rlm realm, groupID string, startAfterOrderID uint64, maxOrderCount int) (claimedOrderCount int, nextCursor uint64)
72
73 // ForceCancelOrder closes an order that blocks its group's rounds,
74 // as CancelOrder does for its owner: accrued output and unsold input
75 // go to the owner. The implementation checks on-chain that the order
76 // blocks its group and rejects any other. Keeper role only.
77 ForceCancelOrder(_ int, rlm realm, orderID uint64) (refundedAmount int64, claimedAmount int64)
78
79 // CollectPendingExecutionFee forwards the execution fee pending for
80 // tokenPath to the protocol fee realm. Anyone may call it.
81 CollectPendingExecutionFee(_ int, rlm realm, tokenPath string) (forwardedAmount int64, pendingAmount int64)
82}
83
84// IDCAOrderAdmin covers admin or governance operations.
85// Every rate is in basis points of BasisPointDenominator.
86type IDCAOrderAdmin interface {
87 // SetExecutionFeeRate sets the share of an order's gross output,
88 // in basis points, sent to the protocol fee realm.
89 // Orders snapshot it at creation; existing orders keep their rate.
90 SetExecutionFeeRate(_ int, rlm realm, executionFeeRate int64)
91
92 // AddAllowedInterval and RemoveAllowedInterval manage the intervals new
93 // orders may use; existing orders keep their interval.
94 AddAllowedInterval(_ int, rlm realm, interval int64)
95 RemoveAllowedInterval(_ int, rlm realm, interval int64)
96 // SetOrderLimits sets the minimum input per execution
97 // and the maximum executions per order.
98 SetOrderLimits(_ int, rlm realm, minAmountPerExecution int64, maxExecutionCount int64)
99
100 // SetMinExecutionGapRate sets the minimum gap between a group's
101 // executions, in basis points of its interval.
102 SetMinExecutionGapRate(_ int, rlm realm, minExecutionGapRate int64)
103
104 // SetMaxClaimBatchSize caps the orders one ClaimGroupOrders call examines.
105 SetMaxClaimBatchSize(_ int, rlm realm, maxClaimBatchSize int64)
106
107 // SetMaxPoolPriceDeviationRate sets how far, in basis points of price, a
108 // pool's price may sit on the favorable side of its swap price limit and
109 // still be quoted; 0 disables the check.
110 SetMaxPoolPriceDeviationRate(_ int, rlm realm, maxPoolPriceDeviationRate int64)
111
112 // SetMaxPairPriceLimitAge sets how long, in seconds, a pair price limit
113 // stays usable after it was set.
114 SetMaxPairPriceLimitAge(_ int, rlm realm, maxPairPriceLimitAge int64)
115
116 // SetSlotStep sets the spacing of the slot offsets
117 // new orders may use at interval.
118 SetSlotStep(_ int, rlm realm, interval int64, slotStep int64)
119
120 // SetTokenMinAmountPerExecution sets the minimum input per execution of
121 // orders selling tokenPath, on top of the global minimum; 0 removes it.
122 // Admin, governance, or the manager role assigned to the selector.
123 SetTokenMinAmountPerExecution(_ int, rlm realm, tokenPath string, minAmountPerExecution int64)
124
125 // SetPairPriceLimit sets the minimum pool output per unit of input,
126 // in Q128, of rounds selling inputToken for outputToken; "0" removes it.
127 // A pair direction without a limit cannot be quoted, executed,
128 // or receive new orders.
129 // Admin, governance, or the manager role assigned to the selector.
130 SetPairPriceLimit(_ int, rlm realm, inputToken string, outputToken string, minOutputPerInputX128 string)
131}
132
133// IDCAOrderGetter covers read-only queries.
134// Returned orders, groups, and configs are copies of the stored state.
135// Store trees are exposed as read-only views keyed as in the store layout;
136// entries that are pointers are copied on every read.
137type IDCAOrderGetter interface {
138 GetConfig() *Config
139 GetNextOrderID() uint64
140
141 ExistsOrder(orderID uint64) bool
142 GetOrder(orderID uint64) (*Order, error)
143 GetOrders() *rotree.ReadOnlyTree
144 GetOrdersByOwner() *rotree.ReadOnlyTree
145 GetOrderIDsByOwner(owner address, startAfterID uint64, count int) []uint64
146 GetClaimableAmount(orderID uint64) int64
147 GetOrderExecutionLogs(orderID uint64, count int) ([]*ExecutionLog, error)
148 GetExecutionLogs() *rotree.ReadOnlyTree
149
150 ExistsGroup(groupID string) bool
151 GetGroup(groupID string) (*Group, error)
152 GetGroups() *rotree.ReadOnlyTree
153 GetGroupRoundMarks(groupID string) *rotree.ReadOnlyTree
154 GetOrdersByGroup() *rotree.ReadOnlyTree
155 GetOrderAmountsByGroup() *rotree.ReadOnlyTree
156 GetOrderIDsByGroup(groupID string, startAfterID uint64, count int) []uint64
157 GetScheduledGroups() *rotree.ReadOnlyTree
158 GetExecutableGroups(cursor string, count int) ([]*Group, error)
159 GetExecutionQuote(groupID string) string
160
161 GetTokenMinAmountPerExecution(tokenPath string) int64
162 GetMinAmountPerExecution(tokenPath string) int64
163 GetTokenMinAmountsPerExecution() *rotree.ReadOnlyTree
164 GetPairPriceLimit(inputToken string, outputToken string) (*PairPriceLimit, bool)
165 GetPairPriceLimits() *rotree.ReadOnlyTree
166
167 GetPendingExecutionFeeAmount(tokenPath string) int64
168 GetPendingExecutionFees() *rotree.ReadOnlyTree
169}
170
171// IDCAOrderStore is the persistent storage shared by all versions.
172type IDCAOrderStore interface {
173 HasOrders() bool
174 GetOrders() *bptree.BPTree
175 SetOrders(_ int, rlm realm, orders *bptree.BPTree) error
176
177 HasOrdersByOwner() bool
178 GetOrdersByOwner() *bptree.BPTree
179 SetOrdersByOwner(_ int, rlm realm, ordersByOwner *bptree.BPTree) error
180
181 HasGroups() bool
182 GetGroups() *bptree.BPTree
183 SetGroups(_ int, rlm realm, groups *bptree.BPTree) error
184
185 HasScheduledGroups() bool
186 GetScheduledGroups() *bptree.BPTree
187 SetScheduledGroups(_ int, rlm realm, groups *bptree.BPTree) error
188
189 HasNextOrderID() bool
190 GetNextOrderID() uint64
191 SetNextOrderID(_ int, rlm realm, id uint64) error
192
193 HasConfig() bool
194 GetConfig() *Config
195 SetConfig(_ int, rlm realm, config *Config) error
196
197 IsExecuting() bool
198 SetExecuting(_ int, rlm realm, executing bool) error
199
200 HasOrdersByGroup() bool
201 GetOrdersByGroup() *bptree.BPTree
202 SetOrdersByGroup(_ int, rlm realm, ordersByGroup *bptree.BPTree) error
203
204 HasPendingExecutionFees() bool
205 GetPendingExecutionFees() *bptree.BPTree
206 SetPendingExecutionFees(_ int, rlm realm, pendingExecutionFees *bptree.BPTree) error
207
208 HasExecutionLogs() bool
209 GetExecutionLogs() *bptree.BPTree
210 SetExecutionLogs(_ int, rlm realm, executionLogs *bptree.BPTree) error
211
212 HasOrderAmountsByGroup() bool
213 GetOrderAmountsByGroup() *bptree.BPTree
214 SetOrderAmountsByGroup(_ int, rlm realm, orderAmountsByGroup *bptree.BPTree) error
215
216 HasTokenMinAmountsPerExecution() bool
217 GetTokenMinAmountsPerExecution() *bptree.BPTree
218 SetTokenMinAmountsPerExecution(_ int, rlm realm, tokenMinAmounts *bptree.BPTree) error
219
220 HasPairPriceLimits() bool
221 GetPairPriceLimits() *bptree.BPTree
222 SetPairPriceLimits(_ int, rlm realm, pairPriceLimits *bptree.BPTree) error
223}