@avalabs/bridge-unified 1.0.1 → 2.0.1

package/src/unified-bridge-service.ts

@@ -0,0 +1,90 @@
+import type { FeeParams, TrackingParams, TransferParams } from './types/bridge';
+import type { BridgeServiceConfig } from './types/config';
+import { getBridgeForTransfer, getEnabledBridgeServices } from './utils';
+import type { BridgeAsset, ChainAssetMap } from './types';
+import { isArray, mergeWith } from 'lodash';
+import { BridgeUnavailableError } from './errors';
+
+export const createUnifiedBridgeService = ({ environment, disabledBridgeTypes }: BridgeServiceConfig) => {
+  const enabledBridgeServices = getEnabledBridgeServices(environment, disabledBridgeTypes);
+
+  const updateConfigs = async () => {
+    await Promise.allSettled(
+      Array.from(enabledBridgeServices).map(([, bridgeService]) => bridgeService.updateConfig()),
+    );
+  };
+
+  const init = async () => {
+    await updateConfigs();
+  };
+
+  const getAssets = async () => {
+    const assets = await Promise.all(Array.from(enabledBridgeServices).map(([, bridge]) => bridge.getAssets()));
+    return assets.reduce<ChainAssetMap>((aggregatedAssets, chainAssetMap) => {
+      for (const [chainId, bridgeAssets] of Object.entries(chainAssetMap)) {
+        const existingAssets = aggregatedAssets[chainId];
+
+        if (existingAssets) {
+          for (const bridgeAsset of bridgeAssets) {
+            const index = existingAssets.findIndex(({ symbol }) => symbol === bridgeAsset.symbol);
+
+            if (index === -1) {
+              existingAssets.push(bridgeAsset);
+            } else {
+              mergeWith(existingAssets[index], bridgeAsset, (objValue, srcValue) => {
+                if (isArray(objValue)) {
+                  return [...new Set(objValue.concat(srcValue))];
+                }
+              });
+            }
+          }
+        } else {
+          aggregatedAssets[chainId] = bridgeAssets;
+        }
+      }
+
+      return aggregatedAssets;
+    }, {});
+  };
+
+  const getFees = async (params: FeeParams) => {
+    const { bridge } = getBridgeForTransfer(enabledBridgeServices, params.asset, params.targetChain.chainId);
+    return bridge.getFees(params);
+  };
+
+  const transferAsset = async (params: TransferParams) => {
+    const { bridge } = getBridgeForTransfer(enabledBridgeServices, params.asset, params.targetChain.chainId);
+    return bridge.transferAsset(params);
+  };
+
+  const canTransferAsset = (asset: BridgeAsset, targetChainId: string) => {
+    try {
+      getBridgeForTransfer(enabledBridgeServices, asset, targetChainId);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const trackTransfer = (params: TrackingParams) => {
+    const bridge = enabledBridgeServices.get(params.bridgeTransfer.type);
+
+    if (!bridge) {
+      throw new BridgeUnavailableError();
+    }
+
+    return bridge.trackTransfer(params);
+  };
+
+  return {
+    environment,
+    bridges: enabledBridgeServices,
+    init,
+    updateConfigs,
+    getAssets,
+    getFees,
+    canTransferAsset,
+    transferAsset,
+    trackTransfer,
+  };
+};

package/src/utils/bridge-types.test.ts

@@ -0,0 +1,103 @@
+import { BridgeUnavailableError } from '../errors';
+import {
+  Environment,
+  type BridgeType,
+  type BridgeServiceFactory,
+  type BridgeService,
+  type BridgeAsset,
+} from '../types';
+import * as bridgeTypes from './bridge-types';
+
+const getBridgeMock = () => ({
+  updateConfig: jest.fn(),
+  getAssets: jest.fn(),
+  getFees: jest.fn(),
+  transferAsset: jest.fn(),
+  trackTransfer: jest.fn(),
+});
+
+describe('bridge-types', () => {
+  const environment = Environment.TEST;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  describe('getEnabledBridgeServices', () => {
+    let realSupportedBridges: Map<BridgeType, BridgeServiceFactory>;
+
+    const [bridge1, bridge2, bridge3] = [jest.fn(), jest.fn(), jest.fn()];
+    const enabledBridges = new Map([
+      ['bridge1', bridge1],
+      ['bridge2', bridge2],
+      ['bridge3', bridge3],
+    ]) as unknown as Map<BridgeType, BridgeServiceFactory>;
+
+    beforeAll(() => {
+      realSupportedBridges = bridgeTypes.supportedBridges;
+
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      bridgeTypes.supportedBridges = enabledBridges;
+    });
+
+    afterAll(() => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      bridgeTypes.supportedBridges = realSupportedBridges;
+    });
+
+    beforeEach(() => {
+      bridge1.mockReturnValueOnce({ type: 'bridge1' });
+      bridge2.mockReturnValueOnce({ type: 'bridge2' });
+      bridge3.mockReturnValueOnce({ type: 'bridge3' });
+    });
+
+    it('returns all of the supported bridges correctly', () => {
+      const bridges = bridgeTypes.getEnabledBridgeServices(environment);
+      expect(bridges).toStrictEqual(
+        new Map([
+          ['bridge1', { type: 'bridge1' }],
+          ['bridge2', { type: 'bridge2' }],
+          ['bridge3', { type: 'bridge3' }],
+        ]),
+      );
+    });
+
+    it('returns all of the enabled bridges correctly', () => {
+      const bridges = bridgeTypes.getEnabledBridgeServices(environment, ['bridge2' as unknown as BridgeType]);
+      expect(bridges).toStrictEqual(
+        new Map([
+          ['bridge1', { type: 'bridge1' }],
+          ['bridge3', { type: 'bridge3' }],
+        ]),
+      );
+    });
+  });
+
+  describe('getBridgeForTransfer', () => {
+    const [bridge1, bridge2, bridge3] = [getBridgeMock(), getBridgeMock(), getBridgeMock()];
+    const enabledBridges = new Map([
+      ['bridge1', bridge1],
+      ['bridge2', bridge2],
+      ['bridge3', bridge3],
+    ]) as unknown as Map<BridgeType, BridgeService>;
+    const asset = {
+      destinations: {
+        'eip155:2': ['bridge1', 'bridge3'],
+      },
+    } as unknown as BridgeAsset;
+
+    it('throws if no enabled bridge found', () => {
+      expect(() => bridgeTypes.getBridgeForTransfer(enabledBridges, asset, 'eip155:1')).toThrow(BridgeUnavailableError);
+    });
+
+    it('returns the correct bridge for the transfer', () => {
+      const result = bridgeTypes.getBridgeForTransfer(enabledBridges, asset, 'eip155:2');
+      expect(result).toStrictEqual({
+        type: 'bridge1',
+        bridge: bridge1,
+      });
+    });
+  });
+});

package/src/utils/bridge-types.ts

@@ -0,0 +1,32 @@
+import { cctpBridgeFactory } from '../bridges/cctp/factory';
+import { BridgeUnavailableError } from '../errors';
+import type { BridgeAsset } from '../types/asset';
+import { type BridgeService, BridgeType } from '../types/bridge';
+import { Environment } from '../types/environment';
+
+export const supportedBridges = new Map([[BridgeType.CCTP, cctpBridgeFactory]]);
+
+export const getEnabledBridgeServices = (environment: Environment, disabledBridgeTypes?: BridgeType[]) => {
+  return new Map(
+    [...supportedBridges]
+      .filter(([bridgeType]) => !disabledBridgeTypes?.includes(bridgeType))
+      .map(([bridgeType, factory]) => [bridgeType, factory(environment)]),
+  );
+};
+
+export const getBridgeForTransfer = (
+  enabledBridgeServices: Map<BridgeType, BridgeService>,
+  asset: BridgeAsset,
+  targetChainId: string,
+) => {
+  const bridgeType = asset.destinations[targetChainId]?.find((bridgeType) => enabledBridgeServices.has(bridgeType));
+
+  if (!bridgeType) {
+    throw new BridgeUnavailableError();
+  }
+
+  return {
+    type: bridgeType,
+    bridge: enabledBridgeServices.get(bridgeType)!,
+  };
+};

package/src/utils/caip2.test.ts

@@ -0,0 +1,44 @@
+import caip2 from './caip2';
+
+describe('caip2', () => {
+  describe('toJSON', () => {
+    it.each(['', '1.', '1:', ':2'])('throws when the identifier is invalid', (identifier) => {
+      expect(() => caip2.toJSON(identifier)).toThrow('Invalid identifier provided.');
+    });
+
+    it.each(['1:2', 'toolongnamespace:2', '!:2'])('throws when the namespace is invalid', (identifier) => {
+      expect(() => caip2.toJSON(identifier)).toThrow('Invalid namespace provided.');
+    });
+
+    it.each(['eip155:!', 'eip155:toolong-2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM'])(
+      'throws when the reference is invalid',
+      (identifier) => {
+        expect(() => caip2.toJSON(identifier)).toThrow('Invalid reference provided.');
+      },
+    );
+
+    it.each([
+      {
+        identifier: 'eip155:1',
+        expected: { namespace: 'eip155', reference: '1' },
+      },
+      {
+        identifier: 'bip122:000000000019d6689c085ae165831e93',
+        expected: { namespace: 'bip122', reference: '000000000019d6689c085ae165831e93' },
+      },
+      {
+        identifier: 'ava:2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM',
+        expected: { namespace: 'ava', reference: '2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM' },
+      },
+    ])('returns the correct caip2 object', ({ identifier, expected }) => {
+      expect(caip2.toJSON(identifier)).toStrictEqual(expected);
+    });
+  });
+
+  it('returns the correct identifier', () => {
+    const namespace = 'eip155';
+    const reference = '1';
+
+    expect(caip2.toString({ namespace, reference })).toBe('eip155:1');
+  });
+});

package/src/utils/caip2.ts

@@ -0,0 +1,41 @@
+// ref: https://chainagnostic.org/CAIPs/caip-2
+
+export type Caip2ChainId = {
+  namespace: string;
+  reference: string;
+};
+
+const namespacePattern = '^[-a-z0-9]{3,8}$';
+// the standard allows up to 32 characters for the reference part, but we have to set it to 50 so it accepts our cb58 encoded chain IDs
+const referencePattern = '^[-_a-zA-Z0-9]{1,50}$';
+const delimeter = ':';
+
+const toJSON = (identifier: string): Caip2ChainId => {
+  const [namespace, reference] = identifier.split(delimeter);
+
+  if (!namespace || !reference) {
+    throw new Error('Invalid identifier provided.');
+  }
+
+  if (!new RegExp(namespacePattern).test(namespace)) {
+    throw new Error('Invalid namespace provided.');
+  }
+
+  if (!new RegExp(referencePattern).test(reference)) {
+    throw new Error('Invalid reference provided.');
+  }
+
+  return {
+    namespace,
+    reference,
+  };
+};
+
+const toString = ({ namespace, reference }: Caip2ChainId) => {
+  return `${namespace}${delimeter}${reference}`;
+};
+
+export default {
+  toJSON,
+  toString,
+};

package/src/utils/client.test.ts

@@ -0,0 +1,97 @@
+import {
+  custom,
+  http,
+  type CustomTransport,
+  type HttpTransport,
+  createWalletClient,
+  type WalletClient,
+  publicActions,
+} from 'viem';
+import { TokenType, type Chain, type Provider } from '../types';
+import { getClientForChain } from './client';
+
+jest.mock('viem');
+
+const chainMock: Chain = {
+  chainId: 'eip155:1',
+  chainName: 'test chain',
+  networkToken: {
+    decimals: 18,
+    symbol: 'TEST',
+    name: 'Test Token',
+    type: TokenType.NATIVE,
+  },
+  rpcUrl: 'http://test.com',
+  utilityAddresses: {
+    multicall: '0x1',
+  },
+};
+
+const chainInfo = {
+  id: 1,
+  name: chainMock.chainName,
+  nativeCurrency: {
+    decimals: chainMock.networkToken.decimals,
+    symbol: chainMock.networkToken.symbol,
+    name: chainMock.networkToken.name,
+  },
+  network: chainMock.chainName,
+  rpcUrls: {
+    default: {
+      http: [chainMock.rpcUrl],
+    },
+    public: {
+      http: [chainMock.rpcUrl],
+    },
+  },
+  ...(chainMock.utilityAddresses?.multicall && {
+    contracts: {
+      multicall3: {
+        address: chainMock.utilityAddresses.multicall,
+      },
+    },
+  }),
+};
+
+describe('client', () => {
+  const transportMock = { type: 'transport' };
+  const walletClientMock = { type: 'client', extend: jest.fn() };
+  const extendedWalletClientMock = { ...walletClientMock, extended: true };
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    walletClientMock.extend.mockReturnValueOnce(extendedWalletClientMock);
+
+    jest.mocked(http).mockReturnValueOnce(transportMock as unknown as HttpTransport);
+    jest.mocked(custom).mockReturnValueOnce(transportMock as unknown as CustomTransport);
+    jest.mocked(createWalletClient).mockReturnValueOnce(walletClientMock as unknown as WalletClient);
+  });
+
+  it('returns the client correctly without predefined provider', () => {
+    const client = getClientForChain({ chain: chainMock });
+    expect(client).toStrictEqual(extendedWalletClientMock);
+
+    expect(custom).not.toHaveBeenCalled();
+    expect(http).toHaveBeenCalledWith(chainMock.rpcUrl, { batch: true, retryCount: 0 });
+    expect(createWalletClient).toHaveBeenCalledWith({
+      chain: chainInfo,
+      transport: transportMock,
+    });
+    expect(walletClientMock.extend).toHaveBeenCalledWith(publicActions);
+  });
+
+  it('returns the client correctly with a predefined provider', () => {
+    const providerMock = { type: 'provider' } as unknown as Provider;
+    const client = getClientForChain({ chain: chainMock, provider: providerMock });
+    expect(client).toStrictEqual(extendedWalletClientMock);
+
+    expect(http).not.toHaveBeenCalled();
+    expect(custom).toHaveBeenCalledWith(providerMock);
+    expect(createWalletClient).toHaveBeenCalledWith({
+      chain: chainInfo,
+      transport: transportMock,
+    });
+    expect(walletClientMock.extend).toHaveBeenCalledWith(publicActions);
+  });
+});

