unixfundz/stellar-sim

AI Summary: This issue requests the creation of an end-to-end integration test for a Soroban adder contract. The test should compile a minimal contract, verify its return value, ensure CPU usage is reasonable, and run successfully in CI. It also specifies code formatting and linting requirements for the pull request.

AI Summary: This issue proposes adding a new command-line flag, `--print-storage-diff`, to display changes in storage entries after a simulation. The output should clearly indicate created, modified, and deleted storage items, with support for JSON format. This feature aims to provide better visibility into state transitions during simulations.

AI Summary: This issue requests the implementation of a new `--simulate-auth-checks` flag to enable strict authorization checks during simulation. The goal is to ensure that authorization failures are clearly reported, and that an existing `--skip-auth` flag can disable these checks. The implementation should also include testing with contracts that require specific signers.

AI Summary: This issue proposes adding a new command-line flag, `--print-events-on-failure`, to automatically display all diagnostic events when a simulation fails. This will help users debug failures by providing immediate access to relevant event logs. The implementation requires ensuring events are clearly labeled as failure diagnostics and testing with a failing contract that emits events.

AI Summary: This issue proposes adding a `--wasm-cache` flag to the stellar-sim tool to improve performance by caching compiled WebAssembly (WASM) modules to disk. The cache will be stored in `~/.stellar-sim/cache/`, keyed by WASM file hash, and can be bypassed with a `--no-cache` flag. This aims to speed up repeated simulations by avoiding recompilation.

AI Summary: This issue proposes adding rate limiting to RPC calls within the snapshot subcommand. The goal is to prevent overwhelming RPC endpoints by introducing configurable delays and implementing retry logic for rate-limiting responses (HTTP 429).

AI Summary: This issue requires implementing a Rust function called `categorize_events` that transforms `HostEvents` into `CategorizedEvents`. The function needs to map specific `ContractEventType` variants to lowercase string labels and ensure the `in_successful_contract_call` field is the logical negation of the `failed_call` field. Unit tests are specified to verify these requirements.

AI Summary: This issue proposes adding a new command-line flag, `--print-return-xdr`, to a Rust project. When this flag is enabled, the raw, base64-encoded XDR representation of a return value will be printed alongside its decoded version, specifically within a JSON output field named `return_value_xdr`. The implementation must also include a test to ensure the XDR data can be correctly encoded and decoded.

AI Summary: This issue proposes adding two new command-line flags, `--min-temp-entry-expiry` and `--min-persistent-entry-expiry`, to configure entry expiration settings within a simulation context. The implementation requires accepting and applying these flags, documenting them with sensible defaults, and verifying their effect on simulations through tests. The changes should adhere to Rust's formatting and linting standards.

AI Summary: This issue proposes adding a new command-line flag, `--ledger-timestamp`, to allow users to specify a simulated ledger close time. This change aims to enable testing scenarios where the ledger's timestamp needs to be controlled, ensuring that contracts correctly read and reflect this simulated value.

AI Summary: This issue proposes adding a new `snapshot` subcommand to the `stellar-sim` tool. This subcommand will be responsible for saving the ledger entries of a specified contract to a JSON file, with the output format being compatible with the existing `--ledger` flag. The implementation needs to handle downloading ledger entries, serializing them, and gracefully managing RPC errors.

AI Summary: This issue proposes adding a new `--compare` flag to the `stellar-sim` tool. This flag will allow users to compare the results of two simulation runs, highlighting differences in CPU, memory, and return values. The goal is to provide a clear and concise way to identify changes between simulation executions.

AI Summary: This issue proposes adding a `--repeat` flag to the simulation tool. This flag will allow users to run the simulation multiple times with identical inputs and report the minimum, maximum, and average CPU and memory usage across all runs. This feature aims to provide more robust performance insights.

AI Summary: This issue proposes adding a new command-line flag, `--assert-cpu-limit`, to enable performance regression testing in CI. The flag would allow the program to exit with a non-zero status code if CPU usage exceeds a specified threshold, providing a mechanism to detect performance regressions.

AI Summary: This issue proposes implementing a SourceMapper for WebAssembly (WASM) debug symbols. The goal is to translate WASM code offsets into human-readable source file and line numbers using DWARF debug information. The implementation should gracefully fall back to showing the offset if debug symbols are not present, and include a specific test case for this fallback scenario.

AI Summary: This issue proposes adding a new `--events-only` flag to the command-line interface. When this flag is used, the tool should only output diagnostic events, suppressing all other non-event related output. The implementation needs to ensure compatibility with the `--json` flag and include tests to verify that non-event output is indeed suppressed.

