You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: typescript/solver/README.md
+82-67Lines changed: 82 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,10 +4,12 @@ The solver directory contains the implementation of the Intent Solver, a TypeScr
4
4
5
5
## Table of Contents
6
6
7
-
- Directory Structure
8
-
- Installation
9
-
- Usage
10
-
- Adding a New Solver
7
+
-[Directory Structure](#directory-structure)
8
+
-[Installation](#installation)
9
+
-[Usage](#usage)
10
+
-[Managing Solvers](#managing-solvers)
11
+
-[Intent Filtering](#intent-filtering)
12
+
-[Logging](#logging)
11
13
12
14
## Directory Structure
13
15
@@ -46,13 +48,9 @@ solver/
46
48
### Description of Key Files and Directories
47
49
48
50
-**solver/index.ts**: The main entry point of the solver application. It initializes and starts the listeners and fillers for different solvers.
49
-
50
51
-**logger.ts**: Contains the Logger class used for logging messages with various formats and levels.
51
-
52
52
-**NonceKeeperWallet.ts**: A class that extends ethers Wallet and prevents nonces race conditions when the solver needs to fill different intents (from different solutions) in the same network.
53
-
54
53
-**patch-bigint-buffer-warn.js**: A script to suppress specific warnings related to BigInt and Buffer, ensuring cleaner console output.
55
-
56
54
-**solvers/**: Contains implementations of different solvers and common utilities.
57
55
-**BaseListener.ts**: An abstract base class that provides common functionality for event listeners. It handles setting up contract connections and defines the interface for parsing event arguments.
58
56
-**BaseFiller.ts**: An abstract base class that provides common functionality for fillers. It handles the solver's lifecycle `prepareIntent`, `fill`, and `settle`.
@@ -96,33 +94,96 @@ solver/
96
94
97
95
### Running the Solver Application
98
96
99
-
To start the solver application, execute:
97
+
Start the solver application:
100
98
101
99
```sh
102
100
yarn solver
103
101
```
104
102
105
-
This will run the compiled JavaScript code from the `dist` directory, starting all the listeners defined in index.ts.
103
+
This will run the compiled JavaScript code from the `dist` directory, initializing and starting all enabled solvers as defined in `config/solvers.json`. Each solver's status (enabled/disabled) can be configured in this JSON file.
106
104
107
105
### Development Mode
108
106
109
-
For development, you can run the application in watch mode to automatically restart on code changes:
107
+
Run in watch mode for development:
110
108
111
109
```sh
112
110
yarn dev
113
111
```
114
112
115
-
### Intent filtering
113
+
## Managing Solvers
114
+
115
+
### Adding a New Solver
116
+
117
+
You can add a new solver in two ways:
118
+
119
+
```sh
120
+
# Interactive mode - will prompt for solver name and options
121
+
yarn solver:add
122
+
123
+
# Direct mode - specify the solver name as an argument
124
+
yarn solver:add mySolver
125
+
```
126
+
127
+
This will:
128
+
129
+
1. Validate the solver name
130
+
2. Create the solver directory structure
131
+
3. Generate necessary files with boilerplate code
132
+
4. Update the solvers index
133
+
5. Add solver configuration
134
+
6. Set up allow/block lists
135
+
136
+
The script creates the following structure:
137
+
138
+
```
139
+
solvers/
140
+
└── yourSolver/
141
+
├── index.ts
142
+
├── listener.ts
143
+
├── filler.ts
144
+
├── types.ts
145
+
├── contracts/
146
+
├── rules/
147
+
│ └── index.ts
148
+
└── config/
149
+
├── index.ts
150
+
├── metadata.ts
151
+
└── allowBlockLists.ts
152
+
```
153
+
154
+
After creation:
155
+
156
+
1. Add your contract ABI to: `solvers/yourSolver/contracts/`
157
+
2. Run `yarn contracts:typegen` to generate TypeScript types
158
+
3. Update the listener and filler implementations
159
+
4. Configure your solver options in `config/solvers.ts`
160
+
5. Update metadata in `solvers/yourSolver/config/metadata.ts`
161
+
162
+
### Removing Solvers
163
+
164
+
To remove existing solvers:
165
+
166
+
```sh
167
+
yarn solver:remove
168
+
```
169
+
170
+
This will:
116
171
117
-
Configure which intent to fill , and which to ignore
172
+
1. Show a list of existing solvers (use space to select multiple, enter to confirm)
173
+
2. Ask for confirmation before proceeding
174
+
3. Remove the selected solver directories
175
+
4. Update the solvers index
176
+
5. Remove solver configurations
177
+
6. Clean up generated typechain files
118
178
119
-
By default, the solver will attempt to fill intents sent from its origin chain to any destination chains.
179
+
You can cancel the removal operation at any time by pressing 'q'.
120
180
121
-
Solvers may want to further filter the intents they attempt to fill. For example, fill intents coming from a specific address or going to a subset of chains.
181
+
## Intent Filtering
122
182
123
-
In order to do this, you can configure a block-list or an allow-list at a global level within the [allowBlockList.ts file](./config/allowBlockLists.ts) or at a specific solver level like e.g. [solvers/eco/config/allowBlockList.ts file](./solvers/eco/config/allowBlockLists.ts).
183
+
Configure which intents to fill or ignore using allow/block lists. Configure at:
124
184
125
-
Such configs should be written in the `allowBlockLists` variable
@@ -152,54 +213,8 @@ Both the allow-list and block-lists have "any" semantics. In other words, the So
152
213
153
214
The block-list supersedes the allow-list, i.e. if a message matches both the allow-list and the block-list, it will not be delivered.
154
215
155
-
### Logging
156
-
157
-
The application utilizes a custom Logger class for logging. You can adjust the log level and format by modifying the Logger instantiation in index.ts. By default, it will log to `stdout` in a human-readable format using the `INFO` level.
158
-
159
-
You can customize the logging destination by using a pino transport of your choosing. There's an example for logging to a Syslog server running on `localhost` commented in [logger.ts](logger.ts). Check out the [pino transports docs](https://github.com/pinojs/pino/blob/main/docs/transports.md) for other available transports.
160
-
161
-
## Adding a New Solver
162
-
163
-
To integrate a new solver into the application, follow these steps:
164
-
165
-
1. **Create a New Solver Directory**: Inside solvers/, create a new directory for your solver:
166
-
167
-
```
168
-
solvers/
169
-
└── yourSolver/
170
-
├── listener.ts
171
-
├── filler.ts
172
-
└── contracts/
173
-
└── YourContract.json
174
-
```
175
-
176
-
2. **Implement the Listener**: In listener.ts, extend the `BaseListener` class and implement the required methods to handle your specific event.
177
-
178
-
3. **Implement the Filler**: In filler.ts, extend the `BaseFiller` class and implement the required logic to process events captured by your listener.
179
-
180
-
4. **Add Contract Definitions**: Place your contract ABI and type definitions in the `contracts/` directory.
181
-
182
-
5. **Generate Types from Contract Definitions**: Run the following command:
183
-
184
-
```sh
185
-
yarncontracts:typegen
186
-
```
187
-
188
-
6. **Update the Index**: Export your new solver in index.ts:
216
+
## Logging
189
217
190
-
```typescript
191
-
export*asyourSolverfrom"./yourSolver/index.js";
192
-
```
193
-
194
-
7.**Initialize in Main Application**: In index.ts, import and initialize your solver:
195
-
196
-
```typescript
197
-
import*assolversfrom'./solvers/index.js';
218
+
The application uses a custom Logger class. Default: `stdout` with `INFO` level.
Customize using pino transports. See [pino transports docs](https://github.com/pinojs/pino/blob/main/docs/transports.md). There's an example for logging to a Syslog server running on `localhost` commented in [logger.ts](logger.ts).
0 commit comments