@cowprotocol/sdk-trading 0.1.0-monorepo.0

package/README.md

@@ -0,0 +1,576 @@
+<p align="center">
+  <img width="400" src="https://github.com/cowprotocol/cow-sdk/raw/main/docs/images/CoW.png" />
+</p>
+
+# Trading SDK
+
+CoW Protocol is intent based, decentralized trading protocol that allows users to trade ERC-20 tokens.
+This SDK makes it easier to interact with CoW Protocol by handling order parameters, calculating amounts, and signing orders.
+
+## Basic Trading Flow
+
+1. 🔎 Get a quote (price) for a trade
+2. ✍️ Sign the order
+3. ✅ Post the order to the order-book
+
+The CoW Protocol provides very flexible and powerful trading capabilities. However, this flexibility comes with a cost: the complexity of the protocol. This SDK serves to simplify the interaction with the CoW Protocol. It will put all necessary parameters to your order, calculates proper amounts, and signs the order.
+
+## Why Use This SDK?
+
+- **App-data** - Order metadata handling
+- **Order signing** - EIP-712 signature management
+- **Network costs** - Automatic fee and slippage calculations
+- **Order parameters** - Validity, partial fills, etc.
+- **Quote API settings** - Price quality, signing scheme, etc.
+- **Order types** - Market, limit, on-chain trades, etc.
+
+> See the [examples](https://github.com/cowprotocol/cow-sdk/tree/main/examples) for usage.
+
+## Installation
+
+```bash
+npm install @cowprotocol/sdk-trading
+or
+pnpm add @cowprotocol/sdk-trading
+or
+yarn add @cowprotocol/sdk-trading
+```
+
+## TradingSdk Functions
+
+Main functions:
+
+- `postSwapOrder` - Get a quote and create a swap order.
+- `postLimitOrder` - Create a limit order.
+- `getQuote` - Fetch a quote for a swap order.
+
+Special cases:
+
+- 'setTraderParams' - In case if you work with different chains and need to switch between them in runtime.
+- `postSellNativeCurrencyOrder` - Sell blockchain native tokens (e.g., ETH on Ethereum).
+- `getPreSignTransaction` - Sign an order using a smart contract wallet.
+
+### Setup
+
+You need:
+
+- `chainId` - Supported chain ID ([see list](https://docs.cow.fi/cow-protocol/reference/sdks/core-utilities/sdk-config)).
+- `appCode` - Unique app identifier for tracking orders.
+- `signer` - Private key, ethers signer, or `Eip1193` provider (optional - will use global adapter's signer if not provided).
+
+## Usage
+
+### Individual package usage
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/sdk-trading'
+import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
+import { JsonRpcProvider, Wallet } from 'ethers'
+
+// Configure the adapter
+const provider = new JsonRpcProvider('YOUR_RPC_URL')
+const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
+const adapter = new EthersV6Adapter({ provider, signer: wallet })
+
+// Initialize the SDK
+const sdk = new TradingSdk(
+  {
+    appCode: 'YOUR_APP_CODE',
+  },
+  {
+    chainId: SupportedChainId.SEPOLIA,
+  },
+  adapter, // Pass the adapter
+)
+
+// Define trade parameters
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+// Post the order
+const orderId = await sdk.postSwapOrder(parameters)
+console.log('Order created, id: ', orderId)
+```
+
+### Usage with Umbrella SDK
+
+```typescript
+import { CowSdk, SupportedChainId, OrderKind, TradeParameters } from '@cowprotocol/cow-sdk'
+import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
+import { JsonRpcProvider, Wallet } from 'ethers'
+
+// Configure the adapter
+const provider = new JsonRpcProvider('YOUR_RPC_URL')
+const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
+const adapter = new EthersV6Adapter({ provider, signer: wallet })
+
+// Initialize the unified SDK
+const sdk = new CowSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  adapter,
+  tradingOptions: {
+    traderParams: {
+      appCode: 'YOUR_APP_CODE',
+    },
+    options: {
+      chainId: SupportedChainId.SEPOLIA,
+    },
+  },
+})
+
+// Define trade parameters
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+// Post the order
+const orderId = await sdk.trading.postSwapOrder(parameters)
+console.log('Order created, id: ', orderId)
+
+// Or you can just initialize the SDK and import the trading class in another file:
+// you don't necessarily need to use the trading from inside of CowSdk:
+//...
+const sdk = new CowSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  adapter,
+})
+// Other file:
+import { TradingSdk } from '@cowprotocol/cow-sdk'
+// parameters without passing the adapter. the adapter will be controlled by the umbrella
+const trading = TradingSdk(...)
+```
+
+### Options
+
+For detailed information about trading steps you can enable the SDK logging and configure UTM tracking:
+
+```typescript
+import { SupportedChainId, TradingSdk, TradingSdkOptions } from '@cowprotocol/cow-sdk'
+
+const traderParams = {
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+  signer: '<privateKeyOrEthersSigner>', // signer is optional - will use global adapter's signer if not provided
+}
+
+const sdkOptions: TradingSdkOptions = {
+  enableLogging: true, // enables detailed logging of trading steps
+  utmContent: '🐮 moo-ving to defi 🐮', // custom UTM content for tracking
+  disableUtm: false, // set to true to disable UTM tracking completely
+}
+
+const sdk = new TradingSdk(traderParams, sdkOptions)
+```
+
+### getQuote
+
+In case if you want to get a quote and only then create an order, you can use the `getQuote` function.
+
+The parameters required are the same as for the `postSwapOrder` function.
+
+The function returns `quoteResults` object with the following properties:
+
+- `tradeParameters` - trade type, assets, amounts and other optional parameters
+- `amountsAndCosts` - the order sell/buy amounts including network costs, fees and slippage
+- `orderToSign` - order parameters to sign (see [order signing](https://docs.cow.fi/cow-protocol/reference/sdks/cow-sdk/classes/OrderSigningUtils))
+- `quoteResponse` - DTO from [quote API](https://api.cow.fi/docs/#/default/post_api_v1_quote)
+- `appDataInfo` - [order's metadata](https://docs.cow.fi/cow-protocol/reference/sdks/app-data)
+- `orderTypedData` - EIP-712 typed data for signing
+
+Another parameter is returned by this function is `postSwapOrderFromQuote`.
+It can be used to create an order from the received quote.
+
+#### Example
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const { quoteResults, postSwapOrderFromQuote } = await sdk.getQuote(parameters)
+
+const buyAmount = quoteResults.amountsAndCosts.afterSlippage.buyAmount
+
+if (confirm(`You will get at least: ${buyAmount}, ok?`)) {
+  const orderId = await postSwapOrderFromQuote()
+
+  console.log('Order created, id: ', orderId)
+}
+```
+
+### postSwapOrder
+
+This function fetches a quote for a swap order and just creates the order.
+
+The parameters required are:
+
+- `kind` - the order kind (sell/buy)
+- `sellToken` - the sell token address
+- `sellTokenDecimals` - the sell token decimals
+- `buyToken` - the buy token address
+- `buyTokenDecimals` - the buy token decimals
+- `amount` - the amount to sell/buy in atoms
+
+> When sell token is a blockchain native token (ETH for Ethereum), then order will be created as an on-chain transaction. See the `postSellNativeCurrencyOrder` method below for more details.
+
+#### Example
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const { orderId } = await sdk.postSwapOrder(parameters)
+
+console.log('Order created, id: ', orderId)
+```
+
+### postLimitOrder
+
+This main difference between this function and `postSwapOrder` is that here you need to specify both sell and buy amounts.
+
+You need to provide the following parameters:
+
+- `kind` - the order kind (sell/buy)
+- `sellToken` - the sell token address
+- `sellTokenDecimals` - the sell token decimals
+- `buyToken` - the buy token address
+- `buyTokenDecimals` - the buy token decimals
+- `sellAmount` - the amount to sell in atoms
+- `buyAmount` - the amount to buy in atoms
+
+And optional parameters:
+
+- `quoteId` - id of the quote from the quote API (see getQuote function)
+- `validTo` - the order expiration time in seconds
+
+```typescript
+import { SupportedChainId, OrderKind, LimitTradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const limitOrderParameters: LimitTradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  sellAmount: '120000000000000000',
+  buyAmount: '66600000000000000000',
+}
+
+const { orderId } = await sdk.postLimitOrder(limitOrderParameters)
+
+console.log('Order created, id: ', orderId)
+```
+
+### postSellNativeCurrencyOrder
+
+CoW Protocol supports on-chain trades for selling blockchain native tokens (ETH for Ethereum).
+In this case, the order is created as an on-chain transaction.
+You don't have to think about the case when you use `postSwapOrder` function, it will be handled automatically.
+But if you need more flexible way to create an order to sell native token, you can use the `postSellNativeCurrencyOrder` function.
+
+> We consider the order as native token selling order if the sell token has '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee' address.
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const { orderId } = await sdk.postSellNativeCurrencyOrder(parameters)
+
+console.log('Order created, id: ', orderId)
+```
+
+### Get quote for a smart-contract wallet
+
+If you want to use a smart-contract wallet to sign the order, you should specify the `signingScheme` parameter in order to get more accurate quote in terms of gas efficiency.
+Smart-contract wallets are supported by using a different signing scheme - `SigningScheme.PRESIGN`.
+
+#### Example
+
+```typescript
+import {
+  SupportedChainId,
+  OrderKind,
+  TradeParameters,
+  SwapAdvancedSettings,
+  SigningScheme,
+  TradingSdk,
+} from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const advancedParameters: SwapAdvancedSettings = {
+  quoteRequest: {
+    // Specify the signing scheme
+    signingScheme: SigningScheme.PRESIGN,
+  },
+}
+
+const { quoteResults } = await sdk.getQuote(parameters)
+
+console.log('Quote:', quoteResults)
+```
+
+### Create an order with smart-contract wallet
+
+If you want to create an order with a smart-contract wallet, you should specify the `signingScheme` parameter in the `postSwapOrder` function.
+And then you need to send a transaction from `getPreSignTransaction` result in order to sign the order.
+
+#### Example of Swap order
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const advancedParameters: SwapAdvancedSettings = {
+  quoteRequest: {
+    // Specify the signing scheme
+    signingScheme: SigningScheme.PRESIGN,
+  },
+}
+
+const smartContractWalletAddress = '0x<smartContractWalletAddress>'
+const { orderId } = await sdk.postSwapOrder(parameters, advancedParameters)
+const preSignTransaction = await sdk.getPreSignTransaction({ orderId, account: smartContractWalletAddress })
+
+console.log('Order created with "pre-sign" state, id: ', orderId)
+console.log('Execute the transaction to sign the order', preSignTransaction)
+```
+
+#### Example of Limit order
+
+```typescript
+import {
+  SupportedChainId,
+  OrderKind,
+  LimitTradeParameters,
+  LimitOrderAdvancedSettings,
+  SigningScheme,
+  TradingSdk,
+} from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const smartContractWalletAddress = '0x<smartContractWalletAddress>'
+
+const limitOrderParameters: LimitTradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  sellAmount: '120000000000000000',
+  buyAmount: '66600000000000000000',
+  owner: smartContractWalletAddress, // See note bellow why you need to specify the parameter
+}
+
+const advancedParameters: LimitOrderAdvancedSettings = {
+  additionalParams: {
+    signingScheme: SigningScheme.PRESIGN,
+  },
+}
+
+const { orderId } = await sdk.postLimitOrder(limitOrderParameters, advancedParameters)
+const preSignTransaction = await sdk.getPreSignTransaction({ orderId, account: smartContractWalletAddress })
+
+console.log('Order created with "pre-sign" state, id: ', orderId)
+console.log('Execute the transaction to sign the order', preSignTransaction)
+```
+
+> **Note:** it's important to specify the `owner` parameter if you create an order with a smart-contract wallet, and it differs from the signer (for example Safe).
+> CoW Protocol will use `owner` in order to check the order owner balance, allowance and other things.
+
+### Optional parameters
+
+Both `postSwapOrder` and `postLimitOrder` functions have optional parameters.
+See `TradeOptionalParameters` type for more details.
+
+| **Parameter**       | **Type**     | **Default Value** | **Description**                                                                                                                                                                                   |
+| ------------------- | ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`               | `Env`        | `prod`            | The environment to use (`prod` or `staging`).                                                                                                                                                     |
+| `partiallyFillable` | `boolean`    | `false`           | Indicates whether the order is fill-or-kill or partially fillable.                                                                                                                                |
+| `slippageBps`       | `number`     | 50                | Slippage tolerance applied to the order to get the limit price. Expressed in Basis Points (BPS). One basis point is equivalent to 0.01% (1/100th of a percent).                                   |
+| `receiver`          | `string`     | order creator     | The address that will receive the order's tokens.                                                                                                                                                 |
+| `validFor`          | `number`     | 30 mins           | The order expiration time in seconds.                                                                                                                                                             |
+| `partnerFee`        | `PartnerFee` | -                 | Partners of the protocol can specify their fee for the order, including the fee in basis points (BPS) and the fee recipient address. [Read more](https://docs.cow.fi/governance/fees/partner-fee) |
+
+##### Example
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+  // Optional parameters
+  slippageBps: 200, // 2%
+  validFor: 1200, // 20 mins
+  receiver: '0xdef1ca1fb7f1232777520aa7f396b4e015f497ab', // Just a random address, don't use it!
+}
+
+const { orderId } = await sdk.postSwapOrder(parameters)
+
+console.log('Order created, id: ', orderId)
+```
+
+### Advanced swap order creation
+
+By default, the SDK requires only the basic parameters to create an order.
+However, you can provide additional parameters to customize the order creation.
+
+#### Swap
+
+1. `quoteRequest` - the quote request object. It is used to get a quote from the quote API ([read more](https://docs.cow.fi/cow-protocol/reference/sdks/cow-sdk/modules#orderquoterequest))
+2. `appData` - the order's metadata ([read more](https://docs.cow.fi/cow-protocol/reference/sdks/app-data/modules#appdataparams))
+
+##### Example
+
+```typescript
+import {
+  SupportedChainId,
+  OrderKind,
+  TradeParameters,
+  TradingSdk,
+  SwapAdvancedSettings,
+  PriceQuality,
+} from '@cowprotocol/cow-sdk'
+
+// Proper adapter initialization (see setup example above)
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  appCode: '<YOUR_APP_CODE>',
+})
+
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+}
+
+const advancedSettings: SwapAdvancedSettings = {
+  quoteRequest: {
+    priceQuality: PriceQuality.FAST,
+    validFor: 120,
+  },
+  appData: {
+    hooks: {
+      version: 1,
+      pre: [
+        {
+          target: '0xdef1ca1fb7fbcdc777520aa7f396b4e015f497ab',
+          callData: '0x70a08231000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045',
+          gasLimit: 21000,
+        },
+      ],
+    },
+  },
+}
+const { orderId } = await sdk.postSwapOrder(parameters, advancedSettings)
+
+console.log('Order created, id: ', orderId)
+```
+
+#### Limit order
+
+Same as for the swap order but without the `quoteRequest` parameter.