wallet-stack 1.0.0-alpha.121

package/src/utils/parsing.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Reference file:
+ * https://github.com/celo-org/developer-tooling/blob/6148646a29e5e719df9a1b32d1580ea7e6e61be8/packages/sdk/utils/src/parsing.test.ts
+ */
+
+import BigNumber from 'bignumber.js'
+import { parseInputAmount, stringToBoolean } from 'src/utils/parsing'
+
+test('stringToBoolean()', () => {
+  expect(stringToBoolean('true')).toBe(true)
+  expect(stringToBoolean('      true    ')).toBe(true)
+  expect(stringToBoolean('false')).toBe(false)
+  expect(stringToBoolean('      false   ')).toBe(false)
+
+  expect(stringToBoolean('FaLse')).toBe(false)
+  expect(stringToBoolean('TruE')).toBe(true)
+
+  expect(() => stringToBoolean('fals')).toThrow("Unable to parse 'fals' as boolean")
+})
+
+test('stringToBigNum()', () => {
+  expect(parseInputAmount('.1')).toStrictEqual(new BigNumber('0.1'))
+  expect(parseInputAmount('.1 ')).toStrictEqual(new BigNumber('0.1'))
+  expect(parseInputAmount('1.')).toStrictEqual(new BigNumber('1'))
+  expect(parseInputAmount('0')).toStrictEqual(new BigNumber('0'))
+  expect(parseInputAmount('')).toStrictEqual(new BigNumber('0'))
+  expect(parseInputAmount('1.23')).toStrictEqual(new BigNumber('1.23'))
+  expect(parseInputAmount('1,23')).toStrictEqual(new BigNumber(NaN))
+  expect(parseInputAmount('1,23', ',')).toStrictEqual(new BigNumber('1.23'))
+})

package/src/utils/parsing.ts

@@ -0,0 +1,20 @@
+import BigNumber from 'bignumber.js'
+
+// Ref: https://github.com/celo-org/developer-tooling/blob/6148646a29e5e719df9a1b32d1580ea7e6e61be8/packages/sdk/utils/src/parsing.ts#L7
+export const parseInputAmount = (inputString: string, decimalSeparator = '.'): BigNumber => {
+  if (decimalSeparator !== '.') {
+    inputString = inputString.replace(decimalSeparator, '.')
+  }
+  return new BigNumber(inputString || '0')
+}
+
+// Ref: https://github.com/celo-org/developer-tooling/blob/f1677581b90675e37a4846ce53b29d8615a056e6/packages/sdk/base/src/parsing.ts#L1
+export const stringToBoolean = (inputString: string): boolean => {
+  const lowercasedInput = inputString.toLowerCase().trim()
+  if (lowercasedInput === 'true') {
+    return true
+  } else if (lowercasedInput === 'false') {
+    return false
+  }
+  throw new Error(`Unable to parse '${inputString}' as boolean`)
+}

