@uniswap/token-list-bridge-utils 0.1.1-beta.1

package/src/constants/chainId.ts

@@ -0,0 +1,13 @@
+export enum ChainId {
+  MAINNET = 1,
+  RINKEBY = 4,
+
+  ARBITRUM_ONE = 42161,
+  ARBITRUM_RINKEBY = 421611,
+
+  OPTIMISM = 10,
+  OPTIMISTIC_KOVAN = 69,
+
+  POLYGON = 137,
+  POLYGON_MUMBAI = 80001,
+}

package/src/constants/tokens.ts

@@ -0,0 +1,31 @@
+import { Token } from '@uniswap/sdk-core'
+import { ChainId } from './chainId'
+
+export const DAI = new Token(
+  ChainId.MAINNET,
+  '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+  18,
+  'DAI',
+  'Dai Stablecoin'
+)
+export const DAI_ARBITRUM_ONE = new Token(
+  ChainId.ARBITRUM_ONE,
+  '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+  18,
+  'DAI',
+  'Dai stable coin'
+)
+export const DAI_OPTIMISM = new Token(
+  ChainId.OPTIMISM,
+  '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
+  18,
+  'DAI',
+  'Dai stable coin'
+)
+export const DAI_POLYGON = new Token(
+  ChainId.POLYGON,
+  '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
+  18,
+  'DAI',
+  'Dai Stablecoin'
+)

package/src/fixtures/index.ts

