diff --git a/l1-contracts/contracts/common/libraries/DataEncoding.sol b/l1-contracts/contracts/common/libraries/DataEncoding.sol
index 9df83d67a..ee22cbfab 100644
--- a/l1-contracts/contracts/common/libraries/DataEncoding.sol
+++ b/l1-contracts/contracts/common/libraries/DataEncoding.sol
@@ -120,7 +120,12 @@ library DataEncoding {
         }
     }
 
-    /// @notice Decodes the token data by combining chain id, asset deployment tracker and asset data.
+    /// @notice Decodes the token data
+    /// @dev Note that all the returned metadata of the token is ABI encoded.
+    /// @return chainId The chainId of the origin of the token
+    /// @return name The name of the token.
+    /// @return symbol The symbol of the token.
+    /// @return decimals The decimals of the token.
     function decodeTokenData(
         bytes calldata _tokenData
     ) internal pure returns (uint256 chainId, bytes memory name, bytes memory symbol, bytes memory decimals) {
@@ -135,7 +140,8 @@ library DataEncoding {
         }
     }
 
-    /// @notice Encodes the token data by combining chain id, asset deployment tracker and asset data.
+    /// @notice Encodes the token data by combining chain id, and its metadata.
+    /// @dev Note that all the metadata of the token is expected to be ABI encoded.
     /// @param _chainId The id of the chain token is native to.
     /// @param _name The name of the token.
     /// @param _symbol The symbol of the token.
diff --git a/l1-contracts/contracts/dev-contracts/test/CustomUpgradeTest.sol b/l1-contracts/contracts/dev-contracts/test/CustomUpgradeTest.sol
index 7055ce557..0a3958724 100644
--- a/l1-contracts/contracts/dev-contracts/test/CustomUpgradeTest.sol
+++ b/l1-contracts/contracts/dev-contracts/test/CustomUpgradeTest.sol
@@ -25,7 +25,7 @@ contract CustomUpgradeTest is BaseZkSyncUpgrade {
     /// upgrade.
     function _postUpgrade(bytes calldata _customCallDataForUpgrade) internal override {}
 
-    /// @notice The main function that will be called by the upgrade proxy.
+    /// @notice The main function that will be delegate-called by the chain.
     /// @param _proposedUpgrade The upgrade to be executed.
     function upgrade(ProposedUpgrade calldata _proposedUpgrade) public override returns (bytes32) {
         (uint32 newMinorVersion, bool isPatchOnly) = _setNewProtocolVersion(_proposedUpgrade.newProtocolVersion);
diff --git a/l1-contracts/contracts/upgrades/BaseZkSyncUpgrade.sol b/l1-contracts/contracts/upgrades/BaseZkSyncUpgrade.sol
index edae3870b..32dc186c4 100644
--- a/l1-contracts/contracts/upgrades/BaseZkSyncUpgrade.sol
+++ b/l1-contracts/contracts/upgrades/BaseZkSyncUpgrade.sol
@@ -63,7 +63,7 @@ abstract contract BaseZkSyncUpgrade is ZKChainBase {
     /// @notice Notifies about complete upgrade
     event UpgradeComplete(uint256 indexed newProtocolVersion, bytes32 indexed l2UpgradeTxHash, ProposedUpgrade upgrade);
 
-    /// @notice The main function that will be provided by the upgrade proxy
+    /// @notice The main function that will be delegate-called by the chain.
     /// @dev This is a virtual function and should be overridden by custom upgrade implementations.
     /// @param _proposedUpgrade The upgrade to be executed.
     /// @return txHash The hash of the L2 system contract upgrade transaction.
diff --git a/l1-contracts/contracts/upgrades/DefaultUpgrade.sol b/l1-contracts/contracts/upgrades/DefaultUpgrade.sol
index c6ebb18dc..87c6dd220 100644
--- a/l1-contracts/contracts/upgrades/DefaultUpgrade.sol
+++ b/l1-contracts/contracts/upgrades/DefaultUpgrade.sol
@@ -8,7 +8,7 @@ import {BaseZkSyncUpgrade, ProposedUpgrade} from "./BaseZkSyncUpgrade.sol";
 /// @author Matter Labs
 /// @custom:security-contact security@matterlabs.dev
 contract DefaultUpgrade is BaseZkSyncUpgrade {
-    /// @notice The main function that will be called by the upgrade proxy.
+    /// @notice The main function that will be delegate-called by the chain.
     /// @param _proposedUpgrade The upgrade to be executed.
     function upgrade(ProposedUpgrade calldata _proposedUpgrade) public override returns (bytes32) {
         super.upgrade(_proposedUpgrade);
diff --git a/l1-contracts/contracts/upgrades/GatewayUpgrade.sol b/l1-contracts/contracts/upgrades/GatewayUpgrade.sol
index 9ce428f96..1348d5f74 100644
--- a/l1-contracts/contracts/upgrades/GatewayUpgrade.sol
+++ b/l1-contracts/contracts/upgrades/GatewayUpgrade.sol
@@ -30,7 +30,7 @@ contract GatewayUpgrade is BaseZkSyncUpgrade, Initializable {
         THIS_ADDRESS = address(this);
     }
 
-    /// @notice The main function that will be called by the upgrade proxy.
+    /// @notice The main function that will be delegate-called by the chain.
     /// @param _proposedUpgrade The upgrade to be executed.
     function upgrade(ProposedUpgrade calldata _proposedUpgrade) public override returns (bytes32) {
         (bytes memory l2TxDataStart, bytes memory l2TxDataFinish) = abi.decode(
diff --git a/l1-contracts/contracts/upgrades/L1GenesisUpgrade.sol b/l1-contracts/contracts/upgrades/L1GenesisUpgrade.sol
index 4637c535d..1feaf77a5 100644
--- a/l1-contracts/contracts/upgrades/L1GenesisUpgrade.sol
+++ b/l1-contracts/contracts/upgrades/L1GenesisUpgrade.sol
@@ -21,7 +21,7 @@ import {L2ContractHelper} from "../common/libraries/L2ContractHelper.sol";
 /// @author Matter Labs
 /// @custom:security-contact security@matterlabs.dev
 contract L1GenesisUpgrade is IL1GenesisUpgrade, BaseZkSyncUpgradeGenesis {
-    /// @notice The main function that will be called by the upgrade proxy.
+    /// @notice The main function that will be delegate-called by the chain.
     function genesisUpgrade(
         address _l1GenesisUpgrade,
         uint256 _chainId,