@cowprotocol/cow-sdk 6.0.0-RC.9 → 6.0.0

package/dist/src/trading/README.md

@@ -127,6 +127,51 @@ if (confirm(`You will get at least: ${buyAmount}, ok?`)) {
 }
 ```
 
+#### Slippage
+
+Considering the market volatility, order needs to have a proper slippage value.
+You can manually specify a slippage:
+```typescript
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000',
+  slippageBps: 100 // 1%
+}
+
+const { quoteResults, postSwapOrderFromQuote } = await sdk.getQuote(parameters)
+```
+
+**OR, `TradingSDK` can suggest you slippage specifically for you trade.**
+In that case you should not specify `slippageBps` in the quote request.
+The slippage will be calculated automatically taking into account current network fees, trade amounts, and other conditions.
+The suggested slippage value will be returned as `suggestedSlippageBps` parameter in the quote response.
+If you post an order using `postSwapOrderFromQuote()`, then you don't need to specify any parameters, everything will happen automatically.
+
+> Note: Suggested slippage might be 100% in some cases.
+> This can happen, for example, if the order size is very small.
+> Please verify thise value on your side before posting an order!
+
+```typescript
+const parameters: TradeParameters = {
+  kind: OrderKind.BUY,
+  sellToken: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
+  sellTokenDecimals: 18,
+  buyToken: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
+  buyTokenDecimals: 18,
+  amount: '120000000000000000'
+}
+
+const { quoteResults: { suggestedSlippageBps }, postSwapOrderFromQuote } = await sdk.getQuote(parameters)
+
+console.log(`Suggested slippage is ${suggestedSlippageBps} BPS`)
+
+postSwapOrderFromQuote() // Order will be posted to order-book with the suggested slippage
+```
+
 ### postSwapOrder
 
 This function fetches a quote for a swap order and just creates the order.
@@ -166,7 +211,7 @@ const parameters: TradeParameters = {
   amount: '120000000000000000'
 }
 
-const orderId = await sdk.postSwapOrder(parameters)
+const { orderId } = await sdk.postSwapOrder(parameters)
 
 console.log('Order created, id: ', orderId)
 ```
@@ -212,7 +257,7 @@ const limitOrderParameters: LimitTradeParameters = {
   buyAmount: '66600000000000000000',
 }
 
-const orderId = await sdk.postLimitOrder(limitOrderParameters)
+const { orderId } = await sdk.postLimitOrder(limitOrderParameters)
 
 console.log('Order created, id: ', orderId)
 ```
@@ -249,7 +294,7 @@ const parameters: TradeParameters = {
   amount: '120000000000000000'
 }
 
-const orderId = await sdk.postSellNativeCurrencyOrder(parameters)
+const { orderId } = await sdk.postSellNativeCurrencyOrder(parameters)
 
 console.log('Order created, id: ', orderId)
 ```
@@ -304,7 +349,7 @@ console.log('Quote:', quoteResults)
 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
+#### Example of Swap order
 
 ```typescript
 import {
@@ -337,13 +382,60 @@ const advancedParameters: SwapAdvancedSettings = {
 }
 
 const smartContractWalletAddress = '0x<smartContractWalletAddress>'
-const orderId = await sdk.postSwapOrder(parameters, advancedParameters)
+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'
+
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  signer: '<privateKeyOrEthersSigner>',
+  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.
@@ -382,7 +474,7 @@ const parameters: TradeParameters = {
   receiver: '0xdef1ca1fb7f1232777520aa7f396b4e015f497ab' // Just a random address, don't use it!
 }
 
-const orderId = await sdk.postSwapOrder(parameters)
+const { orderId } = await sdk.postSwapOrder(parameters)
 
 console.log('Order created, id: ', orderId)
 ```
@@ -442,7 +534,7 @@ const advancedSettings: SwapAdvancedSettings = {
     }
   },
 }
