Skip to content

N
nebula
Commit eb11a5bb authored by smartcontracts's avatar smartcontracts Committed by GitHub
Browse files
Options

style(ctb): clean up RLP lib natspec (#2973) 

Co-authored-by: default avatarmergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
parent 6ff5c0a3
Hide whitespace changes
Inline Side-by-side
Showing with 117 additions and 62 deletions
.changeset/lucky-parents-deliver.md 0 → 100644
View file @ eb11a5bb
---
'@eth-optimism/contracts-bedrock': patch
---
Add comments to RLP libraries
packages/contracts-bedrock/contracts/libraries/rlp/RLPReader.sol
View file @ eb11a5bb
......@@ -2,41 +2,42 @@
pragma solidity ^0.8.9;
/**
* @custom:attribution https://github.com/hamdiallam/Solidity-RLP
* @title RLPReader
* @dev Adapted from "RLPReader" by Hamdi Allam (hamdi.allam97@gmail.com).
* @notice RLPReader is a library for parsing RLP-encoded byte arrays into Solidity types. Adapted
* from Solidity-RLP (https://github.com/hamdiallam/Solidity-RLP) by Hamdi Allam with
* various tweaks to improve readability.
*/
library RLPReader {
/*************
* Constants *
*************/
/**
* @notice Max list length that this library will accept.
*/
uint256 internal constant MAX_LIST_LENGTH = 32;
/*********
* Enums *
*********/
/**
* @notice RLP item types.
*
* @custom:value DATA_ITEM Represents an RLP data item (NOT a list).
* @custom:value LIST_ITEM Represents an RLP list item.
*/
enum RLPItemType {
DATA_ITEM,
LIST_ITEM
}
/***********
* Structs *
***********/
/**
* @notice Struct representing an RLP item.
*/
struct RLPItem {
uint256 length;
uint256 ptr;
}
/**********************
* Internal Functions *
**********************/
/**
* Converts bytes to a reference to memory position and length.
* @notice Converts bytes to a reference to memory position and length.
*
* @param _in Input bytes to convert.
*
* @return Output memory reference.
*/
function toRLPItem(bytes memory _in) internal pure returns (RLPItem memory) {
......@@ -49,8 +50,10 @@ library RLPReader {
}
/**
* Reads an RLP list value into a list of RLP items.
* @notice Reads an RLP list value into a list of RLP items.
*
* @param _in RLP list value.
*
* @return Decoded RLP list items.
*/
function readList(RLPItem memory _in) internal pure returns (RLPItem[] memory) {
......@@ -88,8 +91,10 @@ library RLPReader {
}
/**
* Reads an RLP list value into a list of RLP items.
* @notice Reads an RLP list value into a list of RLP items.
*
* @param _in RLP list value.
*
* @return Decoded RLP list items.
*/
function readList(bytes memory _in) internal pure returns (RLPItem[] memory) {
......@@ -97,8 +102,10 @@ library RLPReader {
}
/**
* Reads an RLP bytes value into bytes.
* @notice Reads an RLP bytes value into bytes.
*
* @param _in RLP bytes value.
*
* @return Decoded bytes.
*/
function readBytes(RLPItem memory _in) internal pure returns (bytes memory) {
......@@ -110,8 +117,10 @@ library RLPReader {
}
/**
* Reads an RLP bytes value into bytes.
* @notice Reads an RLP bytes value into bytes.
*
* @param _in RLP bytes value.
*
* @return Decoded bytes.
*/
function readBytes(bytes memory _in) internal pure returns (bytes memory) {
......@@ -119,8 +128,10 @@ library RLPReader {
}
/**
* Reads an RLP string value into a string.
* @notice Reads an RLP string value into a string.
*
* @param _in RLP string value.
*
* @return Decoded string.
*/
function readString(RLPItem memory _in) internal pure returns (string memory) {
......@@ -128,8 +139,10 @@ library RLPReader {
}
/**
* Reads an RLP string value into a string.
* @notice Reads an RLP string value into a string.
*
* @param _in RLP string value.
*
* @return Decoded string.
*/
function readString(bytes memory _in) internal pure returns (string memory) {
......@@ -137,8 +150,10 @@ library RLPReader {
}
/**
* Reads an RLP bytes32 value into a bytes32.
* @notice Reads an RLP bytes32 value into a bytes32.
*
* @param _in RLP bytes32 value.
*
* @return Decoded bytes32.
*/
function readBytes32(RLPItem memory _in) internal pure returns (bytes32) {
......@@ -163,8 +178,10 @@ library RLPReader {
}
/**
* Reads an RLP bytes32 value into a bytes32.
* @notice Reads an RLP bytes32 value into a bytes32.
*
* @param _in RLP bytes32 value.
*
* @return Decoded bytes32.
*/
function readBytes32(bytes memory _in) internal pure returns (bytes32) {
......@@ -172,8 +189,10 @@ library RLPReader {
}
/**
* Reads an RLP uint256 value into a uint256.
* @notice Reads an RLP uint256 value into a uint256.
*
* @param _in RLP uint256 value.
*
* @return Decoded uint256.
*/
function readUint256(RLPItem memory _in) internal pure returns (uint256) {
......@@ -181,8 +200,10 @@ library RLPReader {
}
/**
* Reads an RLP uint256 value into a uint256.
* @notice Reads an RLP uint256 value into a uint256.
*
* @param _in RLP uint256 value.
*
* @return Decoded uint256.
*/
function readUint256(bytes memory _in) internal pure returns (uint256) {
......@@ -190,8 +211,10 @@ library RLPReader {
}
/**
* Reads an RLP bool value into a bool.
* @notice Reads an RLP bool value into a bool.
*
* @param _in RLP bool value.
*
* @return Decoded bool.
*/
function readBool(RLPItem memory _in) internal pure returns (bool) {
......@@ -209,8 +232,10 @@ library RLPReader {
}
/**
* Reads an RLP bool value into a bool.
* @notice Reads an RLP bool value into a bool.
*
* @param _in RLP bool value.
*
* @return Decoded bool.
*/
function readBool(bytes memory _in) internal pure returns (bool) {
......@@ -218,8 +243,10 @@ library RLPReader {
}
/**
* Reads an RLP address value into a address.
* @notice Reads an RLP address value into a address.
*
* @param _in RLP address value.
*
* @return Decoded address.
*/
function readAddress(RLPItem memory _in) internal pure returns (address) {
......@@ -233,8 +260,10 @@ library RLPReader {
}
/**
* Reads an RLP address value into a address.
* @notice Reads an RLP address value into a address.
*
* @param _in RLP address value.
*
* @return Decoded address.
*/
function readAddress(bytes memory _in) internal pure returns (address) {
......@@ -242,8 +271,10 @@ library RLPReader {
}
/**
* Reads the raw bytes of an RLP item.
* @notice Reads the raw bytes of an RLP item.
*
* @param _in RLP item to read.
*
* @return Raw RLP bytes.
*/
function readRawBytes(RLPItem memory _in) internal pure returns (bytes memory) {
......@@ -255,8 +286,10 @@ library RLPReader {
*********************/
/**
* Decodes the length of an RLP item.
* @notice Decodes the length of an RLP item.
*
* @param _in RLP item to decode.
*
* @return Offset of the encoded data.
* @return Length of the encoded data.
* @return RLP item type (LIST_ITEM or DATA_ITEM).
......@@ -333,10 +366,12 @@ library RLPReader {
}
/**
* Copies the bytes from a memory location.
* @param _src Pointer to the location to read from.
* @notice Copies the bytes from a memory location.
*
* @param _src Pointer to the location to read from.
* @param _offset Offset to start reading from.
* @param _length Number of bytes to read.
*
* @return Copied bytes.
*/
function _copy(
......@@ -378,8 +413,10 @@ library RLPReader {
}
/**
* Copies an RLP item into bytes.
* @notice Copies an RLP item into bytes.
*
* @param _in RLP item to copy.
*
* @return Copied bytes.
*/
function _copy(RLPItem memory _in) private pure returns (bytes memory) {
......
packages/contracts-bedrock/contracts/libraries/rlp/RLPWriter.sol
View file @ eb11a5bb
......@@ -2,17 +2,18 @@
pragma solidity ^0.8.9;
/**
* @custom:attribution https://github.com/bakaoh/solidity-rlp-encode
* @title RLPWriter
* @author Bakaoh (with modifications)
* @author RLPWriter is a library for encoding Solidity types to RLP bytes. Adapted from Bakaoh's
* RLPEncode library (https://github.com/bakaoh/solidity-rlp-encode) with minor
* modifications to improve legibility.
*/
library RLPWriter {
/**********************
* Internal Functions *
**********************/
/**
* RLP encodes a byte string.
* @notice RLP encodes a byte string.
*
* @param _in The byte string to encode.
*
* @return The RLP encoded string in bytes.
*/
function writeBytes(bytes memory _in) internal pure returns (bytes memory) {
......@@ -28,8 +29,10 @@ library RLPWriter {
}
/**
* RLP encodes a list of RLP encoded byte byte strings.
* @notice RLP encodes a list of RLP encoded byte byte strings.
*
* @param _in The list of RLP encoded byte strings.
*
* @return The RLP encoded list of items in bytes.
*/
function writeList(bytes[] memory _in) internal pure returns (bytes memory) {
......@@ -38,8 +41,10 @@ library RLPWriter {
}
/**
* RLP encodes a string.
* @notice RLP encodes a string.
*
* @param _in The string to encode.
*
* @return The RLP encoded string in bytes.
*/
function writeString(string memory _in) internal pure returns (bytes memory) {
......@@ -47,8 +52,10 @@ library RLPWriter {
}
/**
* RLP encodes an address.
* @notice RLP encodes an address.
*
* @param _in The address to encode.
*
* @return The RLP encoded address in bytes.
*/
function writeAddress(address _in) internal pure returns (bytes memory) {
......@@ -56,8 +63,10 @@ library RLPWriter {
}
/**
* RLP encodes a uint.
* @notice RLP encodes a uint.
*
* @param _in The uint256 to encode.
*
* @return The RLP encoded uint256 in bytes.
*/
function writeUint(uint256 _in) internal pure returns (bytes memory) {
......@@ -65,8 +74,10 @@ library RLPWriter {
}
/**
* RLP encodes a bool.
* @notice RLP encodes a bool.
*
* @param _in The bool to encode.
*
* @return The RLP encoded bool in bytes.
*/
function writeBool(bool _in) internal pure returns (bytes memory) {
......@@ -75,14 +86,12 @@ library RLPWriter {
return encoded;
}
/*********************
* Private Functions *
*********************/
/**
* Encode the first byte, followed by the `len` in binary form if `length` is more than 55.
* @param _len The length of the string or the payload.
* @notice Encode the first byte and then the `len` in binary form if `length` is more than 55.
*
* @param _len The length of the string or the payload.
* @param _offset 128 if item is string, 192 if item is list.
*
* @return RLP encoded bytes.
*/
function _writeLength(uint256 _len, uint256 _offset) private pure returns (bytes memory) {
......@@ -110,9 +119,10 @@ library RLPWriter {
}
/**
* Encode integer in big endian binary form with no leading zeroes.
* @notice TODO: This should be optimized with assembly to save gas costs.
* @notice Encode integer in big endian binary form with no leading zeroes.
*
* @param _x The integer to encode.
*
* @return RLP encoded bytes.
*/
function _toBinary(uint256 _x) private pure returns (bytes memory) {
......@@ -134,11 +144,12 @@ library RLPWriter {
}
/**
* Copies a piece of memory to another location.
* @notice From: https://github.com/Arachnid/solidity-stringutils/blob/master/src/strings.sol.
* @custom:attribution https://github.com/Arachnid/solidity-stringutils
* @notice Copies a piece of memory to another location.
*
* @param _dest Destination location.
* @param _src Source location.
* @param _len Length of memory to copy.
* @param _src Source location.
* @param _len Length of memory to copy.
*/
function _memcpy(
uint256 _dest,
......@@ -169,9 +180,11 @@ library RLPWriter {
}
/**
* Flattens a list of byte strings into one byte string.
* @notice From: https://github.com/sammayo/solidity-rlp-encoder/blob/master/RLPEncode.sol.
* @custom:attribution https://github.com/sammayo/solidity-rlp-encoder
* @notice Flattens a list of byte strings into one byte string.
*
* @param _list List of byte strings to flatten.
*
* @return The flattened byte string.
*/
function _flatten(bytes[] memory _list) private pure returns (bytes memory) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment