📖 Update 🐍Vyper Conventions

Signed-off-by: Pascal Marco Caversaccio <pascal.caversaccio@hotmail.ch>

Author: pcaversaccio

CHANGELOG.md

@@ -52,7 +52,7 @@
 - The contracts `create_address.vy` and `create2_address.vy` have been renamed to `create.vy` and `create2.vy`, respectively. In `create.vy`, the functions `_compute_address_rlp_self`, `_compute_address_rlp`, and `_convert_keccak256_2_address` have been renamed to `_compute_create_address_self`, `_compute_create_address`, and `_convert_keccak256_to_address`. Similarly, in `create2.vy`, the functions `_compute_address_self` and `_compute_address` have been renamed to `_compute_create2_address_self` and `_compute_create2_address`. ([#323](https://github.com/pcaversaccio/snekmate/pull/323))
 - All 🐍 snekmate contracts now target the new 🐍Vyper [default EVM version](https://github.com/vyperlang/vyper/pull/4633) `prague` ([#331](https://github.com/pcaversaccio/snekmate/pull/331)). If you intend to deploy on an EVM chain with no `prague` support, you must compile — using the `cancun` EVM version as an example — the main contract that uses the 🐍 snekmate module contracts with the `--evm-version cancun` option; e.g. `vyper --evm-version cancun src/snekmate/tokens/mocks/erc20_mock.vy`, or add the `# pragma evm-version cancun` directive to the main contract that uses the 🐍 snekmate module contracts:
 
-```vyper
+```vy
 # pragma version ~=0.4.3
 # pragma evm-version cancun
 
@@ -176,7 +176,7 @@
 - The mathematical utility functions `_log_2`, `_log_10`, and `_log_256` are renamed to `_log2`, `_log10`, and `_log256`. ([#242](https://github.com/pcaversaccio/snekmate/pull/242))
 - All 🐍 snekmate contracts now target the new 🐍Vyper [default EVM version](https://github.com/vyperlang/vyper/pull/4029) `cancun` ([#245](https://github.com/pcaversaccio/snekmate/pull/245)). If you intend to deploy on an EVM chain with no `cancun` support, you must compile — using the `shanghai` EVM version as an example — the main contract that uses the 🐍 snekmate module contracts with the `--evm-version shanghai` option; e.g. `vyper --evm-version shanghai src/snekmate/tokens/mocks/erc20_mock.vy`, or add the `# pragma evm-version shanghai` directive to the main contract that uses the 🐍 snekmate module contracts:
 
-```vyper
+```vy
 # pragma version ~=0.4.0
 # pragma evm-version shanghai
 
@@ -254,7 +254,7 @@
 
 - All 🐍 snekmate contracts now target the 🐍Vyper version [`0.3.10`](https://github.com/vyperlang/vyper/releases/tag/v0.3.10) ([#164](https://github.com/pcaversaccio/snekmate/pull/164)). It is strongly recommended to upgrade accordingly your local 🐍Vyper version prior to using the 🐍 snekmate contracts. **Important:** The default EVM version since 🐍Vyper version [`0.3.8`](https://github.com/vyperlang/vyper/releases/tag/v0.3.8) is set to `shanghai` (i.e. the EVM includes the [`PUSH0`](https://eips.ethereum.org/EIPS/eip-3855) instruction). If you intend to deploy on an EVM chain with no `PUSH0` support, you must compile the 🐍 snekmate contracts with the `--evm-version paris` option; e.g. `vyper --evm-version paris utils/Math.vy`, or add the `# pragma evm-version paris` directive to the 🐍 snekmate contracts:
 
-```vyper
+```vy
 # pragma version ^0.3.10
 # pragma evm-version paris
 # pragma optimize gas

GUIDELINES.md

@@ -54,7 +54,7 @@ Branch names do not matter, and commit messages within a PR are mostly not impor
 - The names of `constant`, `immutable`, and state variables, functions, and function parameters use the _snake case_ notation (e.g. `my_function`) if no other notation is enforced via an EIP standard. In particular, `constant` and `immutable` variable names use the _screaming snake case_ notation (e.g. `DEFAULT_CONSTANT`) if no other notation is enforced via an EIP standard.
 - `internal` `constant`, `immutable`, state variables and functions must have an underscore prefix:
 
-```vyper
+```vy
 _SUPPORTED_INTERFACES: constant(bytes4[1]) = [0x01FFC9A7]
 
 _CACHED_DOMAIN_SEPARATOR: immutable(bytes32)
@@ -70,6 +70,21 @@ def _as_singleton_array(element: uint256) -> DynArray[uint256, 1]:
 - Use `internal` functions where feasible to improve composability and modularity.
 - Unchecked arithmetic calculations should contain comments explaining why an overflow/underflow is guaranteed not to occur.
 - Numeric literals should use underscores as thousand separators for readability (e.g., `1_000_000` instead of `1000000`). This applies to large constants, magic numbers, and any literal where readability would be improved.
+- Function decorators must follow this order:
+  1. Visibility: `@external`, `@internal`, or `@deploy`
+  2. Mutability: `@pure`, `@view`, or `@payable` (the 🐍Vyper default mutability `@nonpayable` is always omitted if applicable)
+  3. Nonreentrancy locks: `@nonreentrant`
+  4. Raw return: `@raw_return`
+
+```vy
+@external
+@payable
+@nonreentrant
+@raw_return
+def forward_call(target: address) -> Bytes[1_024]:
+    return raw_call(target, msg.data, max_outsize=1_024, value=msg.value)
+```
+
 - All functions should be provided with full [NatSpec](https://docs.vyperlang.org/en/latest/natspec.html) comments containing the tags `@dev`, `@notice` (if applicable), `@param` for each function parameter, and `@return` if a return statement is present.
 - Please note the following order of layout:
   - Version pragma statement
@@ -81,6 +96,8 @@ def _as_singleton_array(element: uint256) -> DynArray[uint256, 1]:
   - `internal` constants
   - `public` immutables
   - `internal` immutables
+  - `flag` definitions
+  - `struct` definitions
   - `public` state variables
   - `internal` state variables
   - `event` declarations