feat(LibBytes): add address<->bytes32 conversion helpers (EXSC-618) [LibBytes v1.1.0]

.agents/rules/100-solidity-basics.md

@@ -22,6 +22,15 @@ paths:
 - Functions/vars camelCase; constants & immutables are CONSTANT_CASE.
 - Function params use leading underscore (e.g., `_amount`).
 
+## Address ⇄ bytes32 Conversions ([CONV:ADDR-BYTES32])
+
+- Use the `LibBytes` helpers; never hand-roll the cast:
+  - `LibBytes.toBytes32(addr)` — address → bytes32 (widening, lossless).
+  - `LibBytes.toAddress(b)` — bytes32 → address, **checked** (reverts `NotAnAddress` if the top 96 bits are set). This is the default.
+  - `LibBytes.toAddressUnchecked(b)` — bytes32 → address by truncation; only where dropping the high bits is intentional / already guarded.
+- A raw `bytes32(uint256(uint160(x)))` / `address(uint160(uint256(x)))` in new code is flagged by the Olympix `unsafe-downcast` detector. The helper centralises the (dismissed) finding so call sites stay clean.
+- Numeric narrowing (`uintN(...)`) is out of scope here — tracked separately (EXSC-617).
+
 ## NatSpec Requirements ([CONV:NATSPEC])
 
 - Contracts & interfaces must include:

src/Facets/AcrossFacetPackedV4.sol

