-
Notifications
You must be signed in to change notification settings - Fork 27
/
interfaces.ts
312 lines (290 loc) · 9.3 KB
/
interfaces.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
import { LogParams } from 'ethers'
/**
* Used to specify which type of event to listen for.
*/
export enum StreamEventType {
Bundle = 'bundle',
Transaction = 'transaction',
}
export type StreamEventName = `${StreamEventType}`
/** Data about the event history endpoint. */
export type EventHistoryInfo = {
count: number,
minBlock: number,
maxBlock: number,
minTimestamp: number,
maxTimestamp: number,
maxLimit: number,
}
/** Arguments for the `getEventHistory` function. */
export type EventHistoryParams = {
blockStart?: number,
blockEnd?: number,
timestampStart?: number,
timestampEnd?: number,
limit?: number,
offset?: number,
}
/** Raw data about an event from the getEventHistory function. */
export type IEventHistoryEntry = {
block: number,
timestamp: number,
hint: {
txs?: Array<{
to: string,
callData: string,
functionSelector: string,
}>,
hash: string,
logs?: Array<LogParams>,
gasUsed: string,
mevGasPrice: string,
}
}
/**
* Configuration used to connect to the MEV-Share node.
*
* Use [supportedNetworks](./networks.ts) for presets.
*/
export type MevShareNetwork = {
/** Matchmaker event stream URL. */
streamUrl: string,
/** MEV-Share bundle & transaction API URL. */
apiUrl: string,
/** Custom headers to add to api requests to the apiUrl */
apiHeaders?: { [key: string]: string }
}
/**
* Hints specify which data is shared with searchers on mev-share.
*/
export interface HintPreferences {
/** Share the calldata of the transaction. */
calldata?: boolean,
/** Share the contract address of the transaction. */
contractAddress?: boolean,
/** Share the 4byte function selector of the transaction. */
functionSelector?: boolean,
/** Share all logs emitted by the transaction. */
logs?: boolean,
/** Share specific subset of swap-adjacent logs of the transaction. */
defaultLogs?: boolean,
/** Share tx hashes of transactions in bundle. */
txHash?: boolean,
}
/**
* Parameters accepted by the `sendTransaction` function.
*/
export interface TransactionOptions {
/** Hints define what data about a transaction is shared with searchers. */
hints?: HintPreferences,
/** Maximum block number for the transaction to be included in. */
maxBlockNumber?: number,
builders?: string[],
}
/**
* Parameters sent to mev_sendBundle.
*/
export interface BundleParams {
/** Smart bundle spec version. */
version?: string,
/** Conditions for the bundle to be considered for inclusion in a block, evaluated _before_ the bundle is placed in a block. */
inclusion: {
/** Target block number in which to include the bundle. */
block: number,
/** Maximum block height in which the bundle can be included. */
maxBlock?: number,
},
/** Transactions that make up the bundle. `hash` refers to a transaction hash from the MEV-Share event stream. */
body: Array<
{ hash: string } |
{ tx: string, canRevert: boolean } |
{ bundle: BundleParams }
>,
/** Conditions for bundle to be considered for inclusion in a block, evaluated _after_ the bundle is placed in the block. */
validity?: {
/** Conditions for receiving refunds (MEV kickbacks). */
refund?: Array<{
/** Index of entry in `body` to which the refund percentage applies. */
bodyIdx: number,
/** Minimum refund percentage required for this bundle to be eligible for use by another searcher. */
percent: number,
}>,
/** Specifies how refund should be paid if bundle is used by another searcher. */
refundConfig?: Array<{
/** The address that receives this portion of the refund. */
address: string,
/** Percentage of refund to be paid to `address`. Set this to `100` unless splitting refunds between multiple recipients. */
percent: number,
}>,
},
/** Bundle privacy parameters. */
privacy?: {
/** Data fields from bundle transactions to be shared with searchers on MEV-Share. */
hints?: HintPreferences,
/** Builders that are allowed to receive this bundle. See [dowg](https://github.com/flashbots/dowg/blob/main/builder-registrations.json) for supported builders. */
builders?: Array<string>,
},
metadata?: {
originId?: string,
}
}
/** Response received from MEV-Share API */
interface ISendBundleResponse {
/** Bundle hash. */
bundleHash: string,
}
/** Bundle details. */
export interface ISendBundleResult {
/** Bundle hash. */
bundleHash: string,
}
/** Decodes a raw sendBundle response. */
export const SendBundleResult = (response: ISendBundleResponse): ISendBundleResult => ({
bundleHash: response.bundleHash,
})
/** Optional fields to override simulation state. */
export interface SimBundleOptions {
/** Block used for simulation state. Defaults to latest block.
*
* Block header data will be derived from parent block by default.
* Specify other params in this interface to override the default values.
*
* Can be a block number or block hash.
*/
parentBlock?: number | string,
// override the default values for the parentBlock header
/** default = parentBlock.number + 1 */
blockNumber?: number,
/** default = parentBlock.coinbase */
coinbase?: string,
/** default = parentBlock.timestamp + 12 */
timestamp?: number,
/** default = parentBlock.gasLimit */
gasLimit?: number,
/** default = parentBlock.baseFeePerGas */
baseFee?: bigint,
/** default = 5 (defined in seconds) */
timeout?: number,
}
/** Logs returned by mev_simBundle. */
export interface SimBundleLogs {
txLogs?: LogParams[],
bundleLogs?: SimBundleLogs[],
}
/** Response received from MEV-Share api. */
interface ISimBundleResponse {
success: boolean,
error?: string,
stateBlock: string,
mevGasPrice: string,
profit: string,
refundableValue: string,
gasUsed: string,
logs?: SimBundleLogs[],
}
/** Simulation details. */
export interface ISimBundleResult {
success: boolean,
error?: string,
stateBlock: number,
mevGasPrice: bigint,
profit: bigint,
refundableValue: bigint,
gasUsed: bigint,
logs?: SimBundleLogs[],
}
/** Decodes a raw simBundle response. */
export const SimBundleResult = (response: ISimBundleResponse): ISimBundleResult => ({
success: response.success,
error: response.error,
stateBlock: parseInt(response.stateBlock, 16),
mevGasPrice: BigInt(response.mevGasPrice),
profit: BigInt(response.profit),
refundableValue: BigInt(response.refundableValue),
gasUsed: BigInt(response.gasUsed),
logs: response.logs,
})
/**
* General API wrapper for events received by the SSE stream (via `mevshare.on(...)`).
*/
export interface IMevShareEvent {
/** Transaction or Bundle hash. */
hash: string,
/** Logs emitted by the transaction or bundle. */
logs?: LogParams[],
txs?: Array<{
/** Transaction recipient address. */
to?: string,
/** 4byte function selector */
functionSelector?: string,
/** Calldata of the tx */
callData?: string,
}>,
/**
* Hex string; change in coinbase value after inserting tx/bundle, divided by gas used.
*
* Can be used to determine the minimum payment to the builder to make your backrun look more profitable to builders.
*
* _Note: this only applies to builders like Flashbots who order bundles by MEV gas price._
*
* _Note: EXPERIMENTAL; only implemented on Goerli._
*/
mevGasPrice?: string,
/** Hex string; gas used by the tx/bundle, rounded up to 2 most significant digits.
*
* _Note: EXPERIMENTAL; only implemented on Goerli._
*/
gasUsed?: string,
}
/**
* Pending transaction from the MEV-Share event stream.
*/
export interface IPendingTransaction extends Omit<Omit<Omit<IMevShareEvent, 'txs'>, 'mevGasPrice'>, 'gasUsed'> {
to?: string,
functionSelector?: string,
callData?: string,
/**
* {@link IMevShareEvent.mevGasPrice}
*/
mevGasPrice?: bigint,
/**
* {@link IMevShareEvent.gasUsed}
*/
gasUsed?: bigint,
}
/** Pending bundle from the MEV-Share event stream. */
export interface IPendingBundle extends Omit<Omit<IMevShareEvent, 'mevGasPrice'>, 'gasUsed'> {
/**
* {@link IMevShareEvent.mevGasPrice}
*/
mevGasPrice?: bigint,
/**
* {@link IMevShareEvent.gasUsed}
*/
gasUsed?: bigint,
}
/** A past event from the MEV-Share event stream. */
export class EventHistoryEntry {
public block: number
public timestamp: number
public hint: {
txs?: Array<{
to: string,
callData: string,
functionSelector: string,
}>,
hash: string,
logs?: Array<LogParams>,
gasUsed: bigint,
mevGasPrice: bigint,
}
constructor(entry: IEventHistoryEntry) {
this.block = entry.block
this.timestamp = entry.timestamp
this.hint = {
...entry.hint,
gasUsed: entry.hint.gasUsed ? BigInt(entry.hint.gasUsed) : BigInt(0),
mevGasPrice: entry.hint.mevGasPrice ? BigInt(entry.hint.mevGasPrice) : BigInt(0),
}
}
}