@wormhole-foundation/sdk-base 0.1.0-beta.3

package/src/constants/platforms.ts

@@ -0,0 +1,128 @@
+import { ChainName } from "./chains";
+import { Network } from "./networks";
+import { RoArray, ToMapping, column, constMap } from "../utils";
+
+const platformAndChainsEntries = [
+  [
+    "Evm",
+    [
+      "Ethereum",
+      "Bsc",
+      "Polygon",
+      "Avalanche",
+      "Oasis",
+      "Aurora",
+      "Fantom",
+      "Karura",
+      "Acala",
+      "Klaytn",
+      "Celo",
+      "Moonbeam",
+      "Neon",
+      "Arbitrum",
+      "Optimism",
+      "Gnosis",
+      "Base",
+      "Sepolia",
+    ],
+  ],
+  ["Solana", ["Solana", "Pythnet"]],
+  ["Cosmwasm", ["Terra", "Terra2", "Injective", "Xpla", "Sei"]],
+  ["Btc", ["Btc"]],
+  ["Algorand", ["Algorand"]],
+  ["Sui", ["Sui"]],
+  ["Aptos", ["Aptos"]],
+  ["Osmosis", ["Osmosis"]],
+  ["Wormchain", ["Wormchain"]],
+  ["Near", ["Near"]],
+] as const satisfies RoArray<readonly [string, RoArray<ChainName>]>;
+
+export const platforms = column(platformAndChainsEntries, 0);
+export type PlatformName = (typeof platforms)[number];
+
+export const platformToChains = constMap(platformAndChainsEntries);
+export const chainToPlatform = constMap(platformAndChainsEntries, [1, 0]);
+
+export const isPlatform = (platform: string): platform is PlatformName =>
+  platformToChains.has(platform);
+
+export type PlatformToChains<P extends PlatformName> = ReturnType<
+  typeof platformToChains<P>
+>[number];
+export type ChainToPlatform<C extends ChainName> = ReturnType<
+  typeof chainToPlatform<C>
+>;
+
+const networkChainEvmCIdEntries = [
+  [
+    "Mainnet",
+    [
+      ["Ethereum", 1n],
+      // TODO: forced to add this to match other list
+      ["Sepolia", 0n],
+      ["Bsc", 56n],
+      ["Polygon", 137n],
+      ["Avalanche", 43114n],
+      ["Oasis", 42262n],
+      ["Aurora", 1313161554n],
+      ["Fantom", 250n],
+      ["Karura", 686n],
+      ["Acala", 787n],
+      ["Klaytn", 8217n],
+      ["Celo", 42220n],
+      ["Moonbeam", 1284n],
+      ["Neon", 245022934n],
+      ["Arbitrum", 42161n],
+      ["Optimism", 10n],
+      ["Gnosis", 100n],
+      ["Base", 8453n],
+    ],
+  ],
+  [
+    "Testnet",
+    [
+      ["Ethereum", 5n], //goerli
+      ["Sepolia", 11155111n], //actually just another ethereum testnet...
+      ["Bsc", 97n],
+      ["Polygon", 80001n], //mumbai
+      ["Avalanche", 43113n], //fuji
+      ["Oasis", 42261n],
+      ["Aurora", 1313161555n],
+      ["Fantom", 4002n],
+      ["Karura", 596n],
+      ["Acala", 597n],
+      ["Klaytn", 1001n], //baobab
+      ["Celo", 44787n], //alfajores
+      ["Moonbeam", 1287n], //moonbase alpha
+      ["Neon", 245022940n],
+      ["Arbitrum", 421613n], //arbitrum goerli
+      ["Optimism", 420n],
+      ["Gnosis", 77n],
+      ["Base", 84531n],
+    ],
+  ],
+] as const satisfies RoArray<
+  readonly [Network, RoArray<readonly [PlatformToChains<"Evm">, bigint]>]
+>;
+
+export const evmChainIdToNetworkChainPair = constMap(
+  networkChainEvmCIdEntries,
+  [2, [0, 1]]
+);
+export const evmNetworkChainToEvmChainId = constMap(networkChainEvmCIdEntries);
+
+const networkChainSolanaGenesisHashes = [
+  ["Mainnet", [["Solana", "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"]]],
+  ["Testnet", [["Solana", "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG"]]], // Note: this is referred to as `devnet` in sol
+] as const satisfies RoArray<
+  readonly [Network, RoArray<readonly [ChainName, string]>]
+>;
+
+export const solGenesisHashToNetworkChainPair = constMap(
+  networkChainSolanaGenesisHashes,
+  [2, [0, 1]]
+);
+
+export const solNetworkChainToGenesisHash = constMap(
+  networkChainSolanaGenesisHashes
+);