package/src/utils/client.ts

@@ -0,0 +1,44 @@
+import { createWalletClient, publicActions, custom, http } from 'viem';
+import type { Chain } from '../types/chain';
+import type { Provider } from '../types';
+import caip2 from './caip2';
+
+const _getChain = (chain: Chain) => {
+  const { reference: chainId } = caip2.toJSON(chain.chainId);
+
+  return {
+    id: Number(chainId),
+    name: chain.chainName,
+    nativeCurrency: {
+      decimals: chain.networkToken.decimals,
+      symbol: chain.networkToken.symbol,
+      name: chain.networkToken.name,
+    },
+    network: chain.chainName,
+    rpcUrls: {
+      default: {
+        http: [chain.rpcUrl],
+      },
+      public: {
+        http: [chain.rpcUrl],
+      },
+    },
+    ...(chain.utilityAddresses?.multicall && {
+      contracts: {
+        multicall3: {
+          address: chain.utilityAddresses.multicall,
+        },
+      },
+    }),
+  };
+};
+
+export const getClientForChain = ({ chain, provider }: { chain: Chain; provider?: Provider }) => {
+  const chainInfo = _getChain(chain);
+  const transport = provider ? custom(provider) : http(chain.rpcUrl, { batch: true, retryCount: 0 });
+
+  return createWalletClient({
+    chain: chainInfo,
+    transport,
+  }).extend(publicActions);
+};