@@ -0,0 +1,104 @@
+import { Token } from '@uniswap/sdk-core'
+import { TokenInfo, TokenList } from '@uniswap/token-lists'
+import { ChainId } from '../constants/chainId'
+import { DAI, DAI_ARBITRUM_ONE, DAI_POLYGON } from '../constants/tokens'
+import { compareTokenInfos } from '../utils'
+
+export const Tokens: Partial<Record<ChainId, Record<string, TokenInfo>>> = {
+  [ChainId.MAINNET]: {
+    DAI: tokenToTokenInfo(DAI),
+  },
+  [ChainId.ARBITRUM_ONE]: {
+    DAI: tokenToTokenInfo(DAI_ARBITRUM_ONE),
+  },
+  [ChainId.POLYGON]: {
+    DAI: tokenToTokenInfo(DAI_POLYGON),
+  },
+}
+
+export const sampleL1TokenList: TokenList = {
+  name: 'Sample',
+  timestamp: new Date(1646146610).toISOString(),
+  version: {
+    major: 1,
+    minor: 0,
+    patch: 0,
+  },
+  tokens: [Tokens[ChainId.MAINNET]!.DAI],
+}
+
+export const arbBridgeL2Address = '0x467194771dae2967aef3ecbedd3bf9a310c76c65'
+export const arbBridgeL1Address = '0xd3b5b60020504bc3489d6949d545893982ba3011'
+
+export const arbedSampleTokenList = {
+  ...sampleL1TokenList,
+  name: 'Arbed Sample',
+  tokens: [
+    {
+      ...Tokens[ChainId.ARBITRUM_ONE]!.DAI,
+      extensions: {
+        bridgeInfo: {
+          [ChainId.MAINNET]: {
+            tokenAddress: DAI.address,
+            originBridgeAddress: arbBridgeL2Address,
+            destBridgeAddress: arbBridgeL1Address,
+          },
+        },
+      },
+    } as unknown as TokenInfo,
+    {
+      ...(Tokens[ChainId.MAINNET]!.DAI as unknown as TokenInfo),
+      extensions: {
+        bridgeInfo: {
+          [ChainId.ARBITRUM_ONE]: {
+            tokenAddress: DAI_ARBITRUM_ONE.address,
+            destBridgeAddress: arbBridgeL2Address,
+            originBridgeAddress: arbBridgeL1Address,
+          },
+        },
+      },
+    } as unknown as TokenInfo,
+  ].sort(compareTokenInfos),
+}
+export const polygonedSampleTokenList = {
+  ...sampleL1TokenList,
+  name: 'Polygoned Sample',
+  tokens: [
+    {
+      ...Tokens[ChainId.POLYGON]!.DAI,
+      extensions: {
+        bridgeInfo: {
+          [ChainId.MAINNET]: {
+            tokenAddress: DAI.address,
+          },
+        },
+      },
+    } as unknown as TokenInfo,
+    {
+      ...(Tokens[ChainId.MAINNET]!.DAI as unknown as TokenInfo),
+      extensions: {
+        bridgeInfo: {
+          [ChainId.POLYGON]: {
+            tokenAddress: DAI_POLYGON.address,
+          },
+        },
+      },
+    } as unknown as TokenInfo,
+  ].sort(compareTokenInfos),
+}
+
+function tokenToTokenInfo({
+  chainId,
+  address,
+  name,
+  decimals,
+  symbol,
+}: Token): TokenInfo {
+  return {
+    chainId,
+    address: address,
+    name: name ?? 'n/a',
+    decimals,
+    symbol: symbol ?? 'n/a',
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,211 @@
+import { TokenInfo } from '@uniswap/token-lists'
+import { chainify, chainifyTokenList, mergeTokenLists } from '.'
+import { ChainId } from './constants/chainId'
+import { DAI, DAI_ARBITRUM_ONE, DAI_POLYGON } from './constants/tokens'
+import {
+  arbBridgeL1Address,
+  arbBridgeL2Address,
+  arbedSampleTokenList,
+  polygonedSampleTokenList,
+  sampleL1TokenList,
+  Tokens,
+} from './fixtures'
+
+describe(chainifyTokenList, () => {
+  it('no-ops on Optimism', async () => {
+    const tokenList = await chainifyTokenList(
+      ChainId.ARBITRUM_ONE,
+      sampleL1TokenList
+    )
+
+    expect(tokenList).toEqual(tokenList)
+  })
+
+  it('outputs arbitrum list correctly', async () => {
+    const tokenList = await chainifyTokenList(
+      ChainId.ARBITRUM_ONE,
+      sampleL1TokenList
+    )
+
+    expect(tokenList).not.toBeUndefined()
+    expect(tokenList?.version).toEqual(arbedSampleTokenList.version)
+    expect(
+      tokenList?.tokens.map((t) => [
+        t.address.toLowerCase(),
+        t.chainId,
+        JSON.parse(JSON.stringify(t.extensions).toLowerCase()),
+      ])
+    ).toEqual(
+      // ignores other metadata
+      arbedSampleTokenList.tokens.map((t) => [
+        t.address.toLowerCase(),
+        t.chainId,
+        JSON.parse(JSON.stringify(t.extensions).toLowerCase()),
+      ])
+    )
+  })
+
+  it('outputs polygon list correctly', async () => {
+    const tokenList = await chainifyTokenList(
+      ChainId.POLYGON,
+      sampleL1TokenList
+    )
+
+    expect(tokenList).toBeDefined()
+    expect(tokenList?.version).toEqual(polygonedSampleTokenList.version)
+    expect(
+      tokenList?.tokens.map((t) => [t.address, t.chainId, t.extensions])
+    ).toEqual(
+      // ignores other metadata
+      polygonedSampleTokenList.tokens.map((t) => [
+        t.address,
+        t.chainId,
+        t.extensions,
+      ])
+    )
+  })
+})
+
+describe(mergeTokenLists, () => {
+  it('correctly deduplicates', () => {
+    const merged = mergeTokenLists(sampleL1TokenList, sampleL1TokenList)
+
+    expect(merged).toEqual(sampleL1TokenList)
+  })
+
+  it('deduplicates with address case insensitivity', () => {
+    const allUpper = JSON.parse(JSON.stringify(sampleL1TokenList))
+    allUpper.tokens = allUpper.tokens.map((t: TokenInfo) => ({
+      ...t,
+      address: t.address.toUpperCase(),
+    }))
+
+    const mergedLeft = mergeTokenLists(sampleL1TokenList, allUpper)
+    expect(mergedLeft).toEqual(sampleL1TokenList)
+
+    // should prefer the first provided token list
+    const mergedRight = mergeTokenLists(allUpper, sampleL1TokenList)
+    expect(mergedRight).not.toEqual(sampleL1TokenList)
+    expect(mergedRight).toEqual(allUpper)
+  })
+
+  it('correctly merges multiple lists', () => {
+    const withPolygon = mergeTokenLists(
+      sampleL1TokenList,
+      polygonedSampleTokenList
+    )
+    const plusArbitrum = mergeTokenLists(withPolygon, arbedSampleTokenList)
+
+    expect(withPolygon.tokens).toEqual([
+      {
+        ...Tokens[ChainId.MAINNET]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.POLYGON]: {
+              tokenAddress: DAI_POLYGON.address,
+            },
+          },
+        },
+      },
+      {
+        ...Tokens[ChainId.POLYGON]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.MAINNET]: {
+              tokenAddress: DAI.address,
+            },
+          },
+        },
+      },
+    ])
+
+    expect(plusArbitrum.tokens).toEqual([
+      {
+        ...Tokens[ChainId.MAINNET]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.POLYGON]: {
+              tokenAddress: DAI_POLYGON.address,
+            },
+            [ChainId.ARBITRUM_ONE]: {
+              tokenAddress: DAI_ARBITRUM_ONE.address,
+              destBridgeAddress: arbBridgeL2Address,
+              originBridgeAddress: arbBridgeL1Address,
+            },
+          },
+        },
+      },
+      {
+        ...Tokens[ChainId.POLYGON]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.MAINNET]: {
+              tokenAddress: DAI.address,
+            },
+          },
+        },
+      },
+      {
+        ...Tokens[ChainId.ARBITRUM_ONE]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.MAINNET]: {
+              tokenAddress: DAI.address,
+              originBridgeAddress: arbBridgeL2Address,
+              destBridgeAddress: arbBridgeL1Address,
+            },
+          },
+        },
+      },
+    ])
+  })
+})
+
+describe(chainify, () => {
+  it('provides bridge extensions', async () => {
+    const chainified = await chainify(sampleL1TokenList)
+
+    expect(chainified.tokens).toEqual([
+      {
+        ...Tokens[ChainId.MAINNET]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.POLYGON]: {
+              tokenAddress: DAI_POLYGON.address,
+            },
+            [ChainId.ARBITRUM_ONE]: {
+              tokenAddress: DAI_ARBITRUM_ONE.address,
+              destBridgeAddress: arbBridgeL2Address,
+              originBridgeAddress: arbBridgeL1Address,
+            },
+          },
+        },
+      },
+      {
+        ...Tokens[ChainId.POLYGON]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.MAINNET]: {
+              tokenAddress: DAI.address,
+            },
+          },
+        },
+      },
+      {
+        ...Tokens[ChainId.ARBITRUM_ONE]!.DAI,
+        extensions: {
+          bridgeInfo: {
+            [ChainId.MAINNET]: {
+              tokenAddress: DAI.address.toLowerCase(),
+              originBridgeAddress: arbBridgeL2Address,
+              destBridgeAddress: arbBridgeL1Address,
+            },
+          },
+        },
+        logoURI:
+          'https://assets.coingecko.com/coins/images/9956/thumb/4943.png?1636636734',
+        name: 'Dai Stablecoin',
+      },
+    ])
+  })
+})

