@steerprotocol/strategy-utils 2.2.1 → 3.1.1

package/readme.md

@@ -0,0 +1,387 @@
+# Strategy Utility Functions API Reference
+
+## Triggers.ts
+
+Trigger logic is created and implemented with the expectation to reduce the number of unnecessary executions. If the state of a liquidity providing vault is acceptable, such trigger logic can be used to determine if action should be taken or not. This reduces gas costs and unnecessary on-chain executions. The trigger functions are designed to return `true` in the event action should be taken (the trigger condition is met). In the case of `false` the condition is satisfactory and the user can factor in their own logic or return `continue` to skip execution. If the trigger depends on some information set by the user like triggering only when the price is over a ceratin percentage from the current active range (see triggerFromPercentage), variables such as the percentage should be added to the strategy configuration.
+
+### Example
+
+Imagine we will have a SushiLiquidityManager that will have a very broad liquidity coverage that we wish to only execute when our positions are out of range from the current tick. To do this we can utilize `triggerPositionsInactive` to check for this condition. In order to use many of the trigger functions, we will need the current positions provided by the `Liquidity Manager Positions` data connector. Additionally, we will need the current tick provided by a `V3 Pool Current Tick` data connector. These will need to be configured at the creation of the vault. In our strategy's execute function, the resulting current positions and current tick will be passed in as parameters in the configured order. Armed with this data, we can use the trigger function and return continue if the execution logic is untriggered.
+
+```assemblyscript
+export function execute(_currentTick: string, _currentPositions: string, ...any other data connector results for custom logic...): string {
+    // parse our data connector results
+    const currentTick = parseInt(_currentTick);
+    currentPositions = parseActiveRange(_positions);
+    // handle null cases
+    ...
+    // call triggerPositionsInactive to see if we should execute
+    if (triggerPositionsInactive(currentPositions, currentTick)) return 'continue'
+    // if we don't return continue, we will execute our main logic for determining the new positions to be minted
+    ...
+}
+
+```
+
+---
+
+### `parseActiveRange(_positions: string): Position`
+
+This function parses the active position range from the type of string output of `LM.getPositions()`. It takes a string parameter `_positions`, which is expected to be in the format `[[#,#,#],[#,#,#],[#,#,#]]`, representing the lower tick, upper tick, and weight of a liquidity manager's positions.
+
+**Parameters**
+
+- `_positions` (string): The string representation of positions in the format `[[#,#,#],[#,#,#],[#,#,#]]`.
+
+**Returns**
+
+- `Position`: An instance of the `Position` class representing the parsed active range, with the lowest starting tick and highest upper tick from the recieved set of positions. Weight is set to 100 by default.
+
+---
+
+### `emptyCurrentPosition(currentPosition: Position): boolean`
+
+This function checks if the current position is empty. It takes a `currentPosition` parameter of type `Position`.
+
+**Parameters**
+
+- `currentPosition` (Position): The current position to check.
+
+**Returns**
+
+- `boolean`: Returns `true` if the current position ticks are the same (empty position), indicating that action should be taken. Returns `false` otherwise.
+
+---
+
+### `triggerFromDistance(currentPosition: Position, rebalanceWidth: i64, currentTick: i64): boolean`
+
+This function triggers an action based on the distance between the current tick and the center of the position range. It compares the current tick to upper and lower trigger bounds calculated from the `rebalanceWidth` parameter.
+
+**Parameters**
+
+- `currentPosition` (Position): The current position.
+- `rebalanceWidth` (i64): The width (distance) from the center of the position range to trigger an action.
+- `currentTick` (i64): The current tick to compare against the trigger bounds.
+
+**Returns**
+
+- `boolean`: Returns `true` if the current tick is outside the trigger bounds, indicating that action should be taken. Returns `false` if the current tick is within the trigger bounds, indicating that execution should be skipped.
+
+---
+
+### `triggerFromPercentage(currentPosition: Position, rebalancePercentage: f64, currentTick: i64): boolean`
+
+This function triggers an action based on the percentage difference between the current tick and the center of the position range. It compares the current tick to upper and lower trigger bounds calculated from the `rebalancePercentage` parameter.
+
+**Parameters**
+
+- `currentPosition` (Position): The current position.
+- `rebalancePercentage` (f64): The percentage difference from the center of the position range to trigger an action.
+- `currentTick` (i64): The current tick to compare against the trigger bounds.
+
+**Returns**
+
+- `boolean`: Returns `true` if the current tick is outside the trigger bounds, indicating that action should be taken. Returns `false` if the current tick is within the trigger bounds, indicating that execution should be skipped.
+
+---
+
+### `triggerPositionsInactive(currentPosition: Position, currentTick: i64): boolean`
+
+This function triggers an action when the current tick is no longer within the current position range.
+
+**Parameters**
+
+- `currentPosition` (Position): The current position.
+- `currentTick` (i64): The current tick to compare against the position range.
+
+**Returns**
+
+- `boolean`: Returns `true` if the current tick is outside the position range, indicating that action should be taken. Returns `false` if the current tick is within the position range, indicating that execution should be skipped.
+
+---
+
+### `triggerFromSpecifiedPrice(triggerTick: i64, currentTick: i64, triggerOver: boolean): boolean`
+
+This function triggers an action when the current tick goes over or under a specified trigger tick.
+
+**Parameters**
+
+- `triggerTick` (i64): The trigger tick to compare against the current tick.
+- `currentTick` (i64): The current tick to compare against the trigger tick.
+- `triggerOver` (boolean): Indicates whether the trigger should activate when the current tick is greater than the trigger tick (`true`), or when it is less than the trigger tick (`false`).
+
+**Returns**
+
+- `boolean`: Returns `true` if the trigger condition is met, indicating that action should be taken. Returns `false` otherwise.
+
+---
+
+### `triggerPricePastPositions(currentPosition: Position, currentTick: i64, triggerOver: boolean): boolean`
+
+This function triggers an action when the current tick goes over or under the current position's range. It only triggers in one direction.
+
+**Parameters**
+
+- `currentPosition` (Position): The current position.
+- `currentTick` (i64): The current tick to compare against the position range.
+- `triggerOver` (boolean): Indicates whether the trigger should activate when the current tick is greater than the position's end tick (`true`), or when it is less than the position's start tick (`false`).
+
+**Returns**
+
+- `boolean`: Returns `true` if the trigger condition is met, indicating that action should be taken. Returns `false` otherwise.
+
+---
+
+## Math.ts
+
+### `_getMax(arr: Array<f64>): f64`
+
+This function calculates the maximum value in an array of floating-point numbers. It takes an array `arr` as input.
+
+**Parameters**
+
+- `arr` (Array<f64>): The array of floating-point numbers.
+
+**Returns**
+
+- `f64`: The maximum value in the array.
+
+---
+
+### `getMax(a: f64, b: f64): f64`
+
+This function returns the maximum value between two floating-point numbers `a` and `b`.
+
+**Parameters**
+
+- `a` (f64): The first floating-point number.
+- `b` (f64): The second floating-point number.
+
+**Returns**
+
+- `f64`: The maximum value between `a` and `b`.
+
+---
+
+### `_normalDensity(std: f64, mean: f64, x: f64): f64`
+
+This function calculates the value of the normal density function for a given standard deviation (`std`), mean (`mean`), and input value (`x`).
+
+**Parameters**
+
+- `std` (f64): The standard deviation.
+- `mean` (f64): The mean.
+- `x` (f64): The input value.
+
+**Returns**
+
+- `f64`: The value of the normal density function.
+
+---
+
+### `_standardDeviation(list: f64[]): f64`
+
+This function calculates the standard deviation for an array of floating-point numbers (`list`).
+
+**Parameters**
+
+- `list` (f64[]): The array of floating-point numbers.
+
+**Returns**
+
+- `f64`: The standard deviation of the input array.
+
+---
+
+### `_mean(list: f64[]): f64`
+
+This function calculates the mean (average) of an array of floating-point numbers (`list`).
+
+**Parameters**
+
+- `list` (f64[]): The array of floating-point numbers.
+
+**Returns**
+
+- `f64`: The mean (average) of the input array.
+
+---
+
+### `closestDivisibleNumber(num: number, divisor: number, floor: boolean): number`
+
+This function finds the closest number to `num` that is divisible by `divisor`. If `floor` is `true`, the function returns the closest lower divisible number; otherwise, it returns the closest higher divisible number.
+
+**Parameters**
+
+- `num` (number): The number for which to find the closest divisible number.
+- `divisor` (number): The divisor used to determine divisibility.
+- `floor` (boolean): Indicates whether to return the closest lower divisible number (`true`) or the closest higher divisible number (`false`).
+
+**Returns**
+
+- `number`: The closest divisible number to `num` based on the specified divisor and rounding rule.
+
+## Ranges.ts
+
+### `getAverageTrueRange(candles: Array<Candle>): f64`
+
+This function calculates the average true range (ATR) based on an array of Candle objects (`candles`).
+
+**Parameters**
+
+- `candles` (Array<Candle>): An array of Candle objects representing price data.
+
+**Returns**
+
+- `f64`: The average true range (ATR) value.
+
+---
+
+### `trailingStop(percent: f64, prices: Candle[]): f64`
+
+This function calculates the trailing stop price based on a specified percentage (`percent`) and an array of Candle objects (`prices`).
+
+**Parameters**
+
+- `percent` (f64): The percentage used to calculate the trailing stop price.
+- `prices` (Candle[]): An array of Candle objects representing price data.
+
+**Returns**
+
+- `f64`: The trailing stop price.
+
+---
+
+### `trueRange(price: Candle): f64`
+
+This function calculates the true range based on a single Candle object (`price`).
+
+**Parameters**
+
+- `price` (Candle): A Candle object representing price data.
+
+**Returns**
+
+- `f64`: The true range value.
+
+---
+
+### `averageTrueRange(prices: Candle[]): f64`
+
+This function calculates the average true range (ATR) based on an array of Candle objects (`prices`).
+
+**Parameters**
+
+- `prices` (Candle[]): An array of Candle objects representing price data.
+
+**Returns**
+
+- `f64`: The average true range (ATR) value.
+
+## Candle.ts
+
+### `Candle` class
+
+This class represents a candlestick object that contains price data.
+
+**Properties**
+
+- `timestamp` (i64): The timestamp of the candle.
+- `high` (f64): The highest price of the candle.
+- `low` (f64): The lowest price of the candle.
+- `open` (f64): The opening price of the candle.
+- `close` (f64): The closing price of the candle.
+- `volume` (f64): The trading volume of the candle.
+
+**Constructor**
+
+- `Candle(timestamp: i64, high: f64, low: f64, open: f64, close: f64, volume: f64)`: Creates a new instance of the Candle class with the provided parameters.
+
+**Methods**
+
+- `toString(): string`: Returns a string representation of the Candle object.
+
+---
+
+### `parsePrices(_data: string): Array<Candle>`
+
+This function parses the data connector data array in string format (`_data`) and returns an array of Candle objects.
+
+**Parameters**
+
+- `_data` (string): The data connector data array in string format.
+
+**Returns**
+
+- `Array<Candle>`: An array of Candle objects.
+
+---
+
+### `parseCandles(_data: string): Array<Candle>`
+
+This function is an alias for `parsePrices(_data)` and performs the same functionality. It parses the data connector data array in string format (`_data`) and returns an array of Candle objects.
+
+**Parameters**
+
+- `_data` (string): The data connector data array in string format.
+
+**Returns**
+
+- `Array<Candle>`: An array of Candle objects.
+
+## Position.ts
+
+### `Position` class
+
+This class represents a position with a start tick, end tick, and weight.
+
+**Properties**
+
+- `startTick` (i32): The starting tick of the position.
+- `endTick` (i32): The ending tick of the position.
+- `weight` (i32): The weight of the position.
+
+**Constructor**
+
+- `Position(startTick: i32, endTick: i32, weight: i32)`: Creates a new instance of the Position class with the provided parameters.
+
+---
+
+## ExecutionContext.ts
+
+### `ExecutionContext` class
+
+This class represents the execution context containing various properties related to the execution environment.
+
+**Properties**
+
+- `executionTimestamp` (number): The execution timestamp.
+- `epochLength` (number): The length of the epoch.
+- `epochTimestamp` (i32): The epoch timestamp.
+- `vaultAddress` (string): The vault address.
+- `blockTime` (i32): The block time.
+- `blockNumber` (i32): The block number.
+
+---
+
+## SlidingWindow.ts
+
+### `SlidingWindow<T>` class
+
+This class represents a sliding window data structure that stores a fixed-size window of values of type `T`.
+
+**Constructor**
+
+- `SlidingWindow(windowSize: i32, formula: (window: Array<T>) => T)`: Creates a new instance of the SlidingWindow class with the specified window size and formula function.
+
+**Methods**
+
+- `addValue(value: T): void`: Adds a value to the sliding window.
+- `getLastValue(): T`: Retrieves the last value added to the sliding window.
+- `clear(): void`: Clears the sliding window, resetting all values to `null`.
+- `setWindowSize(size: i32): void`: Sets the window size to the specified value.
+- `getWindow(): Array<T>`: Retrieves the current window of values.
+- `getFormulaResult(): T`: Calculates the formula result using the current window of values and the provided formula function.
+- `isStable(): bool`: Checks if the sliding window is stable, i.e., if it contains the specified window size or more values.
+
+Please note that the `SlidingWindow<T>` class is a generic class, allowing you to define the type of values stored in the sliding window.

