Chore/improve Readme (#188)

* 7.2.2

* DELTA doc/fix func

* Readme/add delta handling + fee

* examples/improve simpleQuote

* Readme/improve delta example

* Readme/ add market swap example

* include more docs files in package tarball

* Readme/fix missing

* add DeltaPrice.hmac type

* tests/delta/fix test

* fix tests/hmac addition

README.md

@@ -79,7 +79,7 @@ Can be created by providing `chainId` and either `axios` or `window.fetch` (or a
   }
 ```
 
-If optional `providerOptions` is provided as the second parameter, then the resulting SDK will also be able to approve Tokens for swap.
+If optional `providerOptions` is provided as the second parameter, then the resulting SDK will also be able to approve Tokens for swap, sign Orders, etc.
 
 ```ts
   // with ethers@5
@@ -155,6 +155,7 @@ const minParaSwap = constructPartialSDK({
 const priceRoute = await minParaSwap.getRate(params);
 const allowance = await minParaSwap.getAllowance(userAddress, tokenAddress);
 ```
+--------------
 
 ### Basic usage
 
@@ -185,14 +186,14 @@ const Token1 = '0x1234...'
 const Token2 = '0xabcde...'
 
 const quote = await simpleSDK.quote.getQuote({
-  srcToken: Token1,
+  srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'
   destToken: Token2,
   amount,
   userAddress: account,
   srcDecimals: 18,
   destDecimals: 18,
   mode: 'all', // Delta quote if possible, with fallback to Market price
-  side: 'SELL',
+  side: 'SELL', // Delta mode only supports side: SELL currenly
   // partner: "..." // if available
 });
 
@@ -215,7 +216,7 @@ if ('delta' in quote) {
   const deltaAuction = await simpleSDK.delta.submitDeltaOrder({
     deltaPrice,
     owner: account,
-    // beneficiary: anotherAccount, // if need to send destToken to another account
+    // beneficiary: anotherAccount, // if need to send the output destToken to another account
     // permit: "0x1234...", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract
     srcToken: Token1,
     destToken: Token2,
@@ -253,7 +254,230 @@ if ('delta' in quote) {
 }
 ```
 
-#### For Delta protocol usage refer to [DELTA.md](./docs/DELTA.md)
+### Delta Order handling
+
+#### A more detailed overview of the Trade Flow, Delta Order variant.
+
+**ParaSwap Delta** is an intent-based protocol that enables a ParaSwap user to make gasless swaps where multiple agents compete to execute the trade at the best price possible.
+This way the user doesn't need to make a transaction themselve but only to sign a Delta Order.
+
+After getting **deltaPrice** from **/quote** endpoint, there are additional steps to sign the Order and wait for its execution.
+
+### 1. Get deltaPrice from /quote
+
+```ts
+const amount = '1000000000000'; // wei
+const Token1 = '0x1234...'
+const Token2 = '0xabcde...'
+
+const quote = await simpleSDK.quote.getQuote({
+  srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'
+  destToken: Token2,
+  amount,
+  userAddress: account,
+  srcDecimals: 18,
+  destDecimals: 18,
+  mode: 'delta' // or mode: 'all'
+  // partner: "..." // if available
+})
+
+// if used mode: 'all'
+if ('delta' in quote) {
+  const deltaPrice = quote.delta;
+}
+
+// if used mode: 'delta'
+const deltaPrice = quote.delta;
+```
+
+
+### 2. Approve srcToken for DeltaContract
+
+```ts
+const approveTxHash = await simpleSDK.delta.approveTokenForDelta(amount, Token1);
+```
+
+Alternatively sign Permit (DAI or Permit1) or Permit2 TransferFrom with DeltaContract as the verifyingContract
+
+```ts
+const DeltaContract = await simpleSDK.delta.getDeltaContract();
+
+// values depend on the Permit type and the srcToken
+const signature = await signer._signTypedData(domain, types, message);
+```
+
+See more on accepted Permit variants in [ParaSwap documentation](https://developers.paraswap.network/api/paraswap-delta/build-and-sign-a-delta-order#supported-permits)
+
+
+### 3. Sign and submit a Delta Order
+
+```ts
+// calculate acceptable destAmount
+const slippagePercent = 0.5;
+  const destAmountAfterSlippage = (
+    +deltaPrice.destAmount *
+    (1 - slippagePercent / 100)
+  ).toString(10);
+
+const signableOrderData = await simpleSDK.delta.buildDeltaOrder({
+  deltaPrice,
+  owner: account,
+  // beneficiary: anotherAccount, // if need to send the output destToken to another account
+  // permit: "0x1234...", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract
+  srcToken: Token1,
+  destToken: Token2,
+  srcAmount: amount,
+  destAmount: destAmountAfterSlippage, // minimum acceptable destAmount
+  // partner: "..." // if available
+});
+
+const signature = await simpleSDK.delta.signDeltaOrder(signableOrderData);
+
+const deltaAuction = await simpleSDK.delta.postDeltaOrder({
+  // partner: "..." // if available
+  // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill
+  order: signableOrderData.data,
+  signature,
+});
+```
+
+#### 3.a.
+
+As an option the `buildDeltaOrder + signDeltaOrder + signDeltaOrder` can be combined into one SDK call with the following code
+
+```ts
+const deltaAuction = await simpleSDK.delta.submitDeltaOrder({
+  deltaPrice,
+  owner: account,
+  // beneficiary: anotherAccount, // if need to send output destToken to another account
+  // permit: "0x1234...", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract
+  // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill
+  srcToken: Token1,
+  destToken: Token2,
+  srcAmount: amount,
+  destAmount: destAmountAfterSlippage, // minimum acceptable destAmount
+});
+```
+
+This allows to simplify the flow at the expense of control over the Order signing.
+
+#### 3.b adding partner fee
+
+A portion of destToken will be collected as a partner fee if `partner` parameter is provided to `buildDeltaOrder` (and `submitDeltaOrder`). The `partnerFee` itself is `deltaPrice.partnerFee`
+
+To examine the default partnerFee parameters (`{partnerAddress: Address, partnerFee: number, takeSurplus: boolean}`), you can call `getPartnerFee` method. These parameters are then encoded in Order.partnerAndFee field.
+
+```ts
+const partnerFeeResponse = await simpleSDK.delta.getPartnerFee({ partner });
+```
+
+Alternatively, you can supply your own partnerFee parameters that will be encoded in Order.partnerAndFee field
+
+```ts
+const signableOrderData = await simpleSDK.delta.buildDeltaOrder({
+  deltaPrice,
+  owner: account,
+  // beneficiary: anotherAccount, // if need to send the output destToken to another account
+  // permit: "0x1234...", // if signed a Permit1 or Permit2 TransferFrom for DeltaContract
+  // partiallyFillabel: true, // allow the Order to be partially filled as opposed to fill-or-kill
+  srcToken: Token1,
+  destToken: Token2,
+  srcAmount: amount,
+  destAmount: destAmountAfterSlippage, // minimum acceptable destAmount
+  partnerAddress: '0x1234...',
+  partnerFee: 0.12,
+  takeSurplus: true,
+});
+```
+
+### 4. Wait for Delta Order execution
+
+```ts
+// poll if necessary
+const auction = await simpleSDK.delta.getDeltaOrderById(deltaAuction.id);
+if (auction?.status === 'EXECUTED') {
+  console.log('Auction was executed');
+}
+```
+
+#### A more detailed example of Delta Order usage can be found in [examples/delta](./src/examples/delta.ts)
+
+#### For more Delta protocol usage refer to [DELTA.md](./docs/DELTA.md)
+------------
+
+### Market Swap handling
+
+#### A more detailed overview of the Trade Flow, Market variant.
+
+Unlike the Delta Order, a Market swap  requires the user themselves to submit a Swap transaction
+
+### 1. Get Market priceRoute from /quote
+
+```ts
+const amount = '1000000000000'; // wei
+const Token1 = '0x1234...'
+const Token2 = '0xabcde...'
+
+const quote = await simpleSDK.quote.getQuote({
+  srcToken: Token1, // Native token (ETH) is only supported in mode: 'market'
+  destToken: Token2,
+  amount,
+  userAddress: account,
+  srcDecimals: 18,
+  destDecimals: 18,
+  mode: 'market'
+  // partner: "..." // if available
+})
+
+// if used mode: 'all'
+if ('market' in quote) {
+  const priceRoute = quote.market;
+}
+
+// if used mode: 'market'
+const priceRoute = quote.market;
+```
+
+
+### 2. Approve srcToken for TokenTransferProxy
+
+```ts
+const approveTxHash = simpleSDK.swap.approveToken(amount, DAI_TOKEN);
+```
+
+Alternatively sign Permit (DAI or Permit1) or Permit2 TransferFrom with TokenTransferProxy as the verifyingContract
+
+```ts
+const TokenTransferProxy = await simpleSDK.swap.getSpender();
+
+// values depend on the Permit type and the srcToken
+const signature = await signer._signTypedData(domain, types, message);
+```
+
+See more on accepted Permit variants in [ParaSwap documentation](https://developers.paraswap.network/api/build-parameters-for-transaction)
+
+
+### 3. Send Swap transaction
+
+```ts
+const txParams = await simpleSDK.swap.buildTx({
+  srcToken: Token1,
+  destToken: Token2,
+  srcAmount: amount,
+  slippage: 250, // 2.5%
+  // can pass `destAmount` (adjusted for slippage) instead of `slippage`
+  priceRoute,
+  userAddress: account,
+  // partner: '...' // if available
+  // receiver: '0x123ae...' // if need to send the output destToken to another account
+});
+
+const swapTxHash = await signer.sendTransaction(txParams);
+```
+
+#### See more details on `buildTx` parameters in [ParaSwap documentation](https://developers.paraswap.network/api/build-parameters-for-transaction)
+
+------------------------
 
 ### Legacy
 The `ParaSwap` class is exposed for backwards compatibility with previous versions of the SDK.

docs/DELTA.md

@@ -64,7 +64,7 @@ const slippagePercent = 0.5;
     (1 - slippagePercent / 100)
   ).toString(10);
 
-const signableOrderData = await deltaSDK.buildDeltaOrder({
+const deltaAuction = await deltaSDK.submitDeltaOrder({
   deltaPrice,
   owner: account,
   // beneficiary: anotherAccount, // if need to send destToken to another account

package.json

@@ -6,7 +6,9 @@
   "typings": "dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs/DELTA.md",
+    "docs/passed_tests.png"
   ],
   "scripts": {
     "analyze": "size-limit --why",

src/examples/simpleQuote.ts

@@ -43,7 +43,10 @@ async function allQuote() {
     const DeltaContract = await simpleSDK.delta.getDeltaContract();
 
     // or sign a Permit1 or Permit2 TransferFrom for DeltaContract
-    await simpleSDK.delta.approveTokenForDelta(amount, DAI_TOKEN);
+    const approveTxHash = await simpleSDK.delta.approveTokenForDelta(
+      amount,
+      DAI_TOKEN
+    );
 
     const slippagePercent = 0.5;
     const destAmountAfterSlippage = BigInt(

src/methods/delta/getDeltaPrice.ts

@@ -40,6 +40,7 @@ export type DeltaPrice = {
   destUSDBeforeFee: string;
   partner: string;
   partnerFee: number;
+  hmac: string;
 };
 
 type DeltaPriceResponse = {

tests/__snapshots__/delta.test.ts.snap

@@ -244,6 +244,7 @@ exports[`Delta:methods Get Delta Price 1`] = `
   "gasCostBeforeFee": "dynamic_number",
   "gasCostUSD": "dynamic_number",
   "gasCostUSDBeforeFee": "dynamic_number",
+  "hmac": "dynamic_string",
   "partner": "anon",
   "partnerFee": 0,
   "srcAmount": "1000000000000000000",

tests/__snapshots__/partialSdk.test.ts.snap

@@ -115,7 +115,7 @@ exports[`ParaSwap SDK: fetching methods: axiosFetcher Get_SwapTxData: Get_SwapTx
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",
@@ -256,7 +256,7 @@ exports[`ParaSwap SDK: fetching methods: fetchFetcher Get_SwapTxData: Get_SwapTx
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",

tests/__snapshots__/quote.test.ts.snap

@@ -34,7 +34,7 @@ exports[`Quote:methods Get Fallback Market Quote for all 2`] = `
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",
@@ -67,7 +67,7 @@ exports[`Quote:methods Get Quote for market 1`] = `
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",

tests/__snapshots__/simpleSdk.test.ts.snap

@@ -105,7 +105,7 @@ exports[`ParaSwap SDK: fetcher made with: axios Get_SwapTxData: Get_SwapTxData::
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",
@@ -236,7 +236,7 @@ exports[`ParaSwap SDK: fetcher made with: fetch Get_SwapTxData: Get_SwapTxData::
   "destUSD": "dynamic_number",
   "gasCost": "dynamic_number",
   "gasCostUSD": "dynamic_number",
-  "hmac": "dynamic_number",
+  "hmac": "dynamic_string",
   "maxImpactReached": false,
   "network": 1,
   "partner": "anon",