AI Summary: This issue requests the implementation of a new feature to simulate `invoke_contract` operations directly. The simulation will be triggered by a new command-line flag that accepts base64 encoded XDR for the operation. The implementation needs to include decoding the XDR, performing the simulation, and verifying with a test case.

AI Summary: This issue requests the addition of a `--verbose` flag to provide a detailed, step-by-step execution trace. The trace should log each host function call, its return value, and be clearly formatted. This feature aims to improve the diagnostic capabilities of the command-line interface.

AI Summary: This issue proposes adding functionality to the `stellar-sim` CLI tool to read WebAssembly (WASM) bytecode directly from standard input. This would enable users to pipe WASM files into the simulation tool, for example, using `cat contract.wasm | stellar-sim simulate --wasm -`. The implementation should also handle cases where stdin is empty and include tests for piped input.

AI Summary: This issue requests the implementation of a `wipe_ledger_state()` method for SimHost. This method should reset all storage to an empty state while preserving the module cache, effectively rebuilding the host from scratch with its original configuration. The implementation needs to ensure the host remains functional after the wipe and pass specific tests.

AI Summary: This issue proposes adding a new `--source-account` flag to the command-line interface. This flag will allow users to specify a Stellar account ID to be used as the source for transactions, ensuring it's validated and accessible.

AI Summary: This issue proposes adding a new `--print-auth` flag to the command-line interface. This flag will display the authentication entries required for submitting a transaction in base64 XDR format, with a decoded view available when the `--verbose` flag is also used. The implementation should be tested with a contract that necessitates authentication.

AI Summary: This issue proposes adding a new `--footprint` flag to the command-line interface to display the read and write operations performed by a smart contract after simulation. The output should clearly indicate contract data and specific fields being accessed, and also be supported in JSON output.

AI Summary: This issue requires generating an LCOV coverage report from simulation data. The report should detail which WebAssembly (WASM) functions were invoked, using the `CoverageTracker`'s `invoked_functions` HashMap. The generated report needs to be saved to a specified output path and include a test case to verify its content.

AI Summary: This issue proposes adding a new `--auth` flag to the command-line interface. This flag will allow users to specify a file containing base64 encoded authorization entries, which will then be passed to the host. The implementation needs to ensure these entries are loaded correctly, tested with contracts requiring authentication, and handle malformed input with clear errors.

AI Summary: This issue requires implementing a Rust function `extract_missing_key_id` that parses specific string patterns within Soroban host error messages to extract a ledger key ID. The function should handle three distinct formats of key representation found in the error output and return an `Option<String>` containing the key ID if found, or `None` otherwise. The implementation needs to be accompanied by unit tests covering all specified patterns.

AI Summary: This issue proposes adding a new command-line flag, `--resource-calibration`, that accepts a JSON configuration to dynamically adjust CPU and memory resource limits. The implementation should handle parsing the JSON, applying the limits, providing clear error messages for invalid configurations, and include documentation with an example. The project also requires code formatting and linting before submission.

AI Summary: This issue proposes implementing a function to translate raw Soroban/WASM virtual machine error strings into more human-readable English descriptions. The goal is to improve the clarity of error messages for developers by mapping specific error codes to understandable explanations, with a fallback to the original message if no mapping is found. The implementation should cover common VM trap types and include relevant tests.

AI Summary: This issue proposes adding a new command-line flag, `--fee-limit`, to cap the maximum transaction fee in stroops. The implementation should ensure this limit is passed to the simulation, report the estimated fee, and issue a warning if the estimated fee exceeds the specified limit.

AI Summary: This issue requires implementing a Rust function `extract_wasm_instruction` to parse diagnostic event data. The function should extract the WASM instruction name (e.g., 'i32.add') from the `data` field when the event `topics` indicate a budget-related event ('tick' or 'budget'). It needs to handle cases where the instruction is not present or the topic is not relevant, returning `None` in those scenarios.

AI Summary: This issue proposes adding a new command-line flag, `--ledger-sequence`, to allow users to explicitly set the simulated ledger sequence number. This change aims to provide more control over the simulation environment, ensuring that contracts can correctly read and utilize the specified ledger sequence.

AI Summary: This issue requests the implementation of human-readable string formatting for `ScVal` return values. The goal is to decode various `ScVal` variants and display them in a user-friendly format, with examples provided for `I64`, `Symbol`, and `Void`. The solution should handle all common variants, provide a hex fallback for unknown types, and include comprehensive unit tests.