package/src/utils/phoneNumber.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Reference file:
+ * https://github.com/celo-org/developer-tooling/blob/97d5ccf43a9f0f0c41abeb6d825117a88e9ed9bb/packages/sdk/phone-utils/src/phoneNumbers.test.ts
+ */
+
+import {
+  getCountryCode,
+  getDisplayPhoneNumber,
+  getExampleNumber,
+  getRegionCode,
+  getRegionCodeFromCountryCode,
+  parsePhoneNumber,
+} from 'src/utils/phoneNumbers'
+
+const COUNTRY_CODES = {
+  US: '+1',
+  DE: '+49',
+  AR: '+54',
+  MX: '+52',
+  LR: '+231',
+  CI: '+225',
+}
+
+const TEST_PHONE_NUMBERS = {
+  VALID_US_1: '6282287826',
+  VALID_US_2: '(628) 228-7826',
+  VALID_US_3: '+16282287826',
+  VALID_US_4: '16282287826',
+  VALID_DE_1: '015229355106',
+  VALID_DE_2: '01522 (935)-5106',
+  VALID_DE_3: '+49 01522 935 5106',
+  VALID_AR_1: '091126431111',
+  VALID_AR_2: '(911) 2643-1111',
+  VALID_AR_3: '+5411 2643-1111',
+  VALID_AR_4: '9 11 2643 1111',
+  VALID_MX_1: '33 1234-5678',
+  VALID_MX_2: '1 33 1234-5678',
+  VALID_MX_3: '+52 1 33 1234-5678',
+  VALID_LR: '881551952',
+  VALID_CI: '+225 2122003801',
+  FORMATTED_AR: '+5491126431111',
+  FORMATTED_MX: '+523312345678',
+  FORMATTED_LR: '+231881551952',
+  FORMATTED_CI: '+2252122003801',
+  DISPLAY_AR: '9 11 2643-1111',
+  DISPLAY_MX: '33 1234 5678',
+  DISPLAY_MX_3: '+52 1 33 1234-5678',
+  DISPLAY_LR: '88 155 1952',
+  DISPLAY_CI: '21 22 0 03801',
+  INVALID_EMPTY: '',
+  TOO_SHORT: '123',
+  VALID_E164: '+141555544444',
+}
+
+describe('Phone number formatting and utilities', () => {
+  describe('Display formatting', () => {
+    it('Invalid empty', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.INVALID_EMPTY, COUNTRY_CODES.US)).toBe('')
+    })
+    it('Format US phone simple, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_US_1, COUNTRY_CODES.US)).toBe(
+        '(628) 228-7826'
+      )
+    })
+    it('Format US phone messy, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_US_2, COUNTRY_CODES.US)).toBe(
+        '(628) 228-7826'
+      )
+    })
+    it('Format US phone simple, with country code and wrong region', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_US_3, COUNTRY_CODES.AR)).toBe(
+        '(628) 228-7826'
+      )
+    })
+    it('Format US phone simple, with country code but no param', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_US_3, COUNTRY_CODES.US)).toBe(
+        '(628) 228-7826'
+      )
+    })
+    it('Format US phone simple, with country code no plus', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_US_4, COUNTRY_CODES.US)).toBe(
+        '(628) 228-7826'
+      )
+    })
+    it('Format DE phone simple, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_DE_1, COUNTRY_CODES.DE)).toBe(
+        '01522 9355106'
+      )
+    })
+    it('Format DE phone messy, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_DE_2, COUNTRY_CODES.DE)).toBe(
+        '01522 9355106'
+      )
+    })
+    it('Format DE phone messy, wrong country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_DE_2, COUNTRY_CODES.US)).toBe(
+        TEST_PHONE_NUMBERS.VALID_DE_2
+      )
+    })
+    it('Format DE phone with country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_DE_3, COUNTRY_CODES.DE)).toBe(
+        '01522 9355106'
+      )
+    })
+    it('Format AR phone simple, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_AR_1, COUNTRY_CODES.AR)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_AR
+      )
+    })
+    it('Format AR phone messy, no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_AR_2, COUNTRY_CODES.AR)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_AR
+      )
+    })
+    it('Format AR phone with country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_AR_3, COUNTRY_CODES.AR)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_AR
+      )
+    })
+
+    it('Format MX phone with country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_MX_3, COUNTRY_CODES.MX)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_MX_3
+      )
+    })
+
+    it('Format LR phone with no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_LR, COUNTRY_CODES.LR)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_LR
+      )
+    })
+
+    it('Format CI phone with no country code', () => {
+      expect(getDisplayPhoneNumber(TEST_PHONE_NUMBERS.VALID_CI, COUNTRY_CODES.CI)).toBe(
+        TEST_PHONE_NUMBERS.DISPLAY_CI
+      )
+    })
+  })
+
+  describe('Number Parsing', () => {
+    it('Invalid empty', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.INVALID_EMPTY, COUNTRY_CODES.US)).toBe(null)
+    })
+    it('Too short', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.TOO_SHORT, COUNTRY_CODES.US)).toBe(null)
+    })
+    it('Format US messy phone #', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.VALID_US_2, COUNTRY_CODES.US)).toMatchObject({
+        e164Number: '+16282287826',
+        displayNumber: '(628) 228-7826',
+        countryCode: 1,
+        regionCode: 'US',
+      })
+    })
+    it('Format DE messy phone #', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.VALID_DE_2, COUNTRY_CODES.DE)).toMatchObject({
+        e164Number: '+4915229355106',
+        displayNumber: '01522 9355106',
+        countryCode: 49,
+        regionCode: 'DE',
+      })
+    })
+    it('Format AR messy phone # 1', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.VALID_AR_4, COUNTRY_CODES.AR)).toMatchObject({
+        e164Number: TEST_PHONE_NUMBERS.FORMATTED_AR,
+        displayNumber: TEST_PHONE_NUMBERS.DISPLAY_AR,
+        countryCode: 54,
+        regionCode: 'AR',
+      })
+    })
+
+    it('Format MX phone # 1', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.VALID_MX_1, COUNTRY_CODES.MX)).toMatchObject({
+        e164Number: TEST_PHONE_NUMBERS.FORMATTED_MX,
+        displayNumber: TEST_PHONE_NUMBERS.DISPLAY_MX,
+        countryCode: 52,
+        regionCode: 'MX',
+      })
+    })
+
+    it('Format CI phone #', () => {
+      expect(parsePhoneNumber(TEST_PHONE_NUMBERS.VALID_CI, COUNTRY_CODES.CI)).toMatchObject({
+        e164Number: TEST_PHONE_NUMBERS.FORMATTED_CI,
+        displayNumber: TEST_PHONE_NUMBERS.DISPLAY_CI,
+        countryCode: 225,
+        regionCode: 'CI',
+      })
+    })
+  })
+
+  describe('Other phone helper methods', () => {
+    it('gets country code', () => {
+      expect(getCountryCode(TEST_PHONE_NUMBERS.VALID_US_3)).toBe(1)
+      expect(getCountryCode(TEST_PHONE_NUMBERS.VALID_DE_3)).toBe(49)
+      expect(getCountryCode(TEST_PHONE_NUMBERS.VALID_AR_3)).toBe(54)
+      expect(getCountryCode(TEST_PHONE_NUMBERS.VALID_CI)).toBe(225)
+    })
+
+    it('gets region code', () => {
+      expect(getRegionCode(TEST_PHONE_NUMBERS.VALID_US_3)).toBe('US')
+      expect(getRegionCode(TEST_PHONE_NUMBERS.VALID_DE_3)).toBe('DE')
+      expect(getRegionCode(TEST_PHONE_NUMBERS.VALID_AR_3)).toBe('AR')
+      expect(getRegionCode(TEST_PHONE_NUMBERS.VALID_CI)).toBe('CI')
+    })
+
+    it('gets region code from country code', () => {
+      expect(getRegionCodeFromCountryCode(COUNTRY_CODES.US)).toBe('US')
+      expect(getRegionCodeFromCountryCode(COUNTRY_CODES.DE)).toBe('DE')
+      expect(getRegionCodeFromCountryCode(COUNTRY_CODES.AR)).toBe('AR')
+      expect(getRegionCodeFromCountryCode(COUNTRY_CODES.CI)).toBe('CI')
+    })
+  })
+
+  describe('Example phones', () => {
+    it('gets example by country showing zeros', () => {
+      expect(getExampleNumber(COUNTRY_CODES.AR)).toBe('000 0000-0000')
+      expect(getExampleNumber(COUNTRY_CODES.DE)).toBe('000 000000')
+      expect(getExampleNumber(COUNTRY_CODES.US)).toBe('(000) 000-0000')
+      expect(getExampleNumber(COUNTRY_CODES.CI)).toBe('00 00 0 00000')
+    })
+
+    it('gets example by country', () => {
+      expect(getExampleNumber(COUNTRY_CODES.AR, false)).toBe('011 2345-6789')
+      expect(getExampleNumber(COUNTRY_CODES.DE, false)).toBe('030 123456')
+      expect(getExampleNumber(COUNTRY_CODES.US, false)).toBe('(201) 555-0123')
+      expect(getExampleNumber(COUNTRY_CODES.CI, false)).toBe('21 23 4 56789')
+    })
+
+    it('gets example by country showing zeros in international way', () => {
+      expect(getExampleNumber(COUNTRY_CODES.AR, true, true)).toBe('+54 00 0000-0000')
+      expect(getExampleNumber(COUNTRY_CODES.DE, true, true)).toBe('+49 00 000000')
+      expect(getExampleNumber(COUNTRY_CODES.US, true, true)).toBe('+1 000-000-0000')
+      expect(getExampleNumber(COUNTRY_CODES.CI, true, true)).toBe('+225 00 00 0 00000')
+    })
+  })
+})

