4.7 KiB
assetaz-raydium-pool-price-source Specification
Purpose
Provides independently lifecycle-managed price observations for one Raydium pool through the AssetAZ PriceSource component contract.
Requirements
Requirement: One source represents one stable Raydium pool
A Raydium Pool PriceSource instance SHALL represent exactly one Raydium pool, SHALL expose the expected trading pair supplied at construction, and SHALL expose the stable source name Raydium-<poolId>. Construction SHALL validate all dependencies and identity values, leave the source stopped, perform no network access, and require no price sink until startup.
Scenario: Construct a pool source
- WHEN a client constructs a source with a Raydium service, pool ID, and expected trading pair
- THEN the stopped source reports that trading pair and a source name containing that exact pool ID without performing a price retrieval
Scenario: Reject invalid construction
- WHEN a required constructor argument is absent or invalid
- THEN construction fails without starting polling or accessing the network
Requirement: Poll immediately with fixed delay
On startup, the source SHALL begin its first retrieval attempt immediately and SHALL begin each subsequent attempt one minute after the preceding attempt completes. Polling SHALL execute on a daemon scheduler thread owned exclusively by that source instance.
Scenario: Start a source
- WHEN a stopped source is started with a price sink
- THEN its first pool-price retrieval begins immediately on its source-owned daemon scheduler
Scenario: Complete a periodic attempt
- WHEN a retrieval attempt completes
- THEN the next attempt begins after the configured one-minute delay without fixed-rate catch-up attempts
Requirement: Validate and publish pool observations
The source SHALL retrieve the configured pool price and compare the response trading pair with its expected pair. For a matching response, it SHALL create the observation timestamp after the successful response, truncate it to milliseconds, and publish the returned price value through the sink supplied at startup.
Scenario: Receive the expected pair
- WHEN a successful pool response contains the expected trading pair
- THEN the source publishes its price with a post-response timestamp truncated to milliseconds
Scenario: Receive a different pair
- WHEN a pool response contains a trading pair different from the expected pair
- THEN the source publishes no observation, logs the pool ID plus expected and received pairs, and schedules the next attempt normally
Requirement: Isolate temporary polling failures
Temporary network, Raydium, parsing, interruption, or downstream persistence failures SHALL be logged with the pool ID and expected trading pair and SHALL NOT cancel later polling attempts or stop the Ticker service.
Scenario: A polling attempt fails temporarily
- WHEN a retrieval or publication attempt throws an exception
- THEN the source logs the contextual failure and retries on the next fixed-delay interval
Requirement: Restartable source lifecycle
The source SHALL reject a repeated startup before replacing its existing sink. Stopping SHALL be idempotent, terminate source-owned scheduling resources, correctly preserve interruption, and permit a later startup with a newly supplied sink.
Scenario: Start an already-started source
- WHEN startup is invoked while the source is already running
- THEN startup fails and the currently active sink remains unchanged
Scenario: Stop a running source
- WHEN stop is invoked on a running source
- THEN its scheduler terminates and no further polling begins
Scenario: Stop an already-stopped source
- WHEN stop is invoked while the source is stopped
- THEN it completes without error
Scenario: Restart a stopped source
- WHEN a previously stopped source is started with a sink
- THEN it creates fresh source-owned scheduling resources and begins an immediate retrieval attempt
Requirement: Activation uses independent Ticker history
The pool source SHALL participate in the existing Ticker activation contract under its exact trading pair and pool-based source name. It SHALL be active only when that exact history file already exists and SHALL NOT create or migrate history files.
Scenario: Pool history exists
- WHEN the EVE/USDT history file exists beneath the EVE UUID, USDT UUID, and exact pool-based source-name path
- THEN the Ticker activates the Raydium source independently of the hardcoded EVE/USDC history
Scenario: Pool history is absent
- WHEN the exact Raydium source history file is absent
- THEN the Ticker leaves that source inactive and creates no file or directory