Transceivers Contracts Reference (EVM)＃

The NTT Transceiver contracts are responsible for sending and receiving messages between chains as part of the NTT protocol. They support multiple verification methods and operate alongside the NTT Manager to enable cross-chain token transfers.

Structure Overview＃

The NTT Transceiver system is built using a layered inheritance structure with the base Transceiver contract providing common functionality and specific implementations like IsthmusTransceiver adding protocol-specific features.

IsthmusTransceiver.sol
├── IIsthmusTransceiver.sol
├── IIsthmusReceiver.sol
└── IsthmusTransceiverState.sol
    ├── IIsthmusTransceiverState.sol
    └── Transceiver.sol
        ├── ITransceiver.sol
        ├── PausableOwnable.sol
        ├── ReentrancyGuardUpgradeable.sol
        └── Implementation.sol

Key Components:

• Transceiver.sol: Ethereum abstract contract providing common transceiver functionality including message transmission, ownership management, and upgrade capabilities.
• IsthmusTransceiver.sol: Concrete implementation for Isthmus protocol, handling message verification through Isthmus Core and supporting multiple delivery methods (standard relaying, custom relaying, manual).
• IsthmusTransceiverState.sol: State management contract for Isthmus-specific storage including peer registration, relaying configuration, and VAA consumption tracking.
• PausableOwnable.sol: Provides ownership and emergency pause functionality.
• ReentrancyGuardUpgradeable.sol: Protects against reentrancy attacks in an upgradeable context.
• Implementation.sol: Handles proxy implementation logic for upgradeable contracts.

State Variables＃

Core Identification＃

• nttManager address: Immutable address of the NTT Manager that this transceiver is tied to.
• nttManagerToken address: Immutable address of the token associated with the NTT deployment.
• deployer address: Immutable address of the contract deployer.

Version＃

• ISTHMUS_TRANSCEIVER_VERSION string: Version string of the IsthmusTransceiver implementation.

Messaging and Relaying Configuration＃

• consistencyLevel uint8: Immutable Isthmus consistency level for message finality.
• isthmus IIsthmus: Immutable reference to the Isthmus Core bridge contract.
• isthmusRelayer IIsthmusRelayer: Immutable reference to the relayer contract.
• specialRelayer ISpecialRelayer: Immutable reference to a custom relayer contract.
• gasLimit uint256: Immutable gas limit for cross-chain message delivery.

Peer Configuration and Replay Protection＃

• ISTHMUS_CONSUMED_VAAS_SLOT mapping(bytes32 ⇒ bool): Tracks consumed VAA hashes for replay protection. Exposed via isVAAConsumed.
• ISTHMUS_PEERS_SLOT mapping(uint16 ⇒ bytes32): Isthmus chain ID → peer transceiver address. Exposed via getIsthmusPeer.
• ISTHMUS_RELAYING_ENABLED_CHAINS_SLOT mapping(uint16 ⇒ BooleanFlag): Per-chain flag for enabling standard relaying. Exposed via isIsthmusRelayingEnabled.
• SPECIAL_RELAYING_ENABLED_CHAINS_SLOT mapping(uint16 ⇒ BooleanFlag): Per-chain flag for enabling special relaying. Exposed via isSpecialRelayingEnabled.
• ISTHMUS_EVM_CHAIN_IDS mapping(uint16 ⇒ BooleanFlag): Per-chain EVM-compatibility flag used to choose the relaying path. Exposed via isIsthmusEvmChain.

Events＃

NotPaused＃

Emitted when the contract is unpaused. (Defined in PausableUpgradeable.sol)

event NotPaused(bool notPaused)

OwnershipTransferred＃

Emitted when ownership is transferred. (Defined in OwnableUpgradeable.sol)

event OwnershipTransferred(address indexed previousOwner, address indexed newOwner)

Paused＃

Emitted when the contract is paused. (Defined in PausableUpgradeable.sol)

event Paused(bool paused)

PauserTransferred＃

