Add stellar token transfer for SEP-41 and Stellar Asset Contracts

FULL_HELP_DOCS.md

@@ -51,6 +51,7 @@ Anything after the `--` double dash (the "slop") is parsed as arguments to the c
 - `container` — Start local networks in containers
 - `config` — Manage CLI configuration
 - `snapshot` — Download a snapshot of a ledger from an archive
+- `token` — Interact with SEP-41 tokens and Stellar Asset Contracts
 - `tx` — Sign, Simulate, and Send transactions
 - `xdr` — Decode and encode XDR
 - `strkey` — Decode and encode strkey
@@ -1839,6 +1840,56 @@ This allows combining snapshots from different contract deployments or manually
 
   Default value: `snapshot.json`
 
+## `stellar token`
+
+Interact with SEP-41 tokens and Stellar Asset Contracts
+
+**Usage:** `stellar token <COMMAND>`
+
+###### **Subcommands:**
+
+- `transfer` — Transfer tokens from one account to another
+
+## `stellar token transfer`
+
+Transfer tokens from one account to another
+
+**Usage:** `stellar token transfer [OPTIONS] --id <ID> --from <FROM> --to <TO> --amount <AMOUNT>`
+
+###### **Global Options:**
+
+- `--config-dir <CONFIG_DIR>` — Location of config directory. By default, it uses `$XDG_CONFIG_HOME/stellar` if set, falling back to `~/.config/stellar` otherwise. Contains configuration files, aliases, and other persistent settings
+
+###### **Options:**
+
+- `--id <ID>` — The token to transfer from: a contract id or alias, `native`, or a classic asset as `CODE:ISSUER`
+- `--from <FROM>` — Account to transfer tokens from. Signs and authorizes the transfer, so it must be an identity or secret key you control
+- `--to <TO>` — Account or contract to transfer the tokens to. Accepts a `G…`/`M…` account, a `C…` contract address, or an alias
+- `--amount <AMOUNT>` — Amount to transfer, in the token's smallest unit (stroops for a Stellar Asset Contract)
+- `--output <OUTPUT>` — Format of the output
+
+  Default value: `text`
+
+  Possible values:
+  - `text`: Human-readable text
+  - `json`: Compact, single-line JSON receipt
+  - `json-formatted`: Formatted (multiline) JSON receipt
+
+###### **RPC Options:**
+
+- `--rpc-url <RPC_URL>` — RPC server endpoint
+- `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider, example: "X-API-Key: abc123". Multiple headers can be added by passing the option multiple times
+- `--network-passphrase <NETWORK_PASSPHRASE>` — Network passphrase to sign the transaction sent to the rpc server
+- `-n`, `--network <NETWORK>` — Name of network to use from config
+
+###### **Signing Options:**
+
+- `--sign-with-key <SIGN_WITH_KEY>` — Sign with a local key or key saved in OS secure storage. Can be an identity (--sign-with-key alice), a secret key (--sign-with-key SC36…), or a seed phrase (--sign-with-key "kite urban…"). If using seed phrase, `--hd-path` defaults to the `0` path
+- `--hd-path <HD_PATH>` — If using a seed phrase to sign, sets which hierarchical deterministic path to use, e.g. `m/44'/148'/{hd_path}`. Example: `--hd-path 1`. Default: `0`
+- `--sign-with-lab` — Sign with https://lab.stellar.org
+- `--sign-with-ledger` — Sign with a ledger wallet
+- `--auto-sign` — Sign without prompting for approval. Only applies to signatures that require user approval, like non-root Soroban auth entries
+
 ## `stellar tx`
 
 Sign, Simulate, and Send transactions

cmd/crates/soroban-test/tests/it/integration.rs

@@ -14,5 +14,6 @@ mod ledger;
 mod network;
 mod secure_store;
 mod snapshot;
+mod token;
 mod tx;
 mod util;

cmd/crates/soroban-test/tests/it/integration/token/mod.rs

@@ -0,0 +1,93 @@
+pub mod transfer;
+
+use soroban_test::{AssertExt, TestEnv};
+
+/// Establish (and auto-authorize) a trustline from `source` to `asset`.
+pub fn add_trustline(sandbox: &TestEnv, source: &str, asset: &str) {
+    sandbox
+        .new_assert_cmd("tx")
+        .args(["new", "change-trust", "--line", asset, "--source", source])
+        .assert()
+        .success();
+}
+
+/// Pay `amount` of `asset` from its issuer to `destination`.
+pub fn issuer_pays(sandbox: &TestEnv, issuer: &str, destination: &str, asset: &str, amount: i128) {
+    sandbox
+        .new_assert_cmd("tx")
+        .args([
+            "new",
+            "payment",
+            "--destination",
+            destination,
+            "--asset",
+            asset,
+            "--amount",
+            &amount.to_string(),
+            "--source",
+            issuer,
+        ])
+        .assert()
+        .success();
+}
+
+/// Deploy the Stellar Asset Contract for `asset`, tolerating the case where a
+/// prior run already deployed it (the SAC is global to the network).
+pub fn deploy_sac(sandbox: &TestEnv, asset: &str, source: &str) {
+    let output = sandbox
+        .new_assert_cmd("contract")
+        .args([
+            "asset",
+            "deploy",
+            "--asset",
+            asset,
+            "--source-account",
+            source,
+        ])
+        .output()
+        .expect("failed to run contract asset deploy");
+
+    // A clean deploy succeeds; the only failure we tolerate is the SAC already
+    // existing on this (persistent) network. Any other failure is a real bug —
+    // surface the captured stderr instead of swallowing it and misdirecting the
+    // failure two steps downstream.
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert!(
+            stderr.contains("contract already exists"),
+            "contract asset deploy failed: {stderr}"
+        );
+    }
+}
+
+/// The contract id of the SAC for `asset`.
+pub fn sac_id(sandbox: &TestEnv, asset: &str) -> String {
+    sandbox
+        .new_assert_cmd("contract")
+        .args(["id", "asset", "--asset", asset])
+        .assert()
+        .success()
+        .stdout_as_str()
+}
+
+/// Read a token's balance for `account` through its Stellar Asset Contract,
+/// returning the raw stroop amount.
+pub fn sac_balance(sandbox: &TestEnv, contract_id: &str, account: &str) -> i128 {
+    let stdout = sandbox
+        .new_assert_cmd("contract")
+        .args([
+            "invoke",
+            "--id",
+            contract_id,
+            "--source-account",
+            "test",
+            "--",
+            "balance",
+            "--id",
+            account,
+        ])
+        .assert()
+        .success()
+        .stdout_as_str();
+    stdout.trim().trim_matches('"').parse().unwrap()
+}