AI Summary: This issue proposes adding a new command-line flag, `--assert-return`, to a tool. This flag would allow users to specify an expected return value, and the tool would exit with a status code of 0 if the actual return value matches the assertion, and 1 otherwise. This feature is intended to be useful for integration into CI/CD pipelines for automated testing.

AI Summary: This issue requests the implementation of a new batch simulation feature for the command-line interface. Users will be able to provide a JSON manifest file containing a list of function calls to be executed sequentially, with results displayed in a table and failures not halting the entire batch.

AI Summary: This issue proposes adding a WebAssembly (WASM) validation step before executing Soroban contract simulations. The goal is to reject WASM binaries that are not compatible with Soroban, specifically targeting float and SIMD instructions, and to provide clear error messages for rejected contracts. This validation will leverage an existing `vm::enforce_soroban_compatibility` function.

AI Summary: This issue requests the implementation of a new helper function, `scval_to_xdr_base64`, which will serialize `ScVal` objects into base64-encoded XDR strings. The implementation needs to handle specific `ScVal` types, pass a round-trip test, and include unit tests. The issue is marked as 'help wanted' and relates to the Soroban project.

AI Summary: This issue requests the implementation of a helper function in Rust called `contract_id_to_hex`. This function will take a raw contract hash and convert it into a hexadecimal string for display purposes. The implementation should be tested and used in event display output.

AI Summary: This issue proposes adding functionality to load a ledger snapshot from a JSON file before running a simulation. The JSON format is specified, and acceptance criteria include correct loading, error handling for malformed entries, and testing with at least one entry. This feature aims to pre-populate host storage for simulations.

AI Summary: This issue requests the addition of a `--json` flag to the `simulate` subcommand. This flag should enable structured JSON output for the simulation results, while the default plain text output remains unchanged. The implementation needs to ensure valid JSON is produced and both output modes are tested.

AI Summary: This issue requires enhancing the `events` subcommand to decode base64 encoded XDR DiagnosticEvents into a human-readable format. The output should clearly display event type, contract, topics, and data, with specific formatting requirements and validation checks for event type casing and the relationship between `in_successful_contract_call` and `failed_call`.

AI Summary: This issue proposes adding a new command-line flag, `--max-memory`, to allow users to specify a maximum memory limit in bytes. The implementation should ensure this limit is passed to the host, gracefully abort the simulation with an error if exceeded, and document the default limit. The issue is marked as a 'good first issue' and relates to the CLI.

AI Summary: This issue proposes adding a new `inspect` subcommand to a tool that will display the total file size and the size of individual sections within a WebAssembly (WASM) file. The output should be in a human-readable format, and the implementation needs to be tested with a known WASM file.

AI Summary: This issue proposes adding a new `--env` flag to the command-line interface to allow users to set environment variables for simulations. The goal is to enable passing multiple key-value pairs as environment variables to the host process and to include tests to verify this functionality.

AI Summary: This issue requests the implementation of a new function, `render_summary_table`, which will take a slice of simulation results and display them in a formatted table. The table should include columns for Function, Status, CPU, and Memory. The implementation needs to be accompanied by a unit test and adhere to Rust's formatting and linting standards.

AI Summary: This issue requests the addition of a short alias, `--fn`, for the existing `--function` flag within the `simulate` subcommand. The goal is to make the command-line interface more concise. The implementation requires ensuring both flags are accepted, updating the help text, and adding a test case that utilizes the new short alias.

AI Summary: This issue requests the creation of a Makefile for a Rust project. The Makefile should include common development tasks like building, testing, linting, formatting, cleaning, and generating documentation. It also requires a `make help` command to list targets and documentation in the README.

AI Summary: This issue proposes adding a new `--contract-id` flag to the `simulate` subcommand. This flag will allow users to specify a contract ID, which will then be passed to the host for simulation context. The implementation requires validation of the provided contract ID and testing with both valid and invalid inputs.

AI Summary: This issue requests the implementation of basic structured logging within the project using the `tracing` crate. The logging should be configurable via the `RUST_LOG` environment variable, with different log levels (info and debug) exposing varying levels of detail to stderr. The PR must also adhere to code formatting and linting standards.

AI Summary: This issue proposes adding a new `--args-file` flag to the command-line interface. This flag will allow users to specify a JSON file containing arguments, providing an alternative to passing them inline. The implementation should handle file not found and invalid JSON errors, and include tests.

AI Summary: This issue requests that the program always display CPU instruction count and memory usage after each simulation. The output should be formatted with thousands separators and can be suppressed using a `--quiet` flag. This is intended to provide users with immediate performance metrics.

AI Summary: This issue proposes adding a new command-line flag, `--no-color`, as an alias for the existing `NO_COLOR` environment variable. The goal is to provide an alternative way to disable ANSI color output, ensuring it functions correctly alongside the environment variable and is verified by tests.

AI Summary: This issue requests the creation of standardized templates for GitHub issues and pull requests. The goal is to improve the quality of contributions by guiding users to provide essential information like reproduction steps for bugs, motivation for features, and a checklist for pull requests.

AI Summary: This issue proposes adding a `--network` flag to the command-line interface to easily switch between pre-configured testnet and mainnet RPC endpoints. The goal is to simplify network selection while still allowing users to override these presets with custom RPC URLs. Successful implementation will be verified by ensuring both presets function correctly and custom URLs remain effective.

AI Summary: This issue proposes adding a validation step to check if a file starts with the WASM magic bytes ('\0asm') before attempting to parse it. This will prevent errors when processing non-WASM or empty files and requires clear error messages and a unit test for invalid input.

AI Summary: This issue proposes adding a visual progress spinner to indicate when a long-running simulation is in progress. The spinner should be displayed using the `indicatif` crate, appear during the simulation, stop upon completion, and be hidden when the `--quiet` flag is used.

AI Summary: This issue proposes adding a `--timeout` flag to the simulation command to limit its execution time in milliseconds. The simulation should abort with a clear error message if the timeout is exceeded, and a default timeout of 30 seconds should be implemented.

AI Summary: This issue proposes adding distinct error exit codes to the command-line interface (CLI) to provide more specific feedback on failures. The proposed codes include general errors, invalid arguments, missing WASM files, and simulation failures, with success indicated by code 0. The implementation requires documenting these codes and adding tests to verify their correct behavior.

AI Summary: This issue proposes adding a new subcommand to the `inspect` tool that will list all imported functions within a WebAssembly (WASM) binary. The expected output format is a simple list under an 'Imports:' heading, and the implementation should include tests with a sample WASM file.

AI Summary: This issue proposes adding a `--dry-run` flag to the `simulate` subcommand. This flag should validate the provided WASM file and print a summary of the intended simulation without actually executing it, ensuring no side effects occur.

AI Summary: This issue requires adding documentation comments (doc comments) to all public functions within the project. The goal is to ensure that `cargo doc --no-deps` runs without any warnings, indicating that all public APIs are properly documented.

AI Summary: This issue requests the addition of a `.gitignore` file for Rust projects. The `.gitignore` should be comprehensive, covering common build artifacts like `target/`, editor-specific files, and operating system generated files to keep the repository clean.

AI Summary: This issue requests the creation of a CHANGELOG.md file that adheres to the Keep a Changelog format. The file should include an initial entry detailing the project's features.

AI Summary: This issue proposes adding color support to the command-line interface (CLI) output. The goal is to use the `colored` crate to visually distinguish between errors (red), success messages (green), and warnings (yellow). Color should be disabled if the `NO_COLOR` environment variable is set.

AI Summary: This issue proposes adding a new `--output` flag to the simulation tool. This flag will allow users to specify a file path to which the simulation results should be written, instead of defaulting to standard output. The implementation needs to ensure the default behavior remains unchanged and include a test to verify the file content.

AI Summary: This issue requests the implementation of a new `inspect` subcommand for a tool that can load and analyze WebAssembly (.wasm) files. The subcommand should list all exported function names from a given WASM file, with specific acceptance criteria including handling invalid WASM files and including a unit test.

AI Summary: This issue proposes adding a `--quiet` flag to the command-line interface. When this flag is used, the tool should only display error messages and the final outcome, suppressing all other non-essential output. A test will be required to confirm that verbose output is indeed suppressed.

AI Summary: This issue requests the setup of a GitHub Actions CI workflow for a Rust project. The workflow should run `cargo fmt --check`, `cargo clippy`, and `cargo test` on every pull request to ensure code quality and correctness. The successful implementation will be verified by a passing workflow and the addition of a README badge.

AI Summary: This issue requires adding SPDX license headers to all Rust source files (`.rs`). A specific header format is provided, and a CI check script needs to be implemented to ensure compliance. This is a straightforward task focused on code hygiene and automation.

AI Summary: This issue requests the addition of descriptive help text for all command-line interface (CLI) subcommands and their flags. The goal is to improve user experience by providing clear explanations when users invoke the `--help` option.

AI Summary: This issue requests the addition of a `--version` flag to the `stellar-sim` command-line interface. When this flag is used, the CLI should print its current version (e.g., 'stellar-sim x.y.z') and then exit. The implementation should include a test to verify the correct version string is output.