# Module @wormhole-foundation/connect-sdk - v0.3.0

# Connect SDK

The Connect SDK is a TypeScript SDK for interacting with the chains Wormhole supports and the protocols built on top of Wormhole.

## Installation

Install the primary package

    npm install @wormhole-foundation/connect-sdk

As well as any other platforms you wish to use

    npm install @wormhole-foundation/connect-sdk-evm
    npm install @wormhole-foundation/connect-sdk-solana
    npm install @wormhole-foundation/connect-sdk-algorand

And any protocols you intend to use

    npm install @wormhole-foundation/connect-sdk-evm-tokenbridge
    npm install @wormhole-foundation/connect-sdk-solana-tokenbridge
    npm install @wormhole-foundation/connect-sdk-algorand-tokenbridge

## Usage

A developer would use the connect-sdk package in conjunction with one or more of the chain context packages. Most developers don't use every single chain and may only use a couple, which allows developers to import only the dependencies they actually need.

Getting started is simple, just import and pass in the Platform modules you wish to support as an argument to the Wormhole class.

    import { Wormhole, Signer } from "@wormhole-foundation/connect-sdk";
    import { EvmContext } from "@wormhole-foundation/connect-sdk-evm";
    import { SolanaContext } from "@wormhole-foundation/connect-sdk-solana";
    import { AlgorandContext } from "@wormhole-foundation/connect-sdk-algorand";

    // Include the protocols you wish to use
    import "@wormhole-foundation/connect-sdk-evm-tokenbridge";
    import "@wormhole-foundation/connect-sdk-solana-tokenbridge";
    import "@wormhole-foundation/connect-sdk-algorand-tokenbridge";

    const network = "Mainnet"; // Or "Testnet"
    const wh = new Wormhole(network, [EvmPlatform, SolanaPlatform, AlgorandPlatform]);

    // Get a ChainContext object for a specific chain
    // Useful to do things like get the rpc client, make Protocol clients,
    // look up configuration parameters or  even parse addresses
    const srcChain = wh.getChain("Ethereum");

    srcChain.parseAddress("0xdeadbeef..."); // => NativeAddress<'Evm'>
    await srcChain.getTokenBridge(); // => TokenBridge<'Evm'>
    srcChain.getRpcClient(); // => RpcClient<'Evm'>

### Wormhole Transfer

While using the ChainContext and Protocol clients directly is possible, to do things like transfer tokens, the SDK provides some helpful abstractions.

The `WormholeTransfer` interface provides a convenient abstraction to encapsulate the steps involved in a cross-chain transfer.

### Token Transfers

Performing a Token Transfer is trivial for any source and destination chains.

We can create a new `Wormhole` object and use it to to create `TokenTransfer`, `CircleTransfer`, `GatewayTransfer`, etc. objects to transfer tokens between chains. The transfer object is responsible for tracking the transfer through the process and providing updates on its status.

    // We'll send the native gas token on source chain
    const token = "native";

    // Format it for base units
    const amount = normalizeAmount(1, BigInt(srcChain.config.nativeTokenDecimals));

    // Create a TokenTransfer object, allowing us to shepard the transfer through the process and get updates on its status
    const manualXfer = wh.tokenTransfer(
      token, // TokenId of the token to transfer or 'native'
      amount, // Amount in base units
      senderAddress, // Sender address on source chain
      recipientAddress, // Recipient address on destination chain
      false, // No Automatic transfer
    );

    // 1) Submit the transactions to the source chain, passing a signer to sign any txns
    const srcTxids = await manualXfer.initiateTransfer(src.signer);

    // 2) Wait for the VAA to be signed and ready (not required for auto transfer)
    // Note: Depending on chain finality, this timeout may need to be increased.
    // See https://docs.wormhole.com/wormhole/reference/constants#consistency-levels for more info on specific chain finality.
    const timeout = 60_000;
    const attestIds = await manualXfer.fetchAttestation(timeout);

    // 3) Redeem the VAA on the destination chain
    const destTxids = await manualXfer.completeTransfer(dst.signer);

Internally, this uses the TokenBridge protocol client to transfer tokens. The `TokenBridge` protocol, like other Protocols, provides a consistent set of methods across all chains to generate a set of transactions for that specific chain.

See the example here.

### Native USDC Transfers

