1285 Aggregator documentation (#1286)

* Aggregator examples

* Aggregator readme

* yarn.lock

examples/aggregator/.codesandbox/tasks.json

@@ -0,0 +1,9 @@
+{
+  // These tasks will run in order when initializing your CodeSandbox project.
+  "setupTasks": [
+    {
+      "name": "Install Dependencies",
+      "command": "yarn install"
+    }
+  ]
+}

examples/aggregator/.devcontainer/devcontainer.json

@@ -0,0 +1,4 @@
+{
+    "name": "Devcontainer",
+    "image": "ghcr.io/codesandbox/devcontainers/typescript-node:latest"
+}

examples/aggregator/CHANGELOG.md

@@ -0,0 +1 @@
+# xchainjs-aggregator

examples/aggregator/README.md

@@ -0,0 +1,32 @@
+# Aggregator
+
+Aggregator examples to show different use cases
+
+## Examples
+
+### Swaps
+
+#### Estimate swap
+
+Check out how you should estimate a swap in this [example](https://github.com/xchainjs/xchainjs-lib/blob/master/examples/aggregator/swap-do.ts) or run it as
+
+```sh
+yarn estimateSwap fromAsset toAsset amount decimals
+```
+
+#### Do swap
+
+Check out how you should do a swap between BTC and ETH in this [example](https://github.com/xchainjs/xchainjs-lib/blob/master/examples/aggregator/swap-estimate.ts) or run it as
+
+
+```sh
+yarn doSwap phrase amount
+```
+
+#### Get swap history
+
+Check out how you should get the swap history of several addresses in this [example](https://github.com/xchainjs/xchainjs-lib/blob/master/examples/aggregator/swap-history.ts) or run it as
+
+```sh
+yarn swapHistory chain1:address1 chain2:address2
+```

examples/aggregator/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "xchainjs-aggregator",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "swapHistory": "npx ts-node swap-history.ts",
+    "estimateSwap": "npx ts-node swap-estimate.ts",
+    "doSwap": "npx ts-node swap-do.ts",
+    "build": "tsc --noEmit"
+  },
+  "description": "Examples using the Aggregator",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "@xchainjs/xchain-aggregator": "workspace:*",
+    "@xchainjs/xchain-bitcoin": "workspace:*",
+    "@xchainjs/xchain-ethereum": "workspace:*",
+    "@xchainjs/xchain-util": "workspace:*",
+    "@xchainjs/xchain-wallet": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "20.11.28",
+    "ts-node": "10.9.2",
+    "typescript": "^5.0.4"
+  }
+}

examples/aggregator/swap-do.ts

@@ -0,0 +1,33 @@
+import { Aggregator } from '@xchainjs/xchain-aggregator'
+import { AssetBTC, BTCChain, Client as BTCClient, defaultBTCParams } from '@xchainjs/xchain-bitcoin'
+import { AssetETH, Client as ETHClient, ETHChain, defaultEthParams } from '@xchainjs/xchain-ethereum'
+import { CryptoAmount, assetAmount, assetToBase } from '@xchainjs/xchain-util'
+import { Wallet } from '@xchainjs/xchain-wallet'
+
+const main = async () => {
+  const phrase = process.argv[2] || ''
+  const amount = assetToBase(assetAmount(process.argv[4], Number(process.argv[5] || 8)))
+
+  const wallet = new Wallet({
+    BTCChain: new BTCClient({ ...defaultBTCParams, phrase }),
+    ETHChain: new ETHClient({ ...defaultEthParams, phrase }),
+  })
+
+  const aggregator = new Aggregator({
+    wallet,
+  })
+
+  const txSubmited = await aggregator.doSwap({
+    fromAsset: AssetBTC,
+    destinationAsset: AssetETH,
+    fromAddress: await wallet.getAddress(BTCChain),
+    destinationAddress: await wallet.getAddress(ETHChain),
+    amount: new CryptoAmount(amount, AssetBTC),
+  })
+
+  console.log(txSubmited)
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => console.error(err))

examples/aggregator/swap-estimate.ts

@@ -0,0 +1,28 @@
+import { Aggregator } from '@xchainjs/xchain-aggregator'
+import { CryptoAmount, assetAmount, assetFromStringEx, assetToBase } from '@xchainjs/xchain-util'
+
+const main = async () => {
+  const fromAsset = assetFromStringEx(process.argv[2] || '')
+  const toAsset = assetFromStringEx(process.argv[3] || '')
+  const amount = assetToBase(assetAmount(process.argv[4], Number(process.argv[5] || 8)))
+
+  const aggregator = new Aggregator()
+
+  const quote = await aggregator.estimateSwap({
+    fromAsset,
+    destinationAsset: toAsset,
+    amount: new CryptoAmount(amount, fromAsset),
+  })
+
+  console.log({
+    canSwap: quote.canSwap,
+    protocol: quote.protocol,
+    expectedAmount: quote.expectedAmount.assetAmount.amount().toString(),
+    memo: quote.memo,
+    toAddress: quote.toAddress,
+  })
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => console.error(err))

examples/aggregator/swap-history.ts

@@ -0,0 +1,39 @@
+import { Aggregator } from '@xchainjs/xchain-aggregator'
+import { assetToString } from '@xchainjs/xchain-util'
+
+const main = async () => {
+  const chainAddress1 = process.argv[2] || ''
+  const chainAddress2 = process.argv[3] || ''
+
+  const aggregator = new Aggregator()
+
+  const swaps = await aggregator.getSwapHistory({
+    chainAddresses: [
+      {
+        chain: chainAddress1.split(':')[0],
+        address: chainAddress1.split(':')[1],
+      },
+      {
+        chain: chainAddress2.split(':')[0],
+        address: chainAddress2.split(':')[1],
+      },
+    ],
+  })
+
+  console.table(
+    swaps.swaps.map((swap) => {
+      return {
+        protocol: swap.protocol,
+        fromAsset: assetToString(swap.inboundTx.amount.asset),
+        toAsset: swap.outboundTx ? assetToString(swap.outboundTx.amount.asset) : undefined,
+        hash: swap.inboundTx.hash,
+        fromAmount: swap.inboundTx.amount.assetAmount.amount().toString(),
+        toAmount: swap.outboundTx ? swap.outboundTx.amount.assetAmount.amount().toString() : undefined,
+      }
+    }),
+  )
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => console.error(err))

examples/aggregator/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es5",
+        "noEmitOnError": true,
+        "resolveJsonModule": true,
+        "esModuleInterop": true,
+        "lib": [
+            "es6",
+            "dom",
+            "es2016",
+            "es2017"
+        ]
+    }
+}

