wormhole/docs/solana_program.md

Solana Wormhole Program

The Wormhole program acts as a bridge for Solana <> Foreign Chain transfers using the WhP (WormHoleProtocol).

Instructions

Initialize

Initializes a new Bridge at bridge.

Index	Name	Type	signer	writeable	empty	derived
0	sys	SystemProgram
1	clock	Sysvar				✅
2	bridge	BridgeConfig		✅	✅	✅
3	guardian_set	GuardianSet		✅	✅	✅
4	payer	Account	✅

PokeProposal

Pokes a TransferOutProposal so it is reprocessed by the guardians.

Deprecated: PokeProposals were a workaround for unreliable message delivery on Solana. Now that this has been fixed using a control loop (fd6c54de83), poking is no longer required. The feature is left in place for backwards compatibility reasons.

Index	Name	Type	signer	writeable	empty	derived
0	proposal	TransferOutProposal		✅	️	✅

CreateWrappedAsset

Creates a new WrappedAsset to be used to create accounts and later receive transfers on chain.

Index	Name	Type	signer	writeable	empty	derived
0	sys	SystemProgram
1	token_program	SplToken
2	rent	Sysvar				✅
3	bridge	BridgeConfig
4	payer	Account	✅
5	wrapped_mint	WrappedAsset			✅	✅
6	wrapped_meta_account	WrappedAssetMeta		✅	✅	✅

VerifySignatures

Checks secp checks (in the previous instruction) and stores results.

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	sys	SystemProgram
2	instructions	Sysvar				✅
3	bridge_config	BridgeConfig		✅		✅
4	sig_status	SignatureState		✅
5	guardian_set	GuardianSet				✅
6	payer	Account	✅

TransferOut

Burns a wrapped asset token from sender on the Solana chain.

The transfer proposal will be tracked at a new account proposal where VAAs will be submitted by guardians.

This instruction needs to be preceded by a SOL Transfer instruction that transfers the fee to the BridgeConfig. The fee can be calculated using the rules explained in the protocol documentation and Bridge::transfer_fee().

Parameters:

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	sys	SystemProgram
2	token_program	SplToken
3	rent	Sysvar				✅
4	clock	Sysvar				✅
5	instructions	Sysvar				✅
6	token_account	TokenAccount		✅
7	bridge	BridgeConfig
8	proposal	TransferOutProposal		✅	✅	✅
9	token	WrappedAsset		✅		✅
10	payer	Account	✅

TransferOutNative

Locks a Solana native token (spl-token) token from sender on the Solana chain by transferring it to the custody_account.

The transfer proposal will be tracked at a new account proposal where a VAA will be submitted by guardians.

This instruction needs to be preceded by a SOL Transfer instruction that transfers the fee to the BridgeConfig. The fee can be calculated using the rules explained in the protocol documentation and Bridge::transfer_fee().

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	sys	SystemProgram
2	token_program	SplToken
3	rent	Sysvar				✅
4	clock	Sysvar				✅
5	instructions	Sysvar				✅
6	token_account	TokenAccount		✅
7	bridge	BridgeConfig
8	proposal	TransferOutProposal		✅	✅	✅
9	token	Mint		✅
10	payer	Account	✅
11	custody_account	TokenAccount		✅	opt	✅

EvictTransferOut

Deletes a proposal after the VAA_EXPIRATION_TIME to free up space on chain. This returns the rent to guardian.

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	guardian	Account	✅
2	clock	Sysvar				✅
3	bridge	BridgeConfig
4	proposal	TransferOutProposal		✅		✅

EvictClaimedVAA

Deletes a ClaimedVAA after the VAA_EXPIRATION_TIME to free up space on chain. This returns the rent to guardian.

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	guardian	Account	✅
2	clock	Sysvar				✅
3	bridge	BridgeConfig
4	claim	ClaimedVAA		✅		✅

SubmitVAA

Submits a VAA signed by the guardians to perform an action.

The required accounts depend on the action of the VAA:

All require:

Index	Name	Type	signer	writeable	empty	derived
0	bridge_p	BridgeProgram
1	sys	SystemProgram
2	rent	Sysvar				✅
3	clock	Sysvar				✅
4	bridge	BridgeConfig		✅
5	guardian_set	GuardianSet
6	claim	ExecutedVAA		✅	✅	✅
7	sig_info	SigState		✅	✅
8	payer	Account	✅

followed by:

Guardian set update

Index	Name	Type	signer	writeable	empty	derived
9	guardian_set_new	GuardianSet		✅	✅	✅

Contract upgrade

Index	Name	Type	signer	writeable	empty	derived
9	new_contract	Account			✅
10	program_data	Account		✅	✅	✅
11	upgradeable_loader	UpgradeableLoader

Transfer: Ethereum (native) -> Solana (wrapped)

Index	Name	Type	signer	writeable	empty	derived
9	token_program	SplToken
10	token	WrappedAsset				✅
11	destination	TokenAccount		✅
12	wrapped_meta	WrappedMeta		✅	opt	✅

Transfer: Ethereum (wrapped) -> Solana (native)

Index	Name	Type	signer	writeable	empty	derived
9	token_program	SplToken
10	token	Mint				✅
11	destination	TokenAccount		✅	opt
12	custody_src	TokenAccount		✅		✅

Transfer: Solana (any) -> Ethereum (any)

Index	Name	Type	signer	writeable	empty	derived
9	out_proposal	TransferOutProposal		✅		✅

Accounts

The following types of accounts are owned by creators of bridges:

BridgeConfig Account

This account tracks the configuration of the transfer bridge.

Parameter	Description
VAA_EXPIRATION_TIME	Period for how long a VAA is valid. This exists to guarantee data availability and prevent replays
GUARDIAN_SET_INDEX	Index of the current active guardian set //TODO do we need to track this if the VAA contains the index?

Program Accounts

The program own the following types of accounts:

ClaimedVAA Account

Seed derivation: claim || <bridge> || <hash>

bridge: Pubkey of the bridge

hash: signing hash of the VAA

This account is created when a VAA is executed/consumed on Solana (i.e. not when a TransferOutProposal is approved). It tracks a used VAA to protect from replay attacks where a VAA is executed multiple times. This account stays active until the VAA_EXPIRATION_TIME has passed and can then be evicted using IEvictClaimedVAA.

GuardianSet Account

Seed derivation: guardian || <bridge> || <index>

bridge: Pubkey of the bridge

index: Index of the guardian set

This account is created when a new guardian set is set. It tracks the public key hash, creation time and expiration time of this set. The expiration time is set when this guardian set is abandoned. When a switchover happens, the guardian-issued VAAs will still be valid until the expiration time.

TransferOutProposal Account

Seed derivation: transfer || <bridge> || <asset_chain> || <asset> || <target_chain> || <target_address> || <sender> || <nonce>

bridge: Pubkey of the bridge

asset_chain: CHAIN_ID of the native chain of this asset

asset: address of the asset

target_chain: ChainID of the recipient

target_address: address of the recipient

sender: pubkey of the sender

nonce: nonce of the transfer

This account is created when a user wants to lock tokens to transfer them to a foreign chain using the ITransferOut instruction.

It is used to signal a pending transfer to a foreign chain and will also store the respective VAA provided using ISubmitVAA.

Once the VAA has been published this TransferOut is considered completed and can be evicted using EvictTransferOut after VAA_EXPIRATION_TIME has passed.

WrappedAsset Mint

Seed derivation: wrapped || <bridge> || <chain> || <asset>

bridge: Pubkey of the bridge

chain: CHAIN_ID of the native chain of this asset

asset: address of the asset on the foreign chain

This account is an instance of spl-token/Mint tracks a wrapped asset on the Solana chain.

WrappedAssetMeta Mint

Seed derivation: meta || <bridge> || <wrapped>

bridge: Pubkey of the bridge

wrapped: address of the wrapped asset

This account tracks the metadata about a wrapped asset to allow reverse lookups.

Custody TokenAccount

Seed derivation: custody || <bridge> || <asset>

bridge: Pubkey of the bridge

asset: address of the asset mint on the native chain

This account is an instance of spl-token/TokenAccount and holds spl tokens in custody that have been transferred to a foreign chain.