package/src/constants/protocols.ts

@@ -0,0 +1,36 @@
+/* TODO:
+ *   governance actions have a module parameter:
+ *     - "Core" - https://github.com/wormhole-foundation/wormhole/blob/9e61d151c61bedb18ab1d4ca6ffb1c6c91b108f0/ethereum/contracts/Governance.sol#L21
+ *     - "TokenBridge" - https://github.com/wormhole-foundation/wormhole/blob/9e61d151c61bedb18ab1d4ca6ffb1c6c91b108f0/ethereum/contracts/bridge/BridgeGovernance.sol#L24
+ *     - "NFTBridge" - https://github.com/wormhole-foundation/wormhole/blob/9e61d151c61bedb18ab1d4ca6ffb1c6c91b108f0/ethereum/contracts/nft/NFTBridgeGovernance.sol#L23
+ *     - "WormholeRelayer" - https://github.com/wormhole-foundation/wormhole/blob/9e61d151c61bedb18ab1d4ca6ffb1c6c91b108f0/ethereum/contracts/relayer/wormholeRelayer/WormholeRelayerGovernance.sol#L43
+ *   while the core contract is actually called "Wormhole" in most platforms
+ *     - though in solana it's called bridge - https://github.com/wormhole-foundation/wormhole/tree/main/solana/bridge
+ *     - and in algorand it seems to be called wormhole_core - https://github.com/wormhole-foundation/wormhole/blob/main/algorand/wormhole_core.py
+ *     - and in EVM it resides directly in the contracts directory
+ *   the naming of the token bridge and the nft bridge seem to be a lot more consistent, though:
+ *     - for EVM the TokenBridge and NFTbridge reside in the "bridge" and "nft" directory respectively: https://github.com/wormhole-foundation/wormhole/tree/main/ethereum/contracts)
+ *   the WormholeRelayer resides in relayer/wormholeRelayer (only built for EVM so far)
+ *
+ *   Within the solana directory, only the token bridge and the nft bridge are considered modules
+ *     (i.e. are in the modules directory: https://github.com/wormhole-foundation/wormhole/tree/main/solana/modules).
+ *   While in the JS SDK, the core bridge functionality is in the "bridge" directory
+ *     (notice the clash with EVM where bridge refers to the token bridge...).
+ *
+ * With all of this in mind: What should we name modules here?
+ * My preferred choice would be ["CoreBridge", "TokenBridge", "NftBridge", "Relayer"]
+ *   but ["Core", "TokenBridge", "NFTBridge", "WormholeRelayer"] seems to be more consistent given
+ *   current naming "conventions"
+ */
+
+export const protocols = [
+  "CoreBridge",
+  "TokenBridge",
+  "NftBridge",
+  "Relayer",
+  "CCTP",
+] as const;
+
+export type ProtocolName = (typeof protocols)[number];
+export const isProtocolName = (protocol: string): protocol is ProtocolName =>
+  protocols.includes(protocol as ProtocolName);

package/src/constants/rpc.ts