packages/xchain-aggregator/README.md

@@ -1,23 +1,75 @@
-# `@xchainjs/xchain-aggregator`
+<div align="center">
+  <h1 align="center">Aggregator</h1>
 
-Protocol aggregator to make actions in different protocols with the aim to operate with the most optimal protocol for each action
+  <p align="center">
+    <a href='https://www.npmjs.com/package/@xchainjs/xchain-aggregator' target='_blank'>
+      <img alt="NPM Version" src="https://img.shields.io/npm/v/%40xchainjs%2Fxchain-aggregator" />
+    </a>
+      <a href='https://www.npmjs.com/package/@xchainjs/xchain-aggregator' target='_blank'>
+      <img alt="NPM Downloads" src="https://img.shields.io/npm/d18m/%40xchainjs%2Fxchain-aggregator" />
+    </a>
+  </p>
+</div>
 
-## Install 
+<br />
 
-```sh
-yarn install @xchainjs/xchain-aggregator @xchainjs/xchain-mayachain-amm @xchainjs/xchain-thorchain-amm 
-```
+The Aggregator package has been developed to facilitate interaction with multiple decentralised protocols. It provides a unified interface for developers, with the objective of offering end users the best of each protocol in the most straightforward manner.
 
 ## Supported protocols
 
 The current supported protocols are:
 
-- Thorchain
-- Mayachain
+- [Thorchain](https://thorchain.org/)
+- [Maya Protocol](https://www.mayaprotocol.com/)
+- [Chainflip](https://chainflip.io/)
+
+
+## Installation
+
+```sh
+yarn add @xchainjs/xchain-aggregator
+```
+
+or 
+
+```sh
+npm install @xchainjs/xchain-aggregator
+```
+
+## Initialization
+
+Aggregator can be easily initialise providing the [Wallet](https://github.com/xchainjs/xchainjs-lib/tree/master/packages/xchain-wallet) with the XChainJs Clients you are working with. If no protocol is provided, the Aggregator will work with all the supported protocols.
+
+```ts
+import { Aggregator } from '@xchainjs/xchain-aggregator';
+
+const aggregator = new Aggregator({
+  wallet: new Wallet({
+    // Your XChainJS clients
+  }),
+  protocols: [
+    // The protocols you want to work with
+  ],
+  affiliate: {
+    // Affiliate config
+  }
+})
+```
+
+## Features
+
+### Swaps
+
+- Estimate the most efficient swap among protocols
+- Do swaps
+- Get swap history through different protocols
+
+
+## Examples
+
+You can find examples using the Aggregator package in the [aggregator](https://github.com/xchainjs/xchainjs-lib/tree/master/examples/aggregator) examples folder.
 
-## Supported actions
 
-The current supported actions are:
+## Documentation
 
-- Swap
-- Get swap history
+More information about how to use the Aggregator package can be found on [documentation](https://xchainjs.gitbook.io/xchainjs/aggregator)

yarn.lock

@@ -4427,7 +4427,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@xchainjs/xchain-aggregator@workspace:packages/xchain-aggregator":
+"@xchainjs/xchain-aggregator@workspace:*, @xchainjs/xchain-aggregator@workspace:packages/xchain-aggregator":
   version: 0.0.0-use.local
   resolution: "@xchainjs/xchain-aggregator@workspace:packages/xchain-aggregator"
   dependencies:
@@ -13842,6 +13842,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"xchainjs-aggregator@workspace:examples/aggregator":
+  version: 0.0.0-use.local
+  resolution: "xchainjs-aggregator@workspace:examples/aggregator"
+  dependencies:
+    "@types/node": "npm:20.11.28"
+    "@xchainjs/xchain-aggregator": "workspace:*"
+    "@xchainjs/xchain-bitcoin": "workspace:*"
+    "@xchainjs/xchain-ethereum": "workspace:*"
+    "@xchainjs/xchain-util": "workspace:*"
+    "@xchainjs/xchain-wallet": "workspace:*"
+    ts-node: "npm:10.9.2"
+    typescript: "npm:^5.0.4"
+  languageName: unknown
+  linkType: soft
+
 "xchainjs-check-tx@workspace:examples/check-tx":
   version: 0.0.0-use.local
   resolution: "xchainjs-check-tx@workspace:examples/check-tx"