@wormhole-foundation/sdk-definitions 0.1.6-beta.2 → 0.1.7-beta.1

package/src/platform.ts

@@ -9,30 +9,35 @@ import { RpcConnection } from "./rpc";
 import { AnyAddress, Balances, ChainsConfig, SignedTx, TokenId, TxHash } from "./types";
 
 export interface PlatformUtils<P extends PlatformName> {
+  // Get the native (gas) token id for a given chain
   nativeTokenId(chain: ChainName): TokenId;
+  isNativeTokenId(chain: ChainName, tokenId: TokenId): boolean;
 
+  // Check if this chain is supported by this platform
   isSupportedChain(chain: ChainName): boolean;
 
-  isNativeTokenId(chain: ChainName, tokenId: TokenId): boolean;
-
-  // Utils for platform specific queries
+  // Get the number of decimals for a given token
   getDecimals(
     chain: ChainName,
     rpc: RpcConnection<P>,
     token: AnyAddress,
   ): Promise<bigint>;
+  // Get the balance of a token for a given wallet address
   getBalance(
     chain: ChainName,
     rpc: RpcConnection<P>,
     walletAddr: string,
     token: AnyAddress,
   ): Promise<bigint | null>;
+  // Look up the balances for a list of tokens for a given wallet address
+  // TODO: this should be batched but isn't currently
   getBalances(
     chain: ChainName,
     rpc: RpcConnection<P>,
     walletAddress: string,
     tokens: AnyAddress[],
   ): Promise<Balances>;
+  // Look up the latest block 
   getCurrentBlock(rpc: RpcConnection<P>): Promise<number>;
 
   // Platform interaction utils
@@ -42,6 +47,13 @@ export interface PlatformUtils<P extends PlatformName> {
     stxns: SignedTx[],
   ): Promise<TxHash[]>;
 
+  // Look up a Chain from its native chain ID
+  // See implementation for details
+  // Note: this is _not_ the same as the Wormhole chain id
+  chainFromChainId(chainId: string): [Network, ChainName];
+
+  // Given an RPC connection, request the native chain id
+  // then resolve it to a Wormhole Canonical network and chain name
   chainFromRpc(rpc: RpcConnection<P>): Promise<[Network, ChainName]>;
 }
 