@@ -0,0 +1,48 @@
+import { constMap, RoArray } from "../utils";
+import { Network } from "./networks";
+import { ChainName } from "./chains";
+
+const rpcConfig = [
+  [
+    "Mainnet",
+    [
+      ["Ethereum", "https://rpc.ankr.com/eth"],
+      ["Solana", "https://api.mainnet-beta.solana.com"],
+      ["Polygon", "https://rpc.ankr.com/polygon"],
+      ["Bsc", "https://bscrpc.com"],
+      ["Avalanche", "https://rpc.ankr.com/avalanche"],
+      ["Fantom", "https://rpc.ankr.com/fantom"],
+      ["Celo", "https://rpc.ankr.com/celo"],
+      ["Moonbeam", "https://rpc.ankr.com/moonbeam"],
+      ["Sui", "https://rpc.mainnet.sui.io"],
+      ["Aptos", "https://fullnode.mainnet.aptoslabs.com/v1"],
+      ["Arbitrum", "https://arb1.arbitrum.io/rpc"],
+      ["Optimism", "https://mainnet.optimism.io"],
+      ["Sei", ""], // TODO
+    ],
+  ],
+  [
+    "Testnet",
+    [
+      ["Ethereum", "https://rpc.ankr.com/eth_goerli"],
+      ["Polygon", "https://polygon-mumbai.blockpi.network/v1/rpc/public"],
+      ["Bsc", "https://data-seed-prebsc-1-s3.binance.org:8545"],
+      ["Avalanche", "https://api.avax-test.network/ext/bc/C/rpc"],
+      ["Fantom", "https://rpc.ankr.com/fantom_testnet"],
+      ["Celo", "https://alfajores-forno.celo-testnet.org"],
+      ["Solana", "https://api.devnet.solana.com"],
+      ["Moonbeam", "https://rpc.api.moonbase.moonbeam.network"],
+      ["Sui", "https://fullnode.testnet.sui.io"],
+      ["Aptos", "https://fullnode.testnet.aptoslabs.com/v1"],
+      ["Sei", "https://rpc.atlantic-2.seinetwork.io"],
+      ["Arbitrum", "https://arbitrum-goerli.publicnode.com"],
+      ["Optimism", "https://optimism-goerli.publicnode.com"],
+    ],
+  ],
+] as const satisfies RoArray<
+  readonly ["Mainnet" | "Testnet", RoArray<readonly [ChainName, string]>]
+>;
+
+const rpc = constMap(rpcConfig);
+export const rpcAddress = (network: Network, chain: ChainName) =>
+  network === "Devnet" ? undefined : rpc.get(network, chain);

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./constants";
+export * from "./utils";

package/src/utils/array.ts

@@ -0,0 +1,102 @@
+import { ParseNumber, RoArray, RoArray2D } from "./metaprogramming";
+
+
+//TODO the intent here is that number represents a number literal, but strictly speaking
+//  the type allows for unions of number literals (and an array of such unions)
+export type IndexEs = number | RoArray<number>;
+
+export const range = (length: number) => [...Array(length).keys()];
+
+export type Entries<T extends RoArray> =
+  readonly [...{ [K in keyof T]: K extends `${number}` ? [T[K], ParseNumber<K>] : never }];
+
+export type Flatten<T extends RoArray> =
+  T extends readonly [infer Head, ...infer Tail]
+  ? Head extends RoArray
+    ? [...Head, ...Flatten<Tail>]
+    : [Head, ...Flatten<Tail>]
+  : [];
+
+export type InnerFlatten<T extends RoArray> =
+  [...{ [K in keyof T]:
+    K extends `${number}`
+    ? T[K] extends RoArray
+      ? Flatten<T[K]>
+      : T[K]
+    : never
+  }];
+
+export type IsFlat<T extends RoArray> =
+  T extends readonly [infer Head, ...infer Tail]
+  ? Head extends RoArray
+    ? false
+    : IsFlat<Tail>
+  : true;
+
+export type Unflatten<T extends RoArray> =
+  [...{ [K in keyof T]: K extends `${number}` ? readonly [T[K]] : never }];
+
+export type AllSameLength<T extends RoArray2D, L extends number> =
+  T extends readonly [infer Head extends RoArray, ...infer Tail extends RoArray2D]
+  ? Head["length"] extends L
+    ? AllSameLength<Tail, L>
+    : false
+  : true;
+
+export type IsRectangular<T extends RoArray> =
+  T extends RoArray2D
+  ? T extends readonly [infer Head extends RoArray, ...infer Tail extends RoArray2D]
+    ? AllSameLength<Tail, Head["length"]>
+    : true //empty array is rectangular
+  : IsFlat<T>; //1d array is rectangular
+
+export type Column<A extends RoArray2D, I extends number> =
+  [...{ [K in keyof A]: K extends `${number}` ? A[K][I] : never }];
+
+export const column = <A extends RoArray2D, I extends number>(tupArr: A, index: I) =>
+  tupArr.map((tuple) => tuple[index]) as Column<A, I>;
+
+export type Zip<A extends RoArray2D> =
+  //TODO remove, find max length, and return undefined for elements in shorter arrays
+  IsRectangular<A> extends true
+  ? A[0] extends infer Head extends RoArray
+    ? [...{ [K in keyof Head]:
+        K extends `${number}`
+        ? readonly [...{ [K2 in keyof A]: K extends keyof A[K2] ? A[K2][K] : never }]
+        : never
+      }]
+    : []
+  : never
+
+export const zip = <const Args extends RoArray2D>(arr: Args) =>
+  range(arr[0].length).map(col =>
+    range(arr.length).map(row => arr[row][col])
+  ) as unknown as ([Zip<Args>] extends [never] ? RoArray2D : Zip<Args>);
+
+export type OnlyIndexes<E extends RoArray, I extends IndexEs> =
+  I extends number
+  ? OnlyIndexes<E, [I]>
+  : I extends readonly [infer Head extends number, ...infer Tail extends RoArray<number>]
+  ? E[Head] extends undefined
+    ? OnlyIndexes<E, Tail>
+    : [E[Head], ...OnlyIndexes<E, Tail>]
+  : [];
+
+type ExcludeIndexesImpl<T extends RoArray, C extends number> =
+  T extends readonly [infer Head, ...infer Tail]
+  ? Head extends readonly [infer V, infer I extends number]
+    ? I extends C
+      ? ExcludeIndexesImpl<Tail, C>
+      : [V, ...ExcludeIndexesImpl<Tail, C>]
+    : never
+  : [];
+
+export type ExcludeIndexes<T extends RoArray, C extends IndexEs> =
+  ExcludeIndexesImpl<Entries<T>, C extends RoArray<number> ? ParseNumber<keyof IndexEs> : C>;
+
+export type Cartesian<L, R> =
+  L extends RoArray
+  ? Flatten<[...{ [K in keyof L]: K extends `${number}` ? Cartesian<L[K], R> : never }]>
+  : R extends RoArray
+  ? [...{ [K in keyof R]: K extends `${number}` ? readonly [L, R[K]] : never }]
+  : [L, R];

package/src/utils/hexstring.ts