package/src/index.ts

@@ -0,0 +1,92 @@
+import { TokenList } from '@uniswap/token-lists'
+import { cloneDeep, groupBy, merge } from 'lodash'
+import { ChainId } from './constants/chainId'
+import { getMappingProvider } from './providers'
+import {
+  compareTokenInfos,
+  getTokenList,
+  TokenListOrFetchableTokenList
+} from './utils'
+import { verifyExtensions } from './verify'
+
+/**
+ * Adds bridgeInfo to the given token list for Optimism, Polygon and Arbitrum.
+ * @param l1TokenListOrPathOrUrl
+ * @returns TokenList with l2 bridgeInfo filled
+ */
+export async function chainify(
+  l1TokenListOrPathOrUrl: TokenListOrFetchableTokenList
+): Promise<TokenList> {
+  const l1TokenList = await getTokenList(l1TokenListOrPathOrUrl)
+
+  const optimisimed = await chainifyTokenList(
+    ChainId.OPTIMISM,
+    l1TokenListOrPathOrUrl
+  )
+  const polygoned = await chainifyTokenList(
+    ChainId.POLYGON,
+    l1TokenListOrPathOrUrl
+  )
+  const arbified = await chainifyTokenList(
+    ChainId.ARBITRUM_ONE,
+    l1TokenListOrPathOrUrl
+  )
+
+  return mergeTokenLists(
+    l1TokenList, // providing l1 first to make sure duplicated tokens resolve to this list
+    mergeTokenLists(mergeTokenLists(arbified, optimisimed), polygoned)
+  )
+}
+
+/**
+ * Given a network and a TokenList, returns the TokenList with `extensions` filled.
+ * @param chainId chainId to operate on
+ * @param l1TokenListOrPathOrUrl either an L1 TokenList object or a path/url to a TokenList
+ * @returns L1 TokenList with `extensions` filled for the given network
+ */
+export async function chainifyTokenList(
+  chainId: ChainId,
+  l1TokenListOrPathOrUrl: TokenListOrFetchableTokenList
+): Promise<TokenList> {
+  try {
+    const tokenList = await getMappingProvider(chainId).provide(
+      await getTokenList(l1TokenListOrPathOrUrl)
+    )
+    return verifyExtensions(tokenList)
+  } catch (e) {
+    throw new Error(`An error occured: ${e}`)
+  }
+}
+
+/** Merges two token lists, resolving conflicts to primary list. */
+export function mergeTokenLists(
+  primary: TokenList,
+  secondary: TokenList
+): TokenList {
+  primary = cloneDeep(primary)
+  secondary = cloneDeep(secondary)
+
+  const grouped = groupBy(
+    [...secondary.tokens, ...primary.tokens],
+    (t) => `${t.chainId}-${t.address.toLowerCase()}`
+  )
+
+  const merged = Object.values(grouped).map((group) => {
+    if (group.length === 1) {
+      return group[0]
+    }
+
+    const merged = merge(group[0], group[1])
+    if (merged.extensions?.bridgeInfo) {
+      // remove reference to self-chain from merge
+      // @ts-expect-error TokenList schema doesn't yet define objects
+      delete merged.extensions.bridgeInfo[merged.chainId]
+    }
+    return merged
+  })
+
+  return cloneDeep({
+    ...primary,
+    tokens: merged.sort(compareTokenInfos),
+  })
+}