package/src/utils/phoneNumbers.ts

@@ -0,0 +1,240 @@
+/**
+ * Reference file:
+ * https://github.com/celo-org/developer-tooling/blob/97d5ccf43a9f0f0c41abeb6d825117a88e9ed9bb/packages/sdk/phone-utils/src/phoneNumbers.ts
+ */
+
+import {
+  PhoneNumberFormat,
+  PhoneNumberType,
+  PhoneNumberUtil,
+  type PhoneNumber,
+} from 'google-libphonenumber'
+import Logger from 'src/utils/Logger'
+
+const phoneUtil = PhoneNumberUtil.getInstance()
+
+interface ParsedPhoneNumber {
+  e164Number: string
+  displayNumber: string
+  displayNumberInternational: string
+  countryCode?: number
+  regionCode?: string
+}
+
+const MIN_PHONE_LENGTH = 4
+
+export function getCountryCode(e164PhoneNumber: string) {
+  if (!e164PhoneNumber) {
+    return null
+  }
+  try {
+    return phoneUtil.parse(e164PhoneNumber).getCountryCode()
+  } catch (error) {
+    Logger.debug(`getCountryCode, number: ${e164PhoneNumber}, error: ${error}`)
+    return null
+  }
+}
+
+export function getRegionCode(e164PhoneNumber: string) {
+  if (!e164PhoneNumber) {
+    return null
+  }
+  try {
+    return phoneUtil.getRegionCodeForNumber(phoneUtil.parse(e164PhoneNumber))
+  } catch (error) {
+    Logger.debug(`getRegionCodeForNumber, number: ${e164PhoneNumber}, error: ${error}`)
+    return null
+  }
+}
+
+export function getRegionCodeFromCountryCode(countryCode: string) {
+  if (!countryCode) {
+    return null
+  }
+  try {
+    return phoneUtil.getRegionCodeForCountryCode(parseInt(countryCode, 10))
+  } catch (error) {
+    Logger.debug(`getRegionCodeFromCountryCode, countrycode: ${countryCode}, error: ${error}`)
+    return null
+  }
+}
+
+export function getDisplayPhoneNumber(phoneNumber: string, defaultCountryCode: string) {
+  const phoneDetails = parsePhoneNumber(phoneNumber, defaultCountryCode)
+  if (phoneDetails) {
+    return phoneDetails.displayNumber
+  } else {
+    // Fallback to input instead of showing nothing for invalid numbers
+    return phoneNumber
+  }
+}
+
+export function getDisplayNumberInternational(e164PhoneNumber: string) {
+  const countryCode = getCountryCode(e164PhoneNumber)
+  const phoneDetails = parsePhoneNumber(e164PhoneNumber, (countryCode || '').toString())
+  if (phoneDetails) {
+    return phoneDetails.displayNumberInternational
+  } else {
+    // Fallback to input instead of showing nothing for invalid numbers
+    return e164PhoneNumber
+  }
+}
+
+export function isE164NumberStrict(phoneNumber: string) {
+  try {
+    const parsedPhoneNumber = phoneUtil.parse(phoneNumber)
+    if (!phoneUtil.isValidNumber(parsedPhoneNumber)) {
+      return false
+    }
+    return phoneUtil.format(parsedPhoneNumber, PhoneNumberFormat.E164) === phoneNumber
+  } catch {
+    return false
+  }
+}
+
+export function parsePhoneNumber(
+  phoneNumberRaw: string,
+  defaultCountryCode?: string
+): ParsedPhoneNumber | null {
+  try {
+    if (!phoneNumberRaw || phoneNumberRaw.length < MIN_PHONE_LENGTH) {
+      return null
+    }
+
+    const defaultRegionCode = defaultCountryCode
+      ? getRegionCodeFromCountryCode(defaultCountryCode)
+      : null
+    const parsedNumberUnfixed = phoneUtil.parse(phoneNumberRaw, defaultRegionCode || undefined)
+    const parsedCountryCode = parsedNumberUnfixed.getCountryCode()
+    const parsedRegionCode = phoneUtil.getRegionCodeForNumber(parsedNumberUnfixed)
+    const parsedNumber = handleSpecialCasesForParsing(
+      parsedNumberUnfixed,
+      parsedCountryCode,
+      parsedRegionCode
+    )
+
+    if (!parsedNumber) {
+      return null
+    }
+
+    const isValid = phoneUtil.isValidNumberForRegion(parsedNumber, parsedRegionCode)
+
+    return isValid
+      ? {
+          e164Number: phoneUtil.format(parsedNumber, PhoneNumberFormat.E164),
+          displayNumber: handleSpecialCasesForDisplay(parsedNumber, parsedCountryCode),
+          displayNumberInternational: phoneUtil.format(
+            parsedNumber,
+            PhoneNumberFormat.INTERNATIONAL
+          ),
+          countryCode: parsedCountryCode,
+          regionCode: parsedRegionCode,
+        }
+      : null
+  } catch (error) {
+    Logger.debug(`phoneNumbers/parsePhoneNumber/Failed to parse phone number, error: ${error}`)
+    return null
+  }
+}
+
+/**
+ * Some countries require a prefix before the area code depending on if the number is
+ * mobile vs landline and international vs national
+ */
+
+function prependToFormMobilePhoneNumber(
+  parsedNumber: PhoneNumber,
+  regionCode: string,
+  prefix: string
+) {
+  if (phoneUtil.getNumberType(parsedNumber) === PhoneNumberType.MOBILE) {
+    return parsedNumber
+  }
+
+  let nationalNumber = phoneUtil.format(parsedNumber, PhoneNumberFormat.NATIONAL)
+  // Nationally formatted numbers sometimes contain leading 0
+  if (nationalNumber.charAt(0) === '0') {
+    nationalNumber = nationalNumber.slice(1)
+  }
+  // If the number already starts with prefix, don't prepend it again
+  if (nationalNumber.startsWith(prefix)) {
+    return null
+  }
+
+  const adjustedNumber = phoneUtil.parse(prefix + nationalNumber, regionCode)
+  return phoneUtil.getNumberType(adjustedNumber) === PhoneNumberType.MOBILE ? adjustedNumber : null
+}
+
+function handleSpecialCasesForParsing(
+  parsedNumber: PhoneNumber,
+  countryCode?: number,
+  regionCode?: string
+) {
+  if (!countryCode || !regionCode) {
+    return parsedNumber
+  }
+
+  switch (countryCode) {
+    // Argentina
+    // https://github.com/googlei18n/libphonenumber/blob/master/FAQ.md#why-is-this-number-from-argentina-ar-or-mexico-mx-not-identified-as-the-right-number-type
+    // https://en.wikipedia.org/wiki/Telephone_numbers_in_Argentina
+    case 54:
+      return prependToFormMobilePhoneNumber(parsedNumber, regionCode, '9')
+
+    default:
+      return parsedNumber
+  }
+}
+
+// TODO(Rossy) Given the inconsistencies of numbers around the world, we should
+// display e164 everywhere to ensure users knows exactly who their sending money to
+function handleSpecialCasesForDisplay(parsedNumber: PhoneNumber, countryCode?: number) {
+  switch (countryCode) {
+    // Argentina
+    // The Google lib formatter incorretly adds '15' to the nationally formatted number for Argentina
+    // However '15' is only needed when calling a mobile from a landline
+    case 54:
+      return phoneUtil
+        .format(parsedNumber, PhoneNumberFormat.INTERNATIONAL)
+        .replace(/\+54(\s)?/, '')
+
+    case 231:
+      const formatted = phoneUtil.format(parsedNumber, PhoneNumberFormat.NATIONAL)
+      return formatted && formatted[0] === '0' ? formatted.slice(1) : formatted
+
+    default:
+      return phoneUtil.format(parsedNumber, PhoneNumberFormat.NATIONAL)
+  }
+}
+
+export function getExampleNumber(
+  regionCode: string,
+  useOnlyZeroes = true,
+  isInternational = false
+) {
+  const examplePhone = phoneUtil.getExampleNumber(
+    getRegionCodeFromCountryCode(regionCode) as string
+  )
+
+  if (!examplePhone) {
+    return
+  }
+
+  const formatedExample = phoneUtil.format(
+    examplePhone,
+    isInternational ? PhoneNumberFormat.INTERNATIONAL : PhoneNumberFormat.NATIONAL
+  )
+
+  if (useOnlyZeroes) {
+    if (isInternational) {
+      return formatedExample.replace(/(^\+[0-9]{1,3} |[0-9])/g, (value, _, i) => (i ? '0' : value))
+    }
+    return formatedExample.replace(/[0-9]/g, '0')
+  }
+
+  return formatedExample
+}
+
+export function anonymizedPhone(phoneNumber: string) {
+  return phoneNumber.slice(0, -4) + 'XXXX'
+}

