Skip to content
Edit this page

Core Contract (EVM)＃

The Wormhole Core Contract on EVM chains is a proxy-based contract responsible for receiving and verifying Wormhole messages (VAAs). It implements the messaging interface and delegates logic to upgradeable implementation contracts.

Structure Overview＃

The Wormhole Core system consists of a proxy contract and a modular implementation constructed through layered inheritance.

Wormhole.sol (Proxy)
└── Implementation.sol
    └── Governance.sol
        ├── Getters.sol
        ├── GovernanceStructs.sol
        ├── Messages.sol
        ├── Setters.sol
        └── Structs.sol

Key Components:

  • Wormhole.sol: The upgradeable proxy contract that delegates all logic to Implementation.sol.
  • Implementation.sol: The main logic contract, which handles message publication and initialization. Inherits from Governance.sol.
  • Governance.sol: Core governance logic for processing upgrades, setting fees, and updating the Guardian set. Also responsible for verifying governance VAAs and performing privileged actions.
  • Getters.sol: Exposes view functions to access internal contract state, such as current Guardian sets, fees, and contract configuration.
  • GovernanceStructs.sol: Provides structures and helpers for processing governance-related VAAs.
  • Messages.sol: Handles VAA parsing and verification.
  • Setters.sol: Contains internal functions for mutating contract state.
  • Structs.sol: Defines core data structures like GuardianSet and VM (VAA Message) used across multiple modules.

State Variables＃

  • provider Structs.Provider: Holds metadata like chainId, governanceChainId, and governanceContract. This is a nested struct.
  • guardianSets mapping(uint32 => GuardianSet): Mapping of all Guardian sets by index.
  • guardianSetIndex uint32: Index of the currently active Guardian set.
  • guardianSetExpiry uint32: How long a Guardian set remains valid after it's replaced (in seconds).
  • sequences mapping(address => uint64): Tracks message sequences per emitter (used to enforce message ordering).
  • consumedGovernanceActions mapping(bytes32 => bool): Used to prevent governance VAAs from being reused (replay protection).
  • initializedImplementations mapping(address => bool): Tracks which implementation addresses have been initialized (for upgrade safety).
  • messageFee uint256: The amount (in native gas token) required to post a message. Set via governance.
  • evmChainId uint256: The actual EVM chain ID (e.g., 1 for Ethereum, 10 for Optimism). Used in fork recovery.

Events＃

LogMessagePublished＃

Emitted when a message is published via publishMessage. (Defined in Implementation.sol)

event LogMessagePublished(
    address indexed sender,
    uint64 sequence,
    uint32 nonce,
    bytes payload,
    uint8 consistencyLevel
)
Parameters

sender address

Address that called publishMessage.

sequence uint64

The sequence number of the message.

nonce uint32

The provided nonce.

payload bytes

The payload that was published.

consistencyLevel uint8

Finality level requested.

ContractUpgraded＃

Emitted when the Core Contract is upgraded to a new implementation via governance. (Defined in Governance.sol)

event ContractUpgraded(
    address indexed oldContract,
    address indexed newContract
)
Parameters

oldContract address

The address of the previous implementation.

newContract address

The address of the new implementation.

GuardianSetAdded＃

Emitted when a new Guardian set is registered via governance. (Defined in Governance.sol)

event GuardianSetAdded(
    uint32 indexed index
)
Parameters

index uint32

Index of the newly added Guardian set.

LogGuardianSetChanged＃

Emitted when the active Guardian set is changed. (Defined in State.sol)

event LogGuardianSetChanged(
    uint32 oldGuardianIndex,
    uint32 newGuardianIndex
)
Parameters

oldGuardianIndex uint32

The previous active Guardian set index.

newGuardianIndex uint32

The new active Guardian set index.

Functions＃

publishMessage＃

Publishes a message to Wormhole's Guardian Network. (Defined in Implementation.sol)

function publishMessage(
    uint32 nonce,
    bytes memory payload,
    uint8 consistencyLevel
) public payable returns (uint64 sequence)
Parameters

nonce uint32

Custom sequence identifier for the emitter.

payload bytes

Arbitrary user data to be included in the message.

consistencyLevel uint8

Finality requirement for Guardian attestation (e.g., safe or finalized).

Returns

sequence uint64

Unique sequence number assigned to this message.

getCurrentGuardianSetIndex＃

Returns the index of the currently active Guardian set. (Defined in Getters.sol)

Each VAA includes the index of the Guardian set that signed it. This function allows contracts to retrieve the current index, ensuring the VAA is verified against the correct set.

function getCurrentGuardianSetIndex() external view returns (uint32)
Returns

index uint32

The index of the active Guardian set used to verify signatures.

getGuardianSet＃

Retrieves metadata for a given Guardian set index. (Defined in Getters.sol)

function getGuardianSet(uint32 index) external view returns (address[] memory keys, uint32 expirationTime)
Parameters

index uint32

Guardian set index to query.

Returns

keys address[]

Public keys of the guardians in this set.

expirationTime uint32

Timestamp after which the Guardian set is considered expired.

getGuardianSetExpiry＃

