Add stellar tx new begin-sponsoring-future-reserves and stellar tx new end-sponsoring-future-reserves. (#2213)

Author: fnando

FULL_HELP_DOCS.md

@@ -1706,6 +1706,7 @@ Create a new transaction
 ###### **Subcommands:**
 
 * `account-merge` — Transfer XLM balance to another account and remove source account
+* `begin-sponsoring-future-reserves` — Begin sponsoring future reserves for another account
 * `bump-sequence` — Bump sequence number to invalidate older transactions
 * `change-trust` — Create, update, or delete a trustline
 * `claim-claimable-balance` — Claim a claimable balance by its balance ID
@@ -1714,6 +1715,7 @@ Create a new transaction
 * `create-account` — Create and fund a new account
 * `create-claimable-balance` — Create a claimable balance that can be claimed by specified accounts
 * `create-passive-sell-offer` — Create a passive sell offer on the Stellar DEX
+* `end-sponsoring-future-reserves` — End sponsoring future reserves
 * `liquidity-pool-deposit` — Deposit assets into a liquidity pool
 * `liquidity-pool-withdraw` — Withdraw assets from a liquidity pool
 * `manage-buy-offer` — Create, update, or delete a buy offer
@@ -1756,6 +1758,35 @@ Transfer XLM balance to another account and remove source account
 
 
 
+## `stellar tx new begin-sponsoring-future-reserves`
+
+Begin sponsoring future reserves for another account
+
+**Usage:** `stellar tx new begin-sponsoring-future-reserves [OPTIONS] --source-account <SOURCE_ACCOUNT> --sponsored-id <SPONSORED_ID>`
+
+###### **Options:**
+
+* `--fee <FEE>` — fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm
+
+  Default value: `100`
+* `--cost` — Output the cost execution to stderr
+* `--instructions <INSTRUCTIONS>` — Number of instructions to simulate
+* `--build-only` — Build the transaction and only write the base64 xdr to stdout
+* `--rpc-url <RPC_URL>` — RPC server endpoint
+* `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
+* `--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
+* `-s`, `--source-account <SOURCE_ACCOUNT>` [alias: `source`] — Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail
+* `--global` — ⚠️ Deprecated: global config is always on
+* `--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
+* `--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
+* `--sponsored-id <SPONSORED_ID>` — Account that will be sponsored
+
+
+
 ## `stellar tx new bump-sequence`
 
 Bump sequence number to invalidate older transactions
@@ -2007,6 +2038,34 @@ Create a passive sell offer on the Stellar DEX
 
 
 
+## `stellar tx new end-sponsoring-future-reserves`
+
+End sponsoring future reserves
+
+**Usage:** `stellar tx new end-sponsoring-future-reserves [OPTIONS] --source-account <SOURCE_ACCOUNT>`
+
+###### **Options:**
+
+* `--fee <FEE>` — fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm
+
+  Default value: `100`
+* `--cost` — Output the cost execution to stderr
+* `--instructions <INSTRUCTIONS>` — Number of instructions to simulate
+* `--build-only` — Build the transaction and only write the base64 xdr to stdout
+* `--rpc-url <RPC_URL>` — RPC server endpoint
+* `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
+* `--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
+* `-s`, `--source-account <SOURCE_ACCOUNT>` [alias: `source`] — Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail
+* `--global` — ⚠️ Deprecated: global config is always on
+* `--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
+* `--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
+
+
+
 ## `stellar tx new liquidity-pool-deposit`
 
 Deposit assets into a liquidity pool
@@ -2380,6 +2439,7 @@ Add Operation to a transaction
 ###### **Subcommands:**
 
 * `account-merge` — Transfer XLM balance to another account and remove source account
+* `begin-sponsoring-future-reserves` — Begin sponsoring future reserves for another account
 * `bump-sequence` — Bump sequence number to invalidate older transactions
 * `change-trust` — Create, update, or delete a trustline
 * `claim-claimable-balance` — Claim a claimable balance by its balance ID
@@ -2388,6 +2448,7 @@ Add Operation to a transaction
 * `create-account` — Create and fund a new account
 * `create-claimable-balance` — Create a claimable balance that can be claimed by specified accounts
 * `create-passive-sell-offer` — Create a passive sell offer on the Stellar DEX
+* `end-sponsoring-future-reserves` — End sponsoring future reserves
 * `liquidity-pool-deposit` — Deposit assets into a liquidity pool
 * `liquidity-pool-withdraw` — Withdraw assets from a liquidity pool
 * `manage-buy-offer` — Create, update, or delete a buy offer
@@ -2435,6 +2496,40 @@ Transfer XLM balance to another account and remove source account
 
 
 
+## `stellar tx operation add begin-sponsoring-future-reserves`
+
+Begin sponsoring future reserves for another account
+
+**Usage:** `stellar tx operation add begin-sponsoring-future-reserves [OPTIONS] --source-account <SOURCE_ACCOUNT> --sponsored-id <SPONSORED_ID> [TX_XDR]`
+
+###### **Arguments:**
+
+* `<TX_XDR>` — Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty
+
+###### **Options:**
+
+* `--operation-source-account <OPERATION_SOURCE_ACCOUNT>` [alias: `op-source`] — Source account used for the operation
+* `--fee <FEE>` — fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm
+
+  Default value: `100`
+* `--cost` — Output the cost execution to stderr
+* `--instructions <INSTRUCTIONS>` — Number of instructions to simulate
+* `--build-only` — Build the transaction and only write the base64 xdr to stdout
+* `--rpc-url <RPC_URL>` — RPC server endpoint
+* `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
+* `--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
+* `-s`, `--source-account <SOURCE_ACCOUNT>` [alias: `source`] — Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail
+* `--global` — ⚠️ Deprecated: global config is always on
+* `--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
+* `--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
+* `--sponsored-id <SPONSORED_ID>` — Account that will be sponsored
+
+
+
 ## `stellar tx operation add bump-sequence`
 
 Bump sequence number to invalidate older transactions
@@ -2726,6 +2821,39 @@ Create a passive sell offer on the Stellar DEX
 
 
 
+## `stellar tx operation add end-sponsoring-future-reserves`
+
+End sponsoring future reserves
+
+**Usage:** `stellar tx operation add end-sponsoring-future-reserves [OPTIONS] --source-account <SOURCE_ACCOUNT> [TX_XDR]`
+
+###### **Arguments:**
+
+* `<TX_XDR>` — Base-64 transaction envelope XDR or file containing XDR to decode, or stdin if empty
+
+###### **Options:**
+
+* `--operation-source-account <OPERATION_SOURCE_ACCOUNT>` [alias: `op-source`] — Source account used for the operation
+* `--fee <FEE>` — fee amount for transaction, in stroops. 1 stroop = 0.0000001 xlm
+
+  Default value: `100`
+* `--cost` — Output the cost execution to stderr
+* `--instructions <INSTRUCTIONS>` — Number of instructions to simulate
+* `--build-only` — Build the transaction and only write the base64 xdr to stdout
+* `--rpc-url <RPC_URL>` — RPC server endpoint
+* `--rpc-header <RPC_HEADERS>` — RPC Header(s) to include in requests to the RPC provider
+* `--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
+* `-s`, `--source-account <SOURCE_ACCOUNT>` [alias: `source`] — Account that where transaction originates from. Alias `source`. Can be an identity (--source alice), a public key (--source GDKW...), a muxed account (--source MDA…), a secret key (--source SC36…), or a seed phrase (--source "kite urban…"). If `--build-only` or `--sim-only` flags were NOT provided, this key will also be used to sign the final transaction. In that case, trying to sign with public key will fail
+* `--global` — ⚠️ Deprecated: global config is always on
+* `--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
+* `--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
+
+
+
 ## `stellar tx operation add liquidity-pool-deposit`
 
 Deposit assets into a liquidity pool

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

@@ -1580,3 +1580,106 @@ async fn clawback() {
         .assert()
         .failure();
 }
+
+#[tokio::test]
+async fn begin_sponsoring_future_reserves() {
+    let sandbox = &TestEnv::new();
+    let client = sandbox.network.rpc_client().unwrap();
+
+    // Create sponsor account (use test account as sponsor)
+    let sponsor = test_address(sandbox);
+
+    // Create a new account to sponsor (but don't fund it)
+    let sponsored_account = gen_account_no_fund(sandbox, "sponsored");
+
+    let sponsor_balance_before = client.get_account(&sponsor).await.unwrap().balance;
+
+    let sponsor_tx = sandbox
+        .new_assert_cmd("tx")
+        .args([
+            "new",
+            "begin-sponsoring-future-reserves",
+            "--source-account",
+            "test",
+            "--sponsored-id",
+            &sponsored_account,
+            "--fee",
+            "1000000", // Higher fee for sponsoring operations
+            "--build-only",
+        ])
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    // Add create account operation with sponsor as operation source
+    let create_account_tx = sandbox
+        .new_assert_cmd("tx")
+        .args([
+            "op",
+            "add",
+            "create-account",
+            "--destination",
+            &sponsored_account,
+            "--starting-balance",
+            "50000000",
+            "--operation-source-account",
+            "test", // sponsor account
+        ])
+        .write_stdin(sponsor_tx.as_bytes())
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    // Add end sponsoring future reserves operation with sponsored account as operation source
+    let complete_tx = sandbox
+        .new_assert_cmd("tx")
+        .args([
+            "op",
+            "add",
+            "end-sponsoring-future-reserves",
+            "--operation-source-account",
+            "sponsored",
+        ])
+        .write_stdin(create_account_tx.as_bytes())
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    // Sign with sponsor first
+    let sponsor_signed_tx = sandbox
+        .new_assert_cmd("tx")
+        .args(["sign", "--sign-with-key=test"])
+        .write_stdin(complete_tx.as_bytes())
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    // Sign with sponsored account second
+    let fully_signed_tx = sandbox
+        .new_assert_cmd("tx")
+        .args(["sign", "--sign-with-key=sponsored"])
+        .write_stdin(sponsor_signed_tx.as_bytes())
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    // Submit the transaction
+    sandbox
+        .new_assert_cmd("tx")
+        .arg("send")
+        .write_stdin(fully_signed_tx.as_bytes())
+        .assert()
+        .success();
+
+    let sponsor_balance_after = client.get_account(&sponsor).await.unwrap().balance;
+
+    // The sponsored account should exist
+    let sponsored_account_info = client.get_account(&sponsored_account).await.unwrap();
+    assert_eq!(sponsored_account_info.balance, 50000000);
+
+    // The sponsor account balance should be lower due to sponsoring the reserves
+    assert!(
+        sponsor_balance_after < sponsor_balance_before,
+        "Sponsor account should have paid for the sponsored account reserves"
+    );
+}

cmd/soroban-cli/src/commands/tx/help.rs

@@ -20,3 +20,6 @@ pub const PATH_PAYMENT_STRICT_RECEIVE: &str =
 pub const PAYMENT: &str = "Send asset to destination account";
 pub const SET_OPTIONS: &str = "Set account options like flags, signers, and home domain";
 pub const SET_TRUSTLINE_FLAGS: &str = "Configure authorization and trustline flags for an asset";
+pub const BEGIN_SPONSORING_FUTURE_RESERVES: &str =
+    "Begin sponsoring future reserves for another account";
+pub const END_SPONSORING_FUTURE_RESERVES: &str = "End sponsoring future reserves";

cmd/soroban-cli/src/commands/tx/new/begin_sponsoring_future_reserves.rs

@@ -0,0 +1,35 @@
+use clap::{command, Parser};
+
+use crate::{commands::tx, config::address, xdr};
+
+#[derive(Parser, Debug, Clone)]
+#[group(skip)]
+pub struct Cmd {
+    #[command(flatten)]
+    pub tx: tx::Args,
+    #[clap(flatten)]
+    pub op: Args,
+}
+
+#[derive(Debug, clap::Args, Clone)]
+pub struct Args {
+    /// Account that will be sponsored
+    #[arg(long)]
+    pub sponsored_id: address::UnresolvedMuxedAccount,
+}
+
+impl TryFrom<&Cmd> for xdr::OperationBody {
+    type Error = tx::args::Error;
+    fn try_from(
+        Cmd {
+            tx,
+            op: Args { sponsored_id },
+        }: &Cmd,
+    ) -> Result<Self, Self::Error> {
+        Ok(xdr::OperationBody::BeginSponsoringFutureReserves(
+            xdr::BeginSponsoringFutureReservesOp {
+                sponsored_id: tx.resolve_account_id(sponsored_id)?,
+            },
+        ))
+    }
+}

cmd/soroban-cli/src/commands/tx/new/end_sponsoring_future_reserves.rs

@@ -0,0 +1,23 @@
+use clap::{command, Parser};
+
+use crate::{commands::tx, xdr};
+
+#[derive(Parser, Debug, Clone)]
+#[group(skip)]
+pub struct Cmd {
+    #[command(flatten)]
+    pub tx: tx::Args,
+    #[clap(flatten)]
+    pub op: Args,
+}
+
+#[derive(Debug, clap::Args, Clone)]
+pub struct Args {
+    // EndSponsoringFutureReserves has no parameters
+}
+
+impl From<&Cmd> for xdr::OperationBody {
+    fn from(_cmd: &Cmd) -> Self {
+        xdr::OperationBody::EndSponsoringFutureReserves
+    }
+}