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.

[osr21]

This is an important gotcha — the left-vs-right alignment asymmetry is genuinely easy to miss.

To add some additional context that might be useful for the documentation: this is the inverse of the encoding convention used in EVM-to-EVM cross-chain calls. In CCTP V2's depositForBurn on EVM chains, mintRecipient is right-aligned inside bytes32:

// EVM → EVM (e.g. Base Sepolia → Ethereum Sepolia via CCTP V2)
bytes32 mintRecipient = bytes32(uint256(uint160(recipientAddress))); // right-aligned

But as this issue correctly identifies, Base's TokenLib.finalizeTransfer decodes Solana-origin recipients as left-aligned:

// Solana → Base (TokenLib.finalizeTransfer)
address to = address(bytes20(transfer.to)); // reads first 20 bytes — expects left-aligned

So the two encoding conventions are:

Direction	Convention	Solidity
EVM → EVM (CCTP V2)	Right-aligned (zero-padded left)	bytes32(uint256(uint160(addr)))
Solana → Base	Left-aligned (zero-padded right)	bytes32(bytes20(addr))

Using the wrong one produces a silently incorrect recipient — the bridge doesn't revert, the funds just arrive at the wrong address.

A clear note in the SDK and docs distinguishing these two encoding paths (with a table like the one above) would prevent a lot of debugging pain. The current error mode (silent misdirection rather than a revert) makes it especially dangerous.

[FernLovesCrypto]

Nice catch — this is exactly the kind of mismatch that's easy to hit in practice, since ABI-style right-aligned encoding (bytes32(uint256(uint160(recipient)))) is the default mental model for anyone coming from typical Solidity/ethers tooling.
Worth noting this fails silently rather than loudly: address(bytes20(transfer.to)) will still return a syntactically valid address for a right-aligned input — it's just the wrong one (the high 96 bits + first 8 bytes of the real address, effectively garbage). So a misencoded transfer doesn't revert, it just sends funds to an address nobody controls. That makes this more than a docs issue — I'd suggest pairing the documentation fix (#196) with a runtime guard, e.g. require(uint256(transfer.to) & type(uint96).max == 0, "invalid recipient encoding") in the decode path. Left-aligned encodings always have zero low 96 bits; right-aligned ones essentially never do for a real address, so this converts the common integration mistake into a revert instead of unrecoverable fund loss.

[osr21]

Nice catch. One pattern worth considering that doesn't require changing the encoding convention (avoiding a breaking change for already-integrated clients): make TokenLib.finalizeTransfer() fail loudly instead of silently misrouting funds when a client gets the alignment wrong.

Circle's CCTP TokenMessenger handles the analogous problem for its (right-aligned) mintRecipient field by requiring the unused bytes to be zero before casting to address, and reverting otherwise. The same idea applied here, since finalizeTransfer takes the first 20 bytes:

require(uint256(transfer.to) & type(uint96).max == 0, "TokenLib: recipient not left-aligned");
address to = address(bytes20(transfer.to));

If a client (or a Solana program) accidentally right-aligns the address (bytes32(uint256(uint160(recipient)))), the low 96 bits will almost always be non-zero, so this check reverts the transfer instead of quietly crediting the wrong recipient — turning a silent fund-misdirection risk into an explicit, cheap on-chain revert.