134 lines
3.1 KiB
Markdown
134 lines
3.1 KiB
Markdown
# near-intents-monitor
|
|
|
|
Minimal event-driven POC for the first trading-system component:
|
|
|
|
- **venue ingest**: NEAR Intents solver-bus quote flow
|
|
- **central bus**: Redpanda / Kafka-compatible broker
|
|
- **dummy reactor**: placeholder consumer for later trade-decision logic
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
NEAR Intents WebSocket
|
|
|
|
|
v
|
|
src/apps/near-intents-ingest.mjs
|
|
|
|
|
+--> raw.near_intents.quote
|
|
|
|
|
+--> norm.swap_demand
|
|
|
|
|
v
|
|
src/apps/dummy-consumer.mjs
|
|
```
|
|
|
|
The ingest app connects to the NEAR Intents websocket, subscribes to `quote` and `quote_status`, normalizes quote demand, and publishes to a Kafka-compatible topic.
|
|
|
|
## Project structure
|
|
|
|
```text
|
|
src/
|
|
apps/
|
|
near-intents-ingest.mjs
|
|
dummy-consumer.mjs
|
|
bus/
|
|
kafka/
|
|
producer.mjs
|
|
consumer.mjs
|
|
core/
|
|
event-envelope.mjs
|
|
log.mjs
|
|
pair-filter.mjs
|
|
lib/
|
|
env.mjs
|
|
config.mjs
|
|
venues/
|
|
near-intents/
|
|
ingest.mjs
|
|
normalize.mjs
|
|
ws.mjs
|
|
```
|
|
|
|
## Environment
|
|
|
|
Create `.env` in repo root:
|
|
|
|
```env
|
|
NEAR_INTENTS_API_KEY=your_solver_jwt
|
|
NEAR_INTENTS_WS_URL=wss://solver-relay-v2.chaindefuser.com/ws
|
|
KAFKA_BROKERS=127.0.0.1:9092
|
|
KAFKA_CLIENT_ID=trading-system
|
|
KAFKA_TOPIC_NORM_SWAP_DEMAND=norm.swap_demand
|
|
KAFKA_CONSUMER_GROUP_DUMMY=dummy-reactor-v1
|
|
```
|
|
|
|
### Broker notes
|
|
|
|
- `KAFKA_BROKERS` accepts a comma-separated broker list.
|
|
- Redpanda works because the apps use the Kafka protocol via `kafkajs`.
|
|
- `src/lib/config.mjs` is the shared config loader for both app entrypoints.
|
|
- The ingest app publishes normalized quote-demand events to `norm.swap_demand` by default.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Run
|
|
|
|
### Start NEAR Intents ingest
|
|
|
|
Use the package script:
|
|
|
|
```bash
|
|
npm run near-intents:ingest
|
|
```
|
|
|
|
Or run the app directly:
|
|
|
|
```bash
|
|
node src/apps/near-intents-ingest.mjs
|
|
```
|
|
|
|
Optional exact-pair filter:
|
|
|
|
```bash
|
|
npm run near-intents:ingest -- --pair 'asset_a->asset_b'
|
|
```
|
|
|
|
Example:
|
|
|
|
```bash
|
|
npm run near-intents:ingest -- --pair 'nep141:btc.omft.near->nep141:gnosis-0x420ca0f9b9b604ce0fd9c18ef134c705e5fa3430.omft.near'
|
|
```
|
|
|
|
The filter is direction-agnostic, so `asset_a->asset_b` also matches `asset_b->asset_a`.
|
|
|
|
### Start the dummy consumer
|
|
|
|
Use the package script:
|
|
|
|
```bash
|
|
npm run dummy-consumer
|
|
```
|
|
|
|
Or run the app directly:
|
|
|
|
```bash
|
|
node src/apps/dummy-consumer.mjs
|
|
```
|
|
|
|
The dummy consumer subscribes to `norm.swap_demand`, logs the observed pair and quote id, and stands in for a future decision engine.
|
|
|
|
## Scripts
|
|
|
|
- `npm run near-intents:ingest` — start the websocket ingest and publish to Kafka/Redpanda topics
|
|
- `npm run dummy-consumer` — consume normalized demand events
|
|
- `npm start` — legacy wrapper that forwards into the ingest app
|
|
|
|
## Notes
|
|
|
|
- This repo is now bus-first: venue intake and downstream reaction are decoupled through Kafka-compatible topics.
|
|
- `index.mjs` remains only as a compatibility launch wrapper; operational docs should prefer `src/apps/*` entrypoints and npm scripts.
|
|
- Older single-file, Python, or TUI-only runtime instructions are obsolete for this repository state.
|