From 50bc737028dc2eb485681c7508f850b24346c04a Mon Sep 17 00:00:00 2001 From: Evan Gray Date: Fri, 20 Sep 2024 09:43:27 -0400 Subject: [PATCH] docs: current wire formats --- .gitignore | 3 --- README.md | 9 ++++---- docs/NttManager.md | 29 +++++++++++++++++++++++ docs/Transceiver.md | 56 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 89 insertions(+), 8 deletions(-) create mode 100644 docs/NttManager.md create mode 100644 docs/Transceiver.md diff --git a/.gitignore b/.gitignore index 66bf627c0..020952138 100644 --- a/.gitignore +++ b/.gitignore @@ -8,9 +8,6 @@ target/ /broadcast/*/31337/ /broadcast/**/dry-run/ -# Docs -docs/ - # Dotenv file .env diff --git a/README.md b/README.md index 4b7d51d44..891356699 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,15 @@ Wormhole’s Native Token Transfers (NTT) is an open, flexible, and composable f There are two basic components to NTT: -(1) **Transceiver**: This contract is responsible for sending NTT transfers forwarded through the `NttManager` on the source chain and delivered to a corresponding peer `NttManager` on the recipient chain. Transceivers should follow the `ITransceiver` interface. Transceivers can be defined independently of Wormhole core and can be modified to support any verification backend. - -(2) **NttManager**: The NttManager contract is responsible for managing the token and the Transceivers. It also handles the rate-limiting and the message attestation logic. Note that each `NttManager` corresponds to a single token. However, a single `NttManager` can can control multiple transceivers. +(1) **Transceiver**: This contract is responsible for sending NTT transfers forwarded through the `NttManager` on the source chain and delivered to a corresponding peer `NttManager` on the recipient chain. Transceivers should follow the `ITransceiver` interface. Transceivers can be defined independently of Wormhole core and can be modified to support any verification backend. See [docs/Transceiver.md](./docs/Transceiver.md) for more info. +(2) **NttManager**: The NttManager contract is responsible for managing the token and the Transceivers. It also handles the rate-limiting and the message attestation logic. Note that each `NttManager` corresponds to a single token. However, a single `NttManager` can control multiple transceivers. See [docs/NttManager.md](./docs/NttManager.md) for more info.
NTT Architecture Diagram
Figure: NTT Architecture Diagram with Custom Attestations.
- ## Amount trimming In the payload, amounts are encoded as unsigned 64 bit integers, and capped at the configured `TRIMMED_DECIMALS` (e.g. 8) decimal value. @@ -52,5 +50,6 @@ The action identifier specifies the runtime. Currently, these are as follows: - 1: evm - 2: solana -___ +--- + ⚠️ **WARNING:** Ensure that if the `NttManager` on the source chain is configured to be in `LOCKING` mode, the corresponding `NttManager`s on the target chains are configured to be in `BURNING` mode. If not, transfers will NOT go through and user funds may be lost! Proceed with caution! diff --git a/docs/NttManager.md b/docs/NttManager.md new file mode 100644 index 000000000..5311e3ebb --- /dev/null +++ b/docs/NttManager.md @@ -0,0 +1,29 @@ +# NTT Manager + +## Overview + +The NttManager contract is responsible for managing the token and the Transceivers. It also handles the rate-limiting and the message attestation logic. Note that each `NttManager` corresponds to a single token. However, a single `NttManager` can control multiple transceivers. + +## Message Specification + +NttManagers do not directly publish messages. These will be wrapped in a [TransceiverMessage](./Transceiver.md#transceivermessage). + +```go +[32]byte id // a unique message identifier +[32]byte sender // original message sender address +uint16 payload_len // length of the payload +[]byte payload +``` + +### Payloads + +#### NativeTokenTransfer + +```go +[4]byte prefix = 0x994E5454 // 0x99'N''T''T' +uint8 decimals // number of decimals for the amount +uint64 amount // amount being transferred +[32]byte source_token // source chain token address +[32]byte recipient_address // the address of the recipient +uint16 recipient_chain // the Wormhole Chain ID of the recipient +``` diff --git a/docs/Transceiver.md b/docs/Transceiver.md new file mode 100644 index 000000000..4d4839b53 --- /dev/null +++ b/docs/Transceiver.md @@ -0,0 +1,56 @@ +# Transceiver + +## Overview + +The Transceiver is intended to offer a protocol-agnostic interface for sending and receiving cross-chain messages. For Native Token Transfers, this entails initiating attestation generation on the source chain, verifying the resulting attestation on the destination chain, and delivering the message to the associated `NttManager`. + +In the provided implementations ([EVM](/evm/src/Transceiver/Transceiver.sol)/[SVM](/solana/programs/example-native-token-transfers/src/transceivers/wormhole/)), Transceiver are intended to have a many-to-one or one-to-one relationship with Managers. + +## Message Specification + +### TransceiverMessage + +NttManager message emitted by a Transceiver implementation. Each message includes a Transceiver-specified 4-byte prefix. This should be a constant value, set by a protocol-specific Transceiver implementation, that identifies the payload as an NTT Transceiver emitted payload. + +```go +[4]byte prefix +[32]byte source_ntt_manager_address +[32]byte recipient_ntt_manager_address +uint16 ntt_manager_payload_length +[]byte ntt_manager_payload +uint16 transceiver_payload_length +[]byte transceiver_payload +``` + +### Wormhole Transceiver + +#### TransceiverMessage + +```go +prefix = 0x9945FF10 // 0x99'E''W''H' +``` + +#### Initialize Transceiver + +```go +[4]byte prefix = 0x9c23bd3b // bytes4(keccak256("WormholeTransceiverInit")) +[32]byte ntt_manager_address // address of the associated manager +uint8 ntt_manager_mode // the locking/burning mode of the associated manager +[32]byte token_address // address of the associated manager's token +uint8 token_decimals // the number of decimals for that token +``` + +Mode is an enum. + +``` +Locking = 0 +Burning = 1 +``` + +#### Transceiver (Peer) Registration + +```go +[4]byte prefix = 0x18fc67c2 // bytes4(keccak256("WormholePeerRegistration")) +uint16 peer_chain_id // Wormhole Chain ID of the foreign peer transceiver +[32]byte peer_address // the address of the foreign peer transceiver +```