docs: current wire formats

Author: evan-gray

.gitignore

@@ -8,9 +8,6 @@ target/
 /broadcast/*/31337/
 /broadcast/**/dry-run/
 
-# Docs
-docs/
-
 # Dotenv file
 .env
 

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.
 
 <figure>
   <img src="images/ntt_architecture__with_custom_attestation.jpg" alt="NTT Architecture Diagram">
   <figcaption>Figure: NTT Architecture Diagram with Custom Attestations.</figcaption>
 </figure>
 
-
 ## 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!

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
+```

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
+```