Issues/2282 fee args

[mootz12]

What

Rename the --fee argument to --inclusion-fee, and deprecate the fee argument.

Introduces a new command stellar fees to replace stellar feestats. This has two subcommands:

1. stats, a copy/paste of feestats

$ stellar fees stats

2. use, adds the ability to store default inclusion fee settings based on raw stroops of feestats results

-> w/ stroops

$ stellar fees use --amount 1000                                           
ℹ️  The default inclusion fee is set to `1000`

-> w/ fee stats

$ stellar fees use --fee-metric p99 
ℹ️  The default inclusion fee is set to `200`

-> to remove

$ stellar fees unset
ℹ️  The default inclusion fee has been cleared

This change also includes some minor reorganization of arguments now that fee and inclusion-fee has been removed from fee::Args. fee::Args was renamed to resources to better represent the purpose of these args (edit transaction resources), and all fee / build / send related args were moved under Options instead of Options (RPC).

Why

This solves #2282 by allowing users to specify default inclusion fee args easily directly from the CLI. Also, it clears up ambiguity around the meaning of --fee and other arguments that modify soroban_data.

Known limitations

There is a potentially weird edge case caused by how --inclusion-fee is given precendence over --fee. The behavior is detailed in a test here: https://github.com/stellar/stellar-cli/blob/issues/2282-fee-args/cmd/crates/soroban-test/tests/it/integration/fee_args.rs#L82-L94

TL;DR - is a user has some default config for --inclusion-fee but provides a --fee arg directly, the arg will be ignored in favor of the --inclusion-fee. This is mainly caused by us not knowing if clap sourced the --inclusion-fee value from an env variable or directly via an argument.

[Copilot]

Pull request overview

This PR renames the --fee argument to --inclusion-fee to clarify its purpose as the transaction inclusion fee (separate from resource fees). It deprecates --fee while maintaining backward compatibility. A new stellar fees command is introduced with two subcommands: stats (fetches fee statistics) and use (sets default inclusion fee from CLI). The refactoring also reorganizes fee-related code by renaming fee::Args to soroban_data::Args to better represent its purpose of managing Soroban-specific resource data rather than general transaction fees.

Key changes:

• Introduces --inclusion-fee argument with proper precedence handling (arg > env var > config > default 100)
• Adds stellar fees use command to configure default inclusion fees via CLI
• Refactors fee handling by separating inclusion fees from resource fees (resource_fee parameter)

Reviewed changes

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

Show a summary per file

File	Description
cmd/soroban-cli/src/soroban_data.rs	Renamed from fee.rs; removed inclusion fee handling, focused on Soroban resource configuration
cmd/soroban-cli/src/config/mod.rs	Added inclusion_fee field to config with precedence logic (fee → inclusion_fee → default)
cmd/soroban-cli/src/commands/fees/default.rs	New command to set default inclusion fee from amount or fee stats
cmd/soroban-cli/src/commands/fees/stats.rs	New command to fetch and display fee statistics
cmd/soroban-cli/src/assembled.rs	Added resource_fee parameter to override simulated resource fees
cmd/soroban-cli/src/commands/contract/invoke.rs	Updated to use new fee structure; hardcoded fee in simulate method
cmd/soroban-cli/src/commands/contract/upload.rs	Updated to use soroban_data and get_inclusion_fee()
cmd/soroban-cli/src/commands/tx/args.rs	Moved build_only from fee args; uses get_inclusion_fee()
cmd/crates/soroban-test/tests/it/integration/fee_args.rs	New comprehensive tests for fee argument precedence
FULL_HELP_DOCS.md	Extensive documentation updates reflecting new fee structure

[fnando]

The relationship between --inclusion-fee and --resource-fee could be better documented; we should create a cookbook file that shows examples on when you'd use one or the other. This can be addressed in a separate pr.

[mootz12]

The relationship between --inclusion-fee and --resource-fee could be better documented; we should create a cookbook file that shows examples on when you'd use one or the other. This can be addressed in a separate pr.

Agreed, tracking here: #2344