package/src/utils/random.test.ts

@@ -0,0 +1,53 @@
+import { uniqueId } from 'lodash'
+import { deterministicShuffle, shuffle } from './random'
+
+describe('shuffle', () => {
+  it('should run through all permutations', () => {
+    const variants = new Set()
+    while (variants.size < 24) {
+      const shuffled = shuffle(['add', 'dapp', 'profile', 'learn'], uniqueId())
+      variants.add(shuffled.join(''))
+    }
+    expect(variants.size).toBe(24)
+  })
+  it('should shuffle the same for the same seed', () => {
+    const seed = uniqueId()
+    const first = shuffle(['add', 'dapp', 'profile', 'learn'], seed)
+    const second = shuffle(['add', 'dapp', 'profile', 'learn'], seed)
+    expect(first).toEqual(second)
+  })
+})
+
+describe('deterministicShuffle', () => {
+  const pepper = 'somePepper'
+  const sampleArray = [
+    { id: 1, name: 'Alpha' },
+    { id: 2, name: 'Bravo' },
+    { id: 3, name: 'Charlie' },
+    { id: 4, name: 'Delta' },
+  ]
+
+  it('should shuffle the array deterministically based on the pepper', () => {
+    const firstRun = deterministicShuffle(sampleArray, 'id', pepper)
+    const secondRun = deterministicShuffle(sampleArray, 'id', pepper)
+
+    expect(firstRun).not.toEqual(sampleArray)
+    expect(firstRun).toEqual(secondRun)
+  })
+
+  it('should produce a different order when the pepper or identifying property changes', () => {
+    const result = deterministicShuffle(sampleArray, 'id', pepper)
+    const resultWithDifferentPepper = deterministicShuffle(sampleArray, 'id', 'someOtherPepper')
+    const resultWithDifferentId = deterministicShuffle(sampleArray, 'name', pepper)
+
+    expect(result).not.toEqual(resultWithDifferentPepper)
+    expect(result).not.toEqual(resultWithDifferentId)
+    expect(resultWithDifferentPepper).not.toEqual(resultWithDifferentId)
+  })
+
+  it('should handle an empty array without throwing errors', () => {
+    const result = deterministicShuffle([], 'id', pepper)
+
+    expect(result).toEqual([])
+  })
+})