We can also transfer native USDC using Circle's CCTP

    // OR for an native USDC transfer
    const usdcXfer = wh.cctpTransfer(
      1_000_000n, // amount in base units (1 USDC)
      senderAddress, // Sender address on source chain
      recipientAddress, // Recipient address on destination chain
      false, // Automatic transfer
    );

    // 1) Submit the transactions to the source chain, passing a signer to sign any txns
    const srcTxids = await usdcXfer.initiateTransfer(src.signer);

    // 2) Wait for the Circle Attestations to be signed and ready (not required for auto transfer)
    // 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
    const timeout = 120_000;
    const attestIds = await usdcXfer.fetchAttestation(timeout);

    // 3) Redeem the Circle Attestation on the dest chain
    const destTxids = await usdcXfer.completeTransfer(dst.signer);

See the example here.

### Automatic Transfers

Some transfers allow for automatic relaying to the destination, in that case only the `initiateTransfer` is required. The status of the transfer can be tracked by periodically checking the status of the transfer object.

    // OR for an automatic transfer
    const automaticXfer = wh.tokenTransfer(
      "native", // send native gas on source chain
      amt, // amount in base units
      senderAddress, // Sender address on source chain
      recipientAddress, // Recipient address on destination chain
      true, // Automatic transfer
    );

    // 1) Submit the transactions to the source chain, passing a signer to sign any txns
    const srcTxids = await automaticXfer.initiateTransfer(src.signer);
    // 2) If automatic, we're done, just wait for the transfer to complete
    if (automatic) return waitLog(automaticXfer);

### Gateway Transfers

Gateway transfers are transfers that are passed through the Wormhole Gateway to or from Cosmos chains.

See the example here.

### Recovering Transfers

It may be necessary to recover a transfer that was abandoned before being completed. This can be done by instantiating the Transfer class with the `from` static method and passing one of several types of identifiers.

A `TransactionId` may be used

    // Note, this will attempt to recover the transfer from the source chain
    // and attestation types so it may wait depending on the chain finality
    // and when the transactions were issued.
    const timeout = 60_000;
    const xfer = await TokenTransfer.from(
      {
        chain: "Ethereum",
        txid: "0x1234...",
      },
      timeout,
    );

    const dstTxIds = await xfer.completeTransfer(dst.signer);

Or a `WormholeMessageId` if a `VAA` is generated

    const xfer = await TokenTransfer.from({
      chain: "Ethereum",
      emitter: toNative("Ethereum", emitterAddress).toUniversalAddress(),
      sequence: "0x1234...",
    });

    const dstTxIds = await xfer.completeTransfer(dst.signer);

## Concepts

Understanding several higher level concepts of the SDK will help in using it effectively.

### Platforms

Every chain is its own special snowflake but many of them share similar functionality. The `Platform` modules provide a consistent interface for interacting with the chains that share a platform.

Each platform can be installed separately so that dependencies can stay as minimal as possible.

### Chain Context

The `Wormhole` class provides a `getChain` method that returns a `ChainContext` object for a given chain. This object provides access to the chain specific methods and utilities. Much of the functionality in the `ChainContext` is provided by the `Platform` methods but the specific chain may have overriden methods.

The ChainContext object is also responsible for holding a cached rpc client and protocol clients.

    // Get the chain context for the source and destination chains
    // This is useful to grab direct clients for the protocols
    const srcChain = wh.getChain(senderAddress.chain);
    const dstChain = wh.getChain(receiverAddress.chain);

    srcChain.parseAddress("0xdeadbeef..."); // => NativeAddress<'Evm'>
    await srcChain.getTokenBridge(); // => TokenBridge<'Evm'>
    srcChain.getRpcClient(); // => RpcClient<'Evm'>

### Protocols

While Wormhole itself is a Generic Message Passing protocol, a number of protocols have been built on top of it to provide specific functionality.

#### Token Bridge

The most familiar protocol built on Wormhole is the Token Bridge.

Every chain has a `TokenBridge` protocol client that provides a consistent interface for interacting with the Token Bridge. This includes methods to generate the transactions required to transfer tokens, as well as methods to generate and redeem attestations.

Using the `WormholeTransfer` abstractions is the recommended way to interact with these protocols but it is possible to use them directly

    import { signSendWait } from "@wormhole-foundation/connect-sdk";

    import "@wormhole-foundation/connect-sdk-evm-tokenbridge";

    // ...

    const tb = await srcChain.getTokenBridge(); // => TokenBridge<'Evm'>

    const token = "0xdeadbeef...";
    const txGenerator = tb.createAttestation(token); // => AsyncGenerator<UnsignedTransaction, ...>
    const txids = await signSendWait(srcChain, txGenerator, src.signer); // => TxHash[]

Supported protocols are defined in the definitions module.

### Signers

