Example updater script (#388)

Author: barnjamin

README.md

@@ -14,15 +14,15 @@
 //
 // import { ETH_PRIVATE_KEY, SOLANA_PRIVATE_KEY, TERRA_PRIVATE_KEY } from "./consts";
 //
-// export interface TransferStuff {
+// export interface SignerStuff {
 //   chain: ChainContext<Platform>;
 //   signer: Signer;
 //   address: ChainAddress;
 // }
 //
-// export async function getStuff(
+// export async function getSigner(
 //   chain: ChainContext<Platform>,
-// ): Promise<TransferStuff> {
+// ): Promise<SignerStuff> {
 //   let signer: Signer;
 //   switch (chain.platform.platform) {
 //     case "Solana":

__tests__/tilt/helpers/helpers.ts

@@ -20,7 +20,7 @@
 //
 // import { expect, jest, describe, test } from '@jest/globals';
 //
-// import { TEST_ERC20, TEST_SOLANA_TOKEN, getStuff } from './helpers';
+// import { TEST_ERC20, TEST_SOLANA_TOKEN, getSigner } from './helpers';
 //
 //
 // jest.setTimeout(10 * 60 * 1000)
@@ -60,11 +60,11 @@
 //         let dstBalanceToken: NativeAddress<Platform>;
 //
 //         beforeAll(async () => {
-//             const srcStuff = await getStuff(src);
+//             const srcStuff = await getSigner(src);
 //             srcSigner = srcStuff.signer
 //             srcAcct = srcStuff.address
 //
-//             const dstStuff = await getStuff(dst)
+//             const dstStuff = await getSigner(dst)
 //             dstSigner = dstStuff.signer
 //             dstAcct = dstStuff.address
 //

__tests__/tilt/tokenbridge.test.ts

@@ -9,7 +9,7 @@ import {
 } from "@wormhole-foundation/sdk";
 import { evm } from "@wormhole-foundation/sdk/evm";
 import { solana } from "@wormhole-foundation/sdk/solana";
-import { TransferStuff, getStuff, waitForRelay } from "./helpers";
+import { SignerStuff, getSigner, waitForRelay } from "./helpers";
 
 /*
 Notes:
@@ -29,8 +29,8 @@ AutoRelayer takes a 0.1usdc fee when xfering to any chain beside goerli, which i
 
   // Get signer from local key but anything that implements
   // Signer interface (e.g. wrapper around web wallet) should work
-  const source = await getStuff(sendChain);
-  const destination = await getStuff(rcvChain);
+  const source = await getSigner(sendChain);
+  const destination = await getSigner(rcvChain);
 
   // 6 decimals for USDC (except for bsc, so check decimals before using this)
   const amt = amount.units(amount.parse("0.2", 6));
@@ -66,20 +66,27 @@ AutoRelayer takes a 0.1usdc fee when xfering to any chain beside goerli, which i
 
 async function cctpTransfer<N extends Network>(
   wh: Wormhole<N>,
-  src: TransferStuff<N, Chain>,
-  dst: TransferStuff<N, Chain>,
+  src: SignerStuff<N, Chain>,
+  dst: SignerStuff<N, Chain>,
   req: {
     amount: bigint;
     automatic: boolean;
     nativeGas?: bigint;
   },
 ) {
+  // EXAMPLE_CCTP_TRANSFER
   const xfer = await wh.circleTransfer(
+    // amount as bigint (base units)
     req.amount,
+    // sender chain/address
     src.address,
+    // receiver chain/address
     dst.address,
+    // automatic delivery boolean
     req.automatic,
+    // payload to be sent with the transfer
     undefined,
+    // If automatic, native gas can be requested to be sent to the receiver
     req.nativeGas,
   );
   console.log(xfer);
@@ -101,20 +108,24 @@ async function cctpTransfer<N extends Network>(
     return;
   }
 
+  // Note: Depending on chain finality, this timeout may need to be increased.
+  // See https://developers.circle.com/stablecoin/docs/cctp-technical-reference#mainnet for more
   console.log("Waiting for Attestation");
-  const attestIds = await xfer.fetchAttestation();
+  const attestIds = await xfer.fetchAttestation(60_000);
   console.log(`Got Attestation: `, attestIds);
 
   console.log("Completing Transfer");
   const dstTxids = await xfer.completeTransfer(dst.signer);
   console.log(`Completed Transfer: `, dstTxids);
+  // EXAMPLE_CCTP_TRANSFER
 }
 
 export async function completeTransfer(
   wh: Wormhole<Network>,
   txid: TransactionId,
   signer: Signer,
 ): Promise<void> {
+  // EXAMPLE_RECOVER_TRANSFER
   // Rebuild the transfer from the source txid
   const xfer = await CircleTransfer.from(wh, txid);
 
@@ -123,4 +134,5 @@ export async function completeTransfer(
 
   const dstTxIds = await xfer.completeTransfer(signer);
   console.log("Completed transfer: ", dstTxIds);
+  // EXAMPLE_RECOVER_TRANSFER
 }

examples/src/cctp.ts

@@ -2,6 +2,7 @@ import { Wormhole } from "@wormhole-foundation/sdk";
 import { solana } from "@wormhole-foundation/sdk/solana";
 
 (async function () {
+  // EXAMPLE_CONFIG_OVERRIDE
   // Pass a partial WormholeConfig object to override specific
   // fields in the default config
   const wh = new Wormhole("Testnet", [solana.Platform], {
@@ -14,6 +15,7 @@ import { solana } from "@wormhole-foundation/sdk/solana";
       },
     },
   });
+  // EXAMPLE_CONFIG_OVERRIDE
 
   console.log(wh.config.chains.Solana);
 })();

examples/src/config.ts

@@ -13,7 +13,7 @@ import { cosmwasm } from "@wormhole-foundation/sdk/cosmwasm";
 import { evm } from "@wormhole-foundation/sdk/evm";
 import { solana } from "@wormhole-foundation/sdk/solana";
 
-import { TransferStuff, getStuff } from "./helpers";
+import { SignerStuff, getSigner } from "./helpers";
 
 // We're going to transfer into, around, and out of the Cosmos ecosystem
 // First on Avalanche, transparently through gateway and over IBC to Cosmoshub
@@ -44,9 +44,9 @@ import { TransferStuff, getStuff } from "./helpers";
 
   // Get signer from local key but anything that implements
   // Signer interface (e.g. wrapper around web wallet) should work
-  const leg1 = await getStuff(external);
-  const leg2 = await getStuff(cosmos1);
-  const leg3 = await getStuff(cosmos2);
+  const leg1 = await getSigner(external);
+  const leg2 = await getSigner(cosmos1);
+  const leg3 = await getSigner(cosmos2);
 
   // we'll use the native token on the source chain
   const token: TokenId = Wormhole.tokenId(external.chain, "native");
@@ -112,9 +112,10 @@ async function transferIntoCosmos(
   wh: Wormhole<Network>,
   token: TokenId,
   amount: bigint,
-  src: TransferStuff<Network, Chain>,
-  dst: TransferStuff<Network, Chain>,
+  src: SignerStuff<Network, Chain>,
+  dst: SignerStuff<Network, Chain>,
 ): Promise<GatewayTransfer<Network>> {
+  // EXAMPLE_GATEWAY_INBOUND
   console.log(
     `Beginning transfer into Cosmos from ${src.chain.chain}:${src.address.address.toString()} to ${
       dst.chain.chain
@@ -134,6 +135,7 @@ async function transferIntoCosmos(
 
   const attests = await xfer.fetchAttestation(600_000);
   console.log("Got Attestations", attests);
+  // EXAMPLE_GATEWAY_INBOUND
 
   return xfer;
 }
@@ -142,9 +144,10 @@ async function transferBetweenCosmos<N extends Network>(
   wh: Wormhole<N>,
   token: TokenId,
   amount: bigint,
-  src: TransferStuff<N, Chain>,
-  dst: TransferStuff<N, Chain>,
+  src: SignerStuff<N, Chain>,
+  dst: SignerStuff<N, Chain>,
 ): Promise<GatewayTransfer<N>> {
+  // EXAMPLE_GATEWAY_INTERCOSMOS
   console.log(
     `Beginning transfer within cosmos from ${
       src.chain.chain
@@ -164,6 +167,7 @@ async function transferBetweenCosmos<N extends Network>(
 
   const attests = await xfer.fetchAttestation(60_000);
   console.log("Got attests: ", attests);
+  // EXAMPLE_GATEWAY_INTERCOSMOS
 
   return xfer;
 }
@@ -172,9 +176,10 @@ async function transferOutOfCosmos<N extends Network>(
   wh: Wormhole<N>,
   token: TokenId,
   amount: bigint,
-  src: TransferStuff<N, Chain>,
-  dst: TransferStuff<N, Chain>,
+  src: SignerStuff<N, Chain>,
+  dst: SignerStuff<N, Chain>,
 ): Promise<GatewayTransfer<N>> {
+  // EXAMPLE_GATEWAY_OUTBOUND
   console.log(
     `Beginning transfer out of cosmos from ${
       src.chain.chain
@@ -197,6 +202,7 @@ async function transferOutOfCosmos<N extends Network>(
   // Since we're leaving cosmos, this is required to complete the transfer
   const dstTxIds = await xfer.completeTransfer(dst.signer);
   console.log("Completed transfer on destination chain", dstTxIds);
+  // EXAMPLE_GATEWAY_OUTBOUND
 
   return xfer;
 }

examples/src/cosmos.ts

@@ -5,7 +5,7 @@ import { evm } from "@wormhole-foundation/sdk/evm";
 import { solana } from "@wormhole-foundation/sdk/solana";
 
 import { inspect } from "util";
-import { getStuff } from "./helpers";
+import { getSigner } from "./helpers";
 
 (async function () {
   const wh = new Wormhole("Testnet", [evm.Platform, solana.Platform, algorand.Platform]);
@@ -22,7 +22,7 @@ import { getStuff } from "./helpers";
 
   // grab context and signer
   const origChain = wh.getChain(token.chain);
-  const { signer: origSigner } = await getStuff(origChain);
+  const { signer: origSigner } = await getSigner(origChain);
 
   // Note: if the VAA is not produced before the attempt to retrieve it times out
   // you should set this value to the txid logged in the previous run
@@ -61,7 +61,7 @@ import { getStuff } from "./helpers";
   // destination chain
   const chain = "Algorand";
   const destChain = wh.getChain(chain);
-  const { signer } = await getStuff(destChain);
+  const { signer } = await getSigner(destChain);
 
   // grab a ref to the token bridge
   const tb = await destChain.getTokenBridge();

examples/src/createWrapped.ts

@@ -36,15 +36,15 @@ function getEnv(key: string): string {
   return val;
 }
 
-export interface TransferStuff<N extends Network, C extends Chain> {
+export interface SignerStuff<N extends Network, C extends Chain> {
   chain: ChainContext<N, C>;
   signer: Signer<N, C>;
   address: ChainAddress<C>;
 }
 
-export async function getStuff<N extends Network, C extends Chain>(
+export async function getSigner<N extends Network, C extends Chain>(
   chain: ChainContext<N, C>,
-): Promise<TransferStuff<N, C>> {
+): Promise<SignerStuff<N, C>> {
   let signer: Signer;
   const platform = chain.platform.utils()._platform;
   switch (platform) {

examples/src/helpers/helpers.ts

@@ -1,55 +1,66 @@
-import { CONFIG, Wormhole, amount, api, signSendWait } from "@wormhole-foundation/sdk";
-
+// EXAMPLE_IMPORTS
+import { Wormhole } from "@wormhole-foundation/sdk";
 import { algorand } from "@wormhole-foundation/sdk/algorand";
 import { cosmwasm } from "@wormhole-foundation/sdk/cosmwasm";
 import { evm } from "@wormhole-foundation/sdk/evm";
 import { solana } from "@wormhole-foundation/sdk/solana";
 import { sui } from "@wormhole-foundation/sdk/sui";
+// EXAMPLE_IMPORTS
 
-import { getStuff } from "./helpers";
+import { amount, signSendWait } from "@wormhole-foundation/sdk";
+import { getSigner } from "./helpers";
 
 (async function () {
-  // Setup
-  const wh = new Wormhole("Mainnet", [
+  // EXAMPLE_WORMHOLE_INIT
+  const wh = new Wormhole("Testnet", [
     evm.Platform,
     solana.Platform,
     sui.Platform,
     algorand.Platform,
     cosmwasm.Platform,
   ]);
+  // EXAMPLE_WORMHOLE_INIT
+
+  // EXAMPLE_WORMHOLE_CHAIN
+  // Grab a ChainContext object from our configured Wormhole instance
+  const ctx = wh.getChain("Solana");
+  // EXAMPLE_WORMHOLE_CHAIN
 
-  const snd = wh.getChain("Sui");
   const rcv = wh.getChain("Algorand");
 
-  const sender = await getStuff(snd);
-  const receiver = await getStuff(rcv);
+  const sender = await getSigner(ctx);
+  const receiver = await getSigner(rcv);
 
   // Get a Token Bridge contract client on the source
-  const sndTb = await snd.getTokenBridge();
+  const sndTb = await ctx.getTokenBridge();
 
   // Create a transaction stream for transfers
   const transfer = sndTb.transfer(
     sender.address.address,
     receiver.address,
     "native",
-    amount.units(amount.parse("0.1", snd.config.nativeTokenDecimals)),
+    amount.units(amount.parse("0.1", ctx.config.nativeTokenDecimals)),
   );
 
   // Sign and send the transaction
-  const txids = await signSendWait(snd, transfer, sender.signer);
+  const txids = await signSendWait(ctx, transfer, sender.signer);
   console.log("Sent: ", txids);
 
   // Get the wormhole message id from the transaction
-  const [whm] = await snd.parseTransaction(txids[txids.length - 1]!.txid);
+  const [whm] = await ctx.parseTransaction(txids[txids.length - 1]!.txid);
   console.log("Wormhole Messages: ", whm);
 
+  // EXAMPLE_WORMHOLE_VAA
   // Get the VAA from the wormhole message id
-  const vaa = await api.getVaaWithRetry(
-    CONFIG["Testnet"].api,
+  const vaa = await wh.getVaa(
+    // Wormhole Message ID
     whm!,
+    // Protocol:Payload name to use for decoding the VAA payload
     "TokenBridge:Transfer",
+    // Timeout in milliseconds, depending on the chain and network, the VAA may take some time to be available
     60_000,
   );
+  // EXAMPLE_WORMHOLE_VAA
 
   // Now get the token bridge on the redeem side
   const rcvTb = await rcv.getTokenBridge();