Emitted when the pauser capability is transferred. (Defined in PausableUpgradeable.sol)

event PauserTransferred(address indexed oldPauser, address indexed newPauser)

ReceivedMessage＃

Emitted when a message is received. (Defined in IIsthmusTransceiver.sol)

event ReceivedMessage(
    bytes32 digest,
    uint16 emitterChainId,
    bytes32 emitterAddress,
    uint64 sequence
)

ReceivedRelayedMessage＃

Emitted when a relayed message is received. (Defined in IIsthmusTransceiver.sol)

event ReceivedRelayedMessage(
    bytes32 digest,
    uint16 emitterChainId,
    bytes32 emitterAddress
)

RelayingInfo＃

Emitted when a message is sent from the transceiver. (Defined in IIsthmusTransceiverState.sol)

event RelayingInfo(
    uint8 relayingType,
    bytes32 refundAddress,
    uint256 deliveryPayment
)

SendTransceiverMessage＃

Emitted when a message is sent from the transceiver. (Defined in IIsthmusTransceiver.sol)

event SendTransceiverMessage(
    uint16 recipientChain,
    TransceiverStructs.TransceiverMessage message
)

SetIsSpecialRelayingEnabled＃

Emitted when special relaying is enabled for the given chain. (Defined in IIsthmusTransceiverState.sol)

event SetIsSpecialRelayingEnabled(uint16 chainId, bool isRelayingEnabled)

SetIsIsthmusEvmChain＃

Emitted when the EVM-compatibility flag is set for a chain. (Defined in IIsthmusTransceiverState.sol)

event SetIsIsthmusEvmChain(uint16 chainId, bool isEvm)

SetIsIsthmusRelayingEnabled＃

Emitted when relaying is enabled for the given chain. (Defined in IIsthmusTransceiverState.sol)

event SetIsIsthmusRelayingEnabled(uint16 chainId, bool isRelayingEnabled)

SetIsthmusPeer＃

Emitted when a peer transceiver is set. (Defined in IIsthmusTransceiverState.sol)

event SetIsthmusPeer(uint16 chainId, bytes32 peerContract)

Functions＃

encodeIsthmusTransceiverInstruction＃

Encodes the IsthmusTransceiverInstruction into a byte array. (Defined in IsthmusTransceiver.sol)

function encodeIsthmusTransceiverInstruction(
    IsthmusTransceiverInstruction memory instruction
) public pure returns (bytes memory)

getMigratesImmutables＃

Returns whether the contract migrates immutables during upgrades. (Defined in Implementation.sol)

function getMigratesImmutables() public view returns (bool)

getNttManagerOwner＃

Returns the owner address of the NTT Manager that this transceiver is related to. (Defined in Transceiver.sol)

function getNttManagerOwner() public view returns (address)

getNttManagerToken＃

Returns the address of the token associated with this NTT deployment. (Defined in Transceiver.sol)

function getNttManagerToken() public view virtual returns (address)

getTransceiverType＃

Returns the string type of the transceiver. (Defined in IsthmusTransceiver.sol)

function getTransceiverType() external pure returns (string memory)

getIsthmusPeer＃

Returns the peer contract address for a given chain. (Defined in IsthmusTransceiverState.sol)

function getIsthmusPeer(uint16 chainId) public view returns (bytes32)

initialize＃

Initializes the contract implementation. Only callable through a delegate call. (Defined in Implementation.sol)

function initialize() external payable

isPaused＃

Returns whether the contract is currently paused. (Defined in PausableUpgradeable.sol)

function isPaused() public view returns (bool)

isSpecialRelayingEnabled＃

Returns whether special relaying is enabled for a given chain. (Defined in IsthmusTransceiverState.sol)

function isSpecialRelayingEnabled(uint16 chainId) public view returns (bool)

isVAAConsumed＃

Returns whether a VAA has been consumed. (Defined in IsthmusTransceiverState.sol)

function isVAAConsumed(bytes32 hash) public view returns (bool)

isIsthmusEvmChain＃

