Merge pull request #32 from dittonetwork/docs/triggers

Docs: actions & triggers

packages/core/README.md

@@ -1,3 +1,7 @@
+## [Triggers](src/lib/workflow/triggers/README.md)
+
+## [Actions](src/lib/workflow/actions/README.md)
+
 ## Authenticate
 
 **Interfaces:**

packages/core/src/lib/workflow/actions/README.md

@@ -0,0 +1,79 @@
+## Actions
+
+Actions are the building blocks of a workflow. They are the steps that are executed by triggers. \
+Each action has a configuration that defines how it should be executed. And [common configuration](../triggers/README.md#common-configuration) that is used by all actions.
+
+We have the following actions available:
+- Uniswap swap action.
+
+### Uniswap Swap Action
+UniSwap swap action is an action that swaps tokens on UniSwap. We can combine price-based trigger and build limit order workflow.
+
+Configuration for UniSwap swap action:
+```typescript
+type ActionConfig = {
+  fromToken: TokenLight;
+  toToken: TokenLight;
+  fromAmount: string;
+  slippagePercent?: number;
+  providerStrategy:
+    | { type: 'nodejs'; rpcUrl: string; chainId: Chain }
+    | { type: 'browser'; provider: ethers.providers.ExternalProvider };
+};
+```
+
+#### fromToken: { address: string, decimals: number }
+Token object that represents the token from which the swap is made.
+
+#### toToken: { address: string, decimals: number }
+Token object that represents the token to which the swap is made.
+
+#### fromAmount: string
+Amount of `fromToken` that should be swapped. It is a string that represents the amount in weis multiplied by 10^fromToken.decimals.
+
+#### slippagePercent: number
+Optional parameter that determines the slippage percent. 0.5 by default.
+
+#### ProviderStrategy
+It is a config for the provider that is used to execute the swap. It can be one of the following:
+- **NodeJS provider**:\
+Type is `{ type: 'nodejs'; rpcUrl: string; chainId: Chain }`\
+Usually it is
+```typescript
+const providerStrategy = {
+  type: 'nodejs',
+  rpcUrl: 'https://mainnet.infura.io/v3/your-infura-id',
+  chainId: Chain.Polygon,
+}
+```
+
+- **Browser provider**: \
+Type is `{ type: 'browser'; provider: ethers.providers.ExternalProvider }`\
+Usually it is
+```typescript
+const providerStrategy = {
+  type: 'browser',
+  provider: window.ethereum,
+}
+```
+
+**Example**
+```typescript
+new UniswapSwapActionCallDataBuilder(
+  {
+    fromToken: wmatic,
+    toToken: usdt,
+    fromAmount: `333444555000000`,
+    slippagePercent: 0.05,
+    providerStrategy: {
+      type: 'nodejs',
+      chainId: chainId,
+      rpcUrl: process.env.INFURA_API_URL!,
+    },
+  },
+)
+```
+Here we swap 0.000333444555 WMATIC to USDT with 0.05 slippage.
+
+You don't suppose to use native tokens, only wrappers.\
+Under the hood we use `@uniswap/smart-order-router` for generating call data. 

packages/core/src/lib/workflow/triggers/README.md

@@ -0,0 +1,154 @@
+## Triggers
+
+Trigger is an event that starts the workflow. There are three types of triggers:
+- instant trigger
+- time-based trigger
+- price-based trigger
+
+If trigger can not be executed due to lack of native token for gas, the trigger will try to run workflow when the native token will become available.
+
+Each described trigger has own configuration that defines how it should be executed. And [common configuration](#common-configuration) that is used by all triggers.
+
+### Instant Trigger
+Instant trigger is a trigger that starts the workflow immediately after creation. It is useful for one-time workflows. \
+It is a trigger that does not have any configuration.
+
+### Time-based Trigger
+Time-based trigger is a trigger that starts the workflow at a specific time and optional repetitive cycles.\
+It is useful for workflows that need to be executed at a specific time with specific repeat cycles.
+
+It is type of configuration for time-based trigger:
+```typescript
+type TriggerConfig = {
+  startAtTimestamp: number;
+  repeatTimes?: number;
+  cycle: {
+    frequency: number;
+    scale: TimeScale;
+  };
+};
+```
+
+#### startAtTimestamp: number
+timestamp when the workflow should be started. It is a Unix timestamp in seconds\
+(`Math.round(Date.now() / 1000) + 120` will return timestamp for trigger that will start workflow in 2 minutes (120 seconds ) from now). 
+
+
+#### repeatTimes: number
+number of times the workflow should be repeated. If not provided, the workflow will be repeated once.
+
+#### cycle: { frequency: number, scale: TimeScale }  
+Object that contains frequency and scale of the cycle.
+Cycle is a period of time between two executions of the workflow.
+
+- frequency: number of cycles
+- scale: unit of the cycle. It can be one of the following:
+  - `TimeScale.Seconds`
+  - `TimeScale.Minutes`
+  - `TimeScale.Hours`
+  - `TimeScale.Days`
+  - `TimeScale.Weeks`
+  - `TimeScale.Months`
+
+cycle with frequency 2 and scale `TimeScale.Minutes` will repeat the workflow every 2 days, for example.
+
+**Example**
+```typescript
+const trigger = new TimeBasedTrigger(
+  {
+    repeatTimes: 5,
+    startAtTimestamp: new Date().getTime() / 1000 + 120,
+    cycle: {
+      frequency: 10,
+      scale: TimeScale.Minutes,
+    },
+  },
+  commonConfig
+)
+```
+Here, the workflow will be started in 2 minutes and repeated 5 times every 10 minutes.
+
+### Price-based Trigger
+Price-based trigger is a trigger that starts the workflow when the price of the token reaches a specific value in other token.\
+
+It is type of configuration for price-based trigger:
+```typescript
+type TriggerConfig = {
+  uniswapPoolFeeTier: FeeAmount;
+  triggerAtPrice: string;
+  priceMustBeHigherThan?: boolean;
+  fromToken: TokenLight;
+  toToken: TokenLight;
+};
+```
+#### uniswapPoolFeeTier: FeeAmount
+Fee tier of the Uniswap pool. It can be one of the following:
+```typescript
+export declare enum FeeAmount {
+  LOWEST = 100,
+  LOW = 500,
+  MEDIUM = 3000,
+  HIGH = 10000
+}
+```
+#### triggerAtPrice: string
+Price at which the workflow should be started. It is a string that represents the price in weis multiplied by 10^fromToken.decimals.\
+In other words, it is the rate - how much of `fromToken` you should pay to get one `toToken`.
+
+Rate should be:
+- higher than `triggerAtPrice` if `priceMustBeHigherThan` is `true`
+- lower than `triggerAtPrice` if `priceMustBeHigherThan` is `false`
+
+#### priceMustBeHigherThan: boolean
+Optional parameter that determines if the rate should be higher or lower than `triggerAtPrice`.\
+By default is `false`.
+
+#### fromToken: { address: string; decimals: number }
+Token object that represents the token from which the rate is calculated.
+
+#### toToken: { address: string; decimals: number }
+Token object that represents the token to which the rate is calculated.
+
+**Example**
+```typescript
+const priceTrigger = new PriceTrigger({
+  uniswapPoolFeeTier: 3000,
+  triggerAtPrice: '300000',
+  priceMustBeHigherThan: true,
+  fromToken: usdt,
+  toToken: wmatic,
+})
+```
+
+In this example rate is 0.88 (0.88 USDT for 1 WMATIC).
+`triggerAtPrice` is 0.3 (300000 / 10 ^ 6 (decimals of USDT))\
+Current rate is higher than `triggerAtPrice` and `priceMustBeHigherThan` is true,\
+so the trigger should be triggered.
+
+## Common Configuration
+Configuration that is used by all our triggers and actions.\
+It is a type of configuration for common configuration:
+```typescript
+export interface CommonBuilderOptions {
+  chainId: Chain;
+  recipient: Address;
+  accountAddress: string;
+  vaultAddress: Address;
+  provider: DittoProvider;
+}
+```
+
+#### chainId: Chain
+Chain id of the chain on which the workflow should be executed.
+
+#### recipient: string
+Address of the recipient of the workflow. It is an address that will receive the tokens after the workflow is executed.
+
+#### accountAddress: string
+Address of the account that will execute the workflow.
+
+#### vaultAddress: string
+Address of the smart wallet that will be used to execute the workflow. Usually it is the same as `recipient`.
+
+#### provider: DittoProvider
+Instance of the DittoProvider that is used to execute the workflow.