package/src/providers/ArbitrumMappingProvider.ts

@@ -0,0 +1,28 @@
+import { TokenList } from '@uniswap/token-lists'
+import { generateTokenList } from '../arb-token-lists/src/lib/token_list_gen'
+import { compareTokenInfos } from '../utils'
+import { MappingProvider } from './MappingProvider'
+
+/**
+ * The Arbitrum team maintains an (unpublished) package to `arbify` an L1
+ * token list.
+ *
+ * The provider simply invokes this package which we host as a submodule.
+ */
+
+export class ArbitrumMappingProvider implements MappingProvider {
+  async provide(l1TokenList: TokenList): Promise<TokenList> {
+    const arbedTokenList = (await generateTokenList(
+      l1TokenList,
+      /*prevArbTokenList=*/ undefined,
+      {
+        includeAllL1Tokens: true,
+      }
+    )) as unknown as TokenList
+
+    return {
+      ...arbedTokenList,
+      tokens: arbedTokenList.tokens.sort(compareTokenInfos),
+    }
+  }
+}

package/src/providers/MappingProvider.ts

@@ -0,0 +1,5 @@
+import { TokenList } from '@uniswap/token-lists'
+
+export interface MappingProvider {
+  provide(l1TokenList: TokenList): Promise<TokenList>
+}

package/src/providers/OptimismMappingProvider.ts

@@ -0,0 +1,13 @@
+import { TokenList } from '@uniswap/token-lists'
+import { MappingProvider } from './MappingProvider'
+
+/**
+ * The Optimism L2 mapping is manually maintained by the Optimism team.
+ *
+ * This provider mostly no-ops, i.e. grabs the list and returns it.
+ */
+export class OptimismMappingProvider implements MappingProvider {
+  async provide(l1TokenList: TokenList): Promise<TokenList> {
+    return l1TokenList
+  }
+}

package/src/providers/PolygonMappingProvider.ts

