From acb52ac181d23d61c6e2b6d188d02933d4b1349a Mon Sep 17 00:00:00 2001 From: Alexandr Kazachenko Date: Fri, 31 Mar 2023 20:36:25 +0600 Subject: [PATCH] SDK docs update corresponding to the new version (v2) (#6) * SDK docs update corresponding to the new version (v2) * Fix links --- SUMMARY.md | 1 - cow-sdk/README.md | 4 +- cow-sdk/cow-api.md | 6 ++- cow-sdk/getting-started-with-the-sdk.md | 17 ++++--- .../bonus-cidv0-and-appdata.md | 12 ++++- .../create-a-meta-data-document.md | 49 ++++++++++++------- .../download-a-document-given-the-appdata.md | 14 ++++-- .../get-the-appdata-hex.md | 6 ++- .../upload-document-to-ipfs.md | 23 +++++---- cow-sdk/querying-the-cow-subgraph.md | 13 ++--- cow-sdk/sign-and-post-orders/README.md | 2 +- .../bonus-show-link-to-explorer.md | 8 ++- .../instantiate-sdk-with-a-signer.md | 25 ---------- .../step-1-get-market-price.md | 6 ++- .../step-2-sign-the-order.md | 10 +++- ...step-3-post-the-signed-order-to-the-api.md | 9 ++-- 16 files changed, 117 insertions(+), 88 deletions(-) delete mode 100644 cow-sdk/sign-and-post-orders/instantiate-sdk-with-a-signer.md diff --git a/SUMMARY.md b/SUMMARY.md index b83b062..8e64fcf 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -68,7 +68,6 @@ * [CoW API](cow-sdk/cow-api.md) * [Sign and Post orders](cow-sdk/sign-and-post-orders/README.md) * [Enable Tokens](cow-sdk/sign-and-post-orders/enable-tokens.md) - * [Instantiate SDK with a signer](cow-sdk/sign-and-post-orders/instantiate-sdk-with-a-signer.md) * [STEP 1: Get Market Price](cow-sdk/sign-and-post-orders/step-1-get-market-price.md) * [STEP 2: Sign the order](cow-sdk/sign-and-post-orders/step-2-sign-the-order.md) * [STEP 3: Post the signed order to the API](cow-sdk/sign-and-post-orders/step-3-post-the-signed-order-to-the-api.md) diff --git a/cow-sdk/README.md b/cow-sdk/README.md index 404a6b1..b94f55c 100644 --- a/cow-sdk/README.md +++ b/cow-sdk/README.md @@ -26,9 +26,7 @@ CoW Swap uses CoW protocol. One easy way to get familiar with the protocol is by * [https://swap.cow.fi](https://swap.cow.fi/) -You can use it in **Rinkeby** test net if you want. Otherwise, it is avaiable in **Mainnet** and **Gnosis Chain**. +You can use it in **Goerli** test net if you want. Otherwise, it is avaiable in **Mainnet** and **Gnosis Chain**. -> 💡 If you need Rinkeby Ether, you can use this [Faucet](https://www.rinkeby.io/#faucet) -\ Now you are more familiar with the protocol and CoW Swap, let's introduce the SDK in the next section. diff --git a/cow-sdk/cow-api.md b/cow-sdk/cow-api.md index 2f56c59..d0d2cc3 100644 --- a/cow-sdk/cow-api.md +++ b/cow-sdk/cow-api.md @@ -10,8 +10,12 @@ The SDK provides access to the CoW API. The CoW API allows you: For example, you can easily get the last 5 order of a trader: ```typescript +import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk' + +const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.MAINNET }) + // i.e. Get last 5 orders for a given trader -const trades = await cowSdk.cowApi.getOrders({ +const trades = orderBookApi.getOrders({ owner: '0x00000000005ef87f8ca7014309ece7260bbcdaeb', // Trader limit: 5, offset: 0, diff --git a/cow-sdk/getting-started-with-the-sdk.md b/cow-sdk/getting-started-with-the-sdk.md index dbeaac9..a2a373e 100644 --- a/cow-sdk/getting-started-with-the-sdk.md +++ b/cow-sdk/getting-started-with-the-sdk.md @@ -9,18 +9,21 @@ yarn add @cowprotocol/cow-sdk Instantiate the SDK: ```javascript -import { CowSdk } from '@cowprotocol/cow-sdk' +import { OrderBookApi, OrderSigningUtils, SubgraphApi } from '@cowprotocol/cow-sdk' -const chainId = 4 // Rinkeby -const cowSdk = new CowSdk(chainId) +const chainId = 100 // Gnosis chain + +const orderBookApi = new OrderBookApi({ chainId }) +const subgraphApi = new SubgraphApi({ chainId }) +const orderSigningUtils = new OrderSigningUtils() ``` The SDK will expose: -* The CoW API (`cowSdk.cowApi`) -* The CoW Subgraph (`cowSdk.cowSubgraphApi`) -* Convenient method to facilitate signing orders (i.e `cowSdk.signOrder`) +- `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 -> 💡 For a quick snippet with the full process on posting an order see the [Post an Order Example](https://github.com/cowprotocol/cow-sdk/blob/e086d9edeb24b25bb873a11c462019fa1ea4c021/docs/post-order-example.ts) +> 💡 For a quick snippet with the full process on posting an order see the [Quick start example](https://github.com/cowprotocol/cow-sdk/blob/main/examples/cra/src/pages/quickStart/index.tsx) Now you should have a ready to use SDK instance. Let's explore in the next section, how we can use it to query the CoW API. diff --git a/cow-sdk/order-meta-data-appdata/bonus-cidv0-and-appdata.md b/cow-sdk/order-meta-data-appdata/bonus-cidv0-and-appdata.md index a23d102..830e3cd 100644 --- a/cow-sdk/order-meta-data-appdata/bonus-cidv0-and-appdata.md +++ b/cow-sdk/order-meta-data-appdata/bonus-cidv0-and-appdata.md @@ -5,7 +5,11 @@ As explained before, the `AppData` points to an IPFS document. So given any `CID Given an IPFS CIDv0 you can convert it to an `AppData` ```typescript -const decodedAppDataHex = await cowSdk.metadataApi.cidToAppDataHex('QmUf2TrpSANVXdgcYfAAACe6kg551cY3rAemB7xfEMjYvs') +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const decodedAppDataHex = await metadataApi.cidToAppDataHex('QmUf2TrpSANVXdgcYfAAACe6kg551cY3rAemB7xfEMjYvs') ``` This will return an `AppData` hex: `0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a073c9e5b13edc422f209ed80` @@ -15,7 +19,11 @@ This will return an `AppData` hex: `0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a07 Similarly, you can do the opposite and convert an `AppData` into an IPFS document: ```typescript -const decodedAppDataHex = await cowSdk.metadataApi.appDataHexToCid(hash) +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const decodedAppDataHex = await metadataApi.appDataHexToCid(hash) ``` This will return an IPFS CIDv0: `QmUf2TrpSANVXdgcYfAAACe6kg551cY3rAemB7xfEMjYvs` diff --git a/cow-sdk/order-meta-data-appdata/create-a-meta-data-document.md b/cow-sdk/order-meta-data-appdata/create-a-meta-data-document.md index 46abfb6..4bdc46f 100644 --- a/cow-sdk/order-meta-data-appdata/create-a-meta-data-document.md +++ b/cow-sdk/order-meta-data-appdata/create-a-meta-data-document.md @@ -7,18 +7,26 @@ The SDK facilitates the creation of these documents, and getting the `AppData` H 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. ```typescript -const appDataDoc = cowSdk.metadataApi.generateAppDataDoc({}, { - appCode: 'YourApp' +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const appCode = 'YOUR_APP_CODE' + +const appDataDoc = await metadataApi.generateAppDataDoc({ + appDataParams: { appCode }, }) + +console.log(appDataDoc) ``` This will create a document similar to: ```json { - "version": "0.1.0", - "appCode": "YourApp", - "metadata": {}, + "version": "0.5.0", + "appCode": "YOUR_APP_CODE", + "metadata": {} } ``` @@ -28,17 +36,20 @@ For example, you could give information about who reffered the user creating the {% code title="" %} ```typescript -const appDataDoc = cowSdk.metadataApi.generateAppDataDoc( - { - referrer: { - address: '0x1f5B740436Fc5935622e92aa3b46818906F416E9', - version: '0.1.0', - }, - }, - { - appCode: 'YourApp', - } -) +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const appCode = 'YOUR_APP_CODE' +const referrerParams = { address: '0x1f5B740436Fc5935622e92aa3b46818906F416E9' } + +const appDataDoc = await metadataApi.generateAppDataDoc({ + appDataParams: { appCode }, + metadataParams: { referrerParams }, +}) + +console.log(appDataDoc) + ``` {% endcode %} @@ -46,12 +57,12 @@ This will create a document similar to: ```json { - "version": "0.1.0", - "appCode": "YourApp", + "version": "0.5.0", + "appCode": "YOUR_APP_CODE", "metadata": { "referrer": { "address": "0x1f5B740436Fc5935622e92aa3b46818906F416E9", - "version": "0.1.0", + "version": "0.2.0" }, }, } diff --git a/cow-sdk/order-meta-data-appdata/download-a-document-given-the-appdata.md b/cow-sdk/order-meta-data-appdata/download-a-document-given-the-appdata.md index 616e3a4..e1e4c09 100644 --- a/cow-sdk/order-meta-data-appdata/download-a-document-given-the-appdata.md +++ b/cow-sdk/order-meta-data-appdata/download-a-document-given-the-appdata.md @@ -3,20 +3,24 @@ Given the `AppData` of a document that has been uploaded to IPFS, you can easily retrieve the document. ```javascript -const appDataDoc = await cowSdk.metadataApi.decodeAppData('0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a073c9e5b13edc422f209ed80') +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const appDataDoc = await metadataApi.decodeAppData('0x5ddb2c8207c10b96fac92cb934ef9ba004bc007a073c9e5b13edc422f209ed80') ``` This will return a document similar to: ```json { - "version": "0.1.0", + "version": "0.5.0", "appCode": "YourApp", "metadata": { "referrer": { "address": "0x1f5B740436Fc5935622e92aa3b46818906F416E9", - "version": "0.1.0", - }, - }, + "version": "0.2.0" + } + } } ``` diff --git a/cow-sdk/order-meta-data-appdata/get-the-appdata-hex.md b/cow-sdk/order-meta-data-appdata/get-the-appdata-hex.md index 53e3f76..62c66a2 100644 --- a/cow-sdk/order-meta-data-appdata/get-the-appdata-hex.md +++ b/cow-sdk/order-meta-data-appdata/get-the-appdata-hex.md @@ -5,7 +5,11 @@ The `AppData` Hex points to an IPFS document with the meta-data attached to the You can calculate the `AppData` Hex, and its corresponding `cidV0` using the SDK: ```javascript -const { appDataHash, cidv0 } = await cowSdk.metadataApi.calculateAppDataHash(appDataDoc) +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const { appDataHash, cidv0 } = await metadataApi.calculateAppDataHash(appDataDoc) ``` Note how this operation is deterministic, so given the same document, it will always generate the same hash. Also, this operation is done locally, so it's not uploading anything to IPFS, its just calculating what will be the hash that maps to the provided document. diff --git a/cow-sdk/order-meta-data-appdata/upload-document-to-ipfs.md b/cow-sdk/order-meta-data-appdata/upload-document-to-ipfs.md index cc5cae2..36fc356 100644 --- a/cow-sdk/order-meta-data-appdata/upload-document-to-ipfs.md +++ b/cow-sdk/order-meta-data-appdata/upload-document-to-ipfs.md @@ -5,14 +5,19 @@ The SDK uses Pinata to upload it to IPFS, so you will need an API Key in order t Alternativelly, you can upload the document on your own using any other service. ```typescript +import { MetadataApi } from '@cowprotocol/app-data' + +export const metadataApi = new MetadataApi() + +const IPFS_OPTIONS = { + pinataApiKey: `PINATA_API_KEY`, + pinataApiSecret: `PINATA_SECRET_API_KEY`, +} + +const appDataDoc = await metadataApi.generateAppDataDoc(...) + // Make sure you provide the IPFS params when instantiating the SDK -const cowSdk = new CowSdk(4, { - ipfs: { - pinataApiKey: 'YOUR_PINATA_API_KEY', - pinataApiSecret: 'YOUR_PINATA_API_SECRET' - }, -}) - -// Upload to IPFS -const uploadedAppDataHash = await cowSdk.metadataApi.uploadMetadataDocToIpfs(appDataDoc) +const uploadedAppDataHash = await metadataApi.uploadMetadataDocToIpfs(appDataDoc, IPFS_OPTIONS) + +console.log(uploadedAppDataHash) ``` diff --git a/cow-sdk/querying-the-cow-subgraph.md b/cow-sdk/querying-the-cow-subgraph.md index 645d478..a44c761 100644 --- a/cow-sdk/querying-the-cow-subgraph.md +++ b/cow-sdk/querying-the-cow-subgraph.md @@ -7,20 +7,21 @@ 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: ```typescript -const chainId = 1 // Mainnet -const cowSdk = new CowSdk(chainId) +import { SubgraphApi, SupportedChainId } from '@cowprotocol/cow-sdk' + +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 @@ -33,6 +34,6 @@ const query = ` } ` const variables = { n: 5 } -const response = await cowSdk.cowSubgraphApi.runQuery(query, variables) +const response = await cowSubgraphApi.runQuery(query, variables) console.log(response) ``` diff --git a/cow-sdk/sign-and-post-orders/README.md b/cow-sdk/sign-and-post-orders/README.md index 92db647..7201ca9 100644 --- a/cow-sdk/sign-and-post-orders/README.md +++ b/cow-sdk/sign-and-post-orders/README.md @@ -12,4 +12,4 @@ Posting orders is a three steps process: 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 step by step. If you feel impatient and you want just a quick example, please out the the [Post an Order Example](https://github.com/cowprotocol/cow-sdk/blob/e086d9edeb24b25bb873a11c462019fa1ea4c021/docs/post-order-example.ts). +The next sections will guide you through the process of creating a valid order step by step. If you feel impatient and you want just a quick example, please out the the [Quick start example](https://github.com/cowprotocol/cow-sdk/blob/main/examples/cra/src/pages/quickStart/index.tsx). diff --git a/cow-sdk/sign-and-post-orders/bonus-show-link-to-explorer.md b/cow-sdk/sign-and-post-orders/bonus-show-link-to-explorer.md index 6ee7aaf..d87c09d 100644 --- a/cow-sdk/sign-and-post-orders/bonus-show-link-to-explorer.md +++ b/cow-sdk/sign-and-post-orders/bonus-show-link-to-explorer.md @@ -4,11 +4,15 @@ 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`: -For example, you can see one valid order in the explorer by following the link [https://explorer.cow.fi/rinkeby/orders/0xa0a77033edd3ce261f6c7d2afa6c59f07b126e328ebaa8284aca01e4f30437d8](https://explorer.cow.fi/rinkeby/orders/0xa0a77033edd3ce261f6c7d2afa6c59f07b126e328ebaa8284aca01e4f30437d8) +For example, you can see one valid order in the explorer by following the link [https://explorer.cow.fi/goerli/orders/0xa0a77033edd3ce261f6c7d2afa6c59f07b126e328ebaa8284aca01e4f30437d8](https://explorer.cow.fi/goerli/orders/0xa0a77033edd3ce261f6c7d2afa6c59f07b126e328ebaa8284aca01e4f30437d8) ```javascript +import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk' + +const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.GOERLI }) + // View order in explorer -console.log(`https://explorer.cow.fi/rinkeby/orders/${orderId}`) +console.log(orderBookApi.getOrderLink(orderId)) // https://explorer.cow.fi/goerli/orders/${orderId} ``` 🍾 Congrats, you've made it to the end of SDK's Sign and Post Orders tutorial. diff --git a/cow-sdk/sign-and-post-orders/instantiate-sdk-with-a-signer.md b/cow-sdk/sign-and-post-orders/instantiate-sdk-with-a-signer.md deleted file mode 100644 index 9144ea2..0000000 --- a/cow-sdk/sign-and-post-orders/instantiate-sdk-with-a-signer.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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/): - -```typescript -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( - 4, { // Leaving chainId empty will default to MAINNET - signer: wallet // Provide a signer, so you can sign order - }) -``` - -So know we have a SDK instance liked to our signer. That's great, because now creating orders will be a matter of: - -1. **Get Market Prices**: 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` - -Let's start in next section with the first step, getting the Market Price. - -*** diff --git a/cow-sdk/sign-and-post-orders/step-1-get-market-price.md b/cow-sdk/sign-and-post-orders/step-1-get-market-price.md index 3294665..2f28c75 100644 --- a/cow-sdk/sign-and-post-orders/step-1-get-market-price.md +++ b/cow-sdk/sign-and-post-orders/step-1-get-market-price.md @@ -15,7 +15,11 @@ To create an order, you need to get a price/fee quote first: To get the quote, you simply specify the trade you intent to do: ```typescript -const quoteResponse = await cowSdk.cowApi.getQuote({ +import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk' + +const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.MAINNET }) + +const quoteResponse = await orderBookApi.getQuote({ kind: OrderKind.SELL, // Sell order (could also be BUY) sellToken: '0xc778417e063141139fce010982780140aa0cd5ab', // WETH buyToken: '0x4dbcdf9b62e891a7cec5a2568c3f4faf9e8abe2b', // USDC diff --git a/cow-sdk/sign-and-post-orders/step-2-sign-the-order.md b/cow-sdk/sign-and-post-orders/step-2-sign-the-order.md index 268bd71..c7ed565 100644 --- a/cow-sdk/sign-and-post-orders/step-2-sign-the-order.md +++ b/cow-sdk/sign-and-post-orders/step-2-sign-the-order.md @@ -7,6 +7,12 @@ Once you know the price and fee, we can create the order and sign it: * The SDK will provide an easy way to sign orders given the raw data ```typescript +import { OrderSigningUtils, OrderKind, SupportedChainId } from '@cowprotocol/cow-sdk' +import { Web3Provider } from '@ethersproject/providers' + +const provider = new Web3Provider(window.ethereum) +const signer = provider.getSigner() + const { sellToken, buyToken, validTo, buyAmount, sellAmount, receiver, feeAmount } = quoteResponse.quote // Prepare the RAW order @@ -34,7 +40,9 @@ const order = { } // Sign the order -const signedOrder = await cowSdk.signOrder(order) +const signedOrder = await OrderSigningUtils.signOrder(order, SupportedChainId.MAINNET, signer) ``` 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. + +> 📚 Read more about `appData` [here](https://github.com/cowprotocol/app-data) \ No newline at end of file diff --git a/cow-sdk/sign-and-post-orders/step-3-post-the-signed-order-to-the-api.md b/cow-sdk/sign-and-post-orders/step-3-post-the-signed-order-to-the-api.md index 30f0cea..ff0305e 100644 --- a/cow-sdk/sign-and-post-orders/step-3-post-the-signed-order-to-the-api.md +++ b/cow-sdk/sign-and-post-orders/step-3-post-the-signed-order-to-the-api.md @@ -13,10 +13,11 @@ Once you have a signed order, last step is to send it to the API. Post an order using the SDK: ```javascript -const orderId = await cowSdk.cowApi.sendOrder({ - order: { ...order, ...signedOrder }, - owner: '0x1811be0994930fe9480eaede25165608b093ad7a', -}) +import { OrderBookApi, SupportedChainId } from '@cowprotocol/cow-sdk' + +const orderBookApi = new OrderBookApi({ chainId: SupportedChainId.MAINNET }) + +const orderId = await orderBookApi.sendOrder({ ...order, ...signedOrder }) ``` Success 🎉! You managed to post a new valid order. Note that even though you awaited for the `sendOrder` call, this only signals that the order was accepted by the protocol.\