package/tests/index.test.ts

@@ -1,28 +1,238 @@
-const myModule = require("../index");
-
-describe("WASM Module", () => {
-  describe("keltnerChannels", () => {
-    it("Price should ", async () => {
-      const price =  new myModule.Candle("123",1,2,3,4);
-      expect(price.high).toBe(1);
-      expect(price.low).toBe(2);
-      expect(price.open).toBe(3);
-      expect(price.close).toBe(4);
-    });
-    it("True average should compute properly", async () => {
-      const prices =  [new myModule.Candle("12342343",1,2,3,4),new myModule.Candle("12342343",2,3,4,5)];
-      const trueAverage = myModule.getAverageTrueRange(prices, 1);
-      expect(trueAverage).toBe(2);
-    });
-    it("True average should support decimals ", async () => {
-      const prices =  [new myModule.Candle("12342343",6.1,4.2,2.5,1.11),new myModule.Candle("12342343",41,32,41,15)];
-      const trueAverage = myModule.getAverageTrueRange(prices, 1);
-      expect(trueAverage).toBe(39.88999938964844)
-    });
-    it("Should parse candles ", async () => {
-      const candles =  '[{"timestamp":"12312312123","high":6.1,"low":4.2,"open":2.5,"close":1.11},{"timestamp":"12312312123","high":41.1,"low":32.1,"open":41.2,"close":15.1}]'
-      const candlesArray = myModule.parseCandles(candles);
-      expect(candlesArray.length).toBe(2)
-    });
+import {  candles2,  } from "./utils";
+import fs from 'fs';
+import { WasmModule, loadWasm } from "@steerprotocol/app-loader";
+
+
+describe("Unit tests", () => {
+  let myModule: WasmModule;
+  
+  beforeEach(async () => {
+    myModule = await loadWasm(fs.readFileSync(__dirname + "/debug.wasm"), {})
   });
+
+    describe("Trigger tests", () => {
+      // Testing the following options
+      // 'Current Price set distance from center of positions',
+      // 'Price leaves active range',
+      // 'Price moves percentage of active range away',
+      // 'Price moves one way past positions',
+      // 'None'
+// TEST tirggers
+test("Can return positions on none type", async () => {        
+  const config = `{
+    "triggerStyle": "None",
+    "period":6,
+    "standardDeviations":2.0,
+    "liquidityShape": "Linear",
+    "poolFee": 3000,
+    "placementType": "Position over current price",
+    "positionSize": 600
+  }`
+  myModule.initialize(config);
+  const positions = '[[257100],[257300],[1]]'
+  const currentTick = '257301'
+  const timeSinceLastExecution = '5600'
+  const result = myModule.execute
+  (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+  expect(result).not.toEqual('continue')
 });
+
+test
+("Can return continue for active trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price leaves active range",
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 500,
+      "period":6,
+      "standardDeviations":2.0
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257251'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute(//...[JSON.stringify(candles2), positions])
+    JSON.stringify(candles2),
+    positions, 
+    currentTick,
+    timeSinceLastExecution);
+    expect(result).toEqual('continue')
+  });
+
+  test("Can return positions for active trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price leaves active range",
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257301'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).not.toEqual('continue')
+  });
+
+  test("Can return continue for distance trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Current Price set distance from center of positions",
+      "tickDistanceFromCenter": 100,
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257251'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).toEqual('continue')
+  });
+
+  test("Can return positions for distance trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Current Price set distance from center of positions",
+      "tickDistanceFromCenter": 100,
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257301'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).not.toEqual('continue')
+  });
+
+  test("Can return continue for percentage trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price moves percentage of active range away",
+      "percentageOfPositionRangeToTrigger": 1,
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257251'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).toEqual('continue')
+  });
+
+  test("Can return positions for percentage trigger", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price moves percentage of active range away",
+      "percentageOfPositionRangeToTrigger": 1,
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257301'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).not.toEqual('continue')
+  });
+
+  test("Can return continue for one way inactive - active", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price moves one way past positions",
+      "triggerWhenOver": true,
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257251'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).toEqual('continue')
+  });
+
+  test("Can return continue for one way inactive - below", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price moves one way past positions",
+      "triggerWhenOver": true,
+      "strategy": "Classic",
+      "liquidityShape": "Linear",
+      "poolFee": 3000,
+      "placementType": "Position over current price",
+      "triggerWhenOver": true,
+      "period":6,
+      "standardDeviations":2.0,
+      "positionSize": 600
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257000'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify(candles2), positions, currentTick, timeSinceLastExecution);
+    expect(result).toEqual('continue')
+  });
+
+  test("Can return positions for one way inactive - above", async () => {        
+    const config = `{
+      "elapsedTendTime": 604800,
+      "triggerStyle": "Price moves one way past positions",
+      "triggerWhenOver": true,
+      "strategy": "Bollinger Band",
+      "liquidityShape": "Linear",
+      "poolFee": 500,
+      "placementType": "Position over current price",
+      "triggerWhenOver": true,
+      "lookback": 12,
+      "period":6,
+      "standardDeviations":2.0,
+    }`
+    myModule.initialize(config);
+    const positions = '[[257100],[257300],[1]]'
+    const currentTick = '257301'
+    const timeSinceLastExecution = '5600'
+    const result = myModule.execute
+    (JSON.stringify([...candles2]), positions, currentTick, timeSinceLastExecution);
+    expect(result).not.toEqual('continue')
+  });
+    });
+});