Returns the expiration time of a specific Guardian set index. (Defined in Getters.sol)

function getGuardianSetExpiry(uint32 index) external view returns (uint32)
Parameters

index uint32

The index of the Guardian set to query.

Returns

expiry uint32

UNIX timestamp after which the set is no longer valid.

messageFee＃

Returns the current fee (in native tokens) required to publish a message. (Defined in Getters.sol)

function messageFee() public view returns (uint256)
Returns

fee uint256

Fee in Wei required to publish a message successfully. Must be sent as msg.value.

nextSequence＃

Retrieves the next sequence number for a given emitter address. (Defined in Getters.sol)

function nextSequence(address emitter) external view returns (uint64)
Parameters

emitter address

The address for which the next sequence will be issued.

Returns

sequence uint64

The next sequence number for the specified emitter.

parseAndVerifyVM＃

Verifies signatures and parses a signed VAA. (Defined in Messages.sol)

function parseAndVerifyVM(bytes memory encodedVM)
    external
    view
    returns (
        VM memory vm,
        bool valid,
        string memory reason
    )
Parameters

encodedVM bytes

Serialized signed VAA from Guardians.

Returns

vm VM memory

Full parsed VAA contents

valid bool

Whether the VAA is valid according to the current Guardian set.

reason string

Reason for invalidity if valid is false (invalid).

verifyVM＃

Performs low-level VAA signature verification. (Defined in Messages.sol)

function verifyVM(bytes memory encodedVM)
    public view returns (bool isValid, string memory reason)
Parameters

encodedVM bytes

Serialized signed VAA to verify.

Returns

isValid bool

true if the signatures are valid and meet the quorum.

reason string

Explanation for failure if isValid is false.

verifySignatures＃

Used to verify individual Guardian signatures against a VAA digest. (Defined in Messages.sol)

function verifySignatures(
    bytes32 hash,
    Structs.Signature[] memory signatures,
    GuardianSet memory guardianSet
) public view returns (bool)
Parameters

hash bytes32

The message digest to verify.

signatures Structs.Signature[]

An array of Guardian signatures.

guardianSet GuardianSet memory

Guardian set to validate against.

Returns

isValid bool

true if the required number of valid signatures is present.

quorum＃

Returns the number of Guardian signatures required to reach quorum. (Defined in Governance.sol)

function quorum() public view returns (uint8)
Returns

quorum uint8

Number of valid Guardian signatures required to reach consensus for VAA verification.

chainId＃

Returns Wormhole chain ID used internally by the protocol. (Defined in Getters.sol)

function chainId() public view returns (uint16)
Returns

id uint16

Wormhole-specific chain identifier.

evmChainId＃

Returns the EVM chain ID (i.e., value from block.chainid). (Defined in Getters.sol)

function evmChainId() public view returns (uint256)
Returns

id uint256

Native EVM chain ID for the current network.

Errors＃

Invalid Fee＃

Reverts when the message fee (msg.value) sent is not equal to the required fee returned by messageFee(). (Defined in Implementation.sol)

Unsupported＃

Reverts on any call to the fallback function. The contract does not support arbitrary calls. (Defined in Implementation.sol)

The Wormhole Contract Does Not Accept Assets＃

Reverts when native tokens (ETH) are sent directly to the contract via the receive() function. (Defined in Implementation.sol)

Already Initialized＃

Reverts when trying to call initialize() on an implementation that has already been initialized. (Defined in Implementation.sol, via initializer modifier)

Unknown Chain ID＃

Reverts inside the initialize() function if the chain ID stored by the contract does not match any known Wormhole chain. (Defined in Implementation.sol)

Invalid Fork＃

Reverts when attempting to perform a governance action intended only for forked chains on a non-forked chain. (Defined in Governance.sol)

Invalid Module＃

Reverts if the VAA’s module field doesn’t match the expected "Core" module. (Defined in Governance.sol)

Invalid Chain＃

Reverts if the VAA’s target chain doesn’t match the chain on which this contract is deployed. (Defined in Governance.sol)

New Guardian Set is Empty＃

Reverts when trying to register a new Guardian set that has no keys. (Defined in Governance.sol)

Index Must Increase in Steps of 1＃

Reverts when the new Guardian set index is not exactly one greater than the current. (Defined in Governance.sol)

Not a Fork＃

Reverts when trying to recover chain ID on a non-forked chain. (Defined in Governance.sol)

Invalid EVM Chain＃

Reverts if the recovered chain ID doesn't match the current block.chainid. (Defined in Governance.sol)

Governance Action Already Consumed＃

Reverts when the same governance VAA is submitted more than once. (Defined in Governance.sol)

Wrong Governance Contract＃

Reverts when the governance VAA’s emitter address doesn't match the expected governance contract address. (Defined in Governance.sol)

Wrong Governance Chain＃

Reverts when the governance VAA’s emitter chain doesn't match the expected governance chain (Solana). (Defined in Governance.sol)

Not Signed by Current Guardian Set＃

Reverts if the Guardian set index in the VAA doesn’t match the current Guardian set. (Defined in Governance.sol)