evm: coreLayer

src/technical/evm/coreLayer.md

@@ -2,65 +2,24 @@
 
 This section will explain how to properly interact with the Wormhome Core Layer in an EVM ecosystem.
 
-# Configuring the Interface
+## Configuring the Interface
 
 - Get the interface from the repo
 - Instantiate it with the core layer contract address for your blockchain. This is dependent on your development ecosystem and blockchain. This value is usually stored in your contract state.
 
-This is the interface for applications to interact with Wormhole's Core Contract to publish messages or verify and parse a received message.
+[Here](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/ethereum/contracts/interfaces/IWormhole.sol) is the interface for applications to interact with Wormhole's Core Contract to publish messages or verify and parse a received message.
 
-//TODO just link to the github repo, in order to avoid stale information
+Instantiating the interface will depend on your development ecosystem and blockchain. The Wormhole Core Layer contract address is usually stored in your contract address. 
 
+Below is an example line of code to instantiate the interface for mainnet Ethereum:
 ```
-// contracts/Messages.sol
-// SPDX-License-Identifier: Apache 2
-
-pragma solidity ^0.8.0;
-
-import "../Structs.sol";
-
-interface IWormhole is Structs {
-    event LogMessagePublished(address indexed sender, uint64 sequence, uint32 nonce, bytes payload, uint8 consistencyLevel);
-
-    function publishMessage(
-        uint32 nonce,
-        bytes memory payload,
-        uint8 consistencyLevel
-    ) external payable returns (uint64 sequence);
-
-    function parseAndVerifyVM(bytes calldata encodedVM) external view returns (Structs.VM memory vm, bool valid, string memory reason);
-
-    function verifyVM(Structs.VM memory vm) external view returns (bool valid, string memory reason);
-
-    function verifySignatures(bytes32 hash, Structs.Signature[] memory signatures, Structs.GuardianSet memory guardianSet) external pure returns (bool valid, string memory reason) ;
-
-    function parseVM(bytes memory encodedVM) external pure returns (Structs.VM memory vm);
-
-    function getGuardianSet(uint32 index) external view returns (Structs.GuardianSet memory) ;
-
-    function getCurrentGuardianSetIndex() external view returns (uint32) ;
-
-    function getGuardianSetExpiry() external view returns (uint32) ;
-
-    function governanceActionIsConsumed(bytes32 hash) external view returns (bool) ;
-
-    function isInitialized(address impl) external view returns (bool) ;
-
-    function chainId() external view returns (uint16) ;
-
-    function governanceChainId() external view returns (uint16);
-
-    function governanceContract() external view returns (bytes32);
-
-    function messageFee() external view returns (uint256) ;
-}
+address private wormhole_core_bridge_address = address(0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B);
+IWormhole core_bridge = IWormhole(wormhole_core_bridge_address);
 ```
 
-//TODO example line of code for instantiating the interface for mainnet Ethereum
-
 ## Primary functions
 
-The Wormhole Core Layer effectively only has two important interactions. The ability to emit messages, and the ability to verify messages which originated from other chains.
+The Wormhole Core Layer effectively only has two important interactions - (1) the ability to emit messages, and (2) the ability to parse and verify messages which originated from other chains.
 
 ### Emitting a Message
 
@@ -68,9 +27,32 @@ The Wormhole Core Layer effectively only has two important interactions. The abi
 - explain every argument
 - be sure to mention batch VAAs
 
-### Verifying a Message
+To emit a message, always use `publishMessage` which takes in the following arguments:
+
+1.  `nonce` (uint32): a number assigned to each message
+    - The `nonce` gives the receving contract a mechanism by which to make sure it does not double process messages
+    - Batch VAAs allow for  easier compsability and better gas efficiency of multiple messages. To do this, messages emitted within the same transaction with the same nonce are bundled together into one aggregate message. Messages with a nonce of `0` will not be included in a Batch VAA and emitted individually.
+2. `Consistency` (uint8): the number of blocks that Guardians will wait before signing a message.
+    - Each blockchain has different finality periods. In general, higher consistencies mean more security against blockchain reorgs.
+    - [Here]() are the consistency levels by blockchain that are used by the xAsset layer to have a high level of guarantee against reorgs.
+3. `Payload` (bytes[]): raw bytes to emit.
+    - It is up to the receiving contract to properly parse this arbitrary set of bytes.
+
+`publishMessage` will output a `sequence` (uint64) that is used in conjunction with `emitterChainID` and `emitterAddress` to retrive the generated VAA from the Guardian Network.
+
+### Parsing and Verifying a Message
 
 - Explain how a message should be taken in as a byte array
 - Be cognizant of Batch VAAs vs Single VAAs
 - entrypoint code vs module code. If using single VAAs, these are the same, but batch VAAs are more complicated to verify
 - remember to collect your gas after all the VAAs have been verified
+
+Parsing and Verifying a message will depend on the type of VAA that your application expects: a Single VAA or a Batch VAA.
+
+**Single VAA**
+
+The properly parse and verify a single VAA, always use `parseAndVerifyVM` which takes in one argument: `encodedVM`. This function will return three arguments:
+
+1. `vm` (VM): Structured data that reflects the content of the VAA. A breakdown of this message format is described in the [VAA](../../wormhole/4_vaa.md) section.
+2. `valid` (bool):  Boolean that reflects whether or not the VAA was properly signed by the Guardian Network
+3. `reason` (string): Explanatory error message if a VAA is invalid, or an empty string if it is valid.