diff --git a/.github/workflows/case.yml b/.github/workflows/case.yml index 69c21c4a3..5977fb009 100644 --- a/.github/workflows/case.yml +++ b/.github/workflows/case.yml @@ -5,6 +5,8 @@ on: pull_request: branches: - main + paths: + - 'docs/**' jobs: case: diff --git a/docs/api/linea-smart-contracts/interfaces/igenericerrors.mdx b/docs/api/linea-smart-contracts/interfaces/igenericerrors.mdx new file mode 100644 index 000000000..2f60a8e66 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/igenericerrors.mdx @@ -0,0 +1,26 @@ +# `IGenericErrors` + +### ZeroAddressNotAllowed + +```solidity +error ZeroAddressNotAllowed() +``` + +_Thrown when a parameter is the zero address._ + +### ZeroHashNotAllowed + +```solidity +error ZeroHashNotAllowed() +``` + +_Thrown when a parameter is the zero hash._ + +### ArrayLengthsDoNotMatch + +```solidity +error ArrayLengthsDoNotMatch() +``` + +_Thrown when array lengths are mismatched._ + diff --git a/docs/api/linea-smart-contracts/interfaces/imessageservice.mdx b/docs/api/linea-smart-contracts/interfaces/imessageservice.mdx new file mode 100644 index 000000000..02a03fde7 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/imessageservice.mdx @@ -0,0 +1,126 @@ +# `IMessageService` + +### MessageSent + +```solidity +event MessageSent(address _from, address _to, uint256 _fee, uint256 _value, uint256 _nonce, bytes _calldata, bytes32 _messageHash) +``` + +Emitted when a message is sent. + +__calldata has the _ because calldata is a reserved word. +We include the message hash to save hashing costs on the rollup. +This event is used on both L1 and L2._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _from | address | The indexed sender address of the message (msg.sender). | +| _to | address | The indexed intended recipient address of the message on the other layer. | +| _fee | uint256 | The fee being being paid to deliver the message to the recipient in Wei. | +| _value | uint256 | The value being sent to the recipient in Wei. | +| _nonce | uint256 | The unique message number. | +| _calldata | bytes | The calldata being passed to the intended recipient when being called on claiming. | +| _messageHash | bytes32 | The indexed hash of the message parameters. | + +### MessageClaimed + +```solidity +event MessageClaimed(bytes32 _messageHash) +``` + +Emitted when a message is claimed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageHash | bytes32 | The indexed hash of the message that was claimed. | + +### FeeTooLow + +```solidity +error FeeTooLow() +``` + +_Thrown when fees are lower than the minimum fee._ + +### ValueSentTooLow + +```solidity +error ValueSentTooLow() +``` + +_Thrown when the value sent is less than the fee. +Value to forward on is msg.value - _fee._ + +### MessageSendingFailed + +```solidity +error MessageSendingFailed(address destination) +``` + +_Thrown when the destination address reverts._ + +### FeePaymentFailed + +```solidity +error FeePaymentFailed(address recipient) +``` + +_Thrown when the recipient address reverts._ + +### sendMessage + +```solidity +function sendMessage(address _to, uint256 _fee, bytes _calldata) external payable +``` + +Sends a message for transporting from the given chain. + +_This function should be called with a msg.value = _value + _fee. The fee will be paid on the destination chain._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _to | address | The destination address on the destination chain. | +| _fee | uint256 | The message service fee on the origin chain. | +| _calldata | bytes | The calldata used by the destination message service to call the destination contract. | + +### claimMessage + +```solidity +function claimMessage(address _from, address _to, uint256 _fee, uint256 _value, address payable _feeRecipient, bytes _calldata, uint256 _nonce) external +``` + +Deliver a message to the destination chain. +Is called by the Postman, dApp or end user. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _from | address | The msg.sender calling the origin message service. | +| _to | address | The destination address on the destination chain. | +| _fee | uint256 | The message service fee on the origin chain. | +| _value | uint256 | The value to be transferred to the destination address. | +| _feeRecipient | address payable | Address that will receive the fees. | +| _calldata | bytes | The calldata used by the destination message service to call/forward to the destination contract. | +| _nonce | uint256 | Unique message number. | + +### sender + +```solidity +function sender() external view returns (address originalSender) +``` + +Returns the original sender of the message on the origin layer. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalSender | address | The original sender of the message on the origin layer. | + diff --git a/docs/api/linea-smart-contracts/interfaces/ipausemanager.mdx b/docs/api/linea-smart-contracts/interfaces/ipausemanager.mdx new file mode 100644 index 000000000..d09f221c0 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/ipausemanager.mdx @@ -0,0 +1,155 @@ +# `IPauseManager` + +### PauseTypeRole + +```solidity +struct PauseTypeRole { + enum IPauseManager.PauseType pauseType; + bytes32 role; +} +``` + +### PauseType + +```solidity +enum PauseType { + UNUSED, + GENERAL, + L1_L2, + L2_L1, + BLOB_SUBMISSION, + CALLDATA_SUBMISSION, + FINALIZATION, + INITIATE_TOKEN_BRIDGING, + COMPLETE_TOKEN_BRIDGING +} +``` + +### Paused + +```solidity +event Paused(address messageSender, enum IPauseManager.PauseType pauseType) +``` + +Emitted when a pause type is paused. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| messageSender | address | The address performing the pause. | +| pauseType | enum IPauseManager.PauseType | The indexed pause type that was paused. | + +### UnPaused + +```solidity +event UnPaused(address messageSender, enum IPauseManager.PauseType pauseType) +``` + +Emitted when a pause type is unpaused. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| messageSender | address | The address performing the unpause. | +| pauseType | enum IPauseManager.PauseType | The indexed pause type that was unpaused. | + +### PauseTypeRoleSet + +```solidity +event PauseTypeRoleSet(enum IPauseManager.PauseType pauseType, bytes32 role) +``` + +Emitted when a pause type and its associated role are set in the `_pauseTypeRoles` mapping. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pauseType | enum IPauseManager.PauseType | The indexed type of pause. | +| role | bytes32 | The indexed role associated with the pause type. | + +### UnPauseTypeRoleSet + +```solidity +event UnPauseTypeRoleSet(enum IPauseManager.PauseType unPauseType, bytes32 role) +``` + +Emitted when an unpause type and its associated role are set in the `_unPauseTypeRoles` mapping. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| unPauseType | enum IPauseManager.PauseType | The indexed type of unpause. | +| role | bytes32 | The indexed role associated with the unpause type. | + +### IsPaused + +```solidity +error IsPaused(enum IPauseManager.PauseType pauseType) +``` + +_Thrown when a specific pause type is paused._ + +### IsNotPaused + +```solidity +error IsNotPaused(enum IPauseManager.PauseType pauseType) +``` + +_Thrown when a specific pause type is not paused and expected to be._ + +### pauseByType + +```solidity +function pauseByType(enum IPauseManager.PauseType _pauseType) external +``` + +Pauses functionality by specific type. + +_Requires the role mapped in pauseTypeRoles for the pauseType._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +### unPauseByType + +```solidity +function unPauseByType(enum IPauseManager.PauseType _pauseType) external +``` + +Unpauses functionality by specific type. + +_Requires the role mapped in unPauseTypeRoles for the pauseType._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +### isPaused + +```solidity +function isPaused(enum IPauseManager.PauseType _pauseType) external view returns (bool pauseTypeIsPaused) +``` + +Check if a pause type is enabled. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. | + diff --git a/docs/api/linea-smart-contracts/interfaces/ipermissionsmanager.mdx b/docs/api/linea-smart-contracts/interfaces/ipermissionsmanager.mdx new file mode 100644 index 000000000..c7b189b79 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/ipermissionsmanager.mdx @@ -0,0 +1,11 @@ +# `IPermissionsManager` + +### RoleAddress + +```solidity +struct RoleAddress { + address addressWithRole; + bytes32 role; +} +``` + diff --git a/docs/api/linea-smart-contracts/interfaces/iratelimiter.mdx b/docs/api/linea-smart-contracts/interfaces/iratelimiter.mdx new file mode 100644 index 000000000..17db2b885 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/iratelimiter.mdx @@ -0,0 +1,106 @@ +# `IRateLimiter` + +### RateLimitInitialized + +```solidity +event RateLimitInitialized(uint256 periodInSeconds, uint256 limitInWei, uint256 currentPeriodEnd) +``` + +Emitted when the Rate Limit is initialized. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| periodInSeconds | uint256 | The time period in seconds the rate limiter has been initialized to. | +| limitInWei | uint256 | The limit in Wei the rate limiter has been initialized to. | +| currentPeriodEnd | uint256 | The time the current rate limit period will end. | + +### AmountUsedInPeriodReset + +```solidity +event AmountUsedInPeriodReset(address resettingAddress) +``` + +Emitted when the amount in the period is reset to zero. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resettingAddress | address | The indexed address of who reset the used amount back to zero. | + +### LimitAmountChanged + +```solidity +event LimitAmountChanged(address amountChangeBy, uint256 amount, bool amountUsedLoweredToLimit, bool usedAmountResetToZero) +``` + +Emitted when the limit is changed. + +_If the current used amount is higher than the new limit, the used amount is lowered to the limit. +amountUsedLoweredToLimit and usedAmountResetToZero cannot be true at the same time._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amountChangeBy | address | The indexed address of who changed the rate limit. | +| amount | uint256 | The rate limited amount in Wei that was set. | +| amountUsedLoweredToLimit | bool | Indicates if the amount used was lowered to the limit to avoid confusion. | +| usedAmountResetToZero | bool | Indicates if the amount used was set to zero because of the current period expiring. | + +### RateLimitExceeded + +```solidity +error RateLimitExceeded() +``` + +_Thrown when an amount breaches the limit in the period._ + +### PeriodIsZero + +```solidity +error PeriodIsZero() +``` + +_Thrown when the period is initialised to zero._ + +### LimitIsZero + +```solidity +error LimitIsZero() +``` + +_Thrown when the limit is initialised to zero._ + +### resetRateLimitAmount + +```solidity +function resetRateLimitAmount(uint256 _amount) external +``` + +Resets the rate limit amount. + +_If the used amount is higher, it is set to the limit to avoid confusion/issues. +Only the RATE_LIMIT_SETTER_ROLE is allowed to execute this function. +Emits the LimitAmountChanged event. +usedLimitAmountToSet will use the default value of zero if period has expired._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _amount | uint256 | The amount to reset the limit to. | + +### resetAmountUsedInPeriod + +```solidity +function resetAmountUsedInPeriod() external +``` + +Resets the amount used to zero. + +_Only the USED_RATE_LIMIT_RESETTER_ROLE is allowed to execute this function. +Emits the AmountUsedInPeriodReset event._ + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanager.mdx b/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanager.mdx new file mode 100644 index 000000000..04fc8935d --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanager.mdx @@ -0,0 +1,95 @@ +# `IL1MessageManager` + +### RollingHashUpdated + +```solidity +event RollingHashUpdated(uint256 messageNumber, bytes32 rollingHash, bytes32 messageHash) +``` + +Emitted when a new message is sent and the rolling hash updated. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| messageNumber | uint256 | The unique indexed message number for the message. | +| rollingHash | bytes32 | The indexed rolling hash computed for the current message number. | +| messageHash | bytes32 | The indexed hash of the message parameters. | + +### L2MerkleRootAdded + +```solidity +event L2MerkleRootAdded(bytes32 l2MerkleRoot, uint256 treeDepth) +``` + +Emitted when the L2 Merkle root has been anchored on L1. + +_There may be more than one of these in a finalization depending on the amount of L2->L1 messages in the finalization._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| l2MerkleRoot | bytes32 | The indexed L2 Merkle root that has been anchored on L1 Ethereum. | +| treeDepth | uint256 | The indexed tree depth of the Merkle root. | + +### L2MessagingBlockAnchored + +```solidity +event L2MessagingBlockAnchored(uint256 l2Block) +``` + +Emitted when the L2 block contains L2 messages during finalization. + +_This is used externally in the logic for determining which messages belong to which Merkle root when claiming._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| l2Block | uint256 | The indexed L2 block containing L2 to L1 messages. | + +### MessageAlreadyClaimed + +```solidity +error MessageAlreadyClaimed(uint256 messageIndex) +``` + +_Thrown when the message has already been claimed._ + +### L2MerkleRootAlreadyAnchored + +```solidity +error L2MerkleRootAlreadyAnchored(bytes32 merkleRoot) +``` + +_Thrown when the L2 Merkle root has already been anchored on L1._ + +### BytesLengthNotMultipleOfTwo + +```solidity +error BytesLengthNotMultipleOfTwo(uint256 bytesLength) +``` + +_Thrown when the L2 messaging blocks offsets bytes length is not a multiple of 2._ + +### isMessageClaimed + +```solidity +function isMessageClaimed(uint256 _messageNumber) external view returns (bool isClaimed) +``` + +Checks if the L2->L1 message is claimed or not. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | The message number on L2. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| isClaimed | bool | Returns whether or not the message with _messageNumber has been claimed. | + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanagerv1.mdx b/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanagerv1.mdx new file mode 100644 index 000000000..b9b0495be --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/il1messagemanagerv1.mdx @@ -0,0 +1,10 @@ +# `IL1MessageManagerV1` + +### MessageDoesNotExistOrHasAlreadyBeenClaimed + +```solidity +error MessageDoesNotExistOrHasAlreadyBeenClaimed(bytes32 messageHash) +``` + +_Thrown when the message has already been claimed._ + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/il1messageservice.mdx b/docs/api/linea-smart-contracts/interfaces/l1/il1messageservice.mdx new file mode 100644 index 000000000..7fad8aed2 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/il1messageservice.mdx @@ -0,0 +1,65 @@ +# `IL1MessageService` + +### ClaimMessageWithProofParams + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | + +```solidity +struct ClaimMessageWithProofParams { + bytes32[] proof; + uint256 messageNumber; + uint32 leafIndex; + address from; + address to; + uint256 fee; + uint256 value; + address payable feeRecipient; + bytes32 merkleRoot; + bytes data; +} +``` + +### L2MerkleRootDoesNotExist + +```solidity +error L2MerkleRootDoesNotExist() +``` + +_Thrown when L2 Merkle root does not exist._ + +### InvalidMerkleProof + +```solidity +error InvalidMerkleProof() +``` + +_Thrown when the Merkle proof is invalid._ + +### ProofLengthDifferentThanMerkleDepth + +```solidity +error ProofLengthDifferentThanMerkleDepth(uint256 actual, uint256 expected) +``` + +_Thrown when Merkle depth doesn't match proof length._ + +### claimMessageWithProof + +```solidity +function claimMessageWithProof(struct IL1MessageService.ClaimMessageWithProofParams _params) external +``` + +Claims and delivers a cross-chain message using a Merkle proof. + +_if tree depth is empty, it will revert with L2MerkleRootDoesNotExist. +if tree depth is different than proof size, it will revert with ProofLengthDifferentThanMerkleDepth._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _params | struct IL1MessageService.ClaimMessageWithProofParams | Collection of claim data with proof and supporting data. | + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/ilinearollup.mdx b/docs/api/linea-smart-contracts/interfaces/l1/ilinearollup.mdx new file mode 100644 index 000000000..62e8e3944 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/ilinearollup.mdx @@ -0,0 +1,505 @@ +# `ILineaRollup` + +### InitializationData + +Initialization data structure for the LineaRollup contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | + +```solidity +struct InitializationData { + bytes32 initialStateRootHash; + uint256 initialL2BlockNumber; + uint256 genesisTimestamp; + address defaultVerifier; + uint256 rateLimitPeriodInSeconds; + uint256 rateLimitAmountInWei; + struct IPermissionsManager.RoleAddress[] roleAddresses; + struct IPauseManager.PauseTypeRole[] pauseTypeRoles; + struct IPauseManager.PauseTypeRole[] unpauseTypeRoles; + address fallbackOperator; + address defaultAdmin; +} +``` + +### CompressedCalldataSubmission + +Supporting data for compressed calldata submission including compressed data. + +_finalStateRootHash is used to set state root at the end of the data. +snarkHash is the computed hash for compressed data (using a SNARK-friendly hash function) that aggregates per data submission to be used in public input. +compressedData is the compressed transaction data. It contains ordered data for each L2 block - l2Timestamps, the encoded transaction data._ + +```solidity +struct CompressedCalldataSubmission { + bytes32 finalStateRootHash; + bytes32 snarkHash; + bytes compressedData; +} +``` + +### ShnarfData + +Shnarf data for validating a shnarf. + +_parentShnarf is the parent computed shnarf. +snarkHash is the computed hash for compressed data (using a SNARK-friendly hash function) that aggregates per data submission to be used in public input. +finalStateRootHash is the final state root hash. +dataEvaluationPoint is the data evaluation point. +dataEvaluationClaim is the data evaluation claim._ + +```solidity +struct ShnarfData { + bytes32 parentShnarf; + bytes32 snarkHash; + bytes32 finalStateRootHash; + bytes32 dataEvaluationPoint; + bytes32 dataEvaluationClaim; +} +``` + +### BlobSubmission + +Data stucture for compressed blob data submission. + +_submissionData The supporting data for blob data submission excluding the compressed data. +dataEvaluationClaim The data evaluation claim. +kzgCommitment The blob KZG commitment. +kzgProof The blob KZG point proof._ + +```solidity +struct BlobSubmission { + uint256 dataEvaluationClaim; + bytes kzgCommitment; + bytes kzgProof; + bytes32 finalStateRootHash; + bytes32 snarkHash; +} +``` + +### FinalizationDataV3 + +Supporting data for finalization with proof. + +_NB: the dynamic sized fields are placed last on purpose for efficient keccaking on public input. +parentStateRootHash is the expected last state root hash finalized. +endBlockNumber is the end block finalizing until. +shnarfData contains data about the last data submission's shnarf used in finalization. +lastFinalizedTimestamp is the expected last finalized block's timestamp. +finalTimestamp is the timestamp of the last block being finalized. +lastFinalizedL1RollingHash is the last stored L2 computed rolling hash used in finalization. +l1RollingHash is the calculated rolling hash on L2 that is expected to match L1 at l1RollingHashMessageNumber. +This value will be used along with the stored last finalized L2 calculated rolling hash in the public input. +lastFinalizedL1RollingHashMessageNumber is the last stored L2 computed message number used in finalization. +l1RollingHashMessageNumber is the calculated message number on L2 that is expected to match the existing L1 rolling hash. +This value will be used along with the stored last finalized L2 calculated message number in the public input. +l2MerkleTreesDepth is the depth of all l2MerkleRoots. +l2MerkleRoots is an array of L2 message Merkle roots of depth l2MerkleTreesDepth between last finalized block and finalSubmissionData.finalBlockNumber. +l2MessagingBlocksOffsets indicates by offset from currentL2BlockNumber which L2 blocks contain MessageSent events._ + +```solidity +struct FinalizationDataV3 { + bytes32 parentStateRootHash; + uint256 endBlockNumber; + struct ILineaRollup.ShnarfData shnarfData; + uint256 lastFinalizedTimestamp; + uint256 finalTimestamp; + bytes32 lastFinalizedL1RollingHash; + bytes32 l1RollingHash; + uint256 lastFinalizedL1RollingHashMessageNumber; + uint256 l1RollingHashMessageNumber; + uint256 l2MerkleTreesDepth; + bytes32[] l2MerkleRoots; + bytes l2MessagingBlocksOffsets; +} +``` + +### LineaRollupVersionChanged + +```solidity +event LineaRollupVersionChanged(bytes8 previousVersion, bytes8 newVersion) +``` + +Emitted when the LineaRollup contract version has changed. + +_All bytes8 values are string based SemVer in the format M.m - e.g. "6.0"._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| previousVersion | bytes8 | The previous version. | +| newVersion | bytes8 | The new version. | + +### FallbackOperatorRoleGranted + +```solidity +event FallbackOperatorRoleGranted(address caller, address fallbackOperator) +``` + +Emitted when the fallback operator role is granted. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| caller | address | The address that called the function granting the role. | +| fallbackOperator | address | The fallback operator address that received the operator role. | + +### FallbackOperatorAddressSet + +```solidity +event FallbackOperatorAddressSet(address caller, address fallbackOperator) +``` + +Emitted when the fallback operator role is set on the contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| caller | address | The address that set the fallback operator address. | +| fallbackOperator | address | The fallback operator address. | + +### VerifierAddressChanged + +```solidity +event VerifierAddressChanged(address verifierAddress, uint256 proofType, address verifierSetBy, address oldVerifierAddress) +``` + +Emitted when a verifier is set for a particular proof type. + +_The verifier will be set by an account with the VERIFIER_SETTER_ROLE. Typically the Safe. +The oldVerifierAddress can be the zero address._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| verifierAddress | address | The indexed new verifier address being set. | +| proofType | uint256 | The indexed proof type/index that the verifier is mapped to. | +| verifierSetBy | address | The index address who set the verifier at the mapping. | +| oldVerifierAddress | address | Indicates the previous address mapped to the proof type. | + +### DataSubmittedV3 + +```solidity +event DataSubmittedV3(bytes32 parentShnarf, bytes32 shnarf, bytes32 finalStateRootHash) +``` + +Emitted when compressed data is being submitted and verified succesfully on L1. + +_The block range is indexed and parent shnarf included for state reconstruction simplicity._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| parentShnarf | bytes32 | The parent shnarf for the data being submitted. | +| shnarf | bytes32 | The indexed shnarf for the data being submitted. | +| finalStateRootHash | bytes32 | The L2 state root hash that the current blob submission ends on. NB: The last blob in the collection. | + +### DataFinalizedV3 + +```solidity +event DataFinalizedV3(uint256 startBlockNumber, uint256 endBlockNumber, bytes32 shnarf, bytes32 parentStateRootHash, bytes32 finalStateRootHash) +``` + +Emitted when L2 blocks have been finalized on L1. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| startBlockNumber | uint256 | The indexed L2 block number indicating which block the finalization the data starts from. | +| endBlockNumber | uint256 | The indexed L2 block number indicating which block the finalization the data ends on. | +| shnarf | bytes32 | The indexed shnarf being set as currentFinalizedShnarf in the current finalization. | +| parentStateRootHash | bytes32 | The parent L2 state root hash that the current finalization starts from. | +| finalStateRootHash | bytes32 | The L2 state root hash that the current finalization ends on. | + +### LastFinalizationTimeNotLapsed + +```solidity +error LastFinalizationTimeNotLapsed() +``` + +_Thrown when the last finalization time has not lapsed when trying to grant the OPERATOR_ROLE to the fallback operator address._ + +### PointEvaluationResponseInvalid + +```solidity +error PointEvaluationResponseInvalid(uint256 fieldElements, uint256 blsCurveModulus) +``` + +_Thrown when the point evaluation precompile's call return data field(s) are wrong._ + +### PrecompileReturnDataLengthWrong + +```solidity +error PrecompileReturnDataLengthWrong(uint256 expected, uint256 actual) +``` + +_Thrown when the point evaluation precompile's call return data length is wrong._ + +### PointEvaluationFailed + +```solidity +error PointEvaluationFailed() +``` + +_Thrown when the point evaluation precompile call returns false._ + +### EmptyBlobDataAtIndex + +```solidity +error EmptyBlobDataAtIndex(uint256 index) +``` + +_Thrown when the blobhash at an index equals to the zero hash._ + +### BlobSubmissionDataIsMissing + +```solidity +error BlobSubmissionDataIsMissing() +``` + +_Thrown when the data for multiple blobs submission has length zero._ + +### BlobSubmissionDataEmpty + +```solidity +error BlobSubmissionDataEmpty(uint256 emptyBlobIndex) +``` + +_Thrown when a blob has been submitted but there is no data for it._ + +### DataAlreadySubmitted + +```solidity +error DataAlreadySubmitted(bytes32 currentDataHash) +``` + +_Thrown when the current data was already submitted._ + +### EmptySubmissionData + +```solidity +error EmptySubmissionData() +``` + +_Thrown when submissionData is empty._ + +### L1RollingHashDoesNotExistOnL1 + +```solidity +error L1RollingHashDoesNotExistOnL1(uint256 messageNumber, bytes32 rollingHash) +``` + +_Thrown when finalizationData.l1RollingHash does not exist on L1 (Feedback loop)._ + +### FinalizationStateIncorrect + +```solidity +error FinalizationStateIncorrect(bytes32 expected, bytes32 value) +``` + +_Thrown when finalization state does not match._ + +### FinalBlockNumberLessThanOrEqualToLastFinalizedBlock + +```solidity +error FinalBlockNumberLessThanOrEqualToLastFinalizedBlock(uint256 finalBlockNumber, uint256 lastFinalizedBlock) +``` + +_Thrown when the final block number in finalization data is less than or equal to the last finalized block during finalization._ + +### FinalBlockStateEqualsZeroHash + +```solidity +error FinalBlockStateEqualsZeroHash() +``` + +_Thrown when the final block state equals the zero hash during finalization._ + +### FinalizationInTheFuture + +```solidity +error FinalizationInTheFuture(uint256 l2BlockTimestamp, uint256 currentBlockTimestamp) +``` + +_Thrown when final l2 block timestamp higher than current block.timestamp during finalization._ + +### MissingMessageNumberForRollingHash + +```solidity +error MissingMessageNumberForRollingHash(bytes32 rollingHash) +``` + +_Thrown when a rolling hash is provided without a corresponding message number._ + +### MissingRollingHashForMessageNumber + +```solidity +error MissingRollingHashForMessageNumber(uint256 messageNumber) +``` + +_Thrown when a message number is provided without a corresponding rolling hash._ + +### FirstByteIsNotZero + +```solidity +error FirstByteIsNotZero() +``` + +_Thrown when the first byte is not zero. +This is used explicitly with the four bytes in assembly 0x729eebce._ + +### BytesLengthNotMultipleOf32 + +```solidity +error BytesLengthNotMultipleOf32() +``` + +_Thrown when bytes length is not a multiple of 32._ + +### FinalShnarfWrong + +```solidity +error FinalShnarfWrong(bytes32 expected, bytes32 value) +``` + +_Thrown when the computed shnarf does not match what is expected._ + +### ParentBlobNotSubmitted + +```solidity +error ParentBlobNotSubmitted(bytes32 shnarf) +``` + +_Thrown when a shnarf does not exist for a parent blob._ + +### FinalBlobNotSubmitted + +```solidity +error FinalBlobNotSubmitted(bytes32 shnarf) +``` + +_Thrown when a shnarf does not exist for the final blob being finalized._ + +### OnlyNonFallbackOperator + +```solidity +error OnlyNonFallbackOperator() +``` + +_Thrown when the fallback operator tries to renounce their operator role._ + +### setVerifierAddress + +```solidity +function setVerifierAddress(address _newVerifierAddress, uint256 _proofType) external +``` + +Adds or updates the verifier contract address for a proof type. + +_VERIFIER_SETTER_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newVerifierAddress | address | The address for the verifier contract. | +| _proofType | uint256 | The proof type being set/updated. | + +### setFallbackOperator + +```solidity +function setFallbackOperator(uint256 _messageNumber, bytes32 _rollingHash, uint256 _lastFinalizedTimestamp) external +``` + +Sets the fallback operator role to the specified address if six months have passed since the last finalization. + +_Reverts if six months have not passed since the last finalization._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | Last finalized L1 message number as part of the feedback loop. | +| _rollingHash | bytes32 | Last finalized L1 rolling hash as part of the feedback loop. | +| _lastFinalizedTimestamp | uint256 | Last finalized L2 block timestamp. | + +### unsetVerifierAddress + +```solidity +function unsetVerifierAddress(uint256 _proofType) external +``` + +Unsets the verifier contract address for a proof type. + +_VERIFIER_UNSETTER_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _proofType | uint256 | The proof type being set/updated. | + +### submitBlobs + +```solidity +function submitBlobs(struct ILineaRollup.BlobSubmission[] _blobSubmissions, bytes32 _parentShnarf, bytes32 _finalBlobShnarf) external +``` + +Submit one or more EIP-4844 blobs. + +_OPERATOR_ROLE is required to execute. +This should be a blob carrying transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _blobSubmissions | struct ILineaRollup.BlobSubmission[] | The data for blob submission including proofs and required polynomials. | +| _parentShnarf | bytes32 | The parent shnarf used in continuity checks as it includes the parentStateRootHash in its computation. | +| _finalBlobShnarf | bytes32 | The expected final shnarf post computation of all the blob shnarfs. | + +### submitDataAsCalldata + +```solidity +function submitDataAsCalldata(struct ILineaRollup.CompressedCalldataSubmission _submission, bytes32 _parentShnarf, bytes32 _expectedShnarf) external +``` + +Submit blobs using compressed data via calldata. + +_OPERATOR_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _submission | struct ILineaRollup.CompressedCalldataSubmission | The supporting data for compressed data submission including compressed data. | +| _parentShnarf | bytes32 | The parent shnarf used in continuity checks as it includes the parentStateRootHash in its computation. | +| _expectedShnarf | bytes32 | The expected shnarf post computation of all the submission. | + +### finalizeBlocks + +```solidity +function finalizeBlocks(bytes _aggregatedProof, uint256 _proofType, struct ILineaRollup.FinalizationDataV3 _finalizationData) external +``` + +Finalize compressed blocks with proof. + +_OPERATOR_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _aggregatedProof | bytes | The aggregated proof. | +| _proofType | uint256 | The proof type. | +| _finalizationData | struct ILineaRollup.FinalizationDataV3 | The full finalization data. | + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/iplonkverifier.mdx b/docs/api/linea-smart-contracts/interfaces/l1/iplonkverifier.mdx new file mode 100644 index 000000000..ecf004e5a --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/iplonkverifier.mdx @@ -0,0 +1,23 @@ +# `IPlonkVerifier` + +### Verify + +```solidity +function Verify(bytes _proof, uint256[] _public_inputs) external returns (bool success) +``` + +Interface for verifier contracts. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _proof | bytes | The proof used to verify. | +| _public_inputs | uint256[] | The computed public inputs for the proof verification. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| success | bool | Returns true if successfully verified. | + diff --git a/docs/api/linea-smart-contracts/interfaces/l1/izkevmv2.mdx b/docs/api/linea-smart-contracts/interfaces/l1/izkevmv2.mdx new file mode 100644 index 000000000..1e9d3bd42 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l1/izkevmv2.mdx @@ -0,0 +1,42 @@ +# `IZkEvmV2` + +### StartingRootHashDoesNotMatch + +```solidity +error StartingRootHashDoesNotMatch() +``` + +_Thrown when the starting rootHash does not match the existing state._ + +### ProofIsEmpty + +```solidity +error ProofIsEmpty() +``` + +_Thrown when zk proof is empty bytes._ + +### InvalidProofType + +```solidity +error InvalidProofType() +``` + +_Thrown when zk proof type is invalid._ + +### InvalidProof + +```solidity +error InvalidProof() +``` + +_Thrown when zk proof is invalid._ + +### InvalidProofOrProofVerificationRanOutOfGas + +```solidity +error InvalidProofOrProofVerificationRanOutOfGas(string errorReason) +``` + +_Thrown when the call to the verifier runs out of gas or reverts internally._ + diff --git a/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanager.mdx b/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanager.mdx new file mode 100644 index 000000000..341cf725d --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanager.mdx @@ -0,0 +1,89 @@ +# `IL2MessageManager` + +### RollingHashUpdated + +```solidity +event RollingHashUpdated(uint256 messageNumber, bytes32 rollingHash) +``` + +Emitted after all messages are anchored on L2 and the latest message index and rolling hash stored. + +_NB: This event is used to provide data to the rollup. The last messageNumber and rollingHash, +emitted in a rollup will be used in the public input for validating the L1->L2 messaging state transition._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| messageNumber | uint256 | The indexed unique L1 computed indexed message number for the message. | +| rollingHash | bytes32 | The indexed L1 rolling hash computed for the current message number. | + +### ServiceVersionMigrated + +```solidity +event ServiceVersionMigrated(uint256 version) +``` + +_Emitted when the service switches over to a new version. +This is currently not in use, but left for existing consumers._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| version | uint256 | The indexed version. | + +### MessageHashesListLengthIsZero + +```solidity +error MessageHashesListLengthIsZero() +``` + +_Reverts when the message hashes array length is zero._ + +### L1MessageNumberSynchronizationWrong + +```solidity +error L1MessageNumberSynchronizationWrong(uint256 expected, uint256 found) +``` + +_Reverts when message number synchronization is mismatched._ + +### L1RollingHashSynchronizationWrong + +```solidity +error L1RollingHashSynchronizationWrong(bytes32 expected, bytes32 found) +``` + +_Reverts when rolling hash synchronization is mismatched._ + +### FinalRollingHashIsZero + +```solidity +error FinalRollingHashIsZero() +``` + +_Reverts when final rolling hash is zero hash._ + +### anchorL1L2MessageHashes + +```solidity +function anchorL1L2MessageHashes(bytes32[] _messageHashes, uint256 _startingMessageNumber, uint256 _finalMessageNumber, bytes32 _finalRollingHash) external +``` + +Add cross-chain L1->L2 message hashes in storage. + +_Only address that has the role 'L1_L2_MESSAGE_SETTER_ROLE' are allowed to call this function. +NB: In the unlikely event of a duplicate anchoring, the lastAnchoredL1MessageNumber MUST NOT be incremented. +and the rolling hash not calculated, else synchronisation will break. +If starting number is zero, an underflow error is expected._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageHashes | bytes32[] | New message hashes to anchor on L2. | +| _startingMessageNumber | uint256 | The expected L1 message number to start when anchoring. | +| _finalMessageNumber | uint256 | The expected L1 message number to end on when anchoring. | +| _finalRollingHash | bytes32 | The expected L1 rolling hash to end on when anchoring. | + diff --git a/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanagerv1.mdx b/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanagerv1.mdx new file mode 100644 index 000000000..0f795e031 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l2/il2messagemanagerv1.mdx @@ -0,0 +1,48 @@ +# `IL2MessageManagerV1` + +### MinimumFeeChanged + +```solidity +event MinimumFeeChanged(uint256 previousMinimumFee, uint256 newMinimumFee, address calledBy) +``` + +Emitted when L2 minimum fee is changed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| previousMinimumFee | uint256 | The previous minimum fee in Wei. | +| newMinimumFee | uint256 | The new minimum fee in Wei. | +| calledBy | address | The indexed address who changed the minimum fee. | + +### L1L2MessageHashesAddedToInbox + +```solidity +event L1L2MessageHashesAddedToInbox(bytes32[] messageHashes) +``` + +Emitted when L1->L2 message hashes have been added to L2 storage. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| messageHashes | bytes32[] | The message hashes that were added to L2 for claiming. | + +### MessageHashesListLengthHigherThanOneHundred + +```solidity +error MessageHashesListLengthHigherThanOneHundred(uint256 length) +``` + +_Thrown when the message hashes list length is higher than one hundred._ + +### MessageDoesNotExistOrHasAlreadyBeenClaimed + +```solidity +error MessageDoesNotExistOrHasAlreadyBeenClaimed(bytes32 messageHash) +``` + +_Thrown when the message does not exist or has already been claimed._ + diff --git a/docs/api/linea-smart-contracts/interfaces/l2/il2messageservicev1.mdx b/docs/api/linea-smart-contracts/interfaces/l2/il2messageservicev1.mdx new file mode 100644 index 000000000..8108c9df5 --- /dev/null +++ b/docs/api/linea-smart-contracts/interfaces/l2/il2messageservicev1.mdx @@ -0,0 +1,18 @@ +# `IL2MessageServiceV1` + +### setMinimumFee + +```solidity +function setMinimumFee(uint256 _feeInWei) external +``` + +The Fee Manager sets a minimum fee to address DOS protection. + +_MINIMUM_FEE_SETTER_ROLE is required to set the minimum fee._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _feeInWei | uint256 | New minimum fee in Wei. | + diff --git a/docs/api/linea-smart-contracts/lib/callforwardingproxy.mdx b/docs/api/linea-smart-contracts/lib/callforwardingproxy.mdx new file mode 100644 index 000000000..0464089fd --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/callforwardingproxy.mdx @@ -0,0 +1,24 @@ +# `CallForwardingProxy` + +### target + +```solidity +address target +``` + +The underlying target address that is called. + +### constructor + +```solidity +constructor(address _target) public +``` + +### fallback + +```solidity +fallback() external payable +``` + +Defaults to, and forwards all calls to the target address. + diff --git a/docs/api/linea-smart-contracts/lib/l2messageservicepausemanager.mdx b/docs/api/linea-smart-contracts/lib/l2messageservicepausemanager.mdx new file mode 100644 index 000000000..ff78dbccf --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/l2messageservicepausemanager.mdx @@ -0,0 +1,34 @@ +# `L2MessageServicePauseManager` + +### PAUSE_L1_L2_ROLE + +```solidity +bytes32 PAUSE_L1_L2_ROLE +``` + +This is used to pause L1 to L2 communication. + +### UNPAUSE_L1_L2_ROLE + +```solidity +bytes32 UNPAUSE_L1_L2_ROLE +``` + +This is used to unpause L1 to L2 communication. + +### PAUSE_L2_L1_ROLE + +```solidity +bytes32 PAUSE_L2_L1_ROLE +``` + +This is used to pause L2 to L1 communication. + +### UNPAUSE_L2_L1_ROLE + +```solidity +bytes32 UNPAUSE_L2_L1_ROLE +``` + +This is used to unpause L2 to L1 communication. + diff --git a/docs/api/linea-smart-contracts/lib/linearolluppausemanager.mdx b/docs/api/linea-smart-contracts/lib/linearolluppausemanager.mdx new file mode 100644 index 000000000..3b308c7a3 --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/linearolluppausemanager.mdx @@ -0,0 +1,66 @@ +# `LineaRollupPauseManager` + +### PAUSE_L1_L2_ROLE + +```solidity +bytes32 PAUSE_L1_L2_ROLE +``` + +This is used to pause L1 to L2 communication. + +### UNPAUSE_L1_L2_ROLE + +```solidity +bytes32 UNPAUSE_L1_L2_ROLE +``` + +This is used to unpause L1 to L2 communication. + +### PAUSE_L2_L1_ROLE + +```solidity +bytes32 PAUSE_L2_L1_ROLE +``` + +This is used to pause L2 to L1 communication. + +### UNPAUSE_L2_L1_ROLE + +```solidity +bytes32 UNPAUSE_L2_L1_ROLE +``` + +This is used to unpause L2 to L1 communication. + +### PAUSE_BLOB_SUBMISSION_ROLE + +```solidity +bytes32 PAUSE_BLOB_SUBMISSION_ROLE +``` + +This is used to pause blob submission. + +### UNPAUSE_BLOB_SUBMISSION_ROLE + +```solidity +bytes32 UNPAUSE_BLOB_SUBMISSION_ROLE +``` + +This is used to unpause blob submission. + +### PAUSE_FINALIZATION_ROLE + +```solidity +bytes32 PAUSE_FINALIZATION_ROLE +``` + +This is used to pause finalization submission. + +### UNPAUSE_FINALIZATION_ROLE + +```solidity +bytes32 UNPAUSE_FINALIZATION_ROLE +``` + +This is used to unpause finalization submission. + diff --git a/docs/api/linea-smart-contracts/lib/mimc.mdx b/docs/api/linea-smart-contracts/lib/mimc.mdx new file mode 100644 index 000000000..b8dbed1d8 --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/mimc.mdx @@ -0,0 +1,46 @@ +# `Mimc` + +### DataMissing + +```solidity +error DataMissing() +``` + +Thrown when the data is not provided + +### DataIsNotMod32 + +```solidity +error DataIsNotMod32() +``` + +Thrown when the data is not purely in 32 byte chunks + +### FR_FIELD + +```solidity +uint256 FR_FIELD +``` + +### hash + +```solidity +function hash(bytes _msg) external pure returns (bytes32 mimcHash) +``` + +Performs a MiMC hash on the data provided + +_Only data that has length modulus 32 is hashed, reverts otherwise_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _msg | bytes | The data to be hashed | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| mimcHash | bytes32 | The computed MiMC hash | + diff --git a/docs/api/linea-smart-contracts/lib/pausemanager.mdx b/docs/api/linea-smart-contracts/lib/pausemanager.mdx new file mode 100644 index 000000000..8b85b7d9b --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/pausemanager.mdx @@ -0,0 +1,151 @@ +# `PauseManager` + +### PAUSE_ALL_ROLE + +```solidity +bytes32 PAUSE_ALL_ROLE +``` + +This is used to pause all pausable functions. + +### UNPAUSE_ALL_ROLE + +```solidity +bytes32 UNPAUSE_ALL_ROLE +``` + +This is used to unpause all unpausable functions. + +### pauseTypeStatuses + +```solidity +mapping(bytes32 => bool) pauseTypeStatuses +``` + +### whenTypeAndGeneralNotPaused + +```solidity +modifier whenTypeAndGeneralNotPaused(enum IPauseManager.PauseType _pauseType) +``` + +_Modifier to make a function callable only when the specific and general types are not paused._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value being checked. Requirements: - The type must not be paused. | + +### whenTypeNotPaused + +```solidity +modifier whenTypeNotPaused(enum IPauseManager.PauseType _pauseType) +``` + +_Modifier to make a function callable only when the type is not paused._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value being checked. Requirements: - The type must not be paused. | + +### __PauseManager_init + +```solidity +function __PauseManager_init(struct IPauseManager.PauseTypeRole[] _pauseTypeRoleAssignments, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoleAssignments) internal +``` + +Initializes the pause manager with the given pause and unpause roles. + +_This function is called during contract initialization to set up the pause and unpause roles._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseTypeRoleAssignments | struct IPauseManager.PauseTypeRole[] | An array of PauseTypeRole structs defining the pause types and their associated roles. | +| _unpauseTypeRoleAssignments | struct IPauseManager.PauseTypeRole[] | An array of PauseTypeRole structs defining the unpause types and their associated roles. | + +### _requireTypeAndGeneralNotPaused + +```solidity +function _requireTypeAndGeneralNotPaused(enum IPauseManager.PauseType _pauseType) internal view virtual +``` + +_Throws if the specific or general types are paused. +Checks the specific and general pause types._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value being checked. | + +### _requireTypeNotPaused + +```solidity +function _requireTypeNotPaused(enum IPauseManager.PauseType _pauseType) internal view virtual +``` + +_Throws if the type is paused. +Checks the specific pause type._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value being checked. | + +### pauseByType + +```solidity +function pauseByType(enum IPauseManager.PauseType _pauseType) external +``` + +Pauses functionality by specific type. + +_Requires the role mapped in `_pauseTypeRoles` for the pauseType._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +### unPauseByType + +```solidity +function unPauseByType(enum IPauseManager.PauseType _pauseType) external +``` + +Unpauses functionality by specific type. + +_Requires the role mapped in `_unPauseTypeRoles` for the pauseType._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +### isPaused + +```solidity +function isPaused(enum IPauseManager.PauseType _pauseType) public view returns (bool pauseTypeIsPaused) +``` + +Check if a pause type is enabled. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _pauseType | enum IPauseManager.PauseType | The pause type value. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. | + diff --git a/docs/api/linea-smart-contracts/lib/permissionsmanager.mdx b/docs/api/linea-smart-contracts/lib/permissionsmanager.mdx new file mode 100644 index 000000000..23f9a7432 --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/permissionsmanager.mdx @@ -0,0 +1,16 @@ +# `PermissionsManager` + +### __Permissions_init + +```solidity +function __Permissions_init(struct IPermissionsManager.RoleAddress[] _roleAddresses) internal +``` + +Sets permissions for a list of addresses and their roles. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _roleAddresses | struct IPermissionsManager.RoleAddress[] | The list of addresses and roles to assign permissions to. | + diff --git a/docs/api/linea-smart-contracts/lib/sparsemerkleproof.mdx b/docs/api/linea-smart-contracts/lib/sparsemerkleproof.mdx new file mode 100644 index 000000000..153e344fe --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/sparsemerkleproof.mdx @@ -0,0 +1,212 @@ +# `SparseMerkleProof` + +### Account + +The Account struct represents the state of the account including the storage root, nonce, balance and codesize + +_This is mapped directly to the output of the storage proof_ + +```solidity +struct Account { + uint64 nonce; + uint256 balance; + bytes32 storageRoot; + bytes32 mimcCodeHash; + bytes32 keccakCodeHash; + uint64 codeSize; +} +``` + +### Leaf + +Represents the leaf structure in both account and storage tries + +_This is mapped directly to the output of the storage proof_ + +```solidity +struct Leaf { + uint256 prev; + uint256 next; + bytes32 hKey; + bytes32 hValue; +} +``` + +### WrongBytesLength + +```solidity +error WrongBytesLength(uint256 expectedLength, uint256 bytesLength) +``` + +Thrown when expected bytes length is incorrect + +### LengthNotMod32 + +```solidity +error LengthNotMod32() +``` + +Thrown when the length of bytes is not in exactly 32 byte chunks + +### MaxTreeLeafIndexExceed + +```solidity +error MaxTreeLeafIndexExceed() +``` + +Thrown when the leaf index is higher than the tree depth + +### WrongProofLength + +```solidity +error WrongProofLength(uint256 expectedLength, uint256 actualLength) +``` + +Thrown when the length of the unformatted proof is not provided exactly as expected (UNFORMATTED_PROOF_LENGTH) + +### TREE_DEPTH + +```solidity +uint256 TREE_DEPTH +``` + +### UNFORMATTED_PROOF_LENGTH + +```solidity +uint256 UNFORMATTED_PROOF_LENGTH +``` + +### ZERO_HASH + +```solidity +bytes32 ZERO_HASH +``` + +### MAX_TREE_LEAF_INDEX + +```solidity +uint256 MAX_TREE_LEAF_INDEX +``` + +### verifyProof + +```solidity +function verifyProof(bytes[] _rawProof, uint256 _leafIndex, bytes32 _root) external pure returns (bool) +``` + +Formats input, computes root and returns true if it matches the provided merkle root + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _rawProof | bytes[] | Raw sparse merkle tree proof | +| _leafIndex | uint256 | Index of the leaf | +| _root | bytes32 | Sparse merkle root | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | If the computed merkle root matches the provided one | + +### mimcHash + +```solidity +function mimcHash(bytes _input) external pure returns (bytes32) +``` + +Hash a value using MIMC hash + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _input | bytes | Value to hash | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Mimc hash | + +### getLeaf + +```solidity +function getLeaf(bytes _encodedLeaf) external pure returns (struct SparseMerkleProof.Leaf) +``` + +Get leaf + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _encodedLeaf | bytes | Encoded leaf bytes (prev, next, hKey, hValue) | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | struct SparseMerkleProof.Leaf | Leaf Formatted leaf struct | + +### getAccount + +```solidity +function getAccount(bytes _encodedAccountValue) external pure returns (struct SparseMerkleProof.Account) +``` + +Get account + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _encodedAccountValue | bytes | Encoded account value bytes (nonce, balance, storageRoot, mimcCodeHash, keccakCodeHash, codeSize) | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | struct SparseMerkleProof.Account | Account Formatted account struct | + +### hashAccountValue + +```solidity +function hashAccountValue(bytes _value) external pure returns (bytes32) +``` + +Hash account value + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _value | bytes | Encoded account value bytes (nonce, balance, storageRoot, mimcCodeHash, keccakCodeHash, codeSize) | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Account value hash | + +### hashStorageValue + +```solidity +function hashStorageValue(bytes32 _value) external pure returns (bytes32) +``` + +Hash storage value + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _value | bytes32 | Encoded storage value bytes | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Storage value hash | + diff --git a/docs/api/linea-smart-contracts/lib/tokenbridgepausemanager.mdx b/docs/api/linea-smart-contracts/lib/tokenbridgepausemanager.mdx new file mode 100644 index 000000000..b0047aa76 --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/tokenbridgepausemanager.mdx @@ -0,0 +1,26 @@ +# `TokenBridgePauseManager` + +### PAUSE_INITIATE_TOKEN_BRIDGING_ROLE + +```solidity +bytes32 PAUSE_INITIATE_TOKEN_BRIDGING_ROLE +``` + +### UNPAUSE_INITIATE_TOKEN_BRIDGING_ROLE + +```solidity +bytes32 UNPAUSE_INITIATE_TOKEN_BRIDGING_ROLE +``` + +### PAUSE_COMPLETE_TOKEN_BRIDGING_ROLE + +```solidity +bytes32 PAUSE_COMPLETE_TOKEN_BRIDGING_ROLE +``` + +### UNPAUSE_COMPLETE_TOKEN_BRIDGING_ROLE + +```solidity +bytes32 UNPAUSE_COMPLETE_TOKEN_BRIDGING_ROLE +``` + diff --git a/docs/api/linea-smart-contracts/lib/utils.mdx b/docs/api/linea-smart-contracts/lib/utils.mdx new file mode 100644 index 000000000..029dd3dab --- /dev/null +++ b/docs/api/linea-smart-contracts/lib/utils.mdx @@ -0,0 +1,32 @@ +# `Utils` + +### _efficientKeccak + +```solidity +function _efficientKeccak(bytes32 _left, bytes32 _right) internal pure returns (bytes32 value) +``` + +Performs a gas optimized keccak hash for two bytes32 values. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _left | bytes32 | Left value. | +| _right | bytes32 | Right value. | + +### _efficientKeccak + +```solidity +function _efficientKeccak(uint256 _left, address _right) internal pure returns (bytes32 value) +``` + +Performs a gas optimized keccak hash for uint256 and address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _left | uint256 | Left value. | +| _right | address | Right value. | + diff --git a/docs/api/linea-smart-contracts/linearollup.mdx b/docs/api/linea-smart-contracts/linearollup.mdx new file mode 100644 index 000000000..96990127c --- /dev/null +++ b/docs/api/linea-smart-contracts/linearollup.mdx @@ -0,0 +1,466 @@ +# `LineaRollup` + +### CONTRACT_VERSION + +```solidity +string CONTRACT_VERSION +``` + +This is the ABI version and not the reinitialize version. + +### VERIFIER_SETTER_ROLE + +```solidity +bytes32 VERIFIER_SETTER_ROLE +``` + +The role required to set/add proof verifiers by type. + +### VERIFIER_UNSETTER_ROLE + +```solidity +bytes32 VERIFIER_UNSETTER_ROLE +``` + +The role required to set/remove proof verifiers by type. + +### GENESIS_SHNARF + +```solidity +bytes32 GENESIS_SHNARF +``` + +The default genesis shnarf using empty/default hashes and a default state. + +### SHNARF_EXISTS_DEFAULT_VALUE + +```solidity +uint256 SHNARF_EXISTS_DEFAULT_VALUE +``` + +_Value indicating a shnarf exists._ + +### EMPTY_HASH + +```solidity +bytes32 EMPTY_HASH +``` + +_The default hash value._ + +### BLS_CURVE_MODULUS + +```solidity +uint256 BLS_CURVE_MODULUS +``` + +_The BLS Curve modulus value used._ + +### POINT_EVALUATION_PRECOMPILE_ADDRESS + +```solidity +address POINT_EVALUATION_PRECOMPILE_ADDRESS +``` + +_The well-known precompile address for point evaluation._ + +### POINT_EVALUATION_RETURN_DATA_LENGTH + +```solidity +uint256 POINT_EVALUATION_RETURN_DATA_LENGTH +``` + +_The expected point evaluation return data length._ + +### POINT_EVALUATION_FIELD_ELEMENTS_LENGTH + +```solidity +uint256 POINT_EVALUATION_FIELD_ELEMENTS_LENGTH +``` + +_The expected point evaluation field element length returned._ + +### SIX_MONTHS_IN_SECONDS + +```solidity +uint256 SIX_MONTHS_IN_SECONDS +``` + +_In practice, when used, this is expected to be a close approximation to 6 months, and is intentional._ + +### dataFinalStateRootHashes + +```solidity +mapping(bytes32 => bytes32) dataFinalStateRootHashes +``` + +_DEPRECATED in favor of the single blobShnarfExists mapping._ + +### dataParents + +```solidity +mapping(bytes32 => bytes32) dataParents +``` + +_DEPRECATED in favor of the single blobShnarfExists mapping._ + +### dataShnarfHashes + +```solidity +mapping(bytes32 => bytes32) dataShnarfHashes +``` + +_DEPRECATED in favor of the single blobShnarfExists mapping._ + +### dataStartingBlock + +```solidity +mapping(bytes32 => uint256) dataStartingBlock +``` + +_DEPRECATED in favor of the single blobShnarfExists mapping._ + +### dataEndingBlock + +```solidity +mapping(bytes32 => uint256) dataEndingBlock +``` + +_DEPRECATED in favor of the single blobShnarfExists mapping._ + +### currentL2StoredL1MessageNumber + +```solidity +uint256 currentL2StoredL1MessageNumber +``` + +_DEPRECATED in favor of currentFinalizedState hash._ + +### currentL2StoredL1RollingHash + +```solidity +bytes32 currentL2StoredL1RollingHash +``` + +_DEPRECATED in favor of currentFinalizedState hash._ + +### currentFinalizedShnarf + +```solidity +bytes32 currentFinalizedShnarf +``` + +Contains the most recent finalized shnarf. + +### blobShnarfExists + +```solidity +mapping(bytes32 => uint256) blobShnarfExists +``` + +_NB: THIS IS THE ONLY MAPPING BEING USED FOR DATA SUBMISSION TRACKING. +NB: This was shnarfFinalBlockNumbers and is replaced to indicate only that a shnarf exists with a value of 1._ + +### currentFinalizedState + +```solidity +bytes32 currentFinalizedState +``` + +Hash of the L2 computed L1 message number, rolling hash and finalized timestamp. + +### fallbackOperator + +```solidity +address fallbackOperator +``` + +The address of the fallback operator. + +_This address is granted the OPERATOR_ROLE after six months of finalization inactivity by the current operators._ + +### constructor + +```solidity +constructor() public +``` + +### initialize + +```solidity +function initialize(struct ILineaRollup.InitializationData _initializationData) external +``` + +Initializes LineaRollup and underlying service dependencies - used for new networks only. + +_DEFAULT_ADMIN_ROLE is set for the security council. +OPERATOR_ROLE is set for operators. +Note: This is used for new testnets and local/CI testing, and will not replace existing proxy based contracts._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _initializationData | struct ILineaRollup.InitializationData | The initial data used for proof verification. | + +### reinitializeLineaRollupV6 + +```solidity +function reinitializeLineaRollupV6(struct IPermissionsManager.RoleAddress[] _roleAddresses, struct IPauseManager.PauseTypeRole[] _pauseTypeRoles, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoles, address _fallbackOperator) external +``` + +Sets permissions for a list of addresses and their roles as well as initialises the PauseManager pauseType:role mappings and fallback operator. + +_This function is a reinitializer and can only be called once per version. Should be called using an upgradeAndCall transaction to the ProxyAdmin._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _roleAddresses | struct IPermissionsManager.RoleAddress[] | The list of addresses and roles to assign permissions to. | +| _pauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of pause types to associate with roles. | +| _unpauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of unpause types to associate with roles. | +| _fallbackOperator | address | The address of the fallback operator. | + +### renounceRole + +```solidity +function renounceRole(bytes32 _role, address _account) public +``` + +Revokes `role` from the calling account. + +_Fallback operator cannot renounce role. Reverts with OnlyNonFallbackOperator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _role | bytes32 | The role to renounce. | +| _account | address | The account to renounce - can only be the _msgSender(). | + +### setVerifierAddress + +```solidity +function setVerifierAddress(address _newVerifierAddress, uint256 _proofType) external +``` + +Adds or updates the verifier contract address for a proof type. + +_VERIFIER_SETTER_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newVerifierAddress | address | The address for the verifier contract. | +| _proofType | uint256 | The proof type being set/updated. | + +### setFallbackOperator + +```solidity +function setFallbackOperator(uint256 _messageNumber, bytes32 _rollingHash, uint256 _lastFinalizedTimestamp) external +``` + +Sets the fallback operator role to the specified address if six months have passed since the last finalization. + +_Reverts if six months have not passed since the last finalization._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | Last finalized L1 message number as part of the feedback loop. | +| _rollingHash | bytes32 | Last finalized L1 rolling hash as part of the feedback loop. | +| _lastFinalizedTimestamp | uint256 | Last finalized L2 block timestamp. | + +### unsetVerifierAddress + +```solidity +function unsetVerifierAddress(uint256 _proofType) external +``` + +Unset the verifier contract address for a proof type. + +_VERIFIER_UNSETTER_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _proofType | uint256 | The proof type being set/updated. | + +### submitBlobs + +```solidity +function submitBlobs(struct ILineaRollup.BlobSubmission[] _blobSubmissions, bytes32 _parentShnarf, bytes32 _finalBlobShnarf) external +``` + +Submit one or more EIP-4844 blobs. + +_OPERATOR_ROLE is required to execute. +This should be a blob carrying transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _blobSubmissions | struct ILineaRollup.BlobSubmission[] | The data for blob submission including proofs and required polynomials. | +| _parentShnarf | bytes32 | The parent shnarf used in continuity checks as it includes the parentStateRootHash in its computation. | +| _finalBlobShnarf | bytes32 | The expected final shnarf post computation of all the blob shnarfs. | + +### submitDataAsCalldata + +```solidity +function submitDataAsCalldata(struct ILineaRollup.CompressedCalldataSubmission _submission, bytes32 _parentShnarf, bytes32 _expectedShnarf) external +``` + +Submit blobs using compressed data via calldata. + +_OPERATOR_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _submission | struct ILineaRollup.CompressedCalldataSubmission | The supporting data for compressed data submission including compressed data. | +| _parentShnarf | bytes32 | The parent shnarf used in continuity checks as it includes the parentStateRootHash in its computation. | +| _expectedShnarf | bytes32 | The expected shnarf post computation of all the submission. | + +### _computeLastFinalizedState + +```solidity +function _computeLastFinalizedState(uint256 _messageNumber, bytes32 _rollingHash, uint256 _timestamp) internal pure returns (bytes32 hashedFinalizationState) +``` + +Internal function to compute and save the finalization state. + +_Using assembly this way is cheaper gas wise._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | Is the last L2 computed L1 message number in the finalization. | +| _rollingHash | bytes32 | Is the last L2 computed L1 rolling hash in the finalization. | +| _timestamp | uint256 | The final timestamp in the finalization. | + +### _computeShnarf + +```solidity +function _computeShnarf(bytes32 _parentShnarf, bytes32 _snarkHash, bytes32 _finalStateRootHash, bytes32 _dataEvaluationPoint, bytes32 _dataEvaluationClaim) internal pure returns (bytes32 shnarf) +``` + +Internal function to compute the shnarf more efficiently. + +_Using assembly this way is cheaper gas wise._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _parentShnarf | bytes32 | The shnarf of the parent data item. | +| _snarkHash | bytes32 | Is the computed hash for compressed data (using a SNARK-friendly hash function) that aggregates per data submission to be used in public input. | +| _finalStateRootHash | bytes32 | The final state root hash of the data being submitted. | +| _dataEvaluationPoint | bytes32 | The data evaluation point. | +| _dataEvaluationClaim | bytes32 | The data evaluation claim. | + +### _verifyPointEvaluation + +```solidity +function _verifyPointEvaluation(bytes32 _currentDataHash, uint256 _dataEvaluationPoint, uint256 _dataEvaluationClaim, bytes _kzgCommitment, bytes _kzgProof) internal view +``` + +Performs point evaluation for the compressed blob. + +__dataEvaluationPoint is modular reduced to be lower than the BLS_CURVE_MODULUS for precompile checks._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _currentDataHash | bytes32 | The current blob versioned hash. | +| _dataEvaluationPoint | uint256 | The data evaluation point. | +| _dataEvaluationClaim | uint256 | The data evaluation claim. | +| _kzgCommitment | bytes | The blob KZG commitment. | +| _kzgProof | bytes | The blob KZG point proof. | + +### finalizeBlocks + +```solidity +function finalizeBlocks(bytes _aggregatedProof, uint256 _proofType, struct ILineaRollup.FinalizationDataV3 _finalizationData) external +``` + +Finalize compressed blocks with proof. + +_OPERATOR_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _aggregatedProof | bytes | The aggregated proof. | +| _proofType | uint256 | The proof type. | +| _finalizationData | struct ILineaRollup.FinalizationDataV3 | The full finalization data. | + +### _finalizeBlocks + +```solidity +function _finalizeBlocks(struct ILineaRollup.FinalizationDataV3 _finalizationData, uint256 _lastFinalizedBlock) internal returns (bytes32 finalShnarf) +``` + +Internal function to finalize compressed blocks. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _finalizationData | struct ILineaRollup.FinalizationDataV3 | The full finalization data. | +| _lastFinalizedBlock | uint256 | The last finalized block. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| finalShnarf | bytes32 | The final computed shnarf in finalizing. | + +### _validateL2ComputedRollingHash + +```solidity +function _validateL2ComputedRollingHash(uint256 _rollingHashMessageNumber, bytes32 _rollingHash) internal view +``` + +Internal function to validate l1 rolling hash. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _rollingHashMessageNumber | uint256 | Message number associated with the rolling hash as computed on L2. | +| _rollingHash | bytes32 | L1 rolling hash as computed on L2. | + +### _calculateY + +```solidity +function _calculateY(bytes _data, bytes32 _dataEvaluationPoint) internal pure returns (bytes32 compressedDataComputedY) +``` + +Internal function to calculate Y for public input generation. + +_Each chunk of 32 bytes must start with a 0 byte. +The dataEvaluationPoint value is modulo-ed down during the computation and scalar field checking is not needed. +There is a hard constraint in the circuit to enforce the polynomial degree limit (4096), which will also be enforced with EIP-4844._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _data | bytes | Compressed data from submission data. | +| _dataEvaluationPoint | bytes32 | The data evaluation point. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| compressedDataComputedY | bytes32 | The Y calculated value using the Horner method. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l1/l1messagemanager.mdx b/docs/api/linea-smart-contracts/messageservice/l1/l1messagemanager.mdx new file mode 100644 index 000000000..fb5f87c8b --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l1/l1messagemanager.mdx @@ -0,0 +1,111 @@ +# `L1MessageManager` + +### rollingHashes + +```solidity +mapping(uint256 => bytes32) rollingHashes +``` + +Contains the L1 to L2 messaging rolling hashes mapped to message number computed on L1. + +### _messageClaimedBitMap + +```solidity +struct BitMaps.BitMap _messageClaimedBitMap +``` + +This maps which message numbers have been claimed to prevent duplicate claiming. + +### l2MerkleRootsDepths + +```solidity +mapping(bytes32 => uint256) l2MerkleRootsDepths +``` + +Contains the L2 messages Merkle roots mapped to their tree depth. + +### _addRollingHash + +```solidity +function _addRollingHash(uint256 _messageNumber, bytes32 _messageHash) internal +``` + +Take an existing message hash, calculates the rolling hash and stores at the message number. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | The current message number being sent. | +| _messageHash | bytes32 | The hash of the message being sent. | + +### _setL2L1MessageToClaimed + +```solidity +function _setL2L1MessageToClaimed(uint256 _messageNumber) internal +``` + +Set the L2->L1 message as claimed when a user claims a message on L1. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | The message number on L2. | + +### _addL2MerkleRoots + +```solidity +function _addL2MerkleRoots(bytes32[] _newRoots, uint256 _treeDepth) internal +``` + +Add the L2 Merkle roots to the storage. + +_This function is called during block finalization. +The _treeDepth does not need to be checked to be non-zero as it is, +already enforced to be non-zero in the circuit, and used in the proof's public input._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRoots | bytes32[] | New L2 Merkle roots. | +| _treeDepth | uint256 | | + +### _anchorL2MessagingBlocks + +```solidity +function _anchorL2MessagingBlocks(bytes _l2MessagingBlocksOffsets, uint256 _currentL2BlockNumber) internal +``` + +Emit an event for each L2 block containing L2->L1 messages. + +_This function is called during block finalization._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _l2MessagingBlocksOffsets | bytes | Is a sequence of uint16 values, where each value plus the last finalized L2 block number. indicates which L2 blocks have L2->L1 messages. | +| _currentL2BlockNumber | uint256 | Last L2 block number finalized on L1. | + +### isMessageClaimed + +```solidity +function isMessageClaimed(uint256 _messageNumber) external view returns (bool isClaimed) +``` + +Checks if the L2->L1 message is claimed or not. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageNumber | uint256 | The message number on L2. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| isClaimed | bool | Returns whether or not the message with _messageNumber has been claimed. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l1/l1messageservice.mdx b/docs/api/linea-smart-contracts/messageservice/l1/l1messageservice.mdx new file mode 100644 index 000000000..ddc8fdca6 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l1/l1messageservice.mdx @@ -0,0 +1,77 @@ +# `L1MessageService` + +### systemMigrationBlock + +```solidity +uint256 systemMigrationBlock +``` + +_This is currently not in use, but is reserved for future upgrades._ + +### __MessageService_init + +```solidity +function __MessageService_init(uint256 _rateLimitPeriod, uint256 _rateLimitAmount) internal +``` + +Initialises underlying message service dependencies. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _rateLimitPeriod | uint256 | The period to rate limit against. | +| _rateLimitAmount | uint256 | The limit allowed for withdrawing the period. | + +### sendMessage + +```solidity +function sendMessage(address _to, uint256 _fee, bytes _calldata) external payable +``` + +Adds a message for sending cross-chain and emits MessageSent. + +_The message number is preset (nextMessageNumber) and only incremented at the end if successful for the next caller. +This function should be called with a msg.value = _value + _fee. The fee will be paid on the destination chain._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _to | address | The address the message is intended for. | +| _fee | uint256 | The fee being paid for the message delivery. | +| _calldata | bytes | The calldata to pass to the recipient. | + +### claimMessageWithProof + +```solidity +function claimMessageWithProof(struct IL1MessageService.ClaimMessageWithProofParams _params) external +``` + +Claims and delivers a cross-chain message using a Merkle proof. + +_if tree depth is empty, it will revert with L2MerkleRootDoesNotExist. +if tree depth is different than proof size, it will revert with ProofLengthDifferentThanMerkleDepth._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _params | struct IL1MessageService.ClaimMessageWithProofParams | Collection of claim data with proof and supporting data. | + +### sender + +```solidity +function sender() external view returns (address originalSender) +``` + +Claims and delivers a cross-chain message. + +_The message sender address is set temporarily in the transient storage when claiming._ + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalSender | address | The message sender address that is stored temporarily in the transient storage when claiming. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l1/transientstoragereentrancyguardupgradeable.mdx b/docs/api/linea-smart-contracts/messageservice/l1/transientstoragereentrancyguardupgradeable.mdx new file mode 100644 index 000000000..3d9fe9a6b --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l1/transientstoragereentrancyguardupgradeable.mdx @@ -0,0 +1,14 @@ +# `TransientStorageReentrancyGuardUpgradeable` + +### ReentrantCall + +```solidity +error ReentrantCall() +``` + +### nonReentrant + +```solidity +modifier nonReentrant() +``` + diff --git a/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messagemanagerv1.mdx b/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messagemanagerv1.mdx new file mode 100644 index 000000000..38aa292d1 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messagemanagerv1.mdx @@ -0,0 +1,71 @@ +# `L1MessageManagerV1` + +### INBOX_STATUS_UNKNOWN + +```solidity +uint8 INBOX_STATUS_UNKNOWN +``` + +The 2 legacy status constants for message statuses. + +### INBOX_STATUS_RECEIVED + +```solidity +uint8 INBOX_STATUS_RECEIVED +``` + +### OUTBOX_STATUS_UNKNOWN + +```solidity +uint8 OUTBOX_STATUS_UNKNOWN +``` + +The 3 legacy status constants for message statuses. + +### OUTBOX_STATUS_SENT + +```solidity +uint8 OUTBOX_STATUS_SENT +``` + +### OUTBOX_STATUS_RECEIVED + +```solidity +uint8 OUTBOX_STATUS_RECEIVED +``` + +### outboxL1L2MessageStatus + +```solidity +mapping(bytes32 => uint256) outboxL1L2MessageStatus +``` + +_DEPRECATED in favor of the rollingHashes mapping on the L1MessageManager for L1 to L2 messaging._ + +### inboxL2L1MessageStatus + +```solidity +mapping(bytes32 => uint256) inboxL2L1MessageStatus +``` + +_Mapping to store L2->L1 message hashes status. +messageHash => messageStatus (0: unknown, 1: received). +For the most part this has been deprecated. This is only used for messages received pre-AlphaV2._ + +### _updateL2L1MessageStatusToClaimed + +```solidity +function _updateL2L1MessageStatusToClaimed(bytes32 _messageHash) internal +``` + +Update the status of L2->L1 message when a user claims a message on L1. + +_The L2->L1 message is removed from storage. +Due to the nature of the rollup, we should not get a second entry of this._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageHash | bytes32 | Hash of the message. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messageservicev1.mdx b/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messageservicev1.mdx new file mode 100644 index 000000000..f8e985305 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l1/v1/l1messageservicev1.mdx @@ -0,0 +1,81 @@ +# `L1MessageServiceV1` + +### nextMessageNumber + +```solidity +uint256 nextMessageNumber +``` + +### _messageSender + +```solidity +address _messageSender +``` + +_DEPRECATED in favor of new transient storage with `MESSAGE_SENDER_TRANSIENT_KEY` key._ + +### REFUND_OVERHEAD_IN_GAS + +```solidity +uint256 REFUND_OVERHEAD_IN_GAS +``` + +_adding these should not affect storage as they are constants and are stored in bytecode._ + +### MESSAGE_SENDER_TRANSIENT_KEY + +```solidity +bytes32 MESSAGE_SENDER_TRANSIENT_KEY +``` + +_The transient storage key to set the message sender against while claiming._ + +### DEFAULT_MESSAGE_SENDER_TRANSIENT_VALUE + +```solidity +address DEFAULT_MESSAGE_SENDER_TRANSIENT_VALUE +``` + +The default value for the message sender reset to post claiming using the MESSAGE_SENDER_TRANSIENT_KEY. + +### distributeFees + +```solidity +modifier distributeFees(uint256 _feeInWei, address _to, bytes _calldata, address _feeRecipient) +``` + +The unspent fee is refunded if applicable. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _feeInWei | uint256 | The fee paid for delivery in Wei. | +| _to | address | The recipient of the message and gas refund. | +| _calldata | bytes | The calldata of the message. | +| _feeRecipient | address | | + +### claimMessage + +```solidity +function claimMessage(address _from, address _to, uint256 _fee, uint256 _value, address payable _feeRecipient, bytes _calldata, uint256 _nonce) external +``` + +Claims and delivers a cross-chain message. + +__feeRecipient can be set to address(0) to receive as msg.sender. +The original message sender address is temporarily set in transient storage, +while claiming. This address is used in sender()._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _from | address | The address of the original sender. | +| _to | address | The address the message is intended for. | +| _fee | uint256 | The fee being paid for the message delivery. | +| _value | uint256 | The value to be transferred to the destination address. | +| _feeRecipient | address payable | The recipient for the fee. | +| _calldata | bytes | The calldata to pass to the recipient. | +| _nonce | uint256 | The unique auto generated nonce used when sending the message. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l2/l2messagemanager.mdx b/docs/api/linea-smart-contracts/messageservice/l2/l2messagemanager.mdx new file mode 100644 index 000000000..d364fbd45 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l2/l2messagemanager.mdx @@ -0,0 +1,48 @@ +# `L2MessageManager` + +### L1_L2_MESSAGE_SETTER_ROLE + +```solidity +bytes32 L1_L2_MESSAGE_SETTER_ROLE +``` + +The role required to anchor L1 to L2 message hashes. + +### lastAnchoredL1MessageNumber + +```solidity +uint256 lastAnchoredL1MessageNumber +``` + +Contains the last L1 message number anchored on L2. + +### l1RollingHashes + +```solidity +mapping(uint256 => bytes32) l1RollingHashes +``` + +Contains the L1 to L2 messaging rolling hashes mapped to message number computed on L2. + +### anchorL1L2MessageHashes + +```solidity +function anchorL1L2MessageHashes(bytes32[] _messageHashes, uint256 _startingMessageNumber, uint256 _finalMessageNumber, bytes32 _finalRollingHash) external +``` + +Add cross-chain L1->L2 message hashes in storage. + +_Only address that has the role 'L1_L2_MESSAGE_SETTER_ROLE' are allowed to call this function. +NB: In the unlikely event of a duplicate anchoring, the lastAnchoredL1MessageNumber MUST NOT be incremented. +and the rolling hash not calculated, else synchronisation will break. +If starting number is zero, an underflow error is expected._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageHashes | bytes32[] | New message hashes to anchor on L2. | +| _startingMessageNumber | uint256 | The expected L1 message number to start when anchoring. | +| _finalMessageNumber | uint256 | The expected L1 message number to end on when anchoring. | +| _finalRollingHash | bytes32 | The expected L1 rolling hash to end on when anchoring. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l2/l2messageservice.mdx b/docs/api/linea-smart-contracts/messageservice/l2/l2messageservice.mdx new file mode 100644 index 000000000..d83edaf55 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l2/l2messageservice.mdx @@ -0,0 +1,53 @@ +# `L2MessageService` + +### CONTRACT_VERSION + +```solidity +string CONTRACT_VERSION +``` + +_This is the ABI version and not the reinitialize version._ + +### constructor + +```solidity +constructor() public +``` + +### initialize + +```solidity +function initialize(uint256 _rateLimitPeriod, uint256 _rateLimitAmount, address _defaultAdmin, struct IPermissionsManager.RoleAddress[] _roleAddresses, struct IPauseManager.PauseTypeRole[] _pauseTypeRoles, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoles) external +``` + +Initializes underlying message service dependencies. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _rateLimitPeriod | uint256 | The period to rate limit against. | +| _rateLimitAmount | uint256 | The limit allowed for withdrawing the period. | +| _defaultAdmin | address | The account to be given DEFAULT_ADMIN_ROLE on initialization. | +| _roleAddresses | struct IPermissionsManager.RoleAddress[] | The list of addresses to grant roles to. | +| _pauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of pause type roles. | +| _unpauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of unpause type roles. | + +### reinitializePauseTypesAndPermissions + +```solidity +function reinitializePauseTypesAndPermissions(struct IPermissionsManager.RoleAddress[] _roleAddresses, struct IPauseManager.PauseTypeRole[] _pauseTypeRoles, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoles) external +``` + +Sets permissions for a list of addresses and their roles as well as initialises the PauseManager pauseType:role mappings. + +_This function is a reinitializer and can only be called once per version. Should be called using an upgradeAndCall transaction to the ProxyAdmin._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _roleAddresses | struct IPermissionsManager.RoleAddress[] | The list of addresses and roles to assign permissions to. | +| _pauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of pause types to associate with roles. | +| _unpauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of unpause types to associate with roles. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messagemanagerv1.mdx b/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messagemanagerv1.mdx new file mode 100644 index 000000000..cd9b595ad --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messagemanagerv1.mdx @@ -0,0 +1,45 @@ +# `L2MessageManagerV1` + +### INBOX_STATUS_UNKNOWN + +```solidity +uint8 INBOX_STATUS_UNKNOWN +``` + +The 3 status constants for L1 to L2 message statuses. + +### INBOX_STATUS_RECEIVED + +```solidity +uint8 INBOX_STATUS_RECEIVED +``` + +### INBOX_STATUS_CLAIMED + +```solidity +uint8 INBOX_STATUS_CLAIMED +``` + +### inboxL1L2MessageStatus + +```solidity +mapping(bytes32 => uint256) inboxL1L2MessageStatus +``` + +_Mapping to store L1->L2 message hashes status. +messageHash => messageStatus (0: unknown, 1: received, 2: claimed)._ + +### _updateL1L2MessageStatusToClaimed + +```solidity +function _updateL1L2MessageStatusToClaimed(bytes32 _messageHash) internal +``` + +Update the status of L1->L2 message when a user claims a message on L2. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageHash | bytes32 | Hash of the message. | + diff --git a/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messageservicev1.mdx b/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messageservicev1.mdx new file mode 100644 index 000000000..bda39c206 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/l2/v1/l2messageservicev1.mdx @@ -0,0 +1,138 @@ +# `L2MessageServiceV1` + +### MINIMUM_FEE_SETTER_ROLE + +```solidity +bytes32 MINIMUM_FEE_SETTER_ROLE +``` + +The role required to set the minimum DDOS fee. + +### _messageSender + +```solidity +address _messageSender +``` + +_The temporary message sender set when claiming a message._ + +### nextMessageNumber + +```solidity +uint256 nextMessageNumber +``` + +### minimumFeeInWei + +```solidity +uint256 minimumFeeInWei +``` + +### REFUND_OVERHEAD_IN_GAS + +```solidity +uint256 REFUND_OVERHEAD_IN_GAS +``` + +### DEFAULT_SENDER_ADDRESS + +```solidity +address DEFAULT_SENDER_ADDRESS +``` + +_The default message sender address reset after claiming a message._ + +### constructor + +```solidity +constructor() internal +``` + +### sendMessage + +```solidity +function sendMessage(address _to, uint256 _fee, bytes _calldata) external payable +``` + +Adds a message for sending cross-chain and emits a relevant event. + +_The message number is preset and only incremented at the end if successful for the next caller._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _to | address | The address the message is intended for. | +| _fee | uint256 | The fee being paid for the message delivery. | +| _calldata | bytes | The calldata to pass to the recipient. | + +### claimMessage + +```solidity +function claimMessage(address _from, address _to, uint256 _fee, uint256 _value, address payable _feeRecipient, bytes _calldata, uint256 _nonce) external +``` + +Claims and delivers a cross-chain message. + +__feeRecipient Can be set to address(0) to receive as msg.sender. +messageSender Is set temporarily when claiming and reset post._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _from | address | The address of the original sender. | +| _to | address | The address the message is intended for. | +| _fee | uint256 | The fee being paid for the message delivery. | +| _value | uint256 | The value to be transferred to the destination address. | +| _feeRecipient | address payable | The recipient for the fee. | +| _calldata | bytes | The calldata to pass to the recipient. | +| _nonce | uint256 | The unique auto generated message number used when sending the message. | + +### setMinimumFee + +```solidity +function setMinimumFee(uint256 _feeInWei) external +``` + +The Fee Manager sets a minimum fee to address DOS protection. + +_MINIMUM_FEE_SETTER_ROLE is required to set the minimum fee._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _feeInWei | uint256 | New minimum fee in Wei. | + +### sender + +```solidity +function sender() external view returns (address originalSender) +``` + +_The _messageSender address is set temporarily when claiming._ + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalSender | address | The original sender stored temporarily at the _messageSender address in storage. | + +### distributeFees + +```solidity +modifier distributeFees(uint256 _feeInWei, address _to, bytes _calldata, address _feeRecipient) +``` + +The unspent fee is refunded if applicable. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _feeInWei | uint256 | The fee paid for delivery in Wei. | +| _to | address | The recipient of the message and gas refund. | +| _calldata | bytes | The calldata of the message. | +| _feeRecipient | address | | + diff --git a/docs/api/linea-smart-contracts/messageservice/lib/messagehashing.mdx b/docs/api/linea-smart-contracts/messageservice/lib/messagehashing.mdx new file mode 100644 index 000000000..47fe17ffd --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/lib/messagehashing.mdx @@ -0,0 +1,24 @@ +# `MessageHashing` + +### _hashMessage + +```solidity +function _hashMessage(address _from, address _to, uint256 _fee, uint256 _valueSent, uint256 _messageNumber, bytes _calldata) internal pure returns (bytes32 messageHash) +``` + +Hashes messages using assembly for efficiency. + +_Adding 0xc0 is to indicate the calldata offset relative to the memory being added to. +If the calldata is not modulus 32, the extra bit needs to be added on at the end else the hash is wrong._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _from | address | The from address. | +| _to | address | The to address. | +| _fee | uint256 | The fee paid for delivery. | +| _valueSent | uint256 | The value to be sent when delivering. | +| _messageNumber | uint256 | The unique message number. | +| _calldata | bytes | The calldata to be passed to the destination address. | + diff --git a/docs/api/linea-smart-contracts/messageservice/lib/ratelimiter.mdx b/docs/api/linea-smart-contracts/messageservice/lib/ratelimiter.mdx new file mode 100644 index 000000000..d5f9f44ef --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/lib/ratelimiter.mdx @@ -0,0 +1,111 @@ +# `RateLimiter` + +You can use this control numeric limits over a period using timestamp. + +### RATE_LIMIT_SETTER_ROLE + +```solidity +bytes32 RATE_LIMIT_SETTER_ROLE +``` + +### USED_RATE_LIMIT_RESETTER_ROLE + +```solidity +bytes32 USED_RATE_LIMIT_RESETTER_ROLE +``` + +### periodInSeconds + +```solidity +uint256 periodInSeconds +``` + +### limitInWei + +```solidity +uint256 limitInWei +``` + +### currentPeriodEnd + +```solidity +uint256 currentPeriodEnd +``` + +The time at which the current period ends at. + +_Public for ease of consumption._ + +### currentPeriodAmountInWei + +```solidity +uint256 currentPeriodAmountInWei +``` + +Amounts already withdrawn this period. + +_Public for ease of consumption._ + +### __RateLimiter_init + +```solidity +function __RateLimiter_init(uint256 _periodInSeconds, uint256 _limitInWei) internal +``` + +Initialises the limits and period for the rate limiter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _periodInSeconds | uint256 | The length of the period in seconds. | +| _limitInWei | uint256 | The limit allowed in the period in Wei. | + +### _addUsedAmount + +```solidity +function _addUsedAmount(uint256 _usedAmount) internal +``` + +Increments the amount used in the period. + +_The amount determining logic is external to this (e.g. fees are included when calling here). +Ignores the calculation if _usedAmount is zero. +Reverts if the limit is breached._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _usedAmount | uint256 | The amount used to be added. | + +### resetRateLimitAmount + +```solidity +function resetRateLimitAmount(uint256 _amount) external +``` + +Resets the rate limit amount. + +_If the used amount is higher, it is set to the limit to avoid confusion/issues. +Only the RATE_LIMIT_SETTER_ROLE is allowed to execute this function. +Emits the LimitAmountChanged event. +usedLimitAmountToSet will use the default value of zero if period has expired._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _amount | uint256 | The amount to reset the limit to. | + +### resetAmountUsedInPeriod + +```solidity +function resetAmountUsedInPeriod() external +``` + +Resets the amount used to zero. + +_Only the USED_RATE_LIMIT_RESETTER_ROLE is allowed to execute this function. +Emits the AmountUsedInPeriodReset event._ + diff --git a/docs/api/linea-smart-contracts/messageservice/lib/sparsemerkletreeverifier.mdx b/docs/api/linea-smart-contracts/messageservice/lib/sparsemerkletreeverifier.mdx new file mode 100644 index 000000000..3c1cf650a --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/lib/sparsemerkletreeverifier.mdx @@ -0,0 +1,66 @@ +# `SparseMerkleTreeVerifier` + +### SafeCastOverflowedUintDowncast + +```solidity +error SafeCastOverflowedUintDowncast(uint8 bits, uint256 value) +``` + +_Value doesn't fit in a uint of `bits` size. +This is based on OpenZeppelin's SafeCast library._ + +### LeafIndexOutOfBounds + +```solidity +error LeafIndexOutOfBounds(uint32 leafIndex, uint32 maxAllowedIndex) +``` + +_Custom error for when the leaf index is out of bounds._ + +### _verifyMerkleProof + +```solidity +function _verifyMerkleProof(bytes32 _leafHash, bytes32[] _proof, uint32 _leafIndex, bytes32 _root) internal pure returns (bool proofIsValid) +``` + +Verify merkle proof + +_The depth of the tree is expected to be validated elsewhere beforehand._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _leafHash | bytes32 | Leaf hash. | +| _proof | bytes32[] | Sparse merkle tree proof. | +| _leafIndex | uint32 | Index of the leaf. | +| _root | bytes32 | Merkle root. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| proofIsValid | bool | Returns if the proof is valid or not. | + +### safeCastToUint32 + +```solidity +function safeCastToUint32(uint256 _value) internal pure returns (uint32 castUint32) +``` + +Tries to safely cast to uint32. + +_This is based on OpenZeppelin's SafeCast library._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _value | uint256 | The value being cast to uint32. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| castUint32 | uint32 | Returns a uint32 safely cast. | + diff --git a/docs/api/linea-smart-contracts/messageservice/lib/timelock.mdx b/docs/api/linea-smart-contracts/messageservice/lib/timelock.mdx new file mode 100644 index 000000000..203043933 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/lib/timelock.mdx @@ -0,0 +1,10 @@ +# `TimeLock` + +This timelock contract will be the owner of all upgrades that gives users confidence and an ability to exit should they want to before an upgrade takes place + +### constructor + +```solidity +constructor(uint256 minDelay, address[] proposers, address[] executors, address admin) public +``` + diff --git a/docs/api/linea-smart-contracts/messageservice/lib/transientstoragehelpers.mdx b/docs/api/linea-smart-contracts/messageservice/lib/transientstoragehelpers.mdx new file mode 100644 index 000000000..68f4f4c9c --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/lib/transientstoragehelpers.mdx @@ -0,0 +1,72 @@ +# `TransientStorageHelpers` + +### tstoreUint256 + +```solidity +function tstoreUint256(bytes32 _key, uint256 _value) internal +``` + +Internal function that stores a uint256 value at a given key in the EVM's transient storage using the `tstore` opcode. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _key | bytes32 | The key in the EVM transient storage where the value should be stored. | +| _value | uint256 | The uint256 value to be stored at the specified key in the EVM transient storage. | + +### tloadUint256 + +```solidity +function tloadUint256(bytes32 _key) internal view returns (uint256 value) +``` + +Internal function that retrieves a uint256 value from the EVM's transient storage using the `tload` opcode. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _key | bytes32 | The key in the EVM transient storage from which the value should be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| value | uint256 | The uint256 value retrieved from the specified key in the EVM transient storage. | + +### tstoreAddress + +```solidity +function tstoreAddress(bytes32 _key, address _addr) internal +``` + +Internal function that stores an address at a given key in the EVM's transient storage using the `tstore` opcode. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _key | bytes32 | The key in the EVM transient storage where the value should be stored. | +| _addr | address | The address to be stored at the specified key in the EVM transient storage. | + +### tloadAddress + +```solidity +function tloadAddress(bytes32 _key) internal view returns (address addr) +``` + +Internal function that retrieves an address from the EVM's transient storage using the `tload` opcode. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _key | bytes32 | The key in the EVM transient storage from which the value should be retrieved. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| addr | address | The address retrieved from the specified key in the EVM transient storage. | + diff --git a/docs/api/linea-smart-contracts/messageservice/messageservicebase.mdx b/docs/api/linea-smart-contracts/messageservice/messageservicebase.mdx new file mode 100644 index 000000000..54ba690d8 --- /dev/null +++ b/docs/api/linea-smart-contracts/messageservice/messageservicebase.mdx @@ -0,0 +1,105 @@ +# `MessageServiceBase` + +### messageService + +```solidity +contract IMessageService messageService +``` + +The message service address on the current chain. + +### remoteSender + +```solidity +address remoteSender +``` + +The token bridge on the alternate/remote chain. + +### RemoteSenderSet + +```solidity +event RemoteSenderSet(address remoteSender, address setter) +``` + +_Event emitted when the remote sender is set._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| remoteSender | address | The address of the new remote sender. | +| setter | address | The address of the account that set the remote sender. | + +### CallerIsNotMessageService + +```solidity +error CallerIsNotMessageService() +``` + +_Thrown when the caller address is not the message service address_ + +### SenderNotAuthorized + +```solidity +error SenderNotAuthorized() +``` + +_Thrown when remote sender address is not authorized._ + +### onlyMessagingService + +```solidity +modifier onlyMessagingService() +``` + +_Modifier to make sure the caller is the known message service. + +Requirements: + +- The msg.sender must be the message service._ + +### onlyAuthorizedRemoteSender + +```solidity +modifier onlyAuthorizedRemoteSender() +``` + +_Modifier to make sure the original sender is allowed. + +Requirements: + +- The original message sender via the message service must be a known sender._ + +### __MessageServiceBase_init + +```solidity +function __MessageServiceBase_init(address _messageService) internal +``` + +Initializes the message service + +_Must be initialized in the initialize function of the main contract or constructor._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageService | address | The message service address, cannot be empty. | + +### _setRemoteSender + +```solidity +function _setRemoteSender(address _remoteSender) internal +``` + +Sets the remote sender + +_This function sets the remote sender address and emits the RemoteSenderSet event._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _remoteSender | address | The authorized remote sender address, cannot be empty. | + diff --git a/docs/api/linea-smart-contracts/tokenbridge/bridgedtoken.mdx b/docs/api/linea-smart-contracts/tokenbridge/bridgedtoken.mdx new file mode 100644 index 000000000..8f7c4d585 --- /dev/null +++ b/docs/api/linea-smart-contracts/tokenbridge/bridgedtoken.mdx @@ -0,0 +1,89 @@ +# `BridgedToken` + +ERC20 token created when a native token is bridged to a target chain. + +### bridge + +```solidity +address bridge +``` + +### _decimals + +```solidity +uint8 _decimals +``` + +### OnlyBridge + +```solidity +error OnlyBridge(address bridgeAddress) +``` + +### constructor + +```solidity +constructor() public +``` + +_Disable constructor for safety_ + +### initialize + +```solidity +function initialize(string _tokenName, string _tokenSymbol, uint8 _tokenDecimals) external +``` + +### onlyBridge + +```solidity +modifier onlyBridge() +``` + +_Ensures call come from the bridge._ + +### mint + +```solidity +function mint(address _recipient, uint256 _amount) external +``` + +_Called by the bridge to mint tokens during a bridge transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _recipient | address | The address to receive the minted tokens. | +| _amount | uint256 | The amount of tokens to mint. | + +### burn + +```solidity +function burn(address _account, uint256 _amount) external +``` + +_Called by the bridge to burn tokens during a bridge transaction. +User should first have allowed the bridge to spend tokens on their behalf._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _account | address | The account from which tokens will be burned. | +| _amount | uint256 | The amount of tokens to burn. | + +### decimals + +```solidity +function decimals() public view returns (uint8) +``` + +_Overrides ERC20 default function to support tokens with different decimals._ + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint8 | The number of decimal. | + diff --git a/docs/api/linea-smart-contracts/tokenbridge/custombridgedtoken.mdx b/docs/api/linea-smart-contracts/tokenbridge/custombridgedtoken.mdx new file mode 100644 index 000000000..eef9c2b58 --- /dev/null +++ b/docs/api/linea-smart-contracts/tokenbridge/custombridgedtoken.mdx @@ -0,0 +1,10 @@ +# `CustomBridgedToken` + +Custom ERC20 token manually deployed for the Linea TokenBridge. + +### initializeV2 + +```solidity +function initializeV2(string _tokenName, string _tokenSymbol, uint8 _tokenDecimals, address _bridge) public +``` + diff --git a/docs/api/linea-smart-contracts/tokenbridge/interfaces/itokenbridge.mdx b/docs/api/linea-smart-contracts/tokenbridge/interfaces/itokenbridge.mdx new file mode 100644 index 000000000..2225d9481 --- /dev/null +++ b/docs/api/linea-smart-contracts/tokenbridge/interfaces/itokenbridge.mdx @@ -0,0 +1,486 @@ +# `ITokenBridge` + +### InitializationData + +```solidity +struct InitializationData { + address defaultAdmin; + address messageService; + address tokenBeacon; + uint256 sourceChainId; + uint256 targetChainId; + address[] reservedTokens; + struct IPermissionsManager.RoleAddress[] roleAddresses; + struct IPauseManager.PauseTypeRole[] pauseTypeRoles; + struct IPauseManager.PauseTypeRole[] unpauseTypeRoles; +} +``` + +### TokenReserved + +```solidity +event TokenReserved(address token) +``` + +Emitted when the token address is reserved. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | address | The indexed token address. | + +### ReservationRemoved + +```solidity +event ReservationRemoved(address token) +``` + +Emitted when the token address reservation is removed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | address | The indexed token address. | + +### CustomContractSet + +```solidity +event CustomContractSet(address nativeToken, address customContract, address setBy) +``` + +Emitted when the custom token address is set. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| nativeToken | address | The indexed nativeToken token address. | +| customContract | address | The indexed custom contract address. | +| setBy | address | The indexed address of who set the custom contract. | + +### BridgingInitiated + +```solidity +event BridgingInitiated(address sender, address recipient, address token, uint256 amount) +``` + +Emitted when token bridging is initiated. + +_DEPRECATED in favor of BridgingInitiatedV2._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | The indexed sender address. | +| recipient | address | The recipient address. | +| token | address | The indexed token address. | +| amount | uint256 | The indexed token amount. | + +### BridgingInitiatedV2 + +```solidity +event BridgingInitiatedV2(address sender, address recipient, address token, uint256 amount) +``` + +Emitted when token bridging is initiated. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | The indexed sender address. | +| recipient | address | The indexed recipient address. | +| token | address | The indexed token address. | +| amount | uint256 | The token amount. | + +### BridgingFinalized + +```solidity +event BridgingFinalized(address nativeToken, address bridgedToken, uint256 amount, address recipient) +``` + +Emitted when token bridging is finalized. + +_DEPRECATED in favor of BridgingFinalizedV2._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| nativeToken | address | The indexed native token address. | +| bridgedToken | address | The indexed bridged token address. | +| amount | uint256 | The indexed token amount. | +| recipient | address | The recipient address. | + +### BridgingFinalizedV2 + +```solidity +event BridgingFinalizedV2(address nativeToken, address bridgedToken, uint256 amount, address recipient) +``` + +Emitted when token bridging is finalized. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| nativeToken | address | The indexed native token address. | +| bridgedToken | address | The indexed bridged token address. | +| amount | uint256 | The token amount. | +| recipient | address | The indexed recipient address. | + +### NewToken + +```solidity +event NewToken(address token) +``` + +Emitted when a new token is seen being bridged on the origin chain for the first time. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | address | The indexed token address. | + +### NewTokenDeployed + +```solidity +event NewTokenDeployed(address bridgedToken, address nativeToken) +``` + +Emitted when a new token is deployed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| bridgedToken | address | The indexed bridged token address. | +| nativeToken | address | The indexed native token address. | + +### RemoteTokenBridgeSet + +```solidity +event RemoteTokenBridgeSet(address remoteTokenBridge, address setBy) +``` + +Emitted when the remote token bridge is set. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| remoteTokenBridge | address | The indexed remote token bridge address. | +| setBy | address | The indexed address that set the remote token bridge. | + +### TokenDeployed + +```solidity +event TokenDeployed(address token) +``` + +Emitted when the token is set as deployed. + +_This can be triggered by anyone calling confirmDeployment on the alternate chain._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | address | The indexed token address. | + +### DeploymentConfirmed + +```solidity +event DeploymentConfirmed(address[] tokens, address confirmedBy) +``` + +Emitted when the token deployment is confirmed. + +_This can be triggered by anyone provided there is correctly mapped token data._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokens | address[] | The token address list. | +| confirmedBy | address | The indexed address confirming deployment. | + +### MessageServiceUpdated + +```solidity +event MessageServiceUpdated(address newMessageService, address oldMessageService, address setBy) +``` + +Emitted when the message service address is set. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newMessageService | address | The indexed new message service address. | +| oldMessageService | address | The indexed old message service address. | +| setBy | address | The indexed address setting the new message service address. | + +### ReservedToken + +```solidity +error ReservedToken(address token) +``` + +_Thrown when attempting to bridge a reserved token._ + +### RemoteTokenBridgeAlreadySet + +```solidity +error RemoteTokenBridgeAlreadySet(address remoteTokenBridge) +``` + +_Thrown when the remote token bridge is already set._ + +### AlreadyBridgedToken + +```solidity +error AlreadyBridgedToken(address token) +``` + +_Thrown when attempting to reserve an already bridged token._ + +### InvalidPermitData + +```solidity +error InvalidPermitData(bytes4 permitData, bytes4 permitSelector) +``` + +_Thrown when the permit data is invalid._ + +### PermitNotFromSender + +```solidity +error PermitNotFromSender(address owner) +``` + +_Thrown when the permit is not from the sender._ + +### PermitNotAllowingBridge + +```solidity +error PermitNotAllowingBridge(address spender) +``` + +_Thrown when the permit does not grant spending to the bridge._ + +### ZeroAmountNotAllowed + +```solidity +error ZeroAmountNotAllowed(uint256 amount) +``` + +_Thrown when the amount being bridged is zero._ + +### NotReserved + +```solidity +error NotReserved(address token) +``` + +_Thrown when trying to unreserve a non-reserved token._ + +### TokenNotDeployed + +```solidity +error TokenNotDeployed(address token) +``` + +_Thrown when trying to confirm deployment of a non-deployed token._ + +### AlreadyBrigedToNativeTokenSet + +```solidity +error AlreadyBrigedToNativeTokenSet(address token) +``` + +_Thrown when trying to set a custom contract on a bridged token._ + +### NativeToBridgedTokenAlreadySet + +```solidity +error NativeToBridgedTokenAlreadySet(address token) +``` + +_Thrown when trying to set a custom contract on an already set token._ + +### StatusAddressNotAllowed + +```solidity +error StatusAddressNotAllowed(address token) +``` + +_Thrown when trying to set a token that is already either native, deployed or reserved._ + +### DecimalsAreUnknown + +```solidity +error DecimalsAreUnknown(address token) +``` + +_Thrown when the decimals for a token cannot be determined._ + +### TokenListEmpty + +```solidity +error TokenListEmpty() +``` + +_Thrown when the token list is empty._ + +### bridgeTokenWithPermit + +```solidity +function bridgeTokenWithPermit(address _token, uint256 _amount, address _recipient, bytes _permitData) external payable +``` + +Similar to `bridgeToken` function but allows to pass additional + permit data to do the ERC20 approval in a single transaction. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be bridged. | +| _amount | uint256 | The amount of the token to be bridged. | +| _recipient | address | The address that will receive the tokens on the other chain. | +| _permitData | bytes | The permit data for the token, if applicable. | + +### completeBridging + +```solidity +function completeBridging(address _nativeToken, uint256 _amount, address _recipient, uint256 _chainId, bytes _tokenMetadata) external +``` + +_It can only be called from the Message Service. To finalize the bridging + process, a user or postmen needs to use the `claimMessage` function of the + Message Service to trigger the transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeToken | address | The address of the token on its native chain. | +| _amount | uint256 | The amount of the token to be received. | +| _recipient | address | The address that will receive the tokens. | +| _chainId | uint256 | The source chainId or target chaindId for this token | +| _tokenMetadata | bytes | Additional data used to deploy the bridged token if it doesn't exist already. | + +### confirmDeployment + +```solidity +function confirmDeployment(address[] _tokens) external payable +``` + +_Change the status to DEPLOYED to the tokens passed in parameter + Will call the method setDeployed on the other chain using the message Service_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _tokens | address[] | Array of bridged tokens that have been deployed. | + +### setMessageService + +```solidity +function setMessageService(address _messageService) external +``` + +_Change the address of the Message Service._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageService | address | The address of the new Message Service. | + +### setDeployed + +```solidity +function setDeployed(address[] _nativeTokens) external +``` + +_It can only be called from the Message Service. To change the status of + the native tokens to DEPLOYED meaning they have been deployed on the other chain + a user or postman needs to use the `claimMessage` function of the + Message Service to trigger the transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeTokens | address[] | The addresses of the native tokens. | + +### setReserved + +```solidity +function setReserved(address _token) external +``` + +Make sure that _token is native to the current chain + where you are calling this function from + +_Linea can reserve tokens. In this case, the token cannot be bridged. + Linea can only reserve tokens that have not been bridged before._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be set as reserved. | + +### setRemoteTokenBridge + +```solidity +function setRemoteTokenBridge(address _remoteTokenBridge) external +``` + +_Sets the address of the remote token bridge. Can only be called once._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _remoteTokenBridge | address | The address of the remote token bridge to be set. | + +### removeReserved + +```solidity +function removeReserved(address _token) external +``` + +_Removes a token from the reserved list._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be removed from the reserved list. | + +### setCustomContract + +```solidity +function setCustomContract(address _nativeToken, address _targetContract) external +``` + +_Linea can set a custom ERC20 contract for specific ERC20. + For security purpose, Linea can only call this function if the token has + not been bridged yet._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeToken | address | address of the token on the source chain. | +| _targetContract | address | address of the custom contract. | + diff --git a/docs/api/linea-smart-contracts/tokenbridge/lib/storagefiller39.mdx b/docs/api/linea-smart-contracts/tokenbridge/lib/storagefiller39.mdx new file mode 100644 index 000000000..54576613e --- /dev/null +++ b/docs/api/linea-smart-contracts/tokenbridge/lib/storagefiller39.mdx @@ -0,0 +1,2 @@ +# `StorageFiller39` + diff --git a/docs/api/linea-smart-contracts/tokenbridge/tokenbridge.mdx b/docs/api/linea-smart-contracts/tokenbridge/tokenbridge.mdx new file mode 100644 index 000000000..f333b32e7 --- /dev/null +++ b/docs/api/linea-smart-contracts/tokenbridge/tokenbridge.mdx @@ -0,0 +1,523 @@ +# `TokenBridge` + +Contract to manage cross-chain ERC20 bridging. + +### CONTRACT_VERSION + +```solidity +string CONTRACT_VERSION +``` + +_This is the ABI version and not the reinitialize version._ + +### SET_MESSAGE_SERVICE_ROLE + +```solidity +bytes32 SET_MESSAGE_SERVICE_ROLE +``` + +Role used for setting the message service address. + +### SET_REMOTE_TOKENBRIDGE_ROLE + +```solidity +bytes32 SET_REMOTE_TOKENBRIDGE_ROLE +``` + +Role used for setting the remote token bridge address. + +### SET_RESERVED_TOKEN_ROLE + +```solidity +bytes32 SET_RESERVED_TOKEN_ROLE +``` + +Role used for setting a reserved token address. + +### REMOVE_RESERVED_TOKEN_ROLE + +```solidity +bytes32 REMOVE_RESERVED_TOKEN_ROLE +``` + +Role used for removing a reserved token address. + +### SET_CUSTOM_CONTRACT_ROLE + +```solidity +bytes32 SET_CUSTOM_CONTRACT_ROLE +``` + +Role used for setting a custom token contract address. + +### EMPTY + +```solidity +address EMPTY +``` + +EMPTY means a token is not present in the mapping. + +### RESERVED_STATUS + +```solidity +address RESERVED_STATUS +``` + +RESERVED means a token is reserved and cannot be bridged. + +### NATIVE_STATUS + +```solidity +address NATIVE_STATUS +``` + +NATIVE means a token is native to the current local chain. + +### DEPLOYED_STATUS + +```solidity +address DEPLOYED_STATUS +``` + +DEPLOYED means the bridged token contract has been deployed on the remote chain. + +### _PERMIT_SELECTOR + +```solidity +bytes4 _PERMIT_SELECTOR +``` + +_The permit selector to be used when decoding the permit._ + +### tokenBeacon + +```solidity +address tokenBeacon +``` + +The token beacon for deployed tokens. + +### nativeToBridgedToken + +```solidity +mapping(uint256 => mapping(address => address)) nativeToBridgedToken +``` + +The chainId mapped to a native token address which is then mapped to the bridged token address. + +### bridgedToNativeToken + +```solidity +mapping(address => address) bridgedToNativeToken +``` + +The bridged token address mapped to the native token address. + +### sourceChainId + +```solidity +uint256 sourceChainId +``` + +The current layer's chainId from where the bridging is triggered. + +### targetChainId + +```solidity +uint256 targetChainId +``` + +The targeted layer's chainId where the bridging is received. + +### isNewToken + +```solidity +modifier isNewToken(address _token) +``` + +_Ensures the token has not been bridged before._ + +### nonZeroAddress + +```solidity +modifier nonZeroAddress(address _addr) +``` + +_Ensures the address is not address(0)._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _addr | address | Address to check. | + +### nonZeroAmount + +```solidity +modifier nonZeroAmount(uint256 _amount) +``` + +_Ensures the amount is not 0._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _amount | uint256 | amount to check. | + +### constructor + +```solidity +constructor() public +``` + +_Disable constructor for safety_ + +### initialize + +```solidity +function initialize(struct ITokenBridge.InitializationData _initializationData) external +``` + +Initializes TokenBridge and underlying service dependencies - used for new networks only. + +_Contract will be used as proxy implementation._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _initializationData | struct ITokenBridge.InitializationData | The initial data used for initializing the TokenBridge contract. | + +### reinitializePauseTypesAndPermissions + +```solidity +function reinitializePauseTypesAndPermissions(address _defaultAdmin, struct IPermissionsManager.RoleAddress[] _roleAddresses, struct IPauseManager.PauseTypeRole[] _pauseTypeRoles, struct IPauseManager.PauseTypeRole[] _unpauseTypeRoles) external +``` + +Sets permissions for a list of addresses and their roles as well as initialises the PauseManager pauseType:role mappings. + +_This function is a reinitializer and can only be called once per version. Should be called using an upgradeAndCall transaction to the ProxyAdmin._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _defaultAdmin | address | The default admin account's address. | +| _roleAddresses | struct IPermissionsManager.RoleAddress[] | The list of addresses and roles to assign permissions to. | +| _pauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of pause types to associate with roles. | +| _unpauseTypeRoles | struct IPauseManager.PauseTypeRole[] | The list of unpause types to associate with roles. | + +### bridgeToken + +```solidity +function bridgeToken(address _token, uint256 _amount, address _recipient) public payable +``` + +This function is the single entry point to bridge tokens to the + other chain, both for native and already bridged tokens. You can use it + to bridge any ERC20. If the token is bridged for the first time an ERC20 + (BridgedToken.sol) will be automatically deployed on the target chain. + +_User should first allow the bridge to transfer tokens on his behalf. + Alternatively, you can use BridgeTokenWithPermit to do so in a single + transaction. If you want the transfer to be automatically executed on the + destination chain. You should send enough ETH to pay the postman fees. + Note that Linea can reserve some tokens (which use a dedicated bridge). + In this case, the token cannot be bridged. Linea can only reserve tokens + that have not been bridged yet. + Linea can pause the bridge for security reason. In this case new bridge + transaction would revert. +Note: If, when bridging an unbridged token and decimals are unknown, +the call will revert to prevent mismatched decimals. Only those ERC20s, +with a decimals function are supported._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be bridged. | +| _amount | uint256 | The amount of the token to be bridged. | +| _recipient | address | The address that will receive the tokens on the other chain. | + +### bridgeTokenWithPermit + +```solidity +function bridgeTokenWithPermit(address _token, uint256 _amount, address _recipient, bytes _permitData) external payable +``` + +Similar to `bridgeToken` function but allows to pass additional + permit data to do the ERC20 approval in a single transaction. +_permit can fail silently, don't rely on this function passing as a form + of authentication + +_There is no need for validation at this level as the validation on pausing, +and empty values exists on the "bridgeToken" call._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be bridged. | +| _amount | uint256 | The amount of the token to be bridged. | +| _recipient | address | The address that will receive the tokens on the other chain. | +| _permitData | bytes | The permit data for the token, if applicable. | + +### completeBridging + +```solidity +function completeBridging(address _nativeToken, uint256 _amount, address _recipient, uint256 _chainId, bytes _tokenMetadata) external +``` + +_It can only be called from the Message Service. To finalize the bridging + process, a user or postman needs to use the `claimMessage` function of the + Message Service to trigger the transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeToken | address | The address of the token on its native chain. | +| _amount | uint256 | The amount of the token to be received. | +| _recipient | address | The address that will receive the tokens. | +| _chainId | uint256 | The token's origin layer chaindId | +| _tokenMetadata | bytes | Additional data used to deploy the bridged token if it doesn't exist already. | + +### setMessageService + +```solidity +function setMessageService(address _messageService) external +``` + +_Change the address of the Message Service. +SET_MESSAGE_SERVICE_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _messageService | address | The address of the new Message Service. | + +### confirmDeployment + +```solidity +function confirmDeployment(address[] _tokens) external payable +``` + +_Change the status to DEPLOYED to the tokens passed in parameter + Will call the method setDeployed on the other chain using the message Service_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _tokens | address[] | Array of bridged tokens that have been deployed. | + +### setDeployed + +```solidity +function setDeployed(address[] _nativeTokens) external +``` + +_Change the status of tokens to DEPLOYED. New bridge transaction will not + contain token metadata, which save gas. + Can only be called from the Message Service. A user or postman needs to use + the `claimMessage` function of the Message Service to trigger the transaction._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeTokens | address[] | Array of native tokens for which the DEPLOYED status must be set. | + +### setRemoteTokenBridge + +```solidity +function setRemoteTokenBridge(address _remoteTokenBridge) external +``` + +_Sets the address of the remote token bridge. Can only be called once. +SET_REMOTE_TOKENBRIDGE_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _remoteTokenBridge | address | The address of the remote token bridge to be set. | + +### deployBridgedToken + +```solidity +function deployBridgedToken(address _nativeToken, bytes _tokenMetadata, uint256 _chainId) internal returns (address bridgedTokenAddress) +``` + +_Deploy a new EC20 contract for bridged token using a beacon proxy pattern. + To adapt to future requirements, Linea can update the implementation of + all (existing and future) contracts by updating the beacon. This update is + subject to a delay by a time lock. + Contracts are deployed using CREATE2 so deployment address is deterministic._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeToken | address | The address of the native token on the source chain. | +| _tokenMetadata | bytes | The encoded metadata for the token. | +| _chainId | uint256 | The chain id on which the token will be deployed, used to calculate the salt | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| bridgedTokenAddress | address | The address of the newly deployed BridgedToken contract. | + +### setReserved + +```solidity +function setReserved(address _token) external +``` + +Make sure that _token is native to the current chain + where you are calling this function from + +_Linea can reserve tokens. In this case, the token cannot be bridged. + Linea can only reserve tokens that have not been bridged before. +SET_RESERVED_TOKEN_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be set as reserved. | + +### removeReserved + +```solidity +function removeReserved(address _token) external +``` + +_Removes a token from the reserved list. +REMOVE_RESERVED_TOKEN_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the token to be removed from the reserved list. | + +### setCustomContract + +```solidity +function setCustomContract(address _nativeToken, address _targetContract) external +``` + +_Linea can set a custom ERC20 contract for specific ERC20. + For security purpose, Linea can only call this function if the token has + not been bridged yet. +SET_CUSTOM_CONTRACT_ROLE is required to execute._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _nativeToken | address | The address of the token on the source chain. | +| _targetContract | address | The address of the custom contract. | + +### _safeName + +```solidity +function _safeName(address _token) internal view returns (string tokenName) +``` + +_Provides a safe ERC20.name version which returns 'NO_NAME' as fallback string._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the ERC-20 token contract | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenName | string | Returns the string of the token name. | + +### _safeSymbol + +```solidity +function _safeSymbol(address _token) internal view returns (string symbol) +``` + +_Provides a safe ERC20.symbol version which returns 'NO_SYMBOL' as fallback string_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the ERC-20 token contract | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| symbol | string | Returns the string of the symbol. | + +### _safeDecimals + +```solidity +function _safeDecimals(address _token) internal view returns (uint8) +``` + +Provides a safe ERC20.decimals version which reverts when decimals are unknown + Note Tokens with (decimals > 255) are not supported + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | The address of the ERC-20 token contract | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint8 | Returns the token's decimals value. | + +### _returnDataToString + +```solidity +function _returnDataToString(bytes _data) internal pure returns (string decodedString) +``` + +_Converts returned data to string. Returns 'NOT_VALID_ENCODING' as fallback value._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _data | bytes | returned data. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| decodedString | string | The decoded string data. | + +### _permit + +```solidity +function _permit(address _token, bytes _permitData) internal +``` + +Call the token permit method of extended ERC20 +Only support tokens implementing ERC-2612 + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | address | ERC20 token address | +| _permitData | bytes | Raw data of the call `permit` of the token | + diff --git a/docs/api/linea-smart-contracts/zkevmv2.mdx b/docs/api/linea-smart-contracts/zkevmv2.mdx new file mode 100644 index 000000000..c74fc6891 --- /dev/null +++ b/docs/api/linea-smart-contracts/zkevmv2.mdx @@ -0,0 +1,64 @@ +# `ZkEvmV2` + +### MODULO_R + +```solidity +uint256 MODULO_R +``` + +### OPERATOR_ROLE + +```solidity +bytes32 OPERATOR_ROLE +``` + +### currentTimestamp + +```solidity +uint256 currentTimestamp +``` + +_DEPRECATED in favor of currentFinalizedState hash._ + +### currentL2BlockNumber + +```solidity +uint256 currentL2BlockNumber +``` + +The most recent finalized L2 block number. + +### stateRootHashes + +```solidity +mapping(uint256 => bytes32) stateRootHashes +``` + +The most recent L2 state root hash mapped by block number. + +### verifiers + +```solidity +mapping(uint256 => address) verifiers +``` + +The verifier address to use for a proof type when proving. + +### _verifyProof + +```solidity +function _verifyProof(uint256 _publicInput, uint256 _proofType, bytes _proof) internal +``` + +Verifies the proof with locally computed public inputs. + +_If the verifier based on proof type is not found, it reverts with InvalidProofType._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _publicInput | uint256 | The computed public input hash cast as uint256. | +| _proofType | uint256 | The proof type to determine which verifier contract to use. | +| _proof | bytes | The proof to be verified with the proof type verifier contract. | + diff --git a/sidebars.js b/sidebars.js index 050e700ad..a4a9ccf30 100644 --- a/sidebars.js +++ b/sidebars.js @@ -23,13 +23,13 @@ const sidebars = { items: [ "get-started/build/quickstart/deploy", "get-started/build/quickstart/app", - ] + ], }, "get-started/build/ethereum-differences", "get-started/build/network-info", "get-started/build/contracts", "get-started/build/block-explorers", - "get-started/build/repos" + "get-started/build/repos", ], }, { @@ -124,12 +124,12 @@ const sidebars = { label: "Sequencer", link: { type: "doc", - id: "get-started/concepts/sequencer/index" + id: "get-started/concepts/sequencer/index", }, items: [ "get-started/concepts/sequencer/conflation", - "get-started/concepts/sequencer/traces-generator" - ] + "get-started/concepts/sequencer/traces-generator", + ], }, "get-started/concepts/state-manager", { @@ -137,14 +137,14 @@ const sidebars = { label: "Prover", link: { type: "doc", - id: "get-started/concepts/prover/index" + id: "get-started/concepts/prover/index", }, items: [ "get-started/concepts/prover/proving", "get-started/concepts/prover/trace-expansion", - "get-started/concepts/prover/prover-limits" - ] - } + "get-started/concepts/prover/prover-limits", + ], + }, ], }, { @@ -250,23 +250,23 @@ const sidebars = { label: "DipDup", link: { type: "doc", - id: "get-started/tooling/data-indexers/dipdup/overview" + id: "get-started/tooling/data-indexers/dipdup/overview", }, items: [ "get-started/tooling/data-indexers/dipdup/overview", - "get-started/tooling/data-indexers/dipdup/quickstart", + "get-started/tooling/data-indexers/dipdup/quickstart", ], - }, + }, "get-started/tooling/data-indexers/dune", "get-started/tooling/data-indexers/envio", "get-started/tooling/data-indexers/etherscan", - "get-started/tooling/data-indexers/flair", + "get-started/tooling/data-indexers/flair", { type: "category", label: "Goldsky", link: { type: "doc", - id: "get-started/tooling/data-indexers/goldsky/overview" + id: "get-started/tooling/data-indexers/goldsky/overview", }, items: [ "get-started/tooling/data-indexers/goldsky/overview", @@ -310,9 +310,7 @@ const sidebars = { type: "doc", id: "get-started/tooling/node-providers/index", }, - items: [ - "get-started/tooling/node-providers/erpc", - ], + items: ["get-started/tooling/node-providers/erpc"], }, { type: "category", @@ -338,7 +336,7 @@ const sidebars = { label: "Permanent data", link: { type: "doc", - id: "get-started/tooling/permanent-data/index" + id: "get-started/tooling/permanent-data/index", }, items: [ { @@ -346,7 +344,7 @@ const sidebars = { label: "Irys", link: { type: "doc", - id: "get-started/tooling/permanent-data/irys/overview" + id: "get-started/tooling/permanent-data/irys/overview", }, items: [ "get-started/tooling/permanent-data/irys/overview", @@ -377,7 +375,7 @@ const sidebars = { "get-started/tooling/security/scamfari", "get-started/tooling/security/spherex", "get-started/tooling/security/hexagate", - "get-started/tooling/security/hypernative" + "get-started/tooling/security/hypernative", ], }, { @@ -410,7 +408,7 @@ const sidebars = { label: "Ecosystem tutorials", link: { type: "doc", - id: "learn/ecosystem-tutorials/index" + id: "learn/ecosystem-tutorials/index", }, collapsible: false, items: [ @@ -419,17 +417,17 @@ const sidebars = { label: "Irys", link: { type: "doc", - id: "learn/ecosystem-tutorials/irys/index" + id: "learn/ecosystem-tutorials/irys/index", }, items: [ "learn/ecosystem-tutorials/irys/irys-dynamic-nfts", "learn/ecosystem-tutorials/irys/irys-nfts", - ] - } - ] - } - ] - } + ], + }, + ], + }, + ], + }, ], apiSidebar: [ { @@ -447,10 +445,167 @@ const sidebars = { "api/reference/linea-estimategas", "api/reference/linea-gettransactionexclusionstatusv1", "api/reference/linea-getproof", - ] + ], }, "api/linea-sdk", - ] -} + { + type: "category", + label: "Linea smart contracts", + link: null, + collapsible: false, + items: [ + "api/linea-smart-contracts/linearollup", + "api/linea-smart-contracts/zkevmv2", + { + type: "category", + label: "Interfaces", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/interfaces/igenericerrors", + "api/linea-smart-contracts/interfaces/imessageservice", + "api/linea-smart-contracts/interfaces/ipausemanager", + "api/linea-smart-contracts/interfaces/ipermissionsmanager", + "api/linea-smart-contracts/interfaces/iratelimiter", + { + type: "category", + label: "L1", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/interfaces/l1/il1messagemanager", + "api/linea-smart-contracts/interfaces/l1/il1messagemanagerv1", + "api/linea-smart-contracts/interfaces/l1/il1messageservice", + "api/linea-smart-contracts/interfaces/l1/ilinearollup", + "api/linea-smart-contracts/interfaces/l1/iplonkverifier", + "api/linea-smart-contracts/interfaces/l1/izkevmv2", + ], + }, + { + type: "category", + label: "L2", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/interfaces/l2/il2messagemanager", + "api/linea-smart-contracts/interfaces/l2/il2messagemanagerv1", + "api/linea-smart-contracts/interfaces/l2/il2messageservicev1", + ], + }, + ], + }, + { + type: "category", + label: "lib", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/lib/callforwardingproxy", + "api/linea-smart-contracts/lib/l2messageservicepausemanager", + "api/linea-smart-contracts/lib/linearolluppausemanager", + "api/linea-smart-contracts/lib/mimc", + "api/linea-smart-contracts/lib/pausemanager", + "api/linea-smart-contracts/lib/permissionsmanager", + "api/linea-smart-contracts/lib/sparsemerkleproof", + "api/linea-smart-contracts/lib/tokenbridgepausemanager", + "api/linea-smart-contracts/lib/utils", + ], + }, + { + type: "category", + label: "Message service", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/messageservicebase", + { + type: "category", + label: "L1", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/l1/l1messagemanager", + "api/linea-smart-contracts/messageservice/l1/l1messageservice", + "api/linea-smart-contracts/messageservice/l1/transientstoragereentrancyguardupgradeable", + { + type: "category", + label: "v1", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/l1/v1/l1messagemanagerv1", + "api/linea-smart-contracts/messageservice/l1/v1/l1messageservicev1", + ], + }, + ], + }, + { + type: "category", + label: "L2", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/l2/l2messagemanager", + "api/linea-smart-contracts/messageservice/l2/l2messageservice", + { + type: "category", + label: "v1", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/l2/v1/l2messagemanagerv1", + "api/linea-smart-contracts/messageservice/l2/v1/l2messageservicev1", + ], + }, + ], + }, + { + type: "category", + label: "lib", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/messageservice/lib/messagehashing", + "api/linea-smart-contracts/messageservice/lib/ratelimiter", + "api/linea-smart-contracts/messageservice/lib/sparsemerkletreeverifier", + "api/linea-smart-contracts/messageservice/lib/timelock", + "api/linea-smart-contracts/messageservice/lib/transientstoragehelpers", + ], + }, + ], + }, + { + type: "category", + label: "Token bridge", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/tokenbridge/bridgedtoken", + "api/linea-smart-contracts/tokenbridge/custombridgedtoken", + "api/linea-smart-contracts/tokenbridge/tokenbridge", + { + type: "category", + label: "Interfaces", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/tokenbridge/interfaces/itokenbridge", + ], + }, + { + type: "category", + label: "lib", + link: null, + collapsible: true, + items: [ + "api/linea-smart-contracts/tokenbridge/lib/storagefiller39", + ], + }, + ], + }, + ], + }, + ], +}; -module.exports = sidebars; \ No newline at end of file +module.exports = sidebars;