Support muxed account destinations for token transfer

[fnando]

What

Adds real support for muxed (M…) account destinations to token transfer, and hardens muxed handling across the sibling token commands.

• token transfer --to now accepts a muxed (M…) destination — both a direct strkey and an alias whose stored key is muxed. The address is passed through as a muxed ScAddress, and the Stellar Asset Contract records its mux id in the transfer event (to_muxed_id). Verified end-to-end against a local network (protocol 28).
• UnresolvedScAddress::resolve no longer silently collapses a muxed key to its base G… account; it resolves to ScAddress::MuxedAccount, so a transfer reaches the exact recipient (mux id included) that was named.
• The sibling commands still reject muxed accounts up front with a single generic muxed (M…) accounts are not yet supported message, because the host genuinely rejects them there (verified: approve --spender, transfer-from --to, and any muxed source account fail mid-simulation with an opaque host error). The transaction source can't be muxed yet either (see Support muxed (M…) source accounts in the contract invoke pipeline #2645).
• is_muxed_alias now preserves a ShadowedReservedAlias collision as a non-muxed result, so an ambiguous reserved-alias config surfaces the actionable collision error rather than the generic muxed message.

Why

Muxed destinations are supported on-chain for transfer, so the CLI should encode them instead of rejecting or silently downgrading to the base account (which would target a different recipient than the one named). Where the host does not yet accept muxed accounts, a clear up-front error beats an opaque simulation failure.

Testing

• Unit tests: resolve_preserves_muxed_account_alias, is_muxed_alias_false_when_reserved_alias_is_shadowed.
• Integration tests (soroban-test): transfer_to_muxed_destination_succeeds, transfer_to_muxed_alias_succeeds (assert the base account's balance moves), plus the retained muxed-source / sibling rejection tests.

Known limitations

Muxed accounts remain unsupported as a transaction source (#2645) and as approve/transfer-from/burn-from address arguments, matching current host behavior.

[Copilot]

Copilot review overview

🟡 Changes recommended

Account for contract-alias precedence and add coverage for muxed --to aliases in transfer-from.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Honor contract alias precedence before rejecting muxed keys · New
• Add integration coverage for muxed alias in --to · New

What changed in this PR

Hardens muxed-account handling across token commands by standardizing errors and rejecting unsafe muxed aliases.

Changes:

• Adds muxed-alias detection.
• Updates token command validation and error messages.
• Expands integration test coverage.

File	Reviewed changes
cmd/​soroban-cli/​src/​config/​sc_address.rs	Adds muxed-alias detection.
cmd/​soroban-cli/​src/​commands/​token/​transfer.rs	Updates errors and rejects muxed destination aliases.
cmd/​soroban-cli/​src/​commands/​token/​transfer_from.rs	Rejects muxed aliases for source and destination arguments.
cmd/​soroban-cli/​src/​commands/​token/​burn.rs	Standardizes muxed-account errors.
cmd/​soroban-cli/​src/​commands/​token/​approve.rs	Rejects muxed spender aliases.
cmd/​crates/​soroban-test/​tests/​it/​integration/​token/​transfer.rs	Tests muxed destination rejection.
cmd/​crates/​soroban-test/​tests/​it/​integration/​token/​transfer_from.rs	Tests muxed alias rejection.
cmd/​crates/​soroban-test/​tests/​it/​integration/​token/​burn.rs	Updates muxed error expectations.
cmd/​crates/​soroban-test/​tests/​it/​integration/​token/​approve.rs	Tests muxed spender rejection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Fix contract-alias resolution precedence and add coverage for the transfer-from --to muxed-alias path.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Honor contract alias precedence before rejecting muxed keys
• Add integration coverage for muxed alias in --to

[Copilot]

Copilot review overview

🟡 Changes recommended

Preserve ShadowedReservedAlias instead of converting the collision into a generic muxed-account error.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Preserve ShadowedReservedAlias instead of masking it as muxed · New

Resolved since last review (2)

• Honor contract alias precedence before rejecting muxed keys
• Add integration coverage for muxed alias in --to

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate findings remain regarding transfer behavior and test coverage.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 2

Open (4)

• Test mux ID preservation, not just recipient balance · New
• Align PR scope with muxed alias handling · New
• Update rationale for preserved muxed aliases · New
• Update rationale for preserved muxed aliases · New

Resolved since last review (1)

• Preserve ShadowedReservedAlias instead of masking it as muxed

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved findings affect literal muxed-address rejection and mux-id test assertions.

Review effort: Lite
Findings: None

Resolved since last review (4)

• Align PR scope with muxed alias handling
• Test mux ID preservation, not just recipient balance
• Update rationale for preserved muxed aliases
• Update rationale for preserved muxed aliases

Previously missed (3)

In code that hasn't changed since last review

Reject literal muxed spender addresses

cmd/​soroban-cli/​src/​commands/​token/​approve.rs:172

Because is_muxed_alias returns false for an already-parsed UnresolvedScAddress::Resolved, a literal --spender M… bypasses this guard and reaches approve, even though the host rejects muxed spenders. That preserves the opaque simulation failure this preflight is meant to avoid; check both literal and alias-resolved muxed addresses, and cover the literal case with a regression test.

Reject literal muxed from addresses

cmd/​soroban-cli/​src/​commands/​token/​burn_from.rs:168

The new check covers only aliases. A literal --from M… is already a Resolved address, so it bypasses this branch and is passed to burn_from, leaving the user with the host's opaque muxed-account failure rather than the command's clear error. Check resolved muxed addresses as well and add the corresponding direct-strkey regression test.

Preflight reject resolved muxed addresses

cmd/​soroban-cli/​src/​commands/​token/​transfer_from.rs:176

This guard only detects muxed aliases, so literal --from M… or --to M… values are parsed as resolved addresses and bypass it. The command then sends a muxed argument to the host, which rejects these positions with the opaque simulation error described in the surrounding comment; include resolved muxed addresses in the preflight instead of intentionally passing them through.

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate unresolved validation and regression-test issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 2

Open (5)

• Reject resolved muxed spenders before simulation · New
• Reject resolved muxed burn owners upfront · New
• Reject resolved muxed transfer addresses upfront · New
• Update test comment to reflect muxed alias preservation · New
• Correct comment to describe muxed owner rejection · New

[Copilot]

Copilot review overview

🟢 Approval recommended

Only minor help-text nits were identified; no blocking issues remain.

Review effort: Lite
Findings: None

Resolved since last review (5)

• Reject resolved muxed transfer addresses upfront
• Reject resolved muxed burn owners upfront
• Reject resolved muxed spenders before simulation
• Correct comment to describe muxed owner rejection
• Update test comment to reflect muxed alias preservation