@@ -0,0 +1,62 @@
+export const stripPrefix = (prefix: string, str: string): string =>
+  str.startsWith(prefix) ? str.slice(prefix.length) : str;
+
+const tryAsciiHexCharToNumber = (str: string, index: number): number => {
+  //we could use parseInt(char, 16) but given that we are doing this for every single char and
+  //  parseInt has to check for optional "0x" prefix and other conversion stuff, let's just be
+  //  explicit and not overly wasteful with performance
+  const charCode = str.charCodeAt(index);
+  switch (charCode) {
+    case 48: case 49: case 50: case 51: case 52: case 53: case 54: case 55: case 56: case 57:
+      return charCode - 48; //ascii 0-9 is 48-57
+    case 65: case 66: case 67: case 68: case 69: case 70:
+      return charCode - 65 + 10; //ascii A-F is 65-70
+    case 97: case 98: case 99: case 100: case 101: case 102:
+      return charCode - 97 + 10; //ascii a-f is 97-102
+    default:
+      return Number.NaN;
+  }
+}
+
+const asciiHexCharToNumber = (str: string, index: number): number => {
+  const val = tryAsciiHexCharToNumber(str, index);
+  if (Number.isNaN(val))
+    throw new Error(
+      `Character ${str.charAt(index)} at position ${index} in ${str} is not a hex char`
+    );
+
+  return val;
+}
+
+export const isHexByteString = (str: string, expectedBytes?: number): boolean => {
+  let i = ((str.length > 1 && str[1] == "x") ? 2 : 0);
+  if ((str.length % 2 !== 0) ||
+      (expectedBytes !== undefined && str.length - i !== 2 * expectedBytes))
+    return false;
+
+  for (; i < str.length; ++i)
+    if (Number.isNaN(tryAsciiHexCharToNumber(str, i)))
+      return false;
+
+  return true;
+}
+
+//TODO naming: arrayify (ethers), toBytes (solana)
+export const hexByteStringToUint8Array = (str: string): Uint8Array => {
+  if (str.length % 2 !== 0)
+    throw new Error(`hex byte string has odd length: ${str}`);
+
+  const prefixOffset = str.length > 2 && str[1] === "x" ? 2 : 0;
+  const ret = new Uint8Array((str.length - prefixOffset) / 2);
+  for (let i = prefixOffset; i < str.length; i += 2)
+    ret[(i - prefixOffset) / 2] =
+      asciiHexCharToNumber(str, i) * 16 +
+      asciiHexCharToNumber(str, i + 1);
+
+  return ret;
+}
+
+//TODO naming: hexlify (ethers)
+export const uint8ArrayToHexByteString = (arr: Uint8Array, addPrefix = true): string =>
+  (addPrefix ? "0x" : "") +
+  Array.from(arr).map(byte => byte.toString(16).padStart(2, "0")).join("");

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from "./array";
+export * from "./hexstring";
+export * from "./layout";
+export * from "./mapping";
+export * from "./metaprogramming";

package/src/utils/layout/deserialize.ts

