From 5fb72823dcbb9a75a10785c702fcd2254a2751f4 Mon Sep 17 00:00:00 2001 From: Pegasus <83475418+0xp3gasus@users.noreply.github.com> Date: Thu, 3 Oct 2024 11:00:40 +0200 Subject: [PATCH] 1285 Aggregator documentation (#1286) * Aggregator examples * Aggregator readme * yarn.lock --- examples/aggregator/.codesandbox/tasks.json | 9 +++ .../.devcontainer/devcontainer.json | 4 + examples/aggregator/CHANGELOG.md | 1 + examples/aggregator/README.md | 32 ++++++++ examples/aggregator/package.json | 26 +++++++ examples/aggregator/swap-do.ts | 33 ++++++++ examples/aggregator/swap-estimate.ts | 28 +++++++ examples/aggregator/swap-history.ts | 39 ++++++++++ examples/aggregator/tsconfig.json | 15 ++++ packages/xchain-aggregator/README.md | 76 ++++++++++++++++--- yarn.lock | 17 ++++- 11 files changed, 267 insertions(+), 13 deletions(-) create mode 100644 examples/aggregator/.codesandbox/tasks.json create mode 100644 examples/aggregator/.devcontainer/devcontainer.json create mode 100644 examples/aggregator/CHANGELOG.md create mode 100644 examples/aggregator/README.md create mode 100644 examples/aggregator/package.json create mode 100644 examples/aggregator/swap-do.ts create mode 100644 examples/aggregator/swap-estimate.ts create mode 100644 examples/aggregator/swap-history.ts create mode 100644 examples/aggregator/tsconfig.json diff --git a/examples/aggregator/.codesandbox/tasks.json b/examples/aggregator/.codesandbox/tasks.json new file mode 100644 index 000000000..fff1c37f8 --- /dev/null +++ b/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" + } + ] +} \ No newline at end of file diff --git a/examples/aggregator/.devcontainer/devcontainer.json b/examples/aggregator/.devcontainer/devcontainer.json new file mode 100644 index 000000000..9cef189a7 --- /dev/null +++ b/examples/aggregator/.devcontainer/devcontainer.json @@ -0,0 +1,4 @@ +{ + "name": "Devcontainer", + "image": "ghcr.io/codesandbox/devcontainers/typescript-node:latest" +} \ No newline at end of file diff --git a/examples/aggregator/CHANGELOG.md b/examples/aggregator/CHANGELOG.md new file mode 100644 index 000000000..9764cccd2 --- /dev/null +++ b/examples/aggregator/CHANGELOG.md @@ -0,0 +1 @@ +# xchainjs-aggregator diff --git a/examples/aggregator/README.md b/examples/aggregator/README.md new file mode 100644 index 000000000..bce644523 --- /dev/null +++ b/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 +``` diff --git a/examples/aggregator/package.json b/examples/aggregator/package.json new file mode 100644 index 000000000..3f856a7f0 --- /dev/null +++ b/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" + } +} diff --git a/examples/aggregator/swap-do.ts b/examples/aggregator/swap-do.ts new file mode 100644 index 000000000..84cc44f77 --- /dev/null +++ b/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)) diff --git a/examples/aggregator/swap-estimate.ts b/examples/aggregator/swap-estimate.ts new file mode 100644 index 000000000..b66eb0ebf --- /dev/null +++ b/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)) diff --git a/examples/aggregator/swap-history.ts b/examples/aggregator/swap-history.ts new file mode 100644 index 000000000..3d4ee59fb --- /dev/null +++ b/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)) diff --git a/examples/aggregator/tsconfig.json b/examples/aggregator/tsconfig.json new file mode 100644 index 000000000..7b9e0e966 --- /dev/null +++ b/examples/aggregator/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "module": "commonjs", + "target": "es5", + "noEmitOnError": true, + "resolveJsonModule": true, + "esModuleInterop": true, + "lib": [ + "es6", + "dom", + "es2016", + "es2017" + ] + } +} \ No newline at end of file diff --git a/packages/xchain-aggregator/README.md b/packages/xchain-aggregator/README.md index 584b1c1dc..f2fdab76d 100644 --- a/packages/xchain-aggregator/README.md +++ b/packages/xchain-aggregator/README.md @@ -1,23 +1,75 @@ -# `@xchainjs/xchain-aggregator` +
+

Aggregator

-Protocol aggregator to make actions in different protocols with the aim to operate with the most optimal protocol for each action +

+ + NPM Version + + + NPM Downloads + +

+
-## Install +
-```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) \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index 146d78e3b..993ea3737 100644 --- a/yarn.lock +++ b/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"