@@ -190,6 +190,7 @@ contract AcrossFacetPackedV4 is ILiFi, TransferrableOwnership, LiFiData {
 
         // pull tokens from msg.sender
         LibAsset.transferFromERC20(
+            // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
             address(uint160(uint256(sendingAssetId))),
             msg.sender,
             address(this),
@@ -229,6 +230,7 @@ contract AcrossFacetPackedV4 is ILiFi, TransferrableOwnership, LiFiData {
     ) external {
         // Deposit assets
         LibAsset.transferFromERC20(
+            // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
             address(uint160(uint256(sendingAssetId))),
             msg.sender,
             address(this),
@@ -357,6 +359,7 @@ contract AcrossFacetPackedV4 is ILiFi, TransferrableOwnership, LiFiData {
         // Check if receiver is EVM address (20 bytes) or non-EVM (longer)
         // If the first 12 bytes are zero, it's likely an EVM address
         if (bytes12(data[44:56]) == bytes12(0)) {
+            // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
             bridgeData.receiver = address(
                 uint160(uint256(bytes32(data[44:76])))
             );
@@ -398,12 +401,14 @@ contract AcrossFacetPackedV4 is ILiFi, TransferrableOwnership, LiFiData {
         }
 
         bridgeData.transactionId = bytes32(data[4:12]); // we truncate intentionally to save gas (not dangerous)
+        // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
         bridgeData.sendingAssetId = address(
             uint160(uint256(bytes32(data[76:108])))
         ); // sendingAssetId
         // Check if receiver is EVM address (20 bytes) or non-EVM (longer)
         // If the first 12 bytes are zero, it's likely an EVM address
         if (bytes12(data[44:56]) == bytes12(0)) {
+            // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
             bridgeData.receiver = address(
                 uint160(uint256(bytes32(data[44:76])))
             );

src/Facets/AcrossFacetV4.sol

@@ -265,6 +265,7 @@ contract AcrossFacetV4 is
     function _convertAddressToBytes32(
         address _address
     ) internal pure returns (bytes32) {
+        // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
         return bytes32(uint256(uint160(_address)));
     }
 }

src/Facets/AcrossV4SwapFacet.sol

@@ -359,6 +359,7 @@ contract AcrossV4SwapFacet is
 
         // Validate asset matches for ERC20 flows
         bool isNative = LibAsset.isNativeAsset(_bridgeData.sendingAssetId);
+        // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
         address decodedInputToken = address(
             uint160(uint256(params.inputToken))
         );
@@ -609,6 +610,7 @@ contract AcrossV4SwapFacet is
         _validateAmount(quote.amount, _bridgeData.minAmount);
 
         // Validate burnToken matches bridgeData asset (native is already excluded by msg.value check above)
+        // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
         address burnToken = address(uint160(uint256(quote.burnToken)));
         if (burnToken != _bridgeData.sendingAssetId) {
             revert InformationMismatch();
@@ -826,6 +828,7 @@ contract AcrossV4SwapFacet is
     function _convertAddressToBytes32(
         address _address
     ) internal pure returns (bytes32) {
+        // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
         return bytes32(uint256(uint160(_address)));
     }
 }

src/Facets/AllBridgeFacet.sol

@@ -155,6 +155,7 @@ contract AllBridgeFacet is
         } else {
             // destination chain is EVM
             // make sure that bridgeData and allBridgeData receiver addresses match
+            // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
             if (
                 _bridgeData.receiver !=
                 address(uint160(uint256(_allBridgeData.recipient)))
@@ -172,6 +173,7 @@ contract AllBridgeFacet is
         if (_allBridgeData.payFeeWithSendingAsset) {
             // pay fee with sending asset
             ALLBRIDGE.swapAndBridge(
+                // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
                 bytes32(uint256(uint160(_bridgeData.sendingAssetId))),
                 _bridgeData.minAmount,
                 _allBridgeData.recipient,
@@ -184,6 +186,7 @@ contract AllBridgeFacet is
         } else {
             // pay fee with native asset
             ALLBRIDGE.swapAndBridge{ value: _allBridgeData.fees }(
+                // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
                 bytes32(uint256(uint160(_bridgeData.sendingAssetId))),
                 _bridgeData.minAmount,
                 _allBridgeData.recipient,

src/Facets/CalldataVerificationFacet.sol

@@ -395,6 +395,7 @@ contract CalldataVerificationFacet {
         }
 
         // Convert callToBytes32 to address type and compare them
+        // TODO(EXSC-626): migrate to LibBytes.toAddressUnchecked (intentional truncation) — see LibBytes v1.1.0
         address callToAddressFromBytes32 = address(
             uint160(uint256(callToBytes32))
         );

src/Facets/CelerCircleBridgeFacet.sol

@@ -125,6 +125,7 @@ contract CelerCircleBridgeFacet is
         CIRCLE_BRIDGE_PROXY.depositForBurn(
             _bridgeData.minAmount,
             uint64(_bridgeData.destinationChainId),
+            // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
             bytes32(uint256(uint160(_bridgeData.receiver))),
             USDC,
             _celerCircleData.maxFee,

src/Facets/GlacisFacet.sol

@@ -131,6 +131,7 @@ contract GlacisFacet is
         } else {
             // destination chain is EVM
             // make sure that bridgeData and glacisData receiver addresses match
+            // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
             if (
                 _bridgeData.receiver !=
                 address(uint160(uint256(_glacisData.receiverAddress)))

src/Facets/LiFiIntentEscrowFacet.sol

@@ -202,6 +202,7 @@ contract LiFiIntentEscrowFacet is
         } else {
             // Check if the receiver is the same according to bridgeData and LIFIIntentData
             // Note: We already know 0 <= _bridgeData.receiver < recipient != 0 thus _bridgeData.receiver != 0.
+            // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
             if (recipient != bytes32(uint256(uint160(_bridgeData.receiver)))) {
                 revert InvalidReceiver();
             }

src/Facets/LiFiIntentEscrowFacetV2.sol

@@ -204,6 +204,7 @@ contract LiFiIntentEscrowFacetV2 is
         } else {
             // Check if the receiver is the same according to bridgeData and LIFIIntentData
             // Note: We already know 0 <= _bridgeData.receiver < recipient != 0 thus _bridgeData.receiver != 0.
+            // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
             if (recipient != bytes32(uint256(uint160(_bridgeData.receiver)))) {
                 revert InvalidReceiver();
             }

src/Facets/NEARIntentsFacet.sol

@@ -275,6 +275,7 @@ contract NEARIntentsFacet is
         ILiFi.BridgeData memory _bridgeData,
         NEARIntentsData calldata _nearData
     ) internal view {
+        // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
         bytes32 receiverBytes32 = _bridgeData.receiver == NON_EVM_ADDRESS
             ? _nearData.nonEVMReceiver
             : bytes32(uint256(uint160(_bridgeData.receiver)));

src/Facets/PolymerCCTPFacet.sol

@@ -286,6 +286,7 @@ contract PolymerCCTPFacet is
             TOKEN_MESSENGER.depositForBurn(
                 bridgeAmount,
                 _chainIdToDomainId(destinationChainId),
+                // TODO(EXSC-626): migrate to LibBytes.toBytes32 — see LibBytes v1.1.0
                 bytes32(uint256(uint160(_bridgeData.receiver))),
                 USDC,
                 UNRESTRICTED_DESTINATION_CALLER,

src/Facets/StargateFacetV2.sol

@@ -111,6 +111,7 @@ contract StargateFacetV2 is ILiFi, ReentrancyGuard, SwapperV2, Validatable {
         ) revert InformationMismatch();
 
         // ensure that receiver addresses match in case of no destination call
+        // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
         if (
             !_bridgeData.hasDestinationCall &&
             (_bridgeData.receiver !=

src/Libraries/LibBytes.sol

@@ -1,14 +1,16 @@
 // SPDX-License-Identifier: LGPL-3.0-only
 pragma solidity ^0.8.17;
 
-/// @custom:version 1.0.0
+/// @custom:version 1.1.0
 library LibBytes {
     // solhint-disable no-inline-assembly
 
     // LibBytes specific errors
     error SliceOverflow();
     error SliceOutOfBounds();
     error AddressOutOfBounds();
+    error HexLengthInsufficient();
+    error NotAnAddress(bytes32 value);
 
     bytes16 private constant _SYMBOLS = "0123456789abcdef";
 
@@ -121,8 +123,33 @@ library LibBytes {
             buffer[i] = _SYMBOLS[value & 0xf];
             value >>= 4;
         }
-        // solhint-disable-next-line gas-custom-errors
-        require(value == 0, "Strings: hex length insufficient");
+        if (value != 0) revert HexLengthInsufficient();
         return string(buffer);
     }
+
+    /// @notice Left-zero-pads an address into bytes32. Widening — always lossless.
+    /// @param _addr The address to convert.
+    /// @return The bytes32 representation of the address.
+    function toBytes32(address _addr) internal pure returns (bytes32) {
+        return bytes32(uint256(uint160(_addr)));
+    }
+
+    /// @notice Narrows a left-zero-padded bytes32 to an address, reverting if the
+    ///         top 96 bits are set (checked downcast).
+    /// @param _value The bytes32 value to convert.
+    /// @return The address representation of the bytes32.
+    function toAddress(bytes32 _value) internal pure returns (address) {
+        if (uint256(_value) >> 160 != 0) revert NotAnAddress(_value);
+        return address(uint160(uint256(_value)));
+    }
+
+    /// @notice Narrows a bytes32 to an address by truncation, keeping only the low
+    ///         160 bits. Use ONLY where dropping the high bits is intentional.
+    /// @param _value The bytes32 value to convert.
+    /// @return The address representation of the low 160 bits.
+    function toAddressUnchecked(
+        bytes32 _value
+    ) internal pure returns (address) {
+        return address(uint160(uint256(_value)));
+    }
 }

src/Periphery/ReceiverOIF.sol

@@ -90,6 +90,7 @@ contract ReceiverOIF is ILiFi, WithdrawablePeriphery, IOutputCallback {
         _swapAndCompleteBridgeTokens(
             transactionId,
             swapData,
+            // TODO(EXSC-626): migrate to LibBytes.toAddress (checked) — see LibBytes v1.1.0
             address(uint160(uint256(token))),
             payable(receiver),
             amount

test/solidity/Libraries/LibBytes.t.sol

@@ -28,6 +28,20 @@ contract LibBytesHarness {
     ) external pure returns (string memory) {
         return LibBytes.toHexString(_value, _length);
     }
+
+    function toBytes32(address _addr) external pure returns (bytes32) {
+        return LibBytes.toBytes32(_addr);
+    }
+
+    function toAddress(bytes32 _value) external pure returns (address) {
+        return LibBytes.toAddress(_value);
+    }
+
+    function toAddressUnchecked(
+        bytes32 _value
+    ) external pure returns (address) {
+        return LibBytes.toAddressUnchecked(_value);
+    }
 }
 
 contract LibBytesTest is Test {
@@ -90,8 +104,44 @@ contract LibBytesTest is Test {
     }
 
     function testRevert_toHexString_LengthInsufficient() public {
-        vm.expectRevert("Strings: hex length insufficient");
+        vm.expectRevert(LibBytes.HexLengthInsufficient.selector);
 
         harness.toHexString(uint256(0x1234), 1);
     }
+
+    function test_toBytes32_LeftZeroPadsAddress() public {
+        address addr = address(0x1234567890AbcdEF1234567890aBcdef12345678);
+
+        assertEq(harness.toBytes32(addr), bytes32(uint256(uint160(addr))));
+    }
+
+    function test_toAddress_bytes32_RoundTrips() public {
+        address addr = address(0x1234567890AbcdEF1234567890aBcdef12345678);
+
+        assertEq(harness.toAddress(harness.toBytes32(addr)), addr);
+    }
+
+    function test_toAddress_bytes32_ZeroValue() public {
+        assertEq(harness.toAddress(bytes32(0)), address(0));
+    }
+
+    function testRevert_toAddress_bytes32_HighBitsSet() public {
+        bytes32 dirty = bytes32(
+            (uint256(1) << 160) |
+                uint160(0x1234567890AbcdEF1234567890aBcdef12345678)
+        );
+
+        vm.expectRevert(
+            abi.encodeWithSelector(LibBytes.NotAnAddress.selector, dirty)
+        );
+
+        harness.toAddress(dirty);
+    }
+
+    function test_toAddressUnchecked_TruncatesHighBits() public {
+        address addr = address(0x1234567890AbcdEF1234567890aBcdef12345678);
+        bytes32 dirty = bytes32((uint256(1) << 160) | uint160(addr));
+
+        assertEq(harness.toAddressUnchecked(dirty), addr);
+    }
 }