feat(core): add docs about actions and triggres

dittonetwork · Jun 10, 2024 · 17642d8 · 17642d8
1 parent 7fc4a3b
commit 17642d8
Show file tree

Hide file tree

Showing 2 changed files with 164 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ A JavaScript SDK for building workflows on the Ditto Network, enabling a Smart A
 
 ## Documentation
 
-For comprehensive documentation and details on how to use the Ditto Network, please refer to the main documentation in the [`@ditto-network/core`](packages/core/README.md) package.
+For comprehensive documentation and details on how to use the Ditto Network, please refer to the main documentation in the [`@ditto-network/core`](https://github.com/dittonetwork/sdk-js/blob/master/packages/core/README.md) package.
 
 ## Contributing
 

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -1,8 +1,20 @@
 # @ditto-network/core
 
-A JavaScript SDK for building workflows on the Ditto Network, enabling a Smart Account experience at any level of your project.
+A JavaScript SDK for building workflows on the Ditto Network, enabling a Smart Account experience at any level of your project. This SDK provides the necessary tools and adapters for interacting with the blockchain and constructing workflows. You can use the provided adapters or implement your own.
 
-This SDK provides the necessary tools and adapters for interacting with the blockchain and constructing workflows. You can use the provided adapters or implement your own.
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Examples](#examples)
+  - [Node.js](#nodejs)
+  - [React](#react)
+- [Actions and Triggers](#actions-and-triggers)
+  - [Actions](#actions)
+  - [Triggers](#triggers)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
 
 ## Installation
@@ -18,15 +30,39 @@ yarn add @ditto-network/core @ditto-network/web3.js web3
 ```
 
 
+## Getting Started
+
+Here’s a quick guide to get you started with the Ditto Network SDK:
+
+
+### Initialize SDK
+
+```javascript
+
+import { Provider, SmartWalletFactory, BrowserStorage } from '@ditto-network/core';
+import { EthersSigner, EthersContractFactory } from '@ditto-network/ethers';
+
+const provider = new Provider({
+  signer: new EthersSigner(signer),
+  storage: new BrowserStorage(),
+  contractFactory: new EthersContractFactory(signer),
+});
+const swFactory = new SmartWalletFactory(provider);
+
+const sw = await swFactory.getDefaultOrCreateVault();
+const vaultAddress = sw.getAddress();
+
+console.log('Vault address:', vaultAddress);
+```
+
 ## Examples
 
 ### Node.js
 
 For Node.js examples, see:
 
-- [Web3.js example](examples/nodejs-example/web3js.ts)
-- [Ethers.js example](examples/nodejs-example/ethers.ts)
-
+- [Web3.js example](https://github.com/dittonetwork/sdk-js/blob/master/examples/nodejs-example/web3js.ts)
+- [Ethers.js example](https://github.com/dittonetwork/sdk-js/blob/master/examples/nodejs-example/ethers.ts)
 
 ### React
 
@@ -45,7 +81,127 @@ yarn serve
 ```
 
 
+## Actions and Triggers
+
+### 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. Here is the available action:
+
+
+#### Uniswap Swap Action
+
+The UniSwap swap action is an action that swaps tokens on UniSwap. It can be combined with price-based triggers to build a limit order workflow.
+
+**Configuration for UniSwap swap action:**
+```typescript
+type ActionConfig = {
+  fromToken: { address: string, decimals: number };
+  toToken: { address: string, decimals: number };
+  fromAmount: string;
+  slippagePercent?: number;
+  providerStrategy:
+    | { type: 'nodejs'; rpcUrl: string; chainId: number }
+    | { type: 'browser'; provider: ethers.providers.ExternalProvider };
+};
+```
+
+- **fromToken**: Token object that represents the token from which the swap is made.
+- **toToken**: Token object that represents the token to which the swap is made.
+- **fromAmount**: Amount of `fromToken` that should be swapped, represented in weis multiplied by 10^fromToken.decimals.
+- **slippagePercent**: Optional parameter that determines the slippage percent, default is 0.5%.
+- **ProviderStrategy**: Configuration for the provider used to execute the swap. It can be one of the following:
+  - **NodeJS provider**: `{ type: 'nodejs'; rpcUrl: string; chainId: number }`
+    ```typescript
+    const providerStrategy = {
+      type: 'nodejs',
+      rpcUrl: 'https://mainnet.infura.io/v3/your-infura-id',
+      chainId: 1, // Ethereum mainnet chain ID
+    };
+    ```
+  - **Browser provider**: `{ type: 'browser'; provider: ethers.providers.ExternalProvider }`
+    ```typescript
+    const providerStrategy = {
+      type: 'browser',
+      provider: window.ethereum,
+    };
+    ```
+
+**Example**
+```typescript
+new UniswapSwapActionCallDataBuilder(
+  {
+    fromToken: { address: '0x...', decimals: 18 },
+    toToken: { address: '0x...', decimals: 6 },
+    fromAmount: '1000000000000000000', // 1 token in wei
+    slippagePercent: 0.05,
+    providerStrategy: {
+      type: 'nodejs',
+      chainId: 1,
+      rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID',
+    },
+  },
+);
+```
+In this example, 1 token of `fromToken` is swapped to `toToken` with 0.05% slippage using the NodeJS provider strategy.
+
+
+### Triggers
+
+Triggers define the conditions under which actions are executed. Here is a description of available triggers:
+
+
+#### Price-Based Trigger
+
+A price-based trigger executes an action when the price of a specified asset meets certain conditions.
+
+**Configuration for Price-Based Trigger:**
+```typescript
+type PriceTriggerConfig = {
+  token: { address: string, decimals: number };
+  targetPrice: string; // Target price in terms of another token (e.g., USD)
+  comparison: 'greaterThan' | 'lessThan';
+  providerStrategy:
+    | { type: 'nodejs'; rpcUrl: string; chainId: number }
+    | { type: 'browser'; provider: ethers.providers.ExternalProvider };
+};
+```
+
+- **token**: Token object representing the asset whose price is being monitored.
+- **targetPrice**: The price target that triggers the action.
+- **comparison**: Specifies whether the action should be triggered when the price is 'greaterThan' or 'lessThan' the target price.
+- **ProviderStrategy**: Configuration for the provider used to monitor the price. It can be one of the following:
+  - **NodeJS provider**: `{ type: 'nodejs'; rpcUrl: string; chainId: number }`
+    ```typescript
+    const providerStrategy = {
+      type: 'nodejs',
+      rpcUrl: 'https://mainnet.infura.io/v3/your-infura-id',
+      chainId: 1, // Ethereum mainnet chain ID
+    };
+    ```
+  - **Browser provider**: `{ type: 'browser'; provider: ethers.providers.ExternalProvider }`
+    ```typescript
+    const providerStrategy = {
+      type: 'browser',
+      provider: window.ethereum,
+    };
+    ```
+
+**Example**
+```typescript
+new PriceBasedTrigger({
+  token: { address: '0x...', decimals: 18 },
+  targetPrice: '2000000000000000000', // 2 tokens in wei
+  comparison: 'greaterThan',
+  providerStrategy: {
+    type: 'nodejs',
+    chainId: 1,
+    rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID',
+  },
+});
+```
+In this example, the trigger is set to execute an action when the price of the specified token is greater than 2 tokens.
+
+
 ## Documentation
 
-- [Triggers](src/lib/workflow/triggers/README.md)
-- [Actions](src/lib/workflow/actions/README.md)
+For detailed documentation and API reference, visit our [documentation site](https://docs.dittonetwork.io).