@@ -0,0 +1,127 @@
+import { TokenInfo, TokenList } from '@uniswap/token-lists'
+import axios from 'axios'
+import { compareTokenInfos } from '../utils'
+import { MappingProvider } from './MappingProvider'
+
+interface PolygonMappedToken {
+  chainId: number
+  child_address_passed_by_user: boolean
+  child_token: string
+  count: number
+  created_at: string
+  decimals: number
+  deleted: boolean
+  id: number
+  map_type: 'POS'
+  mintable: boolean
+  name: string
+  new_child_token: string
+  new_mintable: boolean
+  owner: string
+  reason: string
+  reason_for_remapping: string
+  remapping_allowed: boolean
+  remapping_request_submitted: boolean
+  remapping_verified: boolean
+  root_token: string
+  status: number
+  symbol: string
+  token_type: string // ERC20
+  updated_at: string
+  uri: string
+}
+
+type PolygonMappedTokenData = { [key: string]: PolygonMappedToken }
+
+/**
+ * The Polygon team manually maintains the mapping via user submissions at
+ * https://mapper.polygon.technology.
+ */
+export class PolygonMappingProvider implements MappingProvider {
+  async provide(l1TokenList: TokenList): Promise<TokenList> {
+    const polygonTokens = await fetchPolygonMappedTokens()
+
+    const mappedTokens = []
+    for (const rootToken of l1TokenList.tokens) {
+      const childToken = polygonTokens[rootToken.address.toLowerCase()]
+      const childTokenValid = Boolean(childToken && !childToken.deleted)
+
+      // build extension info if available
+      const toRootExtensions = childTokenValid
+        ? {
+            extensions: {
+              bridgeInfo: {
+                [rootToken.chainId]: {
+                  tokenAddress: childToken.root_token,
+                },
+              },
+            },
+          }
+        : {}
+      const toChildExtensions = childTokenValid
+        ? {
+            extensions: {
+              bridgeInfo: {
+                [childToken.chainId]: {
+                  tokenAddress: childToken.child_token,
+                },
+              },
+            },
+          }
+        : {}
+
+      const rootTokenInfo: TokenInfo = {
+        ...rootToken,
+        ...toChildExtensions,
+      } as unknown as TokenInfo
+
+      const childTokenInfo: TokenInfo = {
+        ...rootToken,
+        chainId: childToken.chainId,
+        name: childToken.name ?? rootToken.name,
+        symbol: childToken.symbol ?? rootToken.symbol,
+        address: childToken.child_token,
+        ...toRootExtensions,
+      } as unknown as TokenInfo
+
+      mappedTokens.push(rootTokenInfo)
+      mappedTokens.push(childTokenInfo)
+    }
+
+    const tokenList = {
+      name: `Polygon ${l1TokenList.name}`,
+      timestamp: new Date().toISOString(),
+      version: l1TokenList.version,
+      tokens: mappedTokens.sort(compareTokenInfos),
+    }
+
+    return tokenList
+  }
+}
+
+const url = 'https://tokenmapper.api.matic.today/api/v1/mapping?'
+const params = 'map_type=[%22POS%22]&chain_id=137&limit=200&offset='
+
+async function fetchPolygonMappedTokens(): Promise<PolygonMappedTokenData> {
+  let offset = 0
+  const tokens: PolygonMappedTokenData = {}
+
+  while (true) {
+    const response = await axios.get(`${url}${params}${offset}`)
+
+    if (response.data.message === 'success') {
+      for (const token of response.data.data.mapping) {
+        tokens[token.root_token.toLowerCase()] = token
+      }
+
+      if (response.data.data.has_next_page === true) {
+        offset += 200
+        continue
+      }
+    }
+
+    break
+  }
+
+  return tokens
+}

package/src/providers/index.ts

@@ -0,0 +1,17 @@
+import { ChainId } from '../constants/chainId'
+import { ArbitrumMappingProvider } from './ArbitrumMappingProvider'
+import { OptimismMappingProvider } from './OptimismMappingProvider'
+import { PolygonMappingProvider } from './PolygonMappingProvider'
+
+export function getMappingProvider(chainId: ChainId) {
+  switch (chainId) {
+    case ChainId.ARBITRUM_ONE:
+      return new ArbitrumMappingProvider()
+    case ChainId.OPTIMISM:
+      return new OptimismMappingProvider()
+    case ChainId.POLYGON:
+      return new PolygonMappingProvider()
+    default:
+      throw new Error(`Chain ${chainId} not supported.`)
+  }
+}

package/src/utils.ts

@@ -0,0 +1,21 @@
+import { TokenInfo, TokenList } from '@uniswap/token-lists'
+import { getTokenListObj } from './arb-token-lists/src/lib/utils'
+
+export type TokenListOrFetchableTokenList = TokenList | string
+
+export function compareTokenInfos(t1: TokenInfo, t2: TokenInfo) {
+  if (t1.chainId === t2.chainId) {
+    return t1.symbol.toLowerCase() < t2.symbol.toLowerCase() ? -1 : 1
+  }
+  return t1.chainId < t2.chainId ? -1 : 1
+}
+
+export async function getTokenList(
+  l1TokenListOrPathOrUrl: TokenListOrFetchableTokenList
+): Promise<TokenList> {
+  if (typeof l1TokenListOrPathOrUrl === 'string') {
+    return getTokenListObj(l1TokenListOrPathOrUrl)
+  } else {
+    return l1TokenListOrPathOrUrl
+  }
+}

package/src/verify.test.ts

@@ -0,0 +1,19 @@
+import {
+  arbedSampleTokenList,
+  polygonedSampleTokenList,
+  sampleL1TokenList,
+} from './fixtures'
+import { verifyExtensions } from './verify'
+
+describe(verifyExtensions, () => {
+  it('passes list without extensions', () => {
+    expect(verifyExtensions(sampleL1TokenList)).toBe(sampleL1TokenList)
+  })
+
+  it('passes a list with extensions', () => {
+    expect(verifyExtensions(polygonedSampleTokenList)).toBe(
+      polygonedSampleTokenList
+    )
+    expect(verifyExtensions(arbedSampleTokenList)).toBe(arbedSampleTokenList)
+  })
+})