@cowprotocol/cow-sdk 5.9.0 → 5.10.0-RC.1

package/README.md

@@ -22,7 +22,50 @@
 yarn add @cowprotocol/cow-sdk
 ```
 
-### Content
+## [Trading SDK](https://github.com/cowprotocol/cow-sdk/blob/main/src/trading/README.md)
+
+CoW Protocol is intent based, decentralized trading protocol that allows users to trade ERC-20 tokens.
+
+The basic swap flow:
+1. 🔎 Get a quote (price) for a trade (_or define your own price with a limit order_)
+2. ✍️ Sign the order
+3. ✅ Post the order to the order-book
+
+The easiest way to start trading is to use the `TradingSdk`:
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Initialize the SDK
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  signer: '<privateKeyOrEthersSigner>',
+  appCode: '<YOUR_APP_CODE>',
+})
+
+// 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)
+```
+
+This example is the simplest way to trade on CoW Protocol.
+
+You might want to use more advanced parameters like `receiver`, `partiallyFillable`, `validTo` and others.
+Check the [Trading SDK documentation](https://github.com/cowprotocol/cow-sdk/blob/main/src/trading/README.md) for more details.
+
+
+## Other utilities
 
 - `OrderBookApi` - provides the ability to retrieve orders and trades from the CoW Protocol 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)
@@ -38,8 +81,6 @@ const subgraphApi = new SubgraphApi({ chainId })
 const orderSigningUtils = new OrderSigningUtils()
 ```
 
-## Quick start
-
 ### Sign, fetch, post and cancel order
 
 For clarity, let's look at the use of the API with a practical example:

package/dist/COPYRIGHT.md

@@ -0,0 +1,13 @@
+# Intellectual Property Notice
+
+Copyright 2021 Gnosis Ltd
+
+Copyrights in this project are retained by contributors. No copyright assignment
+is required to contribute to this project.
+
+Except as otherwise noted (below and/or in individual files), this project is
+licensed under the Apache License, Version 2.0
+([`LICENSE-APACHE`](LICENSE-APACHE) or
+http://www.apache.org/licenses/LICENSE-2.0) or the MIT license,
+([`LICENSE-MIT`](LICENSE-MIT) or http://opensource.org/licenses/MIT), at your
+option.

package/dist/README.md

@@ -22,7 +22,50 @@
 yarn add @cowprotocol/cow-sdk
 ```
 
-### Content
+## [Trading SDK](https://github.com/cowprotocol/cow-sdk/blob/main/src/trading/README.md)
+
+CoW Protocol is intent based, decentralized trading protocol that allows users to trade ERC-20 tokens.
+
+The basic swap flow:
+1. 🔎 Get a quote (price) for a trade (_or define your own price with a limit order_)
+2. ✍️ Sign the order
+3. ✅ Post the order to the order-book
+
+The easiest way to start trading is to use the `TradingSdk`:
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+
+// Initialize the SDK
+const sdk = new TradingSdk({
+  chainId: SupportedChainId.SEPOLIA,
+  signer: '<privateKeyOrEthersSigner>',
+  appCode: '<YOUR_APP_CODE>',
+})
+
+// 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)
+```
+
+This example is the simplest way to trade on CoW Protocol.
+
+You might want to use more advanced parameters like `receiver`, `partiallyFillable`, `validTo` and others.
+Check the [Trading SDK documentation](https://github.com/cowprotocol/cow-sdk/blob/main/src/trading/README.md) for more details.
+
+
+## Other utilities
 
 - `OrderBookApi` - provides the ability to retrieve orders and trades from the CoW Protocol 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)
@@ -38,8 +81,6 @@ const subgraphApi = new SubgraphApi({ chainId })
 const orderSigningUtils = new OrderSigningUtils()
 ```
 
-## Quick start
-
 ### Sign, fetch, post and cancel order
 
 For clarity, let's look at the use of the API with a practical example:

package/dist/docs/architecture.md

