vacp2p/linea-monorepo
1
0
Fork 0
mirror of https://github.com/vacp2p/linea-monorepo.git synced 2026-01-09 20:27:58 -05:00
Code Issues Packages Projects Releases Wiki Activity

[Fix] - L-03 - Add better explicit docstrings (#307)

Browse Source 
* add better explicit docstrings

* additional docstrings for completeness

* tweak natspec

* use required vs require in natspec
This commit is contained in:
The Dark Jester
2024-11-21 10:19:10 +00:00
committed by GitHub
parent 5aa86d6b6a
commit 7a6b981660
13 changed files with 95 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
contracts/contracts/LineaRollup.sol
View File

@@ -24,11 +24,16 @@ contract LineaRollup is
{
using Utils for *;
/// @dev This is the ABI version and not the reinitialize version.
/// @notice This is the ABI version and not the reinitialize version.
string public constant CONTRACT_VERSION = "6.0";
/// @notice The role required to set/add proof verifiers by type.
bytes32 public constant VERIFIER_SETTER_ROLE = keccak256("VERIFIER_SETTER_ROLE");
/// @notice The role required to set/remove proof verifiers by type.
bytes32 public constant VERIFIER_UNSETTER_ROLE = keccak256("VERIFIER_UNSETTER_ROLE");
/// @notice The default genesis shnarf using empty/default hashes and a default state.
bytes32 public constant GENESIS_SHNARF =
keccak256(
abi.encode(
@@ -40,14 +45,26 @@ contract LineaRollup is
)
);
/// @dev Value indicating a shnarf exists.
uint256 internal constant SHNARF_EXISTS_DEFAULT_VALUE = 1;
/// @dev The default hash value.
bytes32 internal constant EMPTY_HASH = 0x0;
/// @dev The BLS Curve modulus value used.
uint256 internal constant BLS_CURVE_MODULUS =
52435875175126190479447740508185965837690552500527637822603658699938581184513;
/// @dev The well-known precompile address for point evaluation.
address internal constant POINT_EVALUATION_PRECOMPILE_ADDRESS = address(0x0a);
/// @dev The expected point evaluation return data length.
uint256 internal constant POINT_EVALUATION_RETURN_DATA_LENGTH = 64;
/// @dev The expected point evaluation field element length returned.
uint256 internal constant POINT_EVALUATION_FIELD_ELEMENTS_LENGTH = 4096;
/// @dev In practice, when used, this is expected to be a close approximation to 6 months, and is intentional.
uint256 internal constant SIX_MONTHS_IN_SECONDS = (365 / 2) * 24 * 60 * 60;
/// @dev DEPRECATED in favor of the single blobShnarfExists mapping.
@@ -66,6 +83,7 @@ contract LineaRollup is
/// @dev DEPRECATED in favor of currentFinalizedState hash.
bytes32 public currentL2StoredL1RollingHash;
/// @notice Contains the most recent finalized shnarf.
bytes32 public currentFinalizedShnarf;
/**
@@ -74,10 +92,10 @@ contract LineaRollup is
*/
mapping(bytes32 shnarf => uint256 exists) public blobShnarfExists;
/// @dev Hash of the L2 computed L1 message number, rolling hash and finalized timestamp.
/// @notice Hash of the L2 computed L1 message number, rolling hash and finalized timestamp.
bytes32 public currentFinalizedState;
/// @dev The address of the fallback operator.
/// @notice The address of the fallback operator.
/// @dev This address is granted the OPERATOR_ROLE after six months of finalization inactivity by the current operators.
address public fallbackOperator;

4
contracts/contracts/ZkEvmV2.sol
View File

@@ -18,9 +18,13 @@ abstract contract ZkEvmV2 is Initializable, AccessControlUpgradeable, L1MessageS
/// @dev DEPRECATED in favor of currentFinalizedState hash.
uint256 public currentTimestamp;
/// @notice The most recent finalized L2 block number.
uint256 public currentL2BlockNumber;
/// @notice The most recent L2 state root hash mapped by block number.
mapping(uint256 blockNumber => bytes32 stateRootHash) public stateRootHashes;
/// @notice The verifier address to use for a proof type when proving.
mapping(uint256 proofType => address verifierAddress) public verifiers;
/// @dev Total contract storage is 54 slots with the gap below.

7
contracts/contracts/lib/L2MessageServicePauseManager.sol
View File

@@ -9,8 +9,15 @@ import { PauseManager } from "./PauseManager.sol";
* @custom:security-contact security-report@linea.build
*/
abstract contract L2MessageServicePauseManager is PauseManager {
/// @notice This is used to pause L1 to L2 communication.
bytes32 public constant PAUSE_L1_L2_ROLE = keccak256("PAUSE_L1_L2_ROLE");
/// @notice This is used to unpause L1 to L2 communication.
bytes32 public constant UNPAUSE_L1_L2_ROLE = keccak256("UNPAUSE_L1_L2_ROLE");
/// @notice This is used to pause L2 to L1 communication.
bytes32 public constant PAUSE_L2_L1_ROLE = keccak256("PAUSE_L2_L1_ROLE");
/// @notice This is used to unpause L2 to L1 communication.
bytes32 public constant UNPAUSE_L2_L1_ROLE = keccak256("UNPAUSE_L2_L1_ROLE");
}

15
contracts/contracts/lib/LineaRollupPauseManager.sol
View File

@@ -9,12 +9,27 @@ import { PauseManager } from "./PauseManager.sol";
* @custom:security-contact security-report@linea.build
*/
abstract contract LineaRollupPauseManager is PauseManager {
/// @notice This is used to pause L1 to L2 communication.
bytes32 public constant PAUSE_L1_L2_ROLE = keccak256("PAUSE_L1_L2_ROLE");
/// @notice This is used to unpause L1 to L2 communication.
bytes32 public constant UNPAUSE_L1_L2_ROLE = keccak256("UNPAUSE_L1_L2_ROLE");
/// @notice This is used to pause L2 to L1 communication.
bytes32 public constant PAUSE_L2_L1_ROLE = keccak256("PAUSE_L2_L1_ROLE");
/// @notice This is used to unpause L2 to L1 communication.
bytes32 public constant UNPAUSE_L2_L1_ROLE = keccak256("UNPAUSE_L2_L1_ROLE");
/// @notice This is used to pause blob submission.
bytes32 public constant PAUSE_BLOB_SUBMISSION_ROLE = keccak256("PAUSE_BLOB_SUBMISSION_ROLE");
/// @notice This is used to unpause blob submission.
bytes32 public constant UNPAUSE_BLOB_SUBMISSION_ROLE = keccak256("UNPAUSE_BLOB_SUBMISSION_ROLE");
/// @notice This is used to pause finalization submission.
bytes32 public constant PAUSE_FINALIZATION_ROLE = keccak256("PAUSE_FINALIZATION_ROLE");
/// @notice This is used to unpause finalization submission.
bytes32 public constant UNPAUSE_FINALIZATION_ROLE = keccak256("UNPAUSE_FINALIZATION_ROLE");
}

8
contracts/contracts/lib/PauseManager.sol
View File

@@ -11,14 +11,22 @@ import { IPauseManager } from "../interfaces/IPauseManager.sol";
* @custom:security-contact security-report@linea.build
*/
abstract contract PauseManager is Initializable, IPauseManager, AccessControlUpgradeable {
/// @notice This is used to pause all pausable functions.
bytes32 public constant PAUSE_ALL_ROLE = keccak256("PAUSE_ALL_ROLE");
/// @notice This is used to unpause all unpausable functions.
bytes32 public constant UNPAUSE_ALL_ROLE = keccak256("UNPAUSE_ALL_ROLE");
// @dev DEPRECATED. USE _pauseTypeStatusesBitMap INSTEAD
mapping(bytes32 pauseType => bool pauseStatus) public pauseTypeStatuses;
/// @dev The bitmap containing the pause statuses mapped by type.
uint256 private _pauseTypeStatusesBitMap;
/// @dev This maps the pause type to the role that is allowed to pause it.
mapping(PauseType pauseType => bytes32 role) private _pauseTypeRoles;
/// @dev This maps the unpause type to the role that is allowed to unpause it.
mapping(PauseType unPauseType => bytes32 role) private _unPauseTypeRoles;
/// @dev Total contract storage is 11 slots with the gap below.

3
contracts/contracts/messageService/MessageServiceBase.sol
View File

@@ -11,7 +11,10 @@ import { IGenericErrors } from "../interfaces/IGenericErrors.sol";
* @custom:security-contact security-report@linea.build
*/
abstract contract MessageServiceBase is Initializable, IGenericErrors {
/// @notice The message service address on the current chain.
IMessageService public messageService;
/// @notice The token bridge on the alternate/remote chain.
address public remoteSender;
/// @dev Total contract storage is 12 slots with the gap below.

5
contracts/contracts/messageService/l1/L1MessageManager.sol
View File

@@ -15,8 +15,13 @@ abstract contract L1MessageManager is L1MessageManagerV1, IL1MessageManager {
using BitMaps for BitMaps.BitMap;
using Utils for *;
/// @notice Contains the L1 to L2 messaging rolling hashes mapped to message number computed on L1.
mapping(uint256 messageNumber => bytes32 rollingHash) public rollingHashes;
/// @notice This maps which message numbers have been claimed to prevent duplicate claiming.
BitMaps.BitMap internal _messageClaimedBitMap;
/// @notice Contains the L2 messages Merkle roots mapped to their tree depth.
mapping(bytes32 merkleRoot => uint256 treeDepth) public l2MerkleRootsDepths;
/// @dev Total contract storage is 53 slots including the gap below.

2
contracts/contracts/messageService/l1/v1/L1MessageManagerV1.sol
View File

@@ -9,9 +9,11 @@ import { IL1MessageManagerV1 } from "../../../interfaces/l1/IL1MessageManagerV1.
* @custom:security-contact security-report@linea.build
*/
abstract contract L1MessageManagerV1 is IL1MessageManagerV1 {
/// @notice The 2 legacy status constants for message statuses.
uint8 public constant INBOX_STATUS_UNKNOWN = 0;
uint8 public constant INBOX_STATUS_RECEIVED = 1;
/// @notice The 3 legacy status constants for message statuses.
uint8 public constant OUTBOX_STATUS_UNKNOWN = 0;
uint8 public constant OUTBOX_STATUS_SENT = 1;
uint8 public constant OUTBOX_STATUS_RECEIVED = 2;

2
contracts/contracts/messageService/l1/v1/L1MessageServiceV1.sol
View File

@@ -38,9 +38,11 @@ abstract contract L1MessageServiceV1 is
/// @dev adding these should not affect storage as they are constants and are stored in bytecode.
uint256 internal constant REFUND_OVERHEAD_IN_GAS = 48252;
/// @dev The transient storage key to set the message sender against while claiming.
bytes32 internal constant MESSAGE_SENDER_TRANSIENT_KEY =
bytes32(uint256(keccak256("eip1967.message.sender.transient.key")) - 1);
/// @notice The default value for the message sender reset to post claiming using the MESSAGE_SENDER_TRANSIENT_KEY.
address internal constant DEFAULT_MESSAGE_SENDER_TRANSIENT_VALUE = address(0);
/**

4
contracts/contracts/messageService/l2/L2MessageManager.sol
View File

@@ -14,9 +14,13 @@ import { Utils } from "../../lib/Utils.sol";
abstract contract L2MessageManager is AccessControlUpgradeable, IL2MessageManager, L2MessageManagerV1 {
using Utils for *;
/// @notice The role required to anchor L1 to L2 message hashes.
bytes32 public constant L1_L2_MESSAGE_SETTER_ROLE = keccak256("L1_L2_MESSAGE_SETTER_ROLE");
/// @notice Contains the last L1 message number anchored on L2.
uint256 public lastAnchoredL1MessageNumber;
/// @notice Contains the L1 to L2 messaging rolling hashes mapped to message number computed on L2.
mapping(uint256 messageNumber => bytes32 rollingHash) public l1RollingHashes;
/// @dev Total contract storage is 52 slots including the gap below.

1
contracts/contracts/messageService/l2/v1/L2MessageManagerV1.sol
View File

@@ -11,6 +11,7 @@ import { L2MessageServicePauseManager } from "../../../lib/L2MessageServicePause
* @custom:security-contact security-report@linea.build
*/
abstract contract L2MessageManagerV1 is Initializable, L2MessageServicePauseManager, IL2MessageManagerV1 {
/// @notice The 3 status constants for L1 to L2 message statuses.
uint8 public constant INBOX_STATUS_UNKNOWN = 0;
uint8 public constant INBOX_STATUS_RECEIVED = 1;
uint8 public constant INBOX_STATUS_CLAIMED = 2;

7
contracts/contracts/messageService/l2/v1/L2MessageServiceV1.sol
View File

@@ -33,19 +33,22 @@ abstract contract L2MessageServiceV1 is
*/
uint256[50] private __gap_L2MessageService;
/// @notice The role required to set the minimum DDOS fee.
bytes32 public constant MINIMUM_FEE_SETTER_ROLE = keccak256("MINIMUM_FEE_SETTER_ROLE");
/// @dev The temporary message sender set when claiming a message.
address internal _messageSender;
// @dev initialize to save user cost with existing slot.
// @notice initialize to save user cost with existing slot.
uint256 public nextMessageNumber;
// @dev initialize minimumFeeInWei variable.
// @notice initialize minimumFeeInWei variable.
uint256 public minimumFeeInWei;
// @dev adding these should not affect storage as they are constants and are stored in bytecode.
uint256 internal constant REFUND_OVERHEAD_IN_GAS = 44596;
/// @dev The default message sender address reset after claiming a message.
address internal constant DEFAULT_SENDER_ADDRESS = address(123456789);
/// @dev Total contract storage is 53 slots including the gap above. NB: Above!

21
contracts/contracts/tokenBridge/TokenBridge.sol
View File

@@ -44,10 +44,19 @@ contract TokenBridge is
/// @dev This is the ABI version and not the reinitialize version.
string public constant CONTRACT_VERSION = "1.0";
/// @notice Role used for setting the message service address.
bytes32 public constant SET_MESSAGE_SERVICE_ROLE = keccak256("SET_MESSAGE_SERVICE_ROLE");
/// @notice Role used for setting the remote token bridge address.
bytes32 public constant SET_REMOTE_TOKENBRIDGE_ROLE = keccak256("SET_REMOTE_TOKENBRIDGE_ROLE");
/// @notice Role used for setting a reserved token address.
bytes32 public constant SET_RESERVED_TOKEN_ROLE = keccak256("SET_RESERVED_TOKEN_ROLE");
/// @notice Role used for removing a reserved token address.
bytes32 public constant REMOVE_RESERVED_TOKEN_ROLE = keccak256("REMOVE_RESERVED_TOKEN_ROLE");
/// @notice Role used for setting a custom token contract address.
bytes32 public constant SET_CUSTOM_CONTRACT_ROLE = keccak256("SET_CUSTOM_CONTRACT_ROLE");
// Special addresses used in the mappings to mark specific states for tokens.
@@ -61,21 +70,27 @@ contract TokenBridge is
address internal constant DEPLOYED_STATUS = address(0x333);
// solhint-disable-next-line var-name-mixedcase
/// @dev The permit selector to be used when decoding the permit.
bytes4 internal constant _PERMIT_SELECTOR = IERC20PermitUpgradeable.permit.selector;
/// @notice used for the token metadata
/// @notice These 3 variables are used for the token metadata.
bytes private constant METADATA_NAME = abi.encodeCall(IERC20MetadataUpgradeable.name, ());
bytes private constant METADATA_SYMBOL = abi.encodeCall(IERC20MetadataUpgradeable.symbol, ());
bytes private constant METADATA_DECIMALS = abi.encodeCall(IERC20MetadataUpgradeable.decimals, ());
/// @notice The token beacon for deployed tokens.
address public tokenBeacon;
/// @notice The chainId mapped to a native token address which is then mapped to the bridged token address.
mapping(uint256 chainId => mapping(address native => address bridged)) public nativeToBridgedToken;
/// @notice The bridged token address mapped to the native token address.
mapping(address bridged => address native) public bridgedToNativeToken;
/// @notice The current layer chainId from where the bridging is triggered
/// @notice The current layer's chainId from where the bridging is triggered.
uint256 public sourceChainId;
/// @notice The targeted layer chainId where the bridging is received
/// @notice The targeted layer's chainId where the bridging is received.
uint256 public targetChainId;
/// @dev Keep free storage slots for future implementation updates to avoid storage collision.