2020-07-31 10:51:07 -07:00
|
|
|
|
# Solana Wormhole Program
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
The `Wormhole` program acts as a bridge for Solana \<> Foreign Chain transfers using the WhP (WormHoleProtocol).
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
## Instructions
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### Initialize
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
Initializes a new Bridge at `bridge`.
|
|
|
|
|
|
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------ | ------------ | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 0 | sys | SystemProgram | | | ️ | |
|
2020-08-03 05:55:58 -07:00
|
|
|
|
| 1 | clock | Sysvar | | | ️ | ✅ |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 2 | bridge | BridgeConfig | | | ✅️ | ✅️ |
|
|
|
|
|
| 3 | guardian_set | GuardianSet | | ✅ | ✅ | ✅ |
|
|
|
|
|
| 4 | payer | Account | ✅ | | | |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### TransferOut
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
Burns a wrapped asset `token` from `sender` on the Solana chain.
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
The transfer proposal will be tracked at a new account `proposal` where VAAs will be submitted by guardians.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
Parameters:
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | -------- | ------------------- | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 0 | sys | SystemProgram | | | ️ | |
|
|
|
|
|
| 1 | token_program | SplToken | | | ️ | |
|
2020-08-07 07:10:30 -07:00
|
|
|
|
| 2 | token_account | TokenAccount | | ✅ | | |
|
|
|
|
|
| 3 | bridge | BridgeConfig | | | | |
|
|
|
|
|
| 4 | proposal | TransferOutProposal | | ✅ | ✅ | ✅ |
|
|
|
|
|
| 5 | token | WrappedAsset | | ✅ | | ✅ |
|
|
|
|
|
| 6 | payer | Account | ✅ | | | |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### TransferOutNative
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
Locks a Solana native token (spl-token) `token` from `sender` on the Solana chain by transferring it to the
|
2020-07-28 03:40:15 -07:00
|
|
|
|
`custody_account`.
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
The transfer proposal will be tracked at a new account `proposal` where a VAA will be submitted by guardians.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | --------------- | ------------------- | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 0 | sys | SystemProgram | | | ️ | |
|
|
|
|
|
| 1 | token_program | SplToken | | | ️ | |
|
2020-08-07 07:10:30 -07:00
|
|
|
|
| 2 | token_account | TokenAccount | | ✅ | | |
|
|
|
|
|
| 3 | bridge | BridgeConfig | | | | |
|
|
|
|
|
| 4 | proposal | TransferOutProposal | | ✅ | ✅ | ✅ |
|
|
|
|
|
| 5 | token | Mint | | ✅ | | |
|
|
|
|
|
| 6 | payer | Account | ✅ | | | |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 7 | custody_account | TokenAccount | | ✅ | opt | ✅ |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### EvictTransferOut
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
Deletes a `proposal` after the `VAA_EXPIRATION_TIME` to free up space on chain. This returns the rent to `guardian`.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | -------- | ------------------- | ------ | --------- | ----- | ------- |
|
|
|
|
|
| 0 | guardian | Account | ✅ | | | |
|
2020-08-03 05:55:58 -07:00
|
|
|
|
| 1 | clock | Sysvar | | | ️ | ✅ |
|
|
|
|
|
| 2 | bridge | BridgeConfig | | | | |
|
|
|
|
|
| 3 | proposal | TransferOutProposal | | ✅ | | ✅ |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### EvictExecutedVAA
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
Deletes a `ExecutedVAA` after the `VAA_EXPIRATION_TIME` to free up space on chain. This returns the rent to `guardian`.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | -------- | ------------------- | ------ | --------- | ----- | ------- |
|
|
|
|
|
| 0 | guardian | Account | ✅ | | | |
|
2020-08-03 05:55:58 -07:00
|
|
|
|
| 1 | clock | Sysvar | | | ️ | ✅ |
|
|
|
|
|
| 2 | bridge | BridgeConfig | | | | |
|
|
|
|
|
| 3 | proposal | ExecutedVAA | | ✅ | | ✅ |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### PostVAA
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
Submits a VAA signed by the guardians to perform an action.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
The required accounts depend on the `action` of the VAA:
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-08-07 03:09:53 -07:00
|
|
|
|
All require:
|
|
|
|
|
|
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------------ | ------------ | ------ | --------- | ----- | ------- |
|
|
|
|
|
| 0 | sys | SystemProgram | | | ️ | |
|
|
|
|
|
| 1 | clock | Sysvar | | | ️ | ✅ |
|
|
|
|
|
| 2 | bridge | BridgeConfig | | | | |
|
|
|
|
|
| 3 | guardian_set | GuardianSet | | | | |
|
|
|
|
|
| 4 | claim | ExecutedVAA | | ✅ | ✅ | ✅ |
|
|
|
|
|
| 5 | payer | Account | ✅ | | | |
|
|
|
|
|
|
|
|
|
|
followed by:
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
##### Guardian set update
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------------ | ------------------- | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 6 | guardian_set_new | GuardianSet | | ✅ | ✅ | ✅ |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
##### Transfer: Ethereum (native) -> Solana (wrapped)
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------------ | ------------ | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 6 | token_program | SplToken | | | ️ | |
|
2020-08-07 07:10:30 -07:00
|
|
|
|
| 7 | token | WrappedAsset | | | opt | ✅ |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 8 | destination | TokenAccount | | ✅ | opt | |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
##### Transfer: Ethereum (wrapped) -> Solana (native)
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------------ | ------------ | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 6 | token_program | SplToken | | | ️ | |
|
|
|
|
|
| 7 | token | Mint | | | | ✅ |
|
|
|
|
|
| 8 | destination | TokenAccount | | ✅ | opt | |
|
|
|
|
|
| 9 | custody_src | TokenAccount | | ✅ | | ✅ |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
##### Transfer: Solana (any) -> Ethereum (any)
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| Index | Name | Type | signer | writeable | empty | derived |
|
|
|
|
|
| ----- | ------------ | ------------------- | ------ | --------- | ----- | ------- |
|
2020-08-07 03:09:53 -07:00
|
|
|
|
| 7 | out_proposal | TransferOutProposal | | ✅ | | ✅ |
|
|
|
|
|
| 8 | sender | Account | ✅ | | | |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
## Accounts
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
The following types of accounts are owned by creators of bridges:
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _BridgeConfig_ Account
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
This account tracks the configuration of the transfer bridge.
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
| 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? |
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
## Program Accounts
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
The program own the following types of accounts:
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _ExecutedVAA_ Account
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
> Seed derivation: `executedvaa_<vaa_hash>`
|
2020-07-28 03:40:15 -07:00
|
|
|
|
>
|
2020-07-31 10:51:07 -07:00
|
|
|
|
> **vaa_hash**: 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 `IEvictExecutedVAA`.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _GuardianSet_ Account
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
> Seed derivation: `guardians_<index>`
|
|
|
|
|
>
|
|
|
|
|
> **index**: Index of the guardian set
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
This account is created when a new guardian set is set. It tracks the public key, 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.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _TransferOutProposal_ Account
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
> Seed derivation: `out_<chain>_<asset>_<transfer_hash>`
|
2020-07-28 03:40:15 -07:00
|
|
|
|
>
|
|
|
|
|
> **chain**: CHAIN_ID of the native chain of this asset
|
|
|
|
|
>
|
|
|
|
|
> **asset**: address of the asset
|
|
|
|
|
>
|
2020-07-31 10:51:07 -07:00
|
|
|
|
> **transfer_hash**: Random ID of the transfer
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
This account is created when a user wants to lock tokens to transfer them to a foreign chain using the `ITransferOut`
|
|
|
|
|
instruction.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
It is used to signal a pending transfer to a foreign chain and will also store the respective VAA provided using
|
|
|
|
|
`IPostVAA`.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
Once the VAA has been published this TransferOut is considered completed and can be evicted using `EvictTransferOut`
|
|
|
|
|
after `VAA_EXPIRATION_TIME` has passed.
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _WrappedAsset_ Mint
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
> Seed derivation: `wrapped_<chain>_<asset>`
|
|
|
|
|
>
|
|
|
|
|
> **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.
|
|
|
|
|
|
2020-07-31 10:51:07 -07:00
|
|
|
|
#### _NativeAsset_ TokenAccount
|
2020-07-28 03:40:15 -07:00
|
|
|
|
|
|
|
|
|
> Seed derivation: `custody_<asset>`
|
|
|
|
|
>
|
|
|
|
|
> **asset**: address of the asset 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.
|