package/src/utils/ensure-config.test.ts

@@ -0,0 +1,43 @@
+import { BridgeInitializationError } from '../errors';
+import { ErrorReason, type BridgeConfig, type BridgeService } from '../types';
+import { ensureHasConfig } from './ensure-config';
+
+describe('ensure-config', () => {
+  it('throws if it fails to update the config', async () => {
+    const bridgeMock = {
+      updateConfig: jest.fn(),
+    } as unknown as BridgeService;
+
+    await expect(ensureHasConfig(bridgeMock)).rejects.toThrow(
+      new BridgeInitializationError(ErrorReason.CONFIG_NOT_AVAILABLE),
+    );
+    expect(bridgeMock.updateConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it('updates the config correctly', async () => {
+    const config = { foo: 'bar' } as unknown as BridgeConfig;
+    const bridgeMock = {
+      updateConfig: jest.fn().mockImplementation(() => {
+        bridgeMock.config = config;
+      }),
+    } as unknown as BridgeService;
+
+    expect(bridgeMock.config).toBeUndefined();
+    await expect(ensureHasConfig(bridgeMock)).resolves.toBeUndefined();
+    expect(bridgeMock.config).toStrictEqual(config);
+    expect(bridgeMock.updateConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it('does nothing if bridge already has config', async () => {
+    const config = { foo: 'bar' } as unknown as BridgeConfig;
+    const bridgeMock = {
+      config,
+      updateConfig: jest.fn(),
+    } as unknown as BridgeService;
+
+    expect(bridgeMock.config).toStrictEqual(config);
+    await expect(ensureHasConfig(bridgeMock)).resolves.toBeUndefined();
+    expect(bridgeMock.config).toStrictEqual(config);
+    expect(bridgeMock.updateConfig).not.toHaveBeenCalled();
+  });
+});

package/src/utils/ensure-config.ts

@@ -0,0 +1,12 @@
+import { BridgeInitializationError } from '../errors';
+import { ErrorReason, type BridgeService } from '../types';
+
+export async function ensureHasConfig(bridge: BridgeService) {
+  if (!bridge.config) {
+    await bridge.updateConfig();
+
+    if (!bridge.config) {
+      throw new BridgeInitializationError(ErrorReason.CONFIG_NOT_AVAILABLE);
+    }
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './bridge-types';
+export { default as caip2 } from './caip2';

package/src/utils/network-fee.test.ts

@@ -0,0 +1,24 @@
+import type { Transaction, TransactionReceipt } from 'viem';
+import { getNetworkFeeEVM } from './network-fee';
+
+describe('network-fee', () => {
+  describe('getNetworkFeeEVM', () => {
+    const transactionMock = {
+      gasPrice: 50,
+    } as unknown as Transaction;
+
+    const receiptMock = {
+      gasUsed: 100,
+    } as unknown as TransactionReceipt;
+
+    it('returns undefined if gasPrice is missing', () => {
+      const networkFee = getNetworkFeeEVM({} as Transaction, receiptMock);
+      expect(networkFee).toBeUndefined();
+    });
+
+    it('returns the correct network fee', () => {
+      const networkFee = getNetworkFeeEVM(transactionMock, receiptMock);
+      expect(networkFee).toEqual(5000n);
+    });
+  });
+});

package/src/utils/network-fee.ts

@@ -0,0 +1,6 @@
+import { type Transaction, type TransactionReceipt } from 'viem';
+
+// returns the network fee for EVM transaction in wei (10**-18)
+export const getNetworkFeeEVM = (transaction: Transaction, receipt: TransactionReceipt) => {
+  return transaction.gasPrice && BigInt(transaction.gasPrice * receipt.gasUsed);
+};

package/src/utils/retry-promise.test.ts

@@ -0,0 +1,115 @@
+import { noop } from 'lodash';
+import { retryPromise } from './retry-promise';
+
+describe('retry-promise', () => {
+  const delay = 5000;
+  const promiseMock = jest.fn();
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.useFakeTimers();
+  });
+
+  it('rejects when cancelled', (done) => {
+    const test = async () => {
+      promiseMock.mockResolvedValue(undefined);
+
+      const { result, cancel } = retryPromise({ promise: promiseMock, delay });
+
+      for (let i = 1; i <= 5; i++) {
+        expect(promiseMock).toHaveBeenCalledTimes(i);
+        await jest.advanceTimersByTimeAsync(delay);
+      }
+
+      result.catch((err) => {
+        expect(err).toBe('cancelled');
+        done();
+      });
+
+      cancel();
+    };
+
+    test();
+  });
+
+  it('delays execution when `startAfter` is provided', (done) => {
+    const test = async () => {
+      const response = { foo: 'bar' };
+      const startAfter = 3000;
+
+      promiseMock
+        .mockResolvedValueOnce(undefined)
+        .mockResolvedValueOnce(undefined)
+        .mockImplementationOnce(async (done) => {
+          done(response);
+        });
+
+      const { result } = retryPromise({ promise: promiseMock, delay, startAfter });
+      expect(promiseMock).not.toHaveBeenCalled();
+
+      // initial delay
+      await jest.advanceTimersByTimeAsync(startAfter);
+      expect(promiseMock).toHaveBeenCalledTimes(1);
+
+      // normal execution
+      await jest.advanceTimersByTimeAsync(delay);
+      expect(promiseMock).toHaveBeenCalledTimes(2);
+
+      await jest.advanceTimersByTimeAsync(delay);
+      expect(promiseMock).toHaveBeenCalledTimes(3);
+
+      result.then((res) => {
+        expect(res).toStrictEqual(response);
+        done();
+      });
+    };
+
+    test();
+  });
+
+  it('uses exponential backoff after errors and resolves correctly', (done) => {
+    const test = async () => {
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(noop);
+      const response = { foo: 'bar' };
+
+      promiseMock
+        .mockResolvedValueOnce(undefined)
+        .mockRejectedValueOnce(new Error('error 1'))
+        .mockRejectedValueOnce(new Error('error 2'))
+        .mockRejectedValueOnce(new Error('error 3'))
+        .mockResolvedValueOnce(undefined)
+        .mockImplementationOnce(async (done) => {
+          done(response);
+        });
+
+      const { result } = retryPromise({ promise: promiseMock, delay });
+      expect(promiseMock).toHaveBeenCalledTimes(1);
+
+      // error 1
+      await jest.advanceTimersByTimeAsync(delay);
+      expect(promiseMock).toHaveBeenCalledTimes(2);
+      expect(consoleErrorSpy).toHaveBeenNthCalledWith(1, 'error 1');
+      // error 2
+      await jest.advanceTimersByTimeAsync(2 * delay);
+      expect(promiseMock).toHaveBeenCalledTimes(3);
+      expect(consoleErrorSpy).toHaveBeenNthCalledWith(2, 'error 2');
+      // error 3
+      await jest.advanceTimersByTimeAsync(4 * delay);
+      expect(promiseMock).toHaveBeenCalledTimes(4);
+      expect(consoleErrorSpy).toHaveBeenNthCalledWith(3, 'error 3');
+
+      await jest.advanceTimersByTimeAsync(8 * delay);
+      expect(promiseMock).toHaveBeenCalledTimes(5);
+
+      await jest.advanceTimersByTimeAsync(delay);
+      expect(promiseMock).toHaveBeenCalledTimes(6);
+
+      result.then((res) => {
+        expect(res).toStrictEqual(response);
+        done();
+      });
+    };
+
+    test();
+  });
+});