Add stellar token clawback subcommand

[fnando]

What

Adds stellar token clawback, a SAC-admin write subcommand that claws tokens back from a holder. --source signs and authorizes the clawback (the asset issuer, or whatever address currently administers the Stellar Asset Contract), --from is the holder, and --amount is the quantity in smallest units. Returns a JSON receipt with the tx hash.

Why

Part of #2620 (typed SEP-41 + SAC client), a SAC-admin command alongside mint. A thin wrapper over contract invoke reusing args::invoke_by_position and args::not_deployed_error. Like the other transaction commands it flattens config::Args, so the signer comes from the standard --source (env STELLAR_ACCOUNT, optional with stellar keys use); like mint, the signer only authorizes and is not a clawback argument, so only [from, amount] are passed positionally.

Known limitations

Muxed (M…) source accounts are rejected with a clear error (same constraint as transfer, see #2645). Clawback requires the asset's issuer to have AUTH_CLAWBACK_ENABLED (which also requires AUTH_REVOCABLE) set before the holder's trustline is created — this is an asset-configuration prerequisite, not enforced by the command.

[Copilot]

Pull request overview

Adds stellar token clawback as an SAC-admin wrapper over contract invocation.

Changes:

• Implements clawback execution, validation, authorization, and JSON receipts.
• Registers the command and documents its CLI options.
• Adds integration tests for success and error paths.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
FULL_HELP_DOCS.md	Documents the clawback command.
cmd/soroban-cli/src/commands/token/mod.rs	Registers and dispatches clawback.
cmd/soroban-cli/src/commands/token/clawback.rs	Implements clawback behavior.
cmd/soroban-cli/src/cli.rs	Enables JSON error formatting.
cmd/crates/soroban-test/tests/it/integration/token/mod.rs	Registers clawback tests.
cmd/crates/soroban-test/tests/it/integration/token/clawback.rs	Tests success, deployment errors, and validation.

---

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

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

cmd/soroban-cli/src/commands/token/clawback.rs:145

• --id native reaches this invocation path, but the native SAC has no Admin contract-data entry (see commands/contract/deploy/asset.rs:234-243), so clawback cannot succeed and surfaces only a downstream invoke failure. Detect a resolved native SAC here and return a typed unsupported/invalid-token error before invoking the contract.

        let token = self
            .id
            .resolve(&config.locator, &network.network_passphrase)?;

cmd/soroban-cli/src/commands/token/clawback.rs:153

• This new muxed-admin rejection has no integration coverage, while the equivalent branches are explicitly tested for token transfer and token approve. Add a clawback integration test using an M… admin and assert the clear unsupported error so the known #2645 guard cannot regress into the raw decode failure.

        if matches!(source_account, crate::xdr::MuxedAccount::MuxedEd25519(_)) {
            return Err(Error::MuxedSourceNotSupported);

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation follows established token-command patterns and includes appropriate integration coverage.

Review effort: Balanced
Findings: 1

Open (1)

• parse_nonneg_i128 is duplicated across multiple stellar token subcommands…

[Copilot]

Copilot review overview

🟡 Changes recommended

Muxed holder addresses are forwarded to an unsupported SAC source position, causing opaque simulation failures.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Reject muxed addresses passed as token source · New
• parse_nonneg_i128 is duplicated across multiple stellar token subcommands…

[Copilot]

Copilot review overview

🟡 Changes recommended

The implemented --source interface conflicts with the PR description’s advertised --admin flag.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Documented --admin flag is missing from CLI · New
• Reject muxed addresses passed as token source
• parse_nonneg_i128 is duplicated across multiple stellar token subcommands…

[Copilot]

Copilot review overview

🟡 Changes recommended

The unrelated mint diagnostic regression should be corrected before approval.

Review effort: Balanced
Findings: 2 · 2

Open (4)

• Documented --admin flag is missing from CLI
• Reject muxed addresses passed as token source
• Preserve mint error workaround guidance for G… accounts · New
• parse_nonneg_i128 is duplicated across multiple stellar token subcommands…

[Copilot]

Copilot review overview

🟢 Approval recommended

The focused implementation is consistent with existing token commands and includes comprehensive integration coverage.

Review effort: Balanced
Findings: None

Resolved since last review (4)

• Documented --admin flag is missing from CLI
• Reject muxed addresses passed as token source
• Preserve mint error workaround guidance for G… accounts
• parse_nonneg_i128 is duplicated across multiple stellar token subcommands…