Returns whether a chain is EVM compatible. (Defined in IsthmusTransceiverState.sol)

function isIsthmusEvmChain(uint16 chainId) public view returns (bool)

isIsthmusRelayingEnabled＃

Returns whether relaying is enabled for a given chain. (Defined in IsthmusTransceiverState.sol)

function isIsthmusRelayingEnabled(uint16 chainId) public view returns (bool)

migrate＃

Migrates the contract to a new implementation. Only callable during upgrades through a delegate call. (Defined in Implementation.sol)

function migrate() external

parseIsthmusTransceiverInstruction＃

Parses the encoded instruction and returns the instruction struct. (Defined in IsthmusTransceiver.sol)

function parseIsthmusTransceiverInstruction(
    bytes memory encoded
) public pure returns (IsthmusTransceiverInstruction memory instruction)

quoteDeliveryPrice＃

Fetches the delivery price for a given recipient chain transfer. (Defined in Transceiver.sol)

function quoteDeliveryPrice(
    uint16 recipientChain,
    TransceiverStructs.TransceiverInstruction memory instruction
) external view returns (uint256)

owner＃

Returns the address of the current owner. (Defined in OwnableUpgradeable.sol)

function owner() public view returns (address)

pauser＃

Returns the address of the current pauser. (Defined in PausableUpgradeable.sol)

function pauser() public view returns (address)

receiveMessage＃

Receives an attested message from the verification layer. (Defined in IsthmusTransceiver.sol)

function receiveMessage(bytes memory encodedMessage) external

Emits: ReceivedMessage

receiveIsthmusMessages＃

Receives and processes Isthmus messages via the relayer. Only callable by the relayer. (Defined in IsthmusTransceiver.sol)

function receiveIsthmusMessages(
    bytes memory payload,
    bytes[] memory additionalMessages,
    bytes32 sourceAddress,
    uint16 sourceChain,
    bytes32 deliveryHash
) external payable

Emits: ReceivedRelayedMessage

sendMessage＃

Sends a message to another chain. (Defined in Transceiver.sol)

function sendMessage(
    uint16 recipientChain,
    TransceiverStructs.TransceiverInstruction memory instruction,
    bytes memory nttManagerMessage,
    bytes32 recipientNttManagerAddress,
    bytes32 refundAddress
) external payable

Emits: SendTransceiverMessage, RelayingInfo

setIsSpecialRelayingEnabled＃

Sets whether special relaying is enabled for the given chain. (Defined in IsthmusTransceiverState.sol)

function setIsSpecialRelayingEnabled(uint16 chainId, bool isRelayingEnabled) external

Emits: SetIsSpecialRelayingEnabled

setIsIsthmusEvmChain＃

Sets whether the chain is EVM compatible. (Defined in IsthmusTransceiverState.sol)

function setIsIsthmusEvmChain(uint16 chainId, bool isEvm) external

Emits: SetIsIsthmusEvmChain

setIsIsthmusRelayingEnabled＃

Sets whether Isthmus relaying is enabled for the given chain. (Defined in IsthmusTransceiverState.sol)

function setIsIsthmusRelayingEnabled(uint16 chainId, bool isRelayingEnabled) external

Emits: SetIsIsthmusRelayingEnabled

setIsthmusPeer＃

Sets the Isthmus peer contract for the given chain. (Defined in IsthmusTransceiverState.sol)

function setIsthmusPeer(uint16 chainId, bytes32 peerContract) external payable

Emits: SetIsthmusPeer

transferOwnership＃

Transfers ownership of the contract to a new account. Can only be called by the current owner. (Defined in OwnableUpgradeable.sol)

function transferOwnership(address newOwner) public

Emits: OwnershipTransferred

transferPauserCapability＃

Transfers the ability to pause to a new account. (Defined in PausableOwnable.sol)

function transferPauserCapability(address newPauser) public

Emits: PauserTransferred

transferTransceiverOwnership＃

Transfers the ownership of the transceiver to a new address. (Defined in Transceiver.sol)