In order to sign transactions, an object that fulfils the `Signer` interface is required. This is a simple interface that can be implemented by wrapping a web wallet or other signing mechanism.

    // 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;

    // 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;
      // Accept an array of unsigned transactions and return
      // an array of signed and serialized transactions.
      // The transactions may be inspected or altered before
      // signing.
      // Note: The serialization is chain specific, if in doubt,
      // see the example implementations linked below
      sign(tx: UnsignedTransaction[]): Promise<SignedTx[]>;
    }

    // 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;
      // Accept an array of unsigned transactions and return
      // an array of transaction ids in the same order as the
      // UnsignedTransactions array.
      signAndSend(tx: UnsignedTransaction[]): Promise<TxHash[]>;
    }

See the testing signers (Evm, Solana, ...) for an example of how to implement a signer for a specific chain or platform.

    // Create a signer for the source and destination chains
    const sender: Signer =  // ...
    const receiver: Signer = // ...

### Addresses

Within the Wormhole context, addresses are normalized to 32 bytes and referred to in this SDK as a `UniversalAddresses`.

Each platform comes with an address type that understands the native address formats, unsuprisingly referred to a NativeAddress. This abstraction allows the SDK to work with addresses in a consistent way regardless of the underlying chain.

    // Convert a string address to its Native address
    const ethAddr: NativeAddress<"Evm"> = toNative("Ethereum", "0xbeef...");
    const solAddr: NativeAddress<"Solana"> = toNative("Solana", "Sol1111...");
    const algoAddr: NativeAddress<"Algorand"> = toNative("Solana", "TRYALGO...");

    // Convert a Native address to its string address
    ethAddr.toString(); // => '0xbeef...'

    // Convert a Native address to a UniversalAddress
    ethAddr.toUniversalAddresS();

    // A common type in the SDK is the `ChainAddress`.
    // A helper exists to provide a ChainAddress for a signer, or [ChainName, string address]
    const senderAddress: ChainAddress = nativeChainAddress(sender);
    const receiverAddress: ChainAddress = nativeChainAddress(receiver);

## See also

The tsdoc is available here

## WIP

:warning: This package is a Work in Progress so the interface may change and there are likely bugs. Please report any issues you find. :warning:

#####
Index

### References

ArrayLayoutItem
BytesLayoutItem
CustomConversion
DynamicItemsOfLayout
FixedConversion
FixedItemsOfLayout
FixedPrimitiveBytesLayoutItem
FixedPrimitiveNumLayoutItem
FixedSizeArrayLayoutItem
FixedSizeBytesLayoutItem
FixedValueBytesLayoutItem
IntLayoutItem
Layout
LayoutItem
LayoutItemToType
LayoutToType
LengthPrefixedArrayLayoutItem
LengthPrefixedBytesLayoutItem
NamedLayoutItem
NumLayoutItem
ObjectLayoutItem
OptionalToFromNumLayoutItem
UintLayoutItem
addFixedValues
calcLayoutSize
deserializeLayout
dynamicItemsOfLayout
fixedItemsOfLayout
layoutDiscriminator
serializeLayout

### Namespaces

AutomaticCircleBridge
AutomaticTokenBridge
CircleBridge
TokenBridge
api
chain
circle
circleApi
contracts
decimals
encoding
explorer
finality
guardians
layout
layoutItems
nativeChainIds
network
platform
rpc
tasks
testing
tokens

### Enumerations

TransferState

### Classes

ChainContext
CircleTransfer
GatewayTransfer
PlatformContext
Signature
TokenTransfer
UniversalAddress
Wormhole

### Interfaces

Address
AttestedTransferReceipt
AutomaticCircleBridge
AutomaticTokenBridge
CircleBridge
CompletedTransferReceipt
CreatedTransferReceipt
GatewayIbcTransferMsg
GatewayMsg
GatewayTransferMsg
GatewayTransferWithPayloadMsg
IbcBridge
IbcTransferData
IbcTransferInfo
PlatformUtils
ProtocolInitializer
Relayer
SignAndSendSigner
SignOnlySigner
SourceFinalizedTransferReceipt
SourceInitiatedTransferReceipt
TokenBridge
TransferProtocol
UnsignedTransaction
VAA
WormholeCore
WormholeTransfer

### Type Aliases

AccountAddress
AllSameLength
And
Attestation
AttestationId
AttestationReceipt
Balances
Cartesian
Chain
ChainAddress
ChainConfig
ChainId
ChainToPlatform
ChainsConfig
CircleAttestation
CircleMessageId
CircleTransferDetails
CircleTransferMessage
Column
ConcatStringLiterals
ConfigOverrides
Contracts
DefinedOrDefault
DistributiveOmit
Entries
ExcludeIndexes
Extends
Flatten
Function
GatewayTransferDetails
IbcMessageId
IndexEs
InnerFlatten
IsAny
IsFlat
IsNever
IsRectangular
IsUnion
IsUnionMember
MapLevel
MappableKey
MappedPlatforms
NamedPayloads
NativeAddress
Network
Not
OnlyIndexes
ParseNumber
Payload
PayloadDiscriminator
PayloadLiteral
Platform
PlatformAddressFormat
PlatformToChains
ProtocolImplementation
ProtocolName
ProtocolPayload
ProtocolVAA
RegisterPayloadTypes
RoArray
RoArray2D
RoPair
RpcConnection
SequenceId
ShallowMapping
SignedTx
Signer
ToMapping
ToMappingAndDepth
TokenAddress
TokenId
TokenTransferDetails
TokenTransferProtocol
TokenTransferVAA
TransactionId
TransferQuote
TransferReceipt
TransferRequest
TxHash
Unflatten
UnionToIntersection
UniversalOrNative
Widen
WormholeConfig
WormholeMessageId
Zip
getCircleAttestation
getWormholeAttestation

### Variables

CONFIG
DEFAULT_NETWORK
DEFAULT_TASK_TIMEOUT
chains

### Functions

ErrNotWrapped
applyOverrides
blindDeserializePayload
buildConfig
chainIdToChain
chainToChainId
chainToPlatform
column
constMap
create
createVAA
deserialize
deserializePayload
displayAmount
gatewayTransferMsg
getContracts
getPayloadLayout
getProtocolInitializer
isAttested
isChain
isCircleMessageId
isCircleTransferDetails
isGatewayIbcTransferMsg
isGatewayTransferDetails
isGatewayTransferMsg
isGatewayTransferWithPayloadMsg
isIbcMessageId
isIbcTransferInfo
isPlatform
isSignAndSendSigner
isSignOnlySigner
isSigner
isSourceFinalized
isSourceInitiated
isTokenId
isTokenTransferDetails
isTransactionIdentifier
isWormholeMessageId
lazyInstantiate
makeGatewayTransferMsg
nativeIsRegistered
networkPlatformConfigs
normalizeAmount
onlyOnce
payloadDiscriminator
platformToAddressFormat
platformToChains
protocolIsRegistered
range
registerNative
registerPayloadType
registerPayloadTypes
registerProtocol
serialize
serializePayload
signSendWait
throws
toChain
toChainId
toGatewayMsg
toNative
toUniversal
zip

## References

### ArrayLayoutItem

Re-exports ArrayLayoutItem

### BytesLayoutItem

Re-exports BytesLayoutItem

### CustomConversion

Re-exports CustomConversion

### DynamicItemsOfLayout

Re-exports DynamicItemsOfLayout

### FixedConversion

Re-exports FixedConversion

### FixedItemsOfLayout

Re-exports FixedItemsOfLayout

### FixedPrimitiveBytesLayoutItem

Re-exports FixedPrimitiveBytesLayoutItem

### FixedPrimitiveNumLayoutItem

Re-exports FixedPrimitiveNumLayoutItem

### FixedSizeArrayLayoutItem

Re-exports FixedSizeArrayLayoutItem

### FixedSizeBytesLayoutItem

Re-exports FixedSizeBytesLayoutItem

### FixedValueBytesLayoutItem

Re-exports FixedValueBytesLayoutItem

### IntLayoutItem

Re-exports IntLayoutItem

### Layout

Re-exports Layout

### LayoutItem

Re-exports LayoutItem

### LayoutItemToType

Re-exports LayoutItemToType

### LayoutToType

Re-exports LayoutToType

### LengthPrefixedArrayLayoutItem

Re-exports LengthPrefixedArrayLayoutItem

### LengthPrefixedBytesLayoutItem

Re-exports LengthPrefixedBytesLayoutItem

### NamedLayoutItem

Re-exports NamedLayoutItem

### NumLayoutItem

Re-exports NumLayoutItem

### ObjectLayoutItem

Re-exports ObjectLayoutItem

### OptionalToFromNumLayoutItem

Re-exports OptionalToFromNumLayoutItem

### UintLayoutItem

Re-exports UintLayoutItem

### addFixedValues

Re-exports addFixedValues

### calcLayoutSize

Re-exports calcLayoutSize

### deserializeLayout

Re-exports deserializeLayout

### dynamicItemsOfLayout

Re-exports dynamicItemsOfLayout

### fixedItemsOfLayout

Re-exports fixedItemsOfLayout

### layoutDiscriminator

Re-exports layoutDiscriminator

### serializeLayout

Re-exports serializeLayout

Generated using TypeDoc