@cowprotocol/cow-sdk 2.0.0-alpha.5 → 2.0.0

package/README.md

@@ -4,375 +4,121 @@
 
 # CoW SDK
 
-[![Styled With Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io/)
-[![Coverage Status](https://coveralls.io/repos/github/cowprotocol/cow-sdk/badge.svg?branch=main)](https://coveralls.io/github/cowprotocol/cow-sdk?branch=main)
+## 📚 [SDK docs website](https://docs.cow.fi/cow-sdk)
 
-## Getting started
-
-Install the SDK:
-
-```bash
-yarn add @cowprotocol/cow-sdk
-```
-
-Instantiate the SDK:
-
-```js
-import { CowSdk } from '@cowprotocol/cow-sdk'
-
-const chainId = 100 // Gnosis chain
-const cowSdk = new CowSdk(chainId)
-```
-
-The SDK will expose:
-
-- The CoW API (`cowSdk.cowApi`)
-- The CoW Subgraph (`cowSdk.cowSubgraphApi`)
-- Convenient method to facilitate signing orders (i.e `cowSdk.signOrder`)
-
-> For a quick snippet with the full process on posting an order see the [Post an Order Example](./docs/post-order-example.ts)
-
-## CoW API
-
-The SDK provides access to the CoW API. The CoW API allows you:
-
-- Post orders
-- Get fee quotes
-- Get order details
-- Get history of orders: i.e. filtering by account, transaction hash, etc.
-
-For example, you can easily get the last 5 order of a trader:
-
-```js
-// i.e. Get last 5 orders for a given trader
-const trades = await cowSdk.cowApi.getOrders({
-  owner: '0x00000000005ef87f8ca7014309ece7260bbcdaeb', // Trader
-  limit: 5,
-  offset: 0,
-})
-console.log(trades)
-```
-
-> For more information about the API methods, you can check [api.cow.fi/docs](https://api.cow.fi/docs).
-
-## Sign and Post orders
-
-In order to trade, you will need to create a valid order first.
-
-On the contraty to other decentralised exchanges, creating orders is free in CoW Protocol. This is because, one of the
-most common ways to do it is by created offchain signed messages (meta-transactions, uses `EIP-712` or `EIP-1271`).
-
-Posting orders is a three steps process:
-
-- 1. **Get Market Pricea**: Fee & Price
-- 2. **Sign the order**: Using off-chain signing or Meta-transactions
-- 3. **Post the signed order to the API**: So, the order becomes `OPEN`
-
-The next sections will guide you through the process of creating a valid order.
-
-> For a quick snippet with the full process on posting an order see the [Post an Order Example](./docs/post-order-example.ts).
+## Test coverage
 
-### Enable tokens (token approval)
-Because of the use of off-chain signing (meta-transactions), users will need to **Enable the sell token** before signed
-orders can be considered as valid ones.
+| Statements                                                                                 | Branches                                                                       | Functions                                                                                | Lines                                                                            |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| ![Statements](https://img.shields.io/badge/statements-94.77%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-76.78%25-red.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-97.43%25-brightgreen.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-97.67%25-brightgreen.svg?style=flat) |
 
-This enabling is technically an `ERC-20` approval, and is something that needs to be done only once. After this all
-order creation can be done for free using offchain signing.
-
-> For more details see https://docs.cow.fi/tutorials/how-to-submit-orders-via-the-api/1.-set-allowance-for-the-sell-token
-
-### Instantiate SDK with a signer
-
-Before you can sign any transaction, you have to instantiate the SDK with a [Ethers.JS signer](https://docs.ethers.io/v5/api/signer/):
-
-```js
-import { Wallet } from 'ethers'
-import { CowSdk, OrderKind } from '@cowprotocol/cow-sdk'
-
-const mnemonic = 'fall dirt bread cactus...'
-const wallet = Wallet.fromMnemonic(mnemonic)
-
-const cowSdk = new CowSdk(
-  100, {            // Leaving chainId empty will default to MAINNET
-  signer: wallet  // Provide a signer, so you can sign order
-})
-```
-
-### STEP 1: Get Market Price
-
-To create an order, you need to get a price/fee quote first:
-
-  * The SDK will give you easy access to the API, which returns the `Market Price` and the `Fee` for any given trade you intent to do.
-  * The returned `Market Price` is not strictly needed, you can use your own pricing logic.
-    * You can choose a price that is below this Market price (**Market Order**), or above Market Price (**Limit Order**).
-  * The `Fee` however is very important.
-    * It is the required amount in sell token the trader agrees on paying for executing the order onchain.
-    * Normally, its value is proportional to the current Gas Price of the network.
-    * This fee is never charged if you don't trade.
-
-To get the quote, you simply specify the trade you intent to do:
-
-```js
-const quoteResponse = await cowSdk.cowApi.getQuote({
-  kind: OrderKind.SELL, // Sell order (could also be BUY)
-  sellToken: '0xc778417e063141139fce010982780140aa0cd5ab', // WETH
-  buyToken: '0x4dbcdf9b62e891a7cec5a2568c3f4faf9e8abe2b', // USDC
-  amount: '1000000000000000000', // 1 WETH
-  userAddress: '0x1811be0994930fe9480eaede25165608b093ad7a', // Trader
-  validTo: 2524608000,
-})
-
-const { sellToken, buyToken, validTo, buyAmount, sellAmount, receiver, feeAmount } = quoteResponse.quote
-```
-
-### STEP 2: Sign the order
-
-Once you know the price and fee, we can create the order and sign it:
-
-- Technically the order is just a signed message with your intent to trade, and contains your `Limit Price` and `Fee`.
-- As explained before, you can choose your `Limit Price`, but some general approach is to take the current Market Price
-  and apply some slippage tolerance to it. `Received Amount = Expected Amount * (1 - Slippage Tolerance)`
-- The SDK will provide an easy way to sign orders given the raw data
-
-```js
-const { sellToken, buyToken, validTo, buyAmount, sellAmount, receiver, feeAmount } = quoteResponse.quote
-
-// Prepare the RAW order
-const order = {
-  kind: OrderKind.SELL, // SELL || BUY
-  receiver, // Your account or any other
-  sellToken,
-  buyToken,
-
-  partiallyFillable: false, // ("false" is for a "Fill or Kill" order, "true" for allowing "Partial execution" which is not supported yet)
-
-  // Deadline
-  validTo,
-
-  // Limit Price
-  //    You can apply some slippage tolerance here to make sure the trade is executed.
-  //    CoW protocol protects from MEV, so it can work with higher slippages
-  sellAmount,
-  buyAmount,
+## Getting started
 
-  // Use the fee you received from the API
-  feeAmount,
+**Usage examples: [VanillaJS](./examples/vanilla/src/index.ts), [Create React App](./examples/cra/src/pages/getOrders/index.tsx), [NodeJS](./examples/nodejs/src/index.ts)**
 
-  // The appData allows you to attach arbitrary information (meta-data) to the order. Its explained in their own section. For now, you can use this 0x0 value
-  appData: '0x0000000000000000000000000000000000000000000000000000000000000000',
-}
+### Installation
 
-// Sign the order
-const signedOrder = await cowSdk.signOrder(order)
+```bash
+yarn add @cowprotocol/cow-sdk
 ```
 
-At this point, you have a signed order. So next step will be to post it to the API so it's considered by the solvers and executed.
-
-## STEP 3: **Post the signed order to the API**:
+### Content
 
-Once you have a signed order, last step is to send it to the API.
+- `OrderBookApi` - provides the ability to retrieve orders and trades from the CowSap order-book, as well as add and cancel them
+- `OrderSigningUtils` - serves to sign orders and cancel them using [EIP-712](https://eips.ethereum.org/EIPS/eip-712)
+- `SubgraphApi` - provides statistics data about CoW protocol from [Subgraph](https://github.com/cowprotocol/subgraph), such as trading volume, trades count and others
 
-- The API will accept the order if its correctly signed, the deadline is correct, and the fee is enough to settle it
-- Once accepted, the order will be `OPEN` until the specified `validTo` date (expiration)
-- The possible outcomes once accepted is:
-  - The order is `EXECUTED`: you will pay the signed fee, and get at least the `buyAmount` tokens you specified, although you will probably get more! (you will probably get a so-called **Surplus**).
-  - The order `EXPIRES`: If your price is not good enough, and the order is out of the market price before
-    expiration, your order will expire. This doesn't have any cost to the user, which **only pays the fee if the trade is executed**.
-  - You cancel the order, so it becomes `CANCELLED`. Cancelling an order can be done both as a free meta-transaction
-    (**soft cancelations**) or as a regular on-chain transaction (**hard cancelations**).
-- The API will return an `orderId` which identifies the order, and is created as a summary (hash) of it. In other words, the `orderId` is deterministic given all the order parameters.
 
-Post an order using the SDK:
+```typescript
+import { OrderBookApi, OrderSigningUtils, SubgraphApi } from '@cowprotocol/cow-sdk'
 
-```js
-const orderId = await cowSdk.cowApi.sendOrder({
-  order: { ...order, ...signedOrder },
-  owner: '0x1811be0994930fe9480eaede25165608b093ad7a',
-})
-```
-
-### BONUS: Show link to Explorer
-Once the order is posted, its good to allow to check the state of it.
-
-One easy is to check in the CoW Explorer. You can create a CoW Explorer link if you have the `orderId`:
+const chainId = 100 // Gnosis chain
 
-```js
-// View order in explorer
-console.log(`https://explorer.cow.fi/gc/orders/${orderId}`)
+const orderBookApi = new OrderBookApi({ chainId })
+const subgraphApi = new SubgraphApi({ chainId })
+const orderSigningUtils = new OrderSigningUtils()
 ```
 
-## Create a meta-data document for attaching to an order
-
-Orders in CoW Protocol can contain arbitrary data in a field called `AppData`.
-
-The SDK facilitates the creation of these documents, and getting the `AppData` Hex number that summarizes it.
-
-The most important thing to define in the meta-data is the name of your app, so the order-flow can be credited to it.
+## Quick start
 
-```js
-const appDataDoc = cowSdk.metadataApi.generateAppDataDoc({
-  appDataParams: { appCode: 'YourApp' },
-})
-```
+### Sign, fetch, post and cancel order
 
-This will create a document similar to:
+For clarity, let's look at the use of the API with a practical example:
+Exchanging `0.4 GNO` to `WETH` on `Goerli` network.
 
-```json
-{
-  "version": "0.4.0",
-  "appCode": "YourApp",
-  "metadata": {}
-}
-```
+We will do the following operations:
+1. Get a quote
+2. Sign the order
+3. Send the order to the order-book
+4. Get the data of the created order
+5. Get trades of the order
+6. Cancel the order (signing + sending)
 
-After creating the most basic document, you can see how to attach additional meta-data items.
+[You also can check this code in the CRA example](./examples/cra/src/pages/quickStart/index.tsx)
 
-For example, you could give information about who referred the user creating the order.
 
-```js
-const appDataDoc = cowSdk.metadataApi.generateAppDataDoc({
-  appDataParams: { appCode: 'YourApp' },
-  metadataParas: {
-    referrerParams: {
-      address: '0x1f5B740436Fc5935622e92aa3b46818906F416E9',
-    },
-  },
-})
-```
+```typescript
+import { OrderBookApi, OrderSigningUtils, SupportedChainId } from '@cowprotocol/cow-sdk'
+import { Web3Provider } from '@ethersproject/providers'
 
-This will create a document similar to:
+const account = 'YOUR_WALLET_ADDRESS'
+const chainId = 5 // Goerli
+const provider = new Web3Provider(window.ethereum)
+const signer = provider.getSigner()
 
-```json
-{
-  "version": "0.4.0",
-  "appCode": "YourApp",
-  "metadata": {
-    "referrer": {
-      "address": "0x1f5B740436Fc5935622e92aa3b46818906F416E9",
-      "version": "0.1.0"
-    }
-  }
+const quoteRequest = {
+  sellToken: '0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6', // WETH goerli
+  buyToken: '0x02abbdbaaa7b1bb64b5c878f7ac17f8dda169532', // GNO goerli
+  from: account,
+  receiver: account,
+  sellAmountBeforeFee: (0.4 * 10 ** 18).toString(), // 0.4 WETH
+  kind: OrderQuoteSide.kind.SELL,
 }
-```
 
-The method `cowSdk.metadataApi.generateAppDataDoc` will always create the latest schema version.
+const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.GOERLI })
 
-For a complete list of metadata that can be attached and for previous versions
-check `@cowprotocol/app-data` [repository](https://github.com/cowprotocol/app-data)
-and [NPM package](https://www.npmjs.com/package/@cowprotocol/app-data)
+async function main() {
+    const { quote } = await orderBookApi.getQuote(quoteRequest)
 
-## Get the AppData Hex
+    const orderSigningResult = await OrderSigningUtils.signOrder(quote, chainId, signer)
 
-The `AppData` Hex points to an IPFS document with the meta-data attached to the order.
+    const orderId = await orderBookApi.sendOrder({ ...quote, ...orderSigningResult })
 
-You can calculate the `AppData` Hex, and its corresponding `cidV0` using the SDK:
+    const order = await orderBookApi.getOrder(orderId)
 
-```js
-const { appDataHash, cidv0 } = await cowSdk.metadataApi.calculateAppDataHash(appDataDoc)
-```
-
-Note how this operation is deterministic, so given the same document, it will always generate the same hash.
+    const trades = await orderBookApi.getTrades({ orderId })
 
-This method can be used to calculate the actual hash before uploading the document to IPFS.
+    const orderCancellationSigningResult = await OrderSigningUtils.signOrderCancellations([orderId], chainId, signer)
 
-## Get meta-data document uploaded to IPFS from AppData
+    const cancellationResult = await orderBookApi.sendSignedOrderCancellations({...orderCancellationSigningResult, orderUids: [orderId] })
 
-Given the `AppData` of a document that has been uploaded to IPFS, you can easily retrieve the document.
-
-```js
-const appDataDoc = await cowSdk.metadataApi.decodeAppData(
-  '0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a073c9e5b13edc422f209ed80'
-)
-```
-
-This will return a document similar to:
-
-```json
-{
-  "version": "0.1.0",
-  "appCode": "YourApp",
-  "metadata": {
-    "referrer": {
-      "address": "0x1f5B740436Fc5935622e92aa3b46818906F416E9",
-      "version": "0.1.0"
-    }
-  }
+    console.log('Results: ', { orderId, order, trades, orderCancellationSigningResult, cancellationResult })
 }
 ```
+### Querying the Cow Subgraph
 
-## Upload document to IPFS
-
-The SDK uses Pinata to upload it to IPFS, so you will need an API Key in order to upload it using the SDK.
+The [Subgraph](https://github.com/cowprotocol/subgraph) is constantly indexing the protocol, making all the information more accessible. It provides information about trades, users, tokens and settlements. Additionally, it has some data aggregations which provides insights on the hourly/daily/totals USD volumes, trades, users, etc.
 
-Alternatively, you can upload the document on your own using any other service.
-
-```js
-// Make sure you provide the IPFS params when instantiating the SDK
-const cowSdk = new CowSdk(100, {
-  ipfs: {
-    pinataApiKey: 'YOUR_PINATA_API_KEY',
-    pinataApiSecret: 'YOUR_PINATA_API_SECRET',
-  },
-})
-
-// Upload to IPFS
-const uploadedAppDataHash = await cowSdk.metadataApi.uploadMetadataDocToIpfs(appDataDoc)
-```
-
-## Convert IPFS CIDv0 to AppData (and back)
-Given an IPFS CIDv0 you can convert it to an `AppData`
-
-```js
-const decodedAppDataHex = await cowSdk.metadataApi.cidToAppDataHex('QmUf2TrpSANVXdgcYfAAACe6kg551cY3rAemB7xfEMjYvs')
-```
-
-This will return an `AppData` hex: `0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a073c9e5b13edc422f209ed80`
-
-> This might be handy if you decide to upload the document to IPFS yourself and then you need the AppData to post your order
-
-Similarly, you can do the opposite and convert an `AppData` into an IPFS document:
-
-```js
-const decodedAppDataHex = await cowSdk.metadataApi.appDataHexToCid(hash)
-```
-
-This will return an IPFS CIDv0: `QmUf2TrpSANVXdgcYfAAACe6kg551cY3rAemB7xfEMjYvs`
-
-## Getting appData schema files
-
-It's possible to get schema files directly for each exported version using `getAppDataSchema`
-
-```js
-const schema = await cowSdk.metadataApi.getAppDataSchema('0.4.0')
-```
-
-## Validating appDataDocs
-
-If for some reason you decide to create an `appDataDoc` without using the helper function, you can use `validateAppDataDoc` to validate it against the schema
-
-```js
-const { success, error } = await cowSdk.metadataApi.validateAppDataDoc({ version: '0.1.0', ... })
-```
-
-## Querying the Cow Subgraph
+The SDK provides just an easy way to access all this information.
 
 You can query the Cow Subgraph either by running some common queries exposed by the `CowSubgraphApi` or by building your own ones:
 
-```js
-const chainId = 1 // Mainnet
-const cowSdk = new CowSdk(chainId)
+```typescript
+import { SubgraphApi, SupportedChainId } from '@cowprotocol/cow-sdk'
 
-// Get Cow Protocol totals
+const subgraphApi = new SubgraphApi({ chainId: SupportedChainId.MAINNET })
+
+// Get CoW Protocol totals
 const { tokens, orders, traders, settlements, volumeUsd, volumeEth, feesUsd, feesEth } =
-  await cowSdk.cowSubgraphApi.getTotals()
+  await csubgraphApi.getTotals()
 console.log({ tokens, orders, traders, settlements, volumeUsd, volumeEth, feesUsd, feesEth })
 
 // Get last 24 hours volume in usd
-const { hourlyTotals } = await cowSdk.cowSubgraphApi.getLastHoursVolume(24)
+const { hourlyTotals } = await cowSubgraphApi.getLastHoursVolume(24)
 console.log(hourlyTotals)
 
 // Get last week volume in usd
-const { dailyTotals } = await cowSdk.cowSubgraphApi.getLastDaysVolume(7)
+const { dailyTotals } = await cowSubgraphApi.getLastDaysVolume(7)
 console.log(dailyTotals)
 
 // Get the last 5 batches
@@ -385,10 +131,19 @@ const query = `
   }
 `
 const variables = { n: 5 }
-const response = await cowSdk.cowSubgraphApi.runQuery(query, variables)
+const response = await cowSubgraphApi.runQuery(query, variables)
 console.log(response)
 ```
 
+
+## Architecture
+
+One way to make the most out of the SDK is to get familiar to its architecture.
+
+> See [SDK Architecture](./docs/architecture.md)
+
+## Development
+
 ### Install Dependencies
 
 ```bash
@@ -409,3 +164,12 @@ yarn start
 ```bash
 yarn test
 ```
+
+### Code generation
+
+Some parets of the SDK are automatically generated. This is the case for the Order Book APU and the Subgraph API
+
+```bash
+# Re-create automatically generated code
+yarn codegen
+```