@@ -57,8 +69,10 @@ export interface Platform<P extends PlatformName> extends PlatformUtils<P> {
   // Create a new Chain context object
   getChain(chain: ChainName): ChainContext<P>;
 
+  // Create a _new_ RPC Connection
   getRpc(chain: ChainName): RpcConnection<P>;
 
+  // Look up transaction logs and parse out Wormhole messages
   parseTransaction(
     chain: ChainName,
     rpc: RpcConnection<P>,

package/src/protocols/cctp.ts

@@ -3,7 +3,7 @@ import {
   LayoutToType,
   PlatformName,
   deserializeLayout,
-  uint8ArrayToHexByteString,
+  encoding,
 } from "@wormhole-foundation/sdk-base";
 import { ChainAddress } from "../address";
 import { CircleMessageId } from "../attestation";
@@ -40,7 +40,7 @@ export const deserializeCircleMessage = (
   data: Uint8Array,
 ): [LayoutToType<typeof circleMessageLayout>, string] => {
   const msg = deserializeLayout(circleMessageLayout, data);
-  const messsageHash = uint8ArrayToHexByteString(keccak256(data));
+  const messsageHash = encoding.hex.encode(keccak256(data));
   return [msg, messsageHash];
 };
 

package/src/protocols/ibc.ts

@@ -3,6 +3,7 @@ import {
   ChainName,
   PlatformName,
   toChainId,
+  encoding,
 } from "@wormhole-foundation/sdk-base";
 import { ChainAddress, NativeAddress } from "../address";
 import { IbcMessageId, WormholeMessageId } from "../attestation";
@@ -48,8 +49,8 @@ export interface GatewayTransferWithPayloadMsg {
 // to be decoded and executed by the Gateway contract.
 export interface GatewayIbcTransferMsg {
   gateway_ibc_token_bridge_payload:
-    | GatewayTransferMsg
-    | GatewayTransferWithPayloadMsg;
+  | GatewayTransferMsg
+  | GatewayTransferWithPayloadMsg;
 }
 
 export function isGatewayTransferMsg(
@@ -112,7 +113,7 @@ export function gatewayTransferMsg(
   if (isGatewayTransferDetails(gtd)) {
     // If we've already got a payload, b64 encode it so it works in json
     const _payload = gtd.payload
-      ? Buffer.from(gtd.payload).toString("base64")
+      ? encoding.b64.encode(gtd.payload)
       : undefined;
 
     // Encode the payload so the gateway contract knows where to forward the
@@ -150,7 +151,7 @@ export function makeGatewayTransferMsg(
     typeof recipient === "string"
       ? recipient
       : //@ts-ignore
-        Buffer.from(recipient.toString()).toString("base64");
+      encoding.b64.encode(recipient.toString());
 
   const common = {
     chain: toChainId(chain),
@@ -161,8 +162,8 @@ export function makeGatewayTransferMsg(
 
   const msg: GatewayTransferWithPayloadMsg | GatewayTransferMsg = payload
     ? ({
-        gateway_transfer_with_payload: { ...common, payload: payload },
-      } as GatewayTransferWithPayloadMsg)
+      gateway_transfer_with_payload: { ...common, payload: payload },
+    } as GatewayTransferWithPayloadMsg)
     : ({ gateway_transfer: { ...common } } as GatewayTransferMsg);
 
   return msg;

package/src/protocols/tokenBridge.ts

@@ -52,26 +52,28 @@ export interface TokenBridge<P extends PlatformName> {
   getOriginalAsset(nativeAddress: AnyAddress): Promise<TokenId>;
   // returns the wrapped version of the native asset
   getWrappedNative(): Promise<NativeAddress<P>>;
-
   // Check to see if a foreign token has a wrapped version
   hasWrappedAsset(foreignToken: TokenId): Promise<boolean>;
   // Returns the address of the native version of this asset
   getWrappedAsset(foreignToken: TokenId): Promise<NativeAddress<P>>;
-
-  // TODO: preview (receive amount, fees, gas estimates, estimated blocks/time)
+  // Checks if a transfer VAA has been redeemed
   isTransferCompleted(
     vaa: TokenBridge.VAA<"Transfer" | "TransferWithPayload">
   ): Promise<boolean>;
-  //signer required:
+  // Create a Token Attestation VAA containing metadata about
+  // the token that may be submitted to a Token bridge on another chain 
+  // to allow it to create a wrapped version of the token
   createAttestation(
     token_to_attest: AnyAddress,
     payer?: AnyAddress
   ): AsyncGenerator<UnsignedTransaction>;
+  // Submit the Token Attestation VAA to the Token bridge
+  // to create the wrapped token represented by the data in the VAA
   submitAttestation(
     vaa: TokenBridge.VAA<"AttestMeta">,
     payer?: AnyAddress
   ): AsyncGenerator<UnsignedTransaction>;
-  //alternative naming: initiateTransfer
+  // Initiate a transfer of some token to another chain
   transfer(
     sender: AnyAddress,
     recipient: ChainAddress,
@@ -79,13 +81,14 @@ export interface TokenBridge<P extends PlatformName> {
     amount: bigint,
     payload?: Uint8Array
   ): AsyncGenerator<UnsignedTransaction>;
-  //alternative naming: completeTransfer
+  // Redeem a transfer VAA to receive the tokens on this chain
   redeem(
     sender: AnyAddress,
     vaa: TokenBridge.VAA<"Transfer" | "TransferWithPayload">,
     unwrapNative?: boolean //default: true
   ): AsyncGenerator<UnsignedTransaction>;
-  // TODO: parse transaction
+
+  // TODO: preview (receive amount, fees, gas estimates, estimated blocks/time)
 }
 
 export interface AutomaticTokenBridge<P extends PlatformName> {

package/src/relayer.ts

@@ -33,18 +33,4 @@ export interface Relayer<P extends PlatformName> {
     tokenId: AnyAddress,
     walletAddress: string,
   ): Promise<bigint>;
-}
-
-//function parseRelayerPayload(transferPayload: Buffer): ParsedRelayerPayload {
-//  return {
-//    relayerPayloadId: transferPayload.readUint8(0),
-//    relayerFee: BigNumber.from(
-//      "0x" + transferPayload.subarray(1, 33).toString("hex")
-//    ),
-//    toNativeTokenAmount: BigNumber.from(
-//      "0x" + transferPayload.subarray(33, 65).toString("hex")
-//    ),
-//    to: "0x" + transferPayload.subarray(65, 98).toString("hex"),
-//  };
-//}
-//
+}

package/src/signer.ts

@@ -0,0 +1,49 @@
+import { ChainName } from "@wormhole-foundation/sdk-base";
+import { UnsignedTransaction } from "./unsignedTransaction";
+import { SignedTx, TxHash } from "./types";
+
+// A Signer is an interface that must be provided to certain methods
+// in the SDK to sign transactions. It can be either a SignOnlySigner
+// or a SignAndSendSigner depending on circumstances. 
+// A Signer can be implemented by wrapping an existing offline wallet
+// or a web wallet 
+export type Signer = SignOnlySigner | SignAndSendSigner;
+
+export function isSigner(thing: Signer | any): thing is Signer {
+    return isSignOnlySigner(thing) || isSignAndSendSigner(thing)
+}
+
+// A SignOnlySender is for situations where the signer is not
+// connected to the network or does not wish to broadcast the
+// transactions themselves 
+export interface SignOnlySigner {
+    chain(): ChainName;
+    address(): string;
+    sign(tx: UnsignedTransaction[]): Promise<SignedTx[]>;
+}
+export function isSignOnlySigner(thing: SignOnlySigner | any): thing is SignOnlySigner {
+    return (
+        typeof (<SignOnlySigner>thing).chain === "function" &&
+        typeof (<SignOnlySigner>thing).address == "function" &&
+        typeof (<SignOnlySigner>thing).sign === "function"
+    );
+}
+
+// A SignAndSendSigner is for situations where the signer is
+// connected to the network and wishes to broadcast the
+// transactions themselves 
+export interface SignAndSendSigner {
+    chain(): ChainName;
+    address(): string;
+    signAndSend(tx: UnsignedTransaction[]): Promise<TxHash[]>;
+}
+
+export function isSignAndSendSigner(thing: SignAndSendSigner | any): thing is SignAndSendSigner {
+    return (
+        typeof (<SignAndSendSigner>thing).chain === "function" &&
+        typeof (<SignAndSendSigner>thing).address == "function" &&
+        typeof (<SignAndSendSigner>thing).signAndSend === "function"
+    );
+}
+
+

package/src/testing/mocks/platform.ts

@@ -143,6 +143,9 @@ export class MockPlatform<P extends PlatformName> implements Platform<P> {
     throw new Error("Method not implemented");
   }
 
+  chainFromChainId(chainId: string): [Network, ChainName] {
+    throw new Error("Not implemented");
+  }
   async chainFromRpc(rpc: RpcConnection<P>): Promise<[Network, ChainName]> {
     throw new Error("Not implemented");
   }

package/src/testing/utils/address.ts

@@ -3,6 +3,7 @@ import {
   ChainName,
   PlatformName,
   chainToPlatform,
+  encoding,
   isPlatform,
   platformToChains,
 } from "@wormhole-foundation/sdk-base";
@@ -14,22 +15,22 @@ import {
 } from "../../";
 
 // return a random buffer of length n
-function randomBuffer(n: number): Buffer {
+function randomBytes(n: number): Uint8Array {
   const buff = new Uint8Array(n);
   crypto.getRandomValues(buff);
-  return Buffer.from(buff);
+  return buff;
 }
 
 // get a random 20 byte address
 function fake20ByteAddress(): string {
-  const buff = randomBuffer(20);
-  return buff.toString("hex");
+  const buff = randomBytes(20);
+  return encoding.hex.encode(buff);
 }
 
 // get a random 32 byte address
 function fake32ByteAddress(): string {
-  const buff = randomBuffer(32);
-  return buff.toString("hex");
+  const buff = randomBytes(32);
+  return encoding.hex.encode(buff);
 }
 
 // make a random native address for a given chain

package/src/types.ts

@@ -7,6 +7,8 @@ import {
 } from "@wormhole-foundation/sdk-base";
 import { ChainAddress, NativeAddress, toNative } from "./address";
 import { Contracts } from "./contracts";
+import { Signer, isSigner } from './signer'
+
 import { UnsignedTransaction } from "./unsignedTransaction";
 import { UniversalAddress } from "./universalAddress";
 
@@ -35,39 +37,6 @@ export type Balances = {
   [key: string]: BigInt | null;
 };
 
-export interface SignOnlySigner {
-  chain(): ChainName;
-  address(): string;
-  sign(tx: UnsignedTransaction[]): Promise<SignedTx[]>;
-}
-export function isSignOnlySigner(thing: SignOnlySigner | any): thing is SignOnlySigner {
-  return (
-    typeof (<SignOnlySigner>thing).chain === "function" &&
-    typeof (<SignOnlySigner>thing).address == "function" &&
-    typeof (<SignOnlySigner>thing).sign === "function"
-  );
-}
-
-export interface SignAndSendSigner {
-  chain(): ChainName;
-  address(): string;
-  signAndSend(tx: UnsignedTransaction[]): Promise<TxHash[]>;
-}
-
-export function isSignAndSendSigner(thing: SignAndSendSigner | any): thing is SignAndSendSigner {
-  return (
-    typeof (<SignAndSendSigner>thing).chain === "function" &&
-    typeof (<SignAndSendSigner>thing).address == "function" &&
-    typeof (<SignAndSendSigner>thing).signAndSend === "function"
-  );
-}
-
-export type Signer = SignOnlySigner | SignAndSendSigner;
-
-export function isSigner(thing: Signer | any): thing is Signer {
-  return isSignOnlySigner(thing) || isSignAndSendSigner(thing)
-}
-
 
 export function nativeChainAddress(
   s: Signer | TokenId | [ChainName, UniversalAddress | Uint8Array | string],

package/src/universalAddress.ts

@@ -1,8 +1,4 @@
-import {
-  hexByteStringToUint8Array,
-  uint8ArrayToHexByteString,
-  isHexByteString,
-} from "@wormhole-foundation/sdk-base";
+import { encoding } from "@wormhole-foundation/sdk-base";
 
 import { Address, NativeAddress, toNative } from "./address";
 
@@ -17,10 +13,10 @@ export class UniversalAddress implements Address {
       if (!UniversalAddress.isValidAddress(address))
         throw new Error(
           `Invalid Wormhole address, expected ${UniversalAddress.byteSize}-byte ` +
-            `hex string but got ${address}`,
+          `hex string but got ${address}`,
         );
 
-      this.address = hexByteStringToUint8Array(address);
+      this.address = encoding.hex.decode(address);
     } else {
       this.address = address;
     }
@@ -36,7 +32,7 @@ export class UniversalAddress implements Address {
     return this.address;
   }
   toString() {
-    return uint8ArrayToHexByteString(this.address);
+    return encoding.hex.encode(this.address, true);
   }
   toUint8Array() {
     return this.address;
@@ -53,7 +49,7 @@ export class UniversalAddress implements Address {
   }
 
   static isValidAddress(address: string) {
-    return isHexByteString(address, UniversalAddress.byteSize);
+    return encoding.hex.valid(address) && encoding.stripPrefix("0x", address).length === UniversalAddress.byteSize * 2;
   }
 
   static instanceof(address: any) {

package/src/vaa.ts

@@ -1,5 +1,5 @@
 import {
-  hexByteStringToUint8Array,
+  encoding,
   Layout,
   LayoutItem,
   LayoutToType,
@@ -29,7 +29,7 @@ import { keccak256 } from "./utils";
 declare global {
   namespace Wormhole {
     //effective type: Record<string, Layout>
-    interface PayloadLiteralToLayoutMapping {}
+    interface PayloadLiteralToLayoutMapping { }
   }
 }
 
@@ -37,8 +37,8 @@ export type LayoutLiteral = keyof Wormhole.PayloadLiteralToLayoutMapping & strin
 type LayoutOf<LL extends LayoutLiteral> =
   //TODO check if this lazy instantiation hack is actually necessary
   LL extends infer V extends LayoutLiteral
-    ? Wormhole.PayloadLiteralToLayoutMapping[V]
-    : never;
+  ? Wormhole.PayloadLiteralToLayoutMapping[V]
+  : never;
 
 type LayoutLiteralToPayloadType<LL extends LayoutLiteral> = LayoutToType<LayoutOf<LL>>;
 
@@ -134,7 +134,7 @@ export type DistributiveVAA<PL extends PayloadLiteral> =
   ? VAA<PL>
   : never;
 
-export type ProtocolVAA<PN extends ProtocolName, PayloadName extends string> = 
+export type ProtocolVAA<PN extends ProtocolName, PayloadName extends string> =
   ComposeLiteral<PN, PayloadName, PayloadLiteral> extends infer PL extends PayloadLiteral
   ? DistributiveVAA<PL>
   : never;
@@ -154,10 +154,10 @@ const payloadLiteralToPayloadItem = <PL extends PayloadLiteral>(
   (payloadLiteral === "Uint8Array"
     ? ({ name: "payload", binary: "bytes" } as const)
     : ({
-        name: "payload",
-        binary: "object",
-        layout: getPayloadLayout(payloadLiteral),
-      } as const)) satisfies LayoutItem;
+      name: "payload",
+      binary: "object",
+      layout: getPayloadLayout(payloadLiteral),
+    } as const)) satisfies LayoutItem;
 
 //annoyingly we can't use the return value of payloadLiteralToPayloadItem
 type PayloadLiteralToDynamicItems<PL extends PayloadLiteral> =
@@ -165,12 +165,12 @@ type PayloadLiteralToDynamicItems<PL extends PayloadLiteral> =
     [
       ...typeof baseLayout,
       PL extends LayoutLiteral
-        ? {
-            name: "payload";
-            binary: "object";
-            layout: DynamicItemsOfLayout<LayoutOf<PL>>;
-          }
-        : { name: "payload"; binary: "bytes" },
+      ? {
+        name: "payload";
+        binary: "object";
+        layout: DynamicItemsOfLayout<LayoutOf<PL>>;
+      }
+      : { name: "payload"; binary: "bytes" },
     ]
   >;
 
@@ -214,7 +214,7 @@ type AtLeast2<T> = readonly [T, T, ...T[]];
 
 export type NamedPayloads = AtLeast1<readonly [string, Layout]>;
 export type RegisterPayloadTypes<ProtocolN extends ProtocolName, NP extends NamedPayloads> =
-  { readonly [E in NP[number] as ToLiteralFormat<ProtocolN, E[0]>]: E[1] };
+  { readonly [E in NP[number]as ToLiteralFormat<ProtocolN, E[0]>]: E[1] };
 
 export function registerPayloadTypes(protocol: ProtocolName, payloads: NamedPayloads) {
   for (const [name, layout] of payloads)
@@ -262,7 +262,7 @@ type PayloadGroupsToLayoutLiterals<PGA extends readonly PayloadGroup[]> =
   : never;
 
 type LLDtoLLs<LLD extends AtLeast2<LayoutLiteral> | readonly [ProtocolName, AtLeast2<string>]
-| AtLeast2<PayloadGroup>> =
+  | AtLeast2<PayloadGroup>> =
   LLD extends AtLeast2<LayoutLiteral>
   ? LLD[number]
   : LLD extends readonly [ProtocolName, AtLeast2<string>]
@@ -273,7 +273,7 @@ type LLDtoLLs<LLD extends AtLeast2<LayoutLiteral> | readonly [ProtocolName, AtLe
 
 export function payloadDiscriminator<
   const LLD extends AtLeast2<LayoutLiteral> | readonly [ProtocolName, AtLeast2<string>]
-    | AtLeast2<PayloadGroup>,
+  | AtLeast2<PayloadGroup>,
   B extends boolean = false
 >(
   payloadLiterals: LLD,
@@ -284,15 +284,15 @@ export function payloadDiscriminator<
       return (payloadLiterals as AtLeast2<PayloadGroup>).flatMap(([protocol, payloadNames]) =>
         payloadNames.map((name) => composeLiteral(protocol, name))
       );
-    
+
     if (typeof payloadLiterals[1] === "string")
       return payloadLiterals as AtLeast2<LayoutLiteral>;
-    
+
     const [protocol, payloadNames] =
       payloadLiterals as readonly [ProtocolName, AtLeast2<LayoutLiteral>];
     return payloadNames.map((name) => composeLiteral(protocol, name));
   })();
-  
+
   const discriminator = layoutDiscriminator(
     literals.map(literal => getPayloadLayout(literal)),
     !!allowAmbiguous
@@ -300,7 +300,7 @@ export function payloadDiscriminator<
 
   return ((data: Byteish) => {
     if (typeof data === "string")
-      data = hexByteStringToUint8Array(data);
+      data = encoding.hex.decode(data);
 
     const cands = discriminator(data);
     return (Array.isArray(cands))
@@ -315,7 +315,7 @@ export function deserialize<T extends PayloadLiteral | PayloadDiscriminator>(
   payloadDet: T,
   data: Byteish,
 ): DistributiveVAA<ExtractLiteral<T>> {
-  if (typeof data === "string") data = hexByteStringToUint8Array(data);
+  if (typeof data === "string") data = encoding.hex.decode(data);
 
   const [header, envelopeOffset] =
     deserializeLayout(headerLayout, data, 0, false);
@@ -339,7 +339,7 @@ export function deserialize<T extends PayloadLiteral | PayloadDiscriminator>(
   );
 
   const [payloadLiteral, payload] =
-      typeof payloadDet === "string"
+    typeof payloadDet === "string"
       ? [
         payloadDet as PayloadLiteral,
         deserializePayload(payloadDet as PayloadLiteral, data, payloadOffset)
@@ -383,7 +383,7 @@ export function deserializePayload<
 ): DeserializePayloadReturn<T> {
   //grouped together to have just a single cast on the return type
   return (() => {
-    if (typeof data === "string") data = hexByteStringToUint8Array(data);
+    if (typeof data === "string") data = encoding.hex.decode(data);
 
     if (payloadDet === "Uint8Array") return data.slice(offset);
 
@@ -397,7 +397,7 @@ export function deserializePayload<
       throw new Error(
         `Encoded data does not match any of the given payload types - ${data}`,
       );
-    
+
     return [
       candidate,
       deserializeLayout(getPayloadLayout(candidate), data, offset),
@@ -420,16 +420,16 @@ export const blindDeserializePayload = (() => {
       [layoutLiterals, discriminator] = rebuildDiscrimininator();
 
     if (typeof data === "string")
-      data = hexByteStringToUint8Array(data);
+      data = encoding.hex.decode(data);
 
     const candidates = discriminator(data).map((c) => layoutLiterals[c]);
     return candidates.reduce((acc, literal) => {
-        try {
-          acc.push([literal, deserializePayload(literal, data)] as DeserializedPair);
-        }
-        catch {}
-        return acc;
-      },
+      try {
+        acc.push([literal, deserializePayload(literal, data)] as DeserializedPair);
+      }
+      catch { }
+      return acc;
+    },
       [] as DeserializedPair[]
     );
   }