@@ -0,0 +1,353 @@
+# Architecture
+
+```mermaid
+flowchart LR
+
+SDK[cow-sdk]
+OrderBookApi
+SubgraphApi
+MetadataApi
+
+SDK --> OrderBookApi
+SDK --> SubgraphApi
+SDK --> MetadataApi
+```
+
+The SDK has 3 main APIs
+
+- **Order Book API**: Allows to get the open orders, historic orders, post new orders, etc.
+- **Subgraph API**: Provides access to on-chain data indexed by The Graph
+- **Metadata API**: Allows to encode/decode meta-data to be attached in orders
+
+## Model: Orders
+
+The orders model used for the API is organized in a hierarchy:
+
+```mermaid
+classDiagram
+
+OrderParameters  <|-- OrderCreation
+OrderCreation  <|-- Order
+OrderMetaData  <|-- Order
+Order <|-- EnrichedOrder
+```
+
+## Model: Orders (details)
+
+```mermaid
+classDiagram
+
+
+class OrderParameters {
+  + sellAmount: TokenAmount;
+  + buyAmount: TokenAmount;
+  + validTo: number;
+  + feeAmount: TokenAmount;
+  + kind: OrderKind;
+  + partiallyFillable: boolean;
+}
+
+Address
+
+class SellTokenSource {
+  <<enum>>
+  ERC20 = 'erc20'
+  INTERNAL = 'internal'
+  EXTERNAL = 'external'
+}
+
+class BuyTokenDestination{
+  <<enum>>
+  ERC20 = 'erc20',
+  INTERNAL = 'internal',
+}
+
+
+class SigningScheme{
+  <<enum>>
+  EIP712 = 'eip712',
+  ETHSIGN = 'ethsign',
+  PRESIGN = 'presign',
+  EIP1271 = 'eip1271',
+}
+
+class AppData {
+  string
+}
+
+class OrderKind {
+  <<enum>>
+  BUY = 'buy'
+  SELL = 'sell'
+}
+
+OrderParameters --> Address: sellToken
+OrderParameters --> Address: buyToken
+OrderParameters --> OrderKind: kind
+OrderParameters "0..1" --> SellTokenSource: sellTokenBalance
+OrderParameters "0..1" --> BuyTokenDestination: buyTokenBalance
+OrderParameters --> SigningScheme: signingScheme
+OrderParameters "0..1" --> Address: receiver
+OrderParameters --> AppData: appData
+
+
+class OrderCreation {
+  + signingScheme: SigningScheme;
+  + signature: Signature
+  + from?: Address | null
+  + quoteId?: number | null
+}
+
+class OrderMetaData {
+  + creationDate: string;
+  + uid: UID;
+  + invalidated: boolean;
+
+  + availableBalance?: TokenAmount | null;
+  + executedSellAmount: BigUint;
+  + executedSellAmountBeforeFees: BigUint;
+  + executedBuyAmount: BigUint;
+  + executedFeeAmount: BigUint;
+  + fullFeeAmount?: TokenAmount;
+  + isLiquidityOrder?: boolean;
+  + onchainUser?: Address;
+  + executedFee?: BigUint | null;
+}
+
+class OrderStatus {
+  <<enum>>
+  PRESIGNATURE_PENDING = 'presignaturePending'
+  OPEN = 'open'
+  FULFILLED = 'fulfilled'
+  CANCELLED = 'cancelled'
+  EXPIRED = 'expired'
+}
+
+class EthflowData {
+  + refundTxHash: TransactionHash | null;
+  + userValidTo: number;
+  + isRefunded: boolean;
+}
+
+OrderMetaData --> OrderStatus: status
+OrderMetaData --> OrderClass: class
+OrderMetaData --> Address2: owner
+OrderMetaData "0..1" --> EthflowData: ethflowData
+OrderMetaData "0..1" --> OnchainOrderData: onchainOrderData
+
+class OrderClass {
+  <<enum>>
+  MARKET = 'market'
+  LIMIT = 'limit'
+  LIQUIDITY = 'liquidity'
+}
+
+
+class EnrichedOrder{
+  totalFee: string
+}
+
+
+OrderParameters  <|-- OrderCreation
+OrderCreation  <|-- Order
+OrderMetaData  <|-- Order
+Order <|-- EnrichedOrder
+
+
+cssClass "OrderParameters,OrderCreation,OrderMetaData, Order" important
+```
+
+## Model: Trades
+
+```mermaid
+classDiagram
+
+
+class Trades {
+  + orderUid: UID
+  + blockNumber: number
+  + logIndex: number
+  + sellAmountBeforeFees: BigUint
+}
+
+Trades --> Address: sellToken
+Trades --> Address: buyToken
+Trades --> Address: owner
+
+Trades --> TokenAmount: sellAmount
+Trades --> TokenAmount: buyAmount
+
+
+Trades "0..1" --> TransactionHash: txHash
+```
+
+## Order Book API
+
+Allows to get the open orders, historic orders, post new orders, etc.
+
+- 📚 [Swagger - Api Docs](https://api.cow.fi/docs)
+- 📚 [Dev Docs - API](https://docs.cow.fi/cow-sdk/cow-api)
+
+The API allows to
+
+```mermaid
+classDiagram
+
+class CowApi {
+  + getTrades(params) Promise~Trades[]~
+  + getOrders(parmas): Promise~EnrichedOrder[]~
+  + getTxOrders(tx: string): Promise~EnrichedOrder[]~
+  + getOrder(uid: UID): Promise~EnrichedOrder~
+  + getQuote(quote: OrderQuoteRequest): Promise~OrderQuoteResponse~
+  + sendSignedOrderCancellation(uid: UID, params): Promise~void~
+  + sendOrder(order: OrderCreation): Promise~UID~
+  + getOrderLink(uid: UID): string
+}
+
+
+
+class OrderQuoteRequest {
+  + sellToken: Address;
+  + buyToken: Address;
+  // ...
+}
+
+
+class OrderQuoteResponse{
+  + id?: number
+  + from?: Address
+  + expiration?: string
+}
+
+OrderQuoteResponse "0..1" --> OrderParameters: quote
+
+CowApi ..> Trade
+CowApi ..> EnrichedOrder
+CowApi ..> SignedOrder
+CowApi ..> OrderCreation
+CowApi ..> OrderQuoteResponse
+CowApi ..> OrderQuoteRequest
+```
+
+## API: Subgraph
+
+Provides access to on-chain data indexed by The Graph
+
+> ⚽️ [Playground](https://thegraph.com/hosted-service/subgraph/cowprotocol/cow)
+
+> 📚 [Dev Docs - SubGraph](https://docs.cow.fi/cow-sdk/querying-the-cow-subgraph)
+
+> 📄 [GitHub code](https://github.com/cowprotocol/subgraph)
+
+**NOTE**: For details about the model, it's better to check the schema using the exported Typescript, or by reviewing the [schema definition](https://thegraph.com/hosted-service/subgraph/cowprotocol/cow).
+
+```mermaid
+classDiagram
+
+class CowSubgraphApi {
+  + getTotals(): Promise~Total~
+  + getLastHoursVolume(): Promise~LastHoursVolumeQuery~
+  + getLastDaysVolume(): Promise~LastDaysVolumeQuery~
+  + runQuery(query, variables): Promise~T~
+}
+
+class Total {
+  + volumeUsd
+  + volumeEth
+  + feesUsd
+  + feesEth
+  ...
+}
+
+
+class LastHoursVolumeQuery{
+  volumeUsd: string
+  ...
+}
+
+class LastDaysVolumeQuery{
+  volumeUsd: string
+  ...
+}
+
+CowSubgraphApi ..> Total
+CowSubgraphApi ..> LastHoursVolumeQuery
+CowSubgraphApi ..> LastDaysVolumeQuery
+
+```
+
+## API: Meta-data
+
+Allows to encode/decode meta-data to be attached in orders
+
+> 📚 [Dev Docs - Metadata](https://docs.cow.fi/cow-sdk/order-meta-data-appdata)
+
+> 📄 [GitHub code](https://github.com/cowprotocol/app-data)
+
+```mermaid
+classDiagram
+
+class MetadataApi {
+  + generateAppDataDoc(params: GenerateAppDataDocParams): AppDataDoc
+  + validateAppDataDoc(appDataDoc: AppDataDoc): ValidateResult
+  + calculateAppDataHash(appDataDoc: AppDataDoc): Promise~IpfsHashInfo|void~
+  + uploadMetadataDocToIpfs(appDataDoc: AppDataDoc, ipfsConfig): Promise~string|void~
+  + decodeAppData(hash: string): AppDataDoc
+  + appDataHexToCid(hash: string): Promise~string|void~
+}
+
+class AppDataDoc {
+  version: Version;
+  appCode?: string;
+  environment?: string;
+}
+
+AppDataDoc --> Metadata: metadata
+
+class Referrer {
+  version: string;
+  address: string;
+}
+
+class Quote {
+  version: string;
+  address: string;
+}
+
+class IpfsHashInfo {
+  + cidV0: string
+  + appDataHash: string
+}
+
+class OrderClass {
+  version: string;
+  orderClass: string;
+}
+
+class AppDataParams {
+  ...
+}
+
+
+class Metadata {
+  ...
+}
+
+class MetadataParams {
+  ...
+}
+
+
+MetadataApi ..> IpfsHashInfo
+MetadataApi ..> GenerateAppDataDocParams
+MetadataApi ..> AppDataDoc
+
+GenerateAppDataDocParams --> AppDataParams: appDataParams
+GenerateAppDataDocParams --> MetadataParams: metadataParams
+
+
+
+Metadata --> Referrer: referrer
+Metadata --> Quote: quote
+Metadata --> OrderClass: orderClass
+```

package/dist/examples/cra/README.md

@@ -0,0 +1,21 @@
+# Example of CoW Protocol SDK usage
+
+## How to start
+
+### Install dependencies
+
+```bash
+yarn install
+```
+
+### Run the local server
+
+```bash
+yarn start
+```
+
+### Open browser with url
+
+```bash
+http://localhost:3000
+```