-const orderId = await sdk.postSwapOrder(parameters, advancedSettings)
+const { orderId } = await sdk.postSwapOrder(parameters, advancedSettings)
 
 console.log('Order created, id: ', orderId)
 ```

package/dist/subgraph/api.d.ts

@@ -1,77 +1,77 @@
-import { Variables } from 'graphql-request';
-import { DocumentNode } from 'graphql/index';
-import { SupportedChainId } from '../chains/types';
-import { ApiContext } from '../common/types/config';
-import { LastDaysVolumeQuery, LastHoursVolumeQuery, TotalsQuery } from './graphql';
-type SubgraphApiBaseUrls = Record<SupportedChainId, string | null>;
-interface SubgraphApiContext extends Omit<ApiContext, 'baseUrls'> {
-    baseUrls?: SubgraphApiBaseUrls;
-}
-type PartialSubgraphApiContext = Partial<SubgraphApiContext>;
-/**
- * CoW Protocol Production Subgraph API configuration.
- * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow}
- * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-gc}
- */
-export declare const SUBGRAPH_PROD_CONFIG: SubgraphApiBaseUrls;
-/**
- * CoW Protocol Staging Subgraph API configuration.
- * @deprecated
- * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-staging}
- * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-gc-staging}
- */
-export declare const SUBGRAPH_STAGING_CONFIG: SubgraphApiBaseUrls;
-/**
- * TheGraph API client for CoW Protocol.
- */
-export declare class SubgraphApi {
-    API_NAME: string;
-    context: SubgraphApiContext;
-    /**
-     * Create a new CoW Protocol API instance.
-     * @param context Any properties of the {@link SubgraphApiContext} may be overridden by passing a {@link PartialSubgraphApiContext}.
-     */
-    constructor(context?: PartialSubgraphApiContext);
-    /**
-     * Query the totals from TheGraph for the CoW Protocol.
-     * @param contextOverride Override the context for this call only.
-     * @returns The totals for the CoW Protocol.
-     */
-    getTotals(contextOverride?: PartialSubgraphApiContext): Promise<TotalsQuery['totals'][0]>;
-    /**
-     * Query the volume over the last N days from TheGraph for the CoW Protocol.
-     * @param {number} days The number of days to query.
-     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
-     * @returns The volume for the last N days.
-     */
-    getLastDaysVolume(days: number, contextOverride?: PartialSubgraphApiContext): Promise<LastDaysVolumeQuery>;
-    /**
-     * Query the volume over the last N hours from TheGraph for the CoW Protocol.
-     * @param {number} hours The number of hours to query.
-     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
-     * @returns The volume for the last N hours.
-     */
-    getLastHoursVolume(hours: number, contextOverride?: PartialSubgraphApiContext): Promise<LastHoursVolumeQuery>;
-    /**
-     * Run a query against the CoW Protocol Subgraph.
-     * @param {string | DocumentNode} query GQL query string or DocumentNode.
-     * @param {Variables | undefined} variables To be passed to the query.
-     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
-     * @returns Results of the query.
-     * @throws {@link CowError} if the query fails.
-     */
-    runQuery<T>(query: string | DocumentNode, variables?: Variables | undefined, contextOverride?: PartialSubgraphApiContext): Promise<T>;
-    /**
-     * Override parts of the context for a specific call.
-     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
-     * @returns {SubgraphApiContext} The context with the override applied.
-     */
-    private getContextWithOverride;
-    /**
-     * Get the base URLs for the given environment.
-     * @param {CowEnv} env The environment to get the base URLs for.
-     * @returns {ApiBaseUrls} The base URLs for the given environment.
-     */
-    private getEnvConfigs;
-}
-export {};
+import { Variables } from 'graphql-request';
+import { DocumentNode } from 'graphql/index';
+import { SupportedChainId } from '../chains/types';
+import { ApiContext } from '../common/types/config';
+import { LastDaysVolumeQuery, LastHoursVolumeQuery, TotalsQuery } from './graphql';
+type SubgraphApiBaseUrls = Record<SupportedChainId, string | null>;
+interface SubgraphApiContext extends Omit<ApiContext, 'baseUrls'> {
+    baseUrls?: SubgraphApiBaseUrls;
+}
+type PartialSubgraphApiContext = Partial<SubgraphApiContext>;
+/**
+ * CoW Protocol Production Subgraph API configuration.
+ * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow}
+ * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-gc}
+ */
+export declare const SUBGRAPH_PROD_CONFIG: SubgraphApiBaseUrls;
+/**
+ * CoW Protocol Staging Subgraph API configuration.
+ * @deprecated
+ * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-staging}
+ * @see {@link https://api.thegraph.com/subgraphs/name/cowprotocol/cow-gc-staging}
+ */
+export declare const SUBGRAPH_STAGING_CONFIG: SubgraphApiBaseUrls;
+/**
+ * TheGraph API client for CoW Protocol.
+ */
+export declare class SubgraphApi {
+    API_NAME: string;
+    context: SubgraphApiContext;
+    /**
+     * Create a new CoW Protocol API instance.
+     * @param context Any properties of the {@link SubgraphApiContext} may be overridden by passing a {@link PartialSubgraphApiContext}.
+     */
+    constructor(context?: PartialSubgraphApiContext);
+    /**
+     * Query the totals from TheGraph for the CoW Protocol.
+     * @param contextOverride Override the context for this call only.
+     * @returns The totals for the CoW Protocol.
+     */
+    getTotals(contextOverride?: PartialSubgraphApiContext): Promise<TotalsQuery['totals'][0]>;
+    /**
+     * Query the volume over the last N days from TheGraph for the CoW Protocol.
+     * @param {number} days The number of days to query.
+     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
+     * @returns The volume for the last N days.
+     */
+    getLastDaysVolume(days: number, contextOverride?: PartialSubgraphApiContext): Promise<LastDaysVolumeQuery>;
+    /**
+     * Query the volume over the last N hours from TheGraph for the CoW Protocol.
+     * @param {number} hours The number of hours to query.
+     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
+     * @returns The volume for the last N hours.
+     */
+    getLastHoursVolume(hours: number, contextOverride?: PartialSubgraphApiContext): Promise<LastHoursVolumeQuery>;
+    /**
+     * Run a query against the CoW Protocol Subgraph.
+     * @param {string | DocumentNode} query GQL query string or DocumentNode.
+     * @param {Variables | undefined} variables To be passed to the query.
+     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
+     * @returns Results of the query.
+     * @throws {@link CowError} if the query fails.
+     */
+    runQuery<T>(query: string | DocumentNode, variables?: Variables | undefined, contextOverride?: PartialSubgraphApiContext): Promise<T>;
+    /**
+     * Override parts of the context for a specific call.
+     * @param {PartialSubgraphApiContext} contextOverride Override the context for this call only.
+     * @returns {SubgraphApiContext} The context with the override applied.
+     */
+    private getContextWithOverride;
+    /**
+     * Get the base URLs for the given environment.
+     * @param {CowEnv} env The environment to get the base URLs for.
+     * @returns {ApiBaseUrls} The base URLs for the given environment.
+     */
+    private getEnvConfigs;
+}
+export {};