TWAP Service
The TWAP service functions as a configuration storage layer for time-weighted average price orders. It manages TWAP order configurations by persisting order configurations and providing endpoints for CRUD operations across multiple blockchain networks.Core Responsibilities
- Storing TWAP order configurations and Safe transaction data
- Providing query endpoints for wallet-specific orders
- Validating order parameters before persistence
- Reading orderbook data to monitor execution status
- Supporting Mainnet (1), Goerli (5), and Gnosis Chain (100)
How to Run
Development
Production
Docker
Configuration
Environment variables control server and database settings:Server
TWAP Database
Orderbook Database
API Endpoints
GET /:chainId/:walletAddress/orders
Retrieves all TWAP orders for a specified wallet and chain. Returns an array of order objects containing token addresses, amounts, timing parameters, and wallet information.POST /:chainId/:walletAddress/orders
Creates a new TWAP order with parameters defining the selling token, buying token, recipient address, part amounts, timing schedule (start time, intervals, number of parts), and Safe transaction hash.Data Models
Order Entity: Stores TWAP configuration including tokens, amounts, recipient, timing parameters (t0, n, t, span), and app data hash. Wallet Entity: Represents Safe wallet addresses with one-to-many relationship to orders. SafeTx Entity: Persists Safe transaction metadata associated with order creation.Database Architecture
The service requires two PostgreSQL instances:- Primary database - For order and wallet storage with TypeORM migrations
- Read-only orderbook database - For tracking execution and settlement events
Plugin System
Fastify plugins provide modular functionality:- Environment Plugin - Validates required configuration variables
- ORM Plugin - Manages TypeORM database connections
- Orderbook Plugin - Establishes read-only orderbook access
- Swagger Plugin - Generates OpenAPI documentation at
/documentation
Execution Model
The TWAP service functions primarily as storage infrastructure. Actual order execution involves:- CoW Protocol Watchtower - Monitoring and part creation
- Orderbook - Matching and settlement
- Safe infrastructure - Transaction execution
Integration
The main API service can proxy TWAP requests using HTTP forwarding, exposing TWAP functionality through a unified API gateway via theTWAP_BASE_URL configuration.