Solana-to-Base transfer.to recipient encoding is not clearly documented and is easy to misuse

[mssystem1]

TokenLib.finalizeTransfer() decodes the EVM recipient address from transfer.to using:

address to = address(bytes20(transfer.to));

This takes the first 20 bytes of the bytes32 value.

That means Solana-to-Base EVM recipients must be encoded as left-aligned bytes20 inside bytes32:

bytes32(bytes20(recipient))

This is easy to misuse because common Solidity-style address-to-bytes32 encoding is often right-aligned:

bytes32(uint256(uint160(recipient)))

If a client or integration uses right-aligned encoding, the bridge may decode the wrong recipient address.

[mssystem1]

Expected behavior:

The expected recipient encoding should be clearly documented and ideally exposed through helper functions.

If left-aligned encoding is intended, docs/comments should explicitly say:

// Correct for Solana-to-Base recipient encoding:
to: bytes32(bytes20(recipient))

And warn against:

// Incorrect for current decoding logic:
to: bytes32(uint256(uint160(recipient)))

[mssystem1]

Steps to reproduce:

1. Open base/src/libraries/TokenLib.sol
2. Check finalizeTransfer()
3. Notice recipient decoding:
   address to = address(bytes20(transfer.to));
4. Open base/test/Bridge.t.sol
5. Notice incoming Solana-to-Base transfer tests use:
   to: bytes32(bytes20(user))
6. Compare with the common right-aligned encoding:
   to: bytes32(uint256(uint160(user)))
7. With the current decoding logic, right-aligned encoding would not decode to the intended address

[mssystem1]

Suggested fix option 1: document the encoding in the Transfer struct.

/// @custom:field to Address of the recipient on the target chain.
/// For Solana-to-Base transfers, the EVM address must be encoded as
/// left-aligned bytes20 inside bytes32: bytes32(bytes20(recipient)).

Suggested fix option 2: add helper functions.

function encodeEvmRecipient(address recipient) internal pure returns (bytes32) {
    return bytes32(bytes20(recipient));
}

function decodeEvmRecipient(bytes32 recipient) internal pure returns (address) {
    return address(bytes20(recipient));
}

Suggested fix option 3: if right-aligned ABI-style encoding is intended, change decoding to:

address to = address(uint160(uint256(transfer.to)));

This may be intentional protocol encoding, but it should be documented more clearly because incorrect encoding can silently route funds to the wrong EVM address.

[FernLovesCrypto]

Fernlovescrypto wuz here.