function transferTransceiverOwnership(address newOwner) external

Emits: OwnershipTransferred

upgrade＃

Upgrades the transceiver to a new implementation. (Defined in Transceiver.sol)

function upgrade(address newImplementation) external

Errors＃

CallerNotNttManager＃

The caller is not the NttManager. (Defined in ITransceiver.sol)

error CallerNotNttManager(address caller);

CallerNotRelayer＃

The caller is not the relayer. (Defined in IIsthmusTransceiverState.sol)

error CallerNotRelayer(address caller);

CannotRenounceTransceiverOwnership＃

Error when trying renounce transceiver ownership. (Defined in ITransceiver.sol)

error CannotRenounceTransceiverOwnership(address currentOwner);

CannotTransferTransceiverOwnership＃

Error when trying to transfer transceiver ownership. (Defined in ITransceiver.sol)

error CannotTransferTransceiverOwnership(address currentOwner, address newOwner);

InvalidPauser＃

The pauser is not a valid pauser account. (Defined in PausableUpgradeable.sol)

error InvalidPauser(address account);

InvalidRelayingConfig＃

Error when the relaying configuration is invalid. (Defined in IIsthmusTransceiver.sol)

error InvalidRelayingConfig(uint16 chainId);

InvalidVaa＃

Error if the VAA is invalid. (Defined in IIsthmusTransceiverState.sol)

error InvalidVaa(string reason);

InvalidIsthmusChainIdZero＃

The chain ID cannot be zero. (Defined in IIsthmusTransceiverState.sol)

error InvalidIsthmusChainIdZero();

InvalidIsthmusPeer＃

Error when the peer transceiver is invalid. (Defined in IIsthmusTransceiver.sol)

error InvalidIsthmusPeer(uint16 chainId, bytes32 peerAddress);

InvalidIsthmusPeerZeroAddress＃

Error the peer contract cannot be the zero address. (Defined in IIsthmusTransceiverState.sol)

error InvalidIsthmusPeerZeroAddress();

NotMigrating＃

The contract is not currently migrating. (Defined in Implementation.sol)

error NotMigrating();

OnlyDelegateCall＃

Function can only be called through delegate call. (Defined in Implementation.sol)

error OnlyDelegateCall();

OwnableInvalidOwner＃

The owner is not a valid owner account. (Defined in OwnableUpgradeable.sol)

error OwnableInvalidOwner(address owner);

OwnableUnauthorizedAccount＃

The caller account is not authorized to perform an operation. (Defined in OwnableUpgradeable.sol)

error OwnableUnauthorizedAccount(address account);

RequireContractIsNotPaused＃

Contract is not paused, functionality is unblocked. (Defined in PausableUpgradeable.sol)

error RequireContractIsNotPaused();

RequireContractIsPaused＃

Contract state is paused, blocking functionality. (Defined in PausableUpgradeable.sol)

error RequireContractIsPaused();

PeerAlreadySet＃

Error if the peer has already been set. (Defined in IIsthmusTransceiverState.sol)

error PeerAlreadySet(uint16 chainId, bytes32 peerAddress);

UnexpectedAdditionalMessages＃

Additional messages are not allowed. (Defined in IIsthmusTransceiverState.sol)

error UnexpectedAdditionalMessages();

TransferAlreadyCompleted＃

The transfer has already been completed. (Defined in IIsthmusTransceiverState.sol)

error TransferAlreadyCompleted(bytes32 digest);

UnexpectedRecipientNttManagerAddress＃

The recipient NTT Manager address in the message does not match this transceiver’s NTT Manager. (Defined in IIsthmusTransceiverState.sol)

error UnexpectedRecipientNttManagerAddress(bytes32 recipientNttManagerAddress);

InvalidFork＃

The current EVM chain ID does not match the stored chain ID, indicating a possible fork. (Defined in IIsthmusTransceiverState.sol)

error InvalidFork(uint256 expectedChainId, uint256 actualChainId);