package/src/utils/random.ts

@@ -0,0 +1,48 @@
+import crypto from 'crypto'
+import seedrandom from 'seedrandom'
+
+// https://stackoverflow.com/a/2450976/112731
+// Fisher–Yates shuffle algorithm to shuffle an array
+export function shuffle(array: any[], seed: string) {
+  let currentIndex = array.length,
+    temporaryValue,
+    randomIndex
+
+  const randomizer = seedrandom(seed)
+  // While there remain elements to shuffle...
+  while (0 !== currentIndex) {
+    // Pick a remaining element...
+    randomIndex = Math.floor(randomizer() * currentIndex)
+    currentIndex -= 1
+
+    // And swap it with the current element.
+    temporaryValue = array[currentIndex]
+    array[currentIndex] = array[randomIndex]
+    array[randomIndex] = temporaryValue
+  }
+
+  return array
+}
+
+export function calculateSha256Hash(input: string) {
+  const hash = crypto.createHash('sha256')
+  hash.update(input)
+  return hash.digest('hex')
+}
+
+export function deterministicShuffle<T>(
+  objectArray: T[],
+  identifyingProperty: keyof T,
+  pepper: string
+): T[] {
+  const map = new Map<string, T>()
+  objectArray.forEach((element) => {
+    const hash = calculateSha256Hash(`${element[identifyingProperty]}${pepper}`)
+    map.set(hash, element)
+  })
+
+  // sort the tokens array based on hash of the identifying property and user's address
+  return Array.from(map.entries())
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([_, token]) => token)
+}