@@ -0,0 +1,177 @@
+import {
+  Layout,
+  LayoutItem,
+  LayoutToType,
+  LayoutItemToType,
+  FixedPrimitiveBytesLayoutItem,
+  FixedValueBytesLayoutItem,
+  CustomConversion,
+  UintSizeToPrimitive,
+  numberMaxSize,
+} from "./layout";
+
+import { checkUint8ArrayDeeplyEqual, checkUintEquals } from "./utils";
+
+export function deserializeLayout<const L extends Layout>(
+  layout: L,
+  encoded: Uint8Array,
+  offset?: number,
+  consumeAll?: true,
+): LayoutToType<L>;
+
+export function deserializeLayout<const L extends Layout>(
+  layout: L,
+  encoded: Uint8Array,
+  offset?: number,
+  consumeAll?: false,
+): readonly [LayoutToType<L>, number];
+
+export function deserializeLayout<const L extends Layout>(
+  layout: L,
+  encoded: Uint8Array,
+  offset = 0,
+  consumeAll = true,
+): LayoutToType<L> | readonly [LayoutToType<L>, number] {
+  const [decoded, finalOffset] = internalDeserializeLayout(layout, encoded, offset);
+
+  if (consumeAll && finalOffset !== encoded.length)
+    throw new Error(`encoded data is longer than expected: ${encoded.length} > ${finalOffset}`);
+
+  return consumeAll ? decoded as LayoutToType<L> : [decoded as LayoutToType<L>, finalOffset];
+}
+
+function internalDeserializeLayout(
+  layout: Layout,
+  encoded: Uint8Array,
+  offset: number,
+): [any, number] {
+  let decoded = {} as any;
+  for (const item of layout)
+    [((item as any).omit ? {} : decoded)[item.name], offset] =
+      deserializeLayoutItem(item, encoded, offset);
+
+  return [decoded, offset];
+}
+
+function updateOffset (
+  encoded: Uint8Array,
+  offset: number,
+  size: number
+): number {
+  const newOffset = offset + size;
+  if (newOffset > encoded.length)
+    throw new Error(`encoded data is shorter than expected: ${encoded.length} < ${newOffset}`);
+
+  return newOffset;
+}
+
+function deserializeUint<S extends number>(
+  encoded: Uint8Array,
+  offset: number,
+  size: S,
+): readonly [UintSizeToPrimitive<S>, number] {
+  let value = 0n;
+  for (let i = 0; i < size; ++i)
+    value += BigInt(encoded[offset + i]) << BigInt((size - 1 - i) * 8);
+
+  return [
+    ((size > numberMaxSize) ? value : Number(value)) as UintSizeToPrimitive<S>,
+    updateOffset(encoded, offset, size)
+  ] as const;
+}
+
+function deserializeLayoutItem(
+  item: LayoutItem,
+  encoded: Uint8Array,
+  offset: number,
+): readonly [any, number] {
+  try {
+    switch (item.binary) {
+      case "object": {
+        return internalDeserializeLayout(item.layout, encoded, offset);
+      }
+      case "array": {
+        let ret = [] as LayoutToType<typeof item.layout>[];
+        if (item.lengthSize !== undefined) {
+          const [length, newOffset] = deserializeUint(encoded, offset, item.lengthSize);
+          offset = newOffset;
+          for (let i = 0; i < length; ++i)
+            [ret[i], offset] = internalDeserializeLayout(item.layout, encoded, offset);
+        }
+        else {
+          while (offset < encoded.length)
+            [ret[ret.length], offset] = internalDeserializeLayout(item.layout, encoded, offset);
+        }
+        return [ret, offset];
+      }
+      case "bytes": {
+        let newOffset;
+        let fixedFrom;
+        let fixedTo;
+        if (item.custom !== undefined) {
+          if (item.custom instanceof Uint8Array)
+            fixedFrom = item.custom;
+          else if (item.custom.from instanceof Uint8Array) {
+            fixedFrom = item.custom.from;
+            fixedTo = item.custom.to;
+          }
+        }
+
+        if (fixedFrom !== undefined)
+          newOffset = updateOffset(encoded, offset, fixedFrom.length);
+        else {
+          item = item as
+            Exclude<typeof item, FixedPrimitiveBytesLayoutItem | FixedValueBytesLayoutItem>;
+          if ("size" in item && item.size !== undefined)
+            newOffset = updateOffset(encoded, offset, item.size);
+          else if (item.lengthSize !== undefined) {
+            let length;
+            [length, offset] = deserializeUint(encoded, offset, item.lengthSize);
+            newOffset = updateOffset(encoded, offset, length);
+          }
+          else
+            newOffset = encoded.length;
+        }
+
+        const value = encoded.slice(offset, newOffset);
+        if (fixedFrom !== undefined) {
+          checkUint8ArrayDeeplyEqual(fixedFrom, value);
+          return [fixedTo ?? fixedFrom, newOffset];
+        }
+
+        type narrowedCustom = CustomConversion<Uint8Array, any>;
+        return [
+          item.custom !== undefined ? (item.custom as narrowedCustom).to(value) : value,
+          newOffset
+        ];
+      }
+      case "uint": {
+        const [value, newOffset] = deserializeUint(encoded, offset, item.size);
+
+        if (item.custom !== undefined) {
+          if (typeof item.custom === "number" || typeof item.custom === "bigint") {
+            checkUintEquals(item.custom, value);
+            return [item.custom, newOffset];
+          }
+          else if (typeof item.custom.from === "number" || typeof item.custom.from === "bigint") {
+            checkUintEquals(item.custom.from, value);
+            return [item.custom.to, newOffset];
+          }
+        }
+
+        //narrowing to CustomConver<number | bigint, any> is a bit hacky here, since the true type
+        //  would be CustomConver<number, any> | CustomConver<bigint, any>, but then we'd have to
+        //  further tease that apart still for no real gain...
+        type narrowedCustom = CustomConversion<number | bigint, any>;
+        return [
+          item.custom !== undefined ? (item.custom as narrowedCustom).to(value) : value,
+          newOffset
+        ];
+      }
+    }
+  }
+  catch (e) {
+    (e as Error).message = `when deserializing item '${item.name}': ${(e as Error).message}`;
+    throw e;
+  }
+}