@galacticcouncil/sdk 0.0.1-beta.1

package/src/suggester/bfs.ts

@@ -0,0 +1,106 @@
+import { Queue } from '../utils/queue';
+
+export type Path = Node[];
+export type Node = [id: number, from: string];
+
+/**
+ * Breadth First Search.
+ *
+ * - uses Queue to find the shortest path
+ * - slower than DFS (Depth First Search)
+ * - better when dst is closer to src
+ * - complexity O(N+E) where N are nodes and E are edges
+ */
+export class Bfs {
+  /**
+   * Check if current node is already present in path
+   *
+   * @param x - current node
+   * @param path - path
+   * @returns true if node in path, otherwise false
+   */
+  isNotVisited(x: number, path: Path): boolean {
+    let notVisited: boolean = true;
+    path.forEach((pv) => {
+      if (pv[0] === x) {
+        notVisited = false;
+      }
+    });
+    return notVisited;
+  }
+
+  /**
+   * Finding paths in graph from given source to destination
+   *
+   * @param g - routes graph containing nodes & corresponding edges
+   * @param src - source node
+   * @param dst - destination node or null if requesting all posible paths from src
+   * @returns paths
+   */
+  findPaths(g: Path[], src: number, dst: number | null): Path[] {
+    // Store the result paths
+    const paths: Path[] = [];
+    // Store the traversing paths
+    const queue = new Queue<Path>();
+    // Store the current path
+    const currentPath: Path = [];
+
+    // First node of path has no from (initial)
+    currentPath.push([src, '']);
+    queue.enqueue(currentPath);
+
+    while (queue.size() > 0) {
+      const path = queue.dequeue();
+
+      if (path == null) {
+        return paths;
+      }
+
+      const last = path[path.length - 1];
+
+      // If destination is undefined save all traversal to paths
+      // If last node is the desired destination save to paths
+      if (dst === null) {
+        paths.push(path);
+      } else if (last[0] === dst) {
+        paths.push(path);
+      }
+
+      // Traverse to all nodes connected to current one and push path to queue
+      const lastNode = g[last[0]];
+      lastNode.forEach((segment) => {
+        if (this.isNotVisited(segment[0], path)) {
+          const newpath = [...path];
+          newpath.push(segment);
+          queue.enqueue(newpath);
+        }
+      });
+    }
+    return paths;
+  }
+
+  /**
+   * Build and populate graph
+   *
+   * @param nodes - list of pool assets
+   * @param edges - list of all edges [id, from, to] between assets
+   * @returns - traversal graph
+   */
+  buildAndPopulateGraph(
+    nodes: string[],
+    edges: [string, string, string][]
+  ): Path[] {
+    const graph: Path[] = [];
+    for (let j = 0; j < nodes.length; j++) {
+      graph.push([]);
+    }
+
+    for (const [address, from, to] of edges) {
+      const fromNumber = parseInt(from);
+      const toNumber = parseInt(to);
+      graph[fromNumber].push([toNumber, address]);
+    }
+
+    return graph;
+  }
+}

package/src/suggester/graph.ts

@@ -0,0 +1,31 @@
+import { PoolBase } from '../types';
+
+export type Edge = [address: string, from: string, to: string];
+
+export type NodeEdges = {
+  [node: string]: Edge[];
+};
+
+/**
+ * Calculate nodes & edges from substrate pools
+ *
+ * @param pools - given substrate pools
+ * @returns nodes & corresponding edges
+ */
+export function getNodesAndEdges(pools: PoolBase[]): NodeEdges {
+  const edgesFromNode: NodeEdges = {};
+  for (const pool of pools) {
+    const n = pool.tokens.length;
+    for (let i = 0; i < n; i++) {
+      if (!edgesFromNode[pool.tokens[i].id]) {
+        edgesFromNode[pool.tokens[i].id] = [];
+      }
+      for (let j = 0; j < n; j++) {
+        if (i == j) continue;
+        const edge: Edge = [pool.address, pool.tokens[i].id, pool.tokens[j].id];
+        edgesFromNode[pool.tokens[i].id].push(edge);
+      }
+    }
+  }
+  return edgesFromNode;
+}

package/src/suggester/index.ts

@@ -0,0 +1,3 @@
+export { RouteSuggester } from './suggester';
+export { Bfs, Path } from './bfs';
+export { Edge, getNodesAndEdges } from './graph';

package/src/suggester/suggester.ts

