From adcf2b29b922da379241d918e8fe540a2283f874 Mon Sep 17 00:00:00 2001 From: ilya saldin Date: Tue, 7 May 2024 16:08:46 +0500 Subject: [PATCH] docs(global): actions and triggers --- packages/core/README.md | 4 + .../core/src/lib/workflow/actions/README.md | 79 +++++++++ .../core/src/lib/workflow/triggers/README.md | 154 ++++++++++++++++++ 3 files changed, 237 insertions(+) create mode 100644 packages/core/src/lib/workflow/actions/README.md create mode 100644 packages/core/src/lib/workflow/triggers/README.md diff --git a/packages/core/README.md b/packages/core/README.md index e9a8595..1f97655 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,3 +1,7 @@ +## [Triggers](src/lib/workflow/triggers/README.md) + +## [Actions](src/lib/workflow/actions/README.md) + ## Authenticate **Interfaces:** diff --git a/packages/core/src/lib/workflow/actions/README.md b/packages/core/src/lib/workflow/actions/README.md new file mode 100644 index 0000000..d46ec01 --- /dev/null +++ b/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. diff --git a/packages/core/src/lib/workflow/triggers/README.md b/packages/core/src/lib/workflow/triggers/README.md new file mode 100644 index 0000000..fcffc47 --- /dev/null +++ b/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.