@@ -0,0 +1,66 @@
+import { PoolBase } from '../types';
+import { Bfs, Node, Path } from './bfs';
+
+import { getNodesAndEdges, Edge } from './graph';
+
+export class RouteSuggester {
+  /**
+   * Proposals are ideal paths from
+   * 1) tokenIn to tokenOut
+   * 2) tokenIn to *(all possible paths are requested)
+   *
+   * calculated from all permutations of tokens of given pools.
+   *
+   * E.g. permutation of pool A={1,3} is 2, such as {1,3}, {3,1} where 1 are 3
+   * are pool assets(tokens)
+   *
+   * Filtering of valid paths and corresponding asset pairs is done by router itself!!!
+   *
+   * @param tokenIn - tokenIn
+   * @param tokenOut - tokenOut or null if all possible paths from tokenIn are requested
+   * @param pools - substrate based pools
+   * @returns all possible path proposals
+   */
+  getProposals(
+    tokenIn: string,
+    tokenOut: string | null,
+    pools: PoolBase[]
+  ): Edge[][] {
+    const nodeEdges = getNodesAndEdges(pools);
+    const poolAssets = Object.keys(nodeEdges);
+    const possiblePairs: Edge[] = poolAssets
+      .map((node) => nodeEdges[node])
+      .flat();
+
+    const bfs = new Bfs();
+    const bfsGraph = bfs.buildAndPopulateGraph(poolAssets, possiblePairs);
+    const possiblePaths = bfs.findPaths(
+      bfsGraph,
+      parseInt(tokenIn),
+      tokenOut ? parseInt(tokenOut) : null
+    );
+    return this.parsePaths(possiblePaths);
+  }
+
+  private parsePaths(possiblePaths: Path[]): Edge[][] {
+    const paths: Edge[][] = [];
+    for (const path of possiblePaths) {
+      const edges: Edge[] = [];
+      for (let i = 0; i < path.length; i++) {
+        const from = path[i];
+        const to = path[i + 1];
+        if (to == null) {
+          break;
+        } else {
+          edges.push(this.toEdge(from, to));
+        }
+      }
+      paths.push(edges);
+    }
+    return paths;
+  }
+
+  private toEdge(from: Node, to: Node): Edge {
+    return [to[1], from[0].toString(), to[0].toString()] as Edge;
+  }
+}

package/src/types.ts

@@ -0,0 +1,61 @@
+import { BigNumber } from './utils/bignumber';
+
+export type PoolAsset = { token: string; symbol: string };
+
+export enum PoolType {
+  XYK = 'XYK',
+  LBP = 'LBP',
+  Stable = 'Stable',
+  Omni = 'Omni',
+}
+
+export interface PoolPair {
+  swapFee: BigNumber;
+  tokenIn: string;
+  tokenOut: string;
+  balanceIn: BigNumber;
+  balanceOut: BigNumber;
+}
+
+export type PoolBase = {
+  address: string;
+  type: PoolType;
+  swapFee: string;
+  tokens: PoolToken[];
+};
+
+export type PoolToken = {
+  id: string;
+  balance: string;
+  decimals: number;
+  symbol: string;
+};
+
+export interface Pool extends PoolBase {
+  validPair(tokenIn: string, tokenOut: string): boolean;
+  parsePoolPair(tokenIn: string, tokenOut: string): PoolPair;
+  calculateInGivenOut(poolPair: PoolPair, amountOut: BigNumber): BigNumber;
+  calculateOutGivenIn(poolPair: PoolPair, amountIn: BigNumber): BigNumber;
+  getSpotPriceIn(poolPair: PoolPair): BigNumber;
+  getSpotPriceOut(poolPair: PoolPair): BigNumber;
+}
+
+export interface PoolService {
+  getPools(): Promise<PoolBase[]>;
+}
+
+export type Hop = {
+  poolType: PoolType;
+  poolId: string;
+  tokenIn: string;
+  tokenOut: string;
+  fee: string;
+};
+
+export type Swap = Hop & {
+  swapAmount: BigNumber;
+  returnAmount: BigNumber;
+  returnFinalAmount: BigNumber;
+  swapFee: BigNumber;
+  spotPrice: BigNumber;
+};

package/src/utils/bignumber.ts

@@ -0,0 +1,25 @@
+import { BigNumber } from 'bignumber.js';
+
+export const DECIMAL_PLACES = 12;
+
+BigNumber.config({
+  EXPONENTIAL_AT: [-100, 100],
+  ROUNDING_MODE: 1,
+  DECIMAL_PLACES: DECIMAL_PLACES,
+});
+
+export const ZERO = bnum(0);
+export const ONE = bnum(1);
+export const INFINITY = bnum('Infinity');
+
+export function scale(input: BigNumber, decimalPlaces: number): BigNumber {
+  const scalePow = new BigNumber(decimalPlaces.toString());
+  const scaleMul = new BigNumber(10).pow(scalePow);
+  return input.times(scaleMul);
+}
+
+export function bnum(val: string | number | BigNumber): BigNumber {
+  return new BigNumber(val.toString());
+}
+
+export { BigNumber };

package/src/utils/math.ts

@@ -0,0 +1,24 @@
+import { BigNumber, bnum, scale, DECIMAL_PLACES } from './bignumber';
+
+export function tradeFee(percentage: string): BigNumber {
+  return bnum(parseFloat(percentage) / 100);
+}
+
+export function calculateTradeFee(
+  amount: BigNumber,
+  tradeFee: BigNumber
+): BigNumber {
+  return amount.multipliedBy(tradeFee).decimalPlaces(0, 1);
+}
+
+export function normalizeAmount(
+  amount: BigNumber,
+  decimals: number
+): BigNumber {
+  if (decimals == DECIMAL_PLACES) {
+    return amount;
+  }
+
+  const normalizedAmount = amount.shiftedBy(-1 * decimals);
+  return scale(normalizedAmount, 12);
+}

package/src/utils/queue.ts

@@ -0,0 +1,26 @@
+export interface IQueue<T> {
+  enqueue(item: T): void;
+  dequeue(): T | undefined;
+  size(): number;
+}
+
+export class Queue<T> implements IQueue<T> {
+  private storage: T[] = [];
+
+  constructor(private capacity: number = Infinity) {}
+
+  enqueue(item: T): void {
+    if (this.size() === this.capacity) {
+      throw Error('Queue has reached max capacity, you cannot add more items');
+    }
+    this.storage.push(item);
+  }
+
+  dequeue(): T | undefined {
+    return this.storage.shift();
+  }
+
+  size(): number {
+    return this.storage.length;
+  }
+}

package/src/utils/stack.ts

@@ -0,0 +1,31 @@
+export interface IStack<T> {
+  push(item: T): void;
+  pop(): T | undefined;
+  peek(): T | undefined;
+  size(): number;
+}
+
+export class Stack<T> implements IStack<T> {
+  private storage: T[] = [];
+
+  constructor(private capacity: number = Infinity) {}
+
+  push(item: T): void {
+    if (this.size() === this.capacity) {
+      throw Error('Stack has reached max capacity, you cannot add more items');
+    }
+    this.storage.push(item);
+  }
+
+  pop(): T | undefined {
+    return this.storage.pop();
+  }
+
+  peek(): T | undefined {
+    return this.storage[this.size() - 1];
+  }
+
+  size(): number {
+    return this.storage.length;
+  }
+}

package/src/utils/traversal/bfs.ts

@@ -0,0 +1,74 @@
+import { Queue } from '../queue';
+
+/**
+ * Breadth First Search.
+ *
+ * - uses Queue to find the shortest path
+ * - slower than DFS (Depth First Search)
+ * - better when dst is closer to src
+ * - complexity O(N+E) where N are nodes and E are edges
+ */
+export class Bfs {
+  /**
+   * Check if current node is already present in path
+   *
+   * @param x - current node
+   * @param path - path
+   * @returns true if node in path, otherwise false
+   */
+  isNotVisited(x: number, path: number[]): boolean {
+    let notVisited: boolean = true;
+    path.forEach((pv) => {
+      if (pv === x) {
+        notVisited = false;
+      }
+    });
+    return notVisited;
+  }
+
+  /**
+   * Finding paths in graph from given source to destination
+   *
+   * @param g - routes graph containing nodes & corresponding edges
+   * @param src - source node
+   * @param dst - destination node
+   * @returns paths
+   */
+  findPaths(g: number[][], src: number, dst: number): number[][] {
+    // Store the results
+    const paths: number[][] = [];
+    // Store the traversing paths
+    const queue = new Queue<number[]>();
+    // Store the current path
+    const currentPath: number[] = [];
+
+    currentPath.push(src);
+    queue.enqueue(currentPath);
+
+    while (queue.size() > 0) {
+      const path = queue.dequeue();
+
+      if (path === undefined) {
+        return paths;
+      }
+
+      const last = path[path.length - 1];
+
+      // If last node is the desired destination save to paths
+      if (last === dst) {
+        paths.push(path);
+      }
+
+      // Traverse to all nodes connected to current node and push path to queue
+      const lastNode = g[last];
+      lastNode.forEach((segment) => {
+        if (this.isNotVisited(segment, path)) {
+          const newpath = [...path];
+          newpath.push(segment);
+          queue.enqueue(newpath);
+        }
+      });
+    }
+    return paths;
+  }
+}

package/test/api/router.spec.ts

@@ -0,0 +1,87 @@
+import { Router } from '../../src/api';
+import { PoolService, PoolType } from '../../src/types';
+import { bnum, scale } from '../../src/utils/bignumber';
+import { MockXykPoolService } from '../lib/mockXykPoolService';
+
+describe('Router', () => {
+  let poolService: PoolService;
+  let router: Router;
+
+  beforeEach(() => {
+    poolService = new MockXykPoolService();
+    router = new Router(poolService);
+  });
+
+  it('Should return suggested hops from token 1 to 2 for given XYK pool', async () => {
+    expect(poolService).toBeDefined();
+    expect(router).toBeDefined();
+    const result = await router.getAllPaths('1', '2');
+    expect(result).toStrictEqual([
+      [
+        {
+          poolId: 'bXi1mHNp4jSRUNXuX3sY1fjCF9Um2EezkpzkFmQuLHaChdPM3',
+          poolType: PoolType.XYK,
+          tokenIn: '1',
+          tokenOut: '2',
+          fee: '0.3',
+        },
+      ],
+      [
+        {
+          poolId: 'bXn6KCrv8k2JV7B2c5jzLttBDqL4BurPCTcLa3NQk5SWDVXCJ',
+          poolType: PoolType.XYK,
+          tokenIn: '1',
+          tokenOut: '0',
+          fee: '0.3',
+        },
+        {
+          poolId: 'bXjT2D2cuxUuP2JzddMxYusg4cKo3wENje5Xdk3jbNwtRvStq',
+          poolType: PoolType.XYK,
+          tokenIn: '0',
+          tokenOut: '2',
+          fee: '0.3',
+        },
+      ],
+    ]);
+  });
+
+  it('Should return all assets from given XYK pool', async () => {
+    expect(poolService).toBeDefined();
+    expect(router).toBeDefined();
+    const result = await router.getAllAssets();
+    expect(result).toStrictEqual([
+      { token: '0', symbol: 'BSX' },
+      { token: '2', symbol: 'AUSD' },
+      { token: '1', symbol: 'KSM' },
+    ]);
+  });
+
+  it('Should return all assets pair reacheable from token 1 in given XYK pool', async () => {
+    expect(poolService).toBeDefined();
+    expect(router).toBeDefined();
+    const result = await router.getAssetPairs('1');
+    expect(result).toStrictEqual([
+      { token: '2', symbol: 'AUSD' },
+      { token: '0', symbol: 'BSX' },
+    ]);
+  });
+
+  it('Should throw error if not-existing asset used in given XYK pool', async () => {
+    expect(poolService).toBeDefined();
+    expect(router).toBeDefined();
+    await expect(async () => {
+      await router.getAssetPairs('not-existing');
+    }).rejects.toThrow('not-existing is not supported token');
+  });
+
+  it('Should return best sell price swaps', async () => {
+    expect(poolService).toBeDefined();
+    expect(router).toBeDefined();
+    const result = await router.getBestSellPrice(
+      '1',
+      '2',
+      scale(bnum('1'), 12)
+    );
+    // TODO write test assertions
+  });
+});

package/test/data/xykPool.ts

@@ -0,0 +1,21 @@
+import { PoolType } from '../../src/types';
+
+export const xykPool = {
+  address: 'bXi1mHNp4jSRUNXuX3sY1fjCF9Um2EezkpzkFmQuLHaChdPM3',
+  type: PoolType.XYK,
+  swapFee: '0.3',
+  tokens: [
+    {
+      id: '1',
+      balance: '3684960401086',
+      decimals: 12,
+      symbol: 'KSM',
+    },
+    {
+      id: '2',
+      balance: '174291804564300',
+      decimals: 12,
+      symbol: 'AUSD',
+    },
+  ],
+};

package/test/data/xykPools.ts

@@ -0,0 +1,61 @@
+import { PoolType } from '../../src/types';
+
+export const xykPools = [
+  {
+    address: 'bXjT2D2cuxUuP2JzddMxYusg4cKo3wENje5Xdk3jbNwtRvStq',
+    type: PoolType.XYK,
+    swapFee: '0.3',
+    tokens: [
+      {
+        id: '0',
+        balance: '235315220453344458259',
+        decimals: 12,
+        symbol: 'BSX',
+      },
+      {
+        id: '2',
+        balance: '34783100690381537',
+        decimals: 12,
+        symbol: 'AUSD',
+      },
+    ],
+  },
+  {
+    address: 'bXi1mHNp4jSRUNXuX3sY1fjCF9Um2EezkpzkFmQuLHaChdPM3',
+    type: PoolType.XYK,
+    swapFee: '0.3',
+    tokens: [
+      {
+        id: '1',
+        balance: '3684960401086',
+        decimals: 12,
+        symbol: 'KSM',
+      },
+      {
+        id: '2',
+        balance: '174291804564300',
+        decimals: 12,
+        symbol: 'AUSD',
+      },
+    ],
+  },
+  {
+    address: 'bXn6KCrv8k2JV7B2c5jzLttBDqL4BurPCTcLa3NQk5SWDVXCJ',
+    type: PoolType.XYK,
+    swapFee: '0.3',
+    tokens: [
+      {
+        id: '0',
+        balance: '261138390134511806721',
+        decimals: 12,
+        symbol: 'BSX',
+      },
+      {
+        id: '1',
+        balance: '842366824680338',
+        decimals: 12,
+        symbol: 'KSM',
+      },
+    ],
+  },
+];

package/test/lib/mockXykPoolService.ts

@@ -0,0 +1,8 @@
+import { PoolBase, PoolService } from '../../src/types';
+import { xykPools } from '../data/xykPools';
+
+export class MockXykPoolService implements PoolService {
+  getPools(): Promise<PoolBase[]> {
+    return Promise.resolve(xykPools);
+  }
+}

package/test/pool/xyk/xykPool.spec.ts

@@ -0,0 +1,26 @@
+import { XykPool } from '../../../src/pool';
+import { xykPool } from '../../data/xykPool';
+
+describe('Xyk Pool', () => {
+  let pool: XykPool;
+
+  beforeEach(() => {
+    pool = XykPool.fromPool(xykPool);
+  });
+
+  it('Should return valid PoolPair for assets 1 & 2', async () => {
+    expect(pool).toBeDefined();
+    const result = pool.parsePoolPair('1', '2');
+    expect(result.swapFee.toString()).toStrictEqual(
+      (parseFloat(xykPool.swapFee) / 100).toString()
+    );
+    expect(result.tokenIn).toStrictEqual(xykPool.tokens[0].id);
+    expect(result.balanceIn.toString()).toStrictEqual(
+      xykPool.tokens[0].balance
+    );
+    expect(result.tokenOut).toStrictEqual(xykPool.tokens[1].id);
+    expect(result.balanceOut.toString()).toStrictEqual(
+      xykPool.tokens[1].balance
+    );
+  });
+});

package/test/script/examples/router/getAllAssets.ts

@@ -0,0 +1,14 @@
+import { ApiPromise } from '@polkadot/api';
+import { PolkadotExecutor } from '../../executor';
+import { PolkadotPoolService } from '../../../../src/pool';
+import { Router } from '../../../../src/api';
+
+class GetAllAssetsExample extends PolkadotExecutor {
+  async script(api: ApiPromise): Promise<any> {
+    const poolService = new PolkadotPoolService(api);
+    const router = new Router(poolService);
+    return router.getAllAssets();
+  }
+}
+
+new GetAllAssetsExample('wss://rpc.basilisk.cloud', 'Get all paths').run();

package/test/script/examples/router/getAllPaths.ts

@@ -0,0 +1,14 @@
+import { ApiPromise } from '@polkadot/api';
+import { PolkadotExecutor } from '../../executor';
+import { PolkadotPoolService } from '../../../../src/pool';
+import { Router } from '../../../../src/api';
+
+class GetAllPathsExample extends PolkadotExecutor {
+  async script(api: ApiPromise): Promise<any> {
+    const poolService = new PolkadotPoolService(api);
+    const router = new Router(poolService);
+    return router.getAllPaths('1', '2');
+  }
+}
+
+new GetAllPathsExample('wss://rpc.basilisk.cloud', 'Get all paths').run();