unixfundz/stellar-sim

AI Summary: This issue requires writing an end-to-end integration test for the `simulate` function. The test should compile a basic Soroban adder contract into a `.wasm` file, execute it via `simulate`, and then assert that the returned value is correct and that the CPU instructions used are within an acceptable range. The test must be configured to run successfully within the continuous integration (CI) pipeline.

AI Summary: The issue proposes adding a new command-line option, `--print-storage-diff`, to a simulation tool. This feature should display a summary of contract storage changes—specifically created, modified, and deleted entries—after a simulation completes. The output needs to support both a human-readable format and a structured JSON format.

AI Summary: This issue proposes implementing a new `--simulate-auth-checks` flag to enable strict authorization checking during simulations. The flag should ensure clear error messages on authentication failures and be disabled by a `--skip-auth` flag. It requires testing with contracts that demand 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. The events should be clearly labelled as failure diagnostics, and the implementation requires testing with a contract designed to fail and emit events.

AI Summary: This issue proposes adding a `--wasm-cache` CLI flag to enable caching of compiled WebAssembly (WASM) modules to disk. This will significantly speed up repeated simulations by reusing previously compiled modules. The cache will be stored in `~/.stellar-sim/cache/`, keyed by the WASM file's hash, and can be bypassed using a `--no-cache` flag.

AI Summary: This issue requests the implementation of rate limiting for RPC calls within the `snapshot` subcommand. It requires adding a `--rpc-delay-ms` flag to configure delays between requests and implementing retry logic specifically for 429 (Too Many Requests) HTTP responses.

AI Summary: This issue requires implementing a `categorize_events` function to transform `HostEvents` into `CategorizedEvents`. The function must assign human-readable string labels (e.g., "contract", "system") to the `category` field based on `ContractEventType`. Additionally, it must ensure the `in_successful_contract_call` field is always the negation of `event.failed_call`, with specific tests required to validate these conditions.

AI Summary: This issue proposes adding a new command-line flag, `--print-return-xdr`, to an existing tool. When set, this flag will cause the raw, base64-encoded XDR of a return value to be printed alongside its decoded version, specifically as `return_value_xdr` in the JSON output. A key acceptance criterion is a test ensuring the XDR can be correctly round-tripped.

AI Summary: This issue proposes adding two new command-line flags, `--min-temp-entry-expiry` and `--min-persistent-entry-expiry`, to configure minimum entry expiration settings within a simulation context. The implementation requires ensuring these flags are accepted, applied correctly, and documented with sensible defaults. A key acceptance criterion is a test that verifies the flags effectively influence simulation entry expiry.

AI Summary: This issue proposes adding a `--ledger-timestamp` command-line flag to allow users to set a simulated ledger close time. The specified timestamp should be set before execution and be accurately reflected when contracts read the ledger's current time. A test is required to verify the accessibility and correctness of this simulated value within contracts.

AI Summary: This issue proposes adding a `snapshot` subcommand to `stellar-sim` to save a specified contract's ledger state. The command will connect to an RPC, download all relevant ledger entries for a contract, and serialize them into a JSON file. The output must be compatible with the existing `--ledger` flag and include robust RPC error handling.

AI Summary: The issue proposes adding a new `stellar-sim compare` command to facilitate diffing between two simulation result JSON files. This command should clearly highlight all differences, specifically showing deltas for CPU usage, memory consumption, and any changes in return values. The implementation requires adherence to standard Rust formatting and linting practices.

AI Summary: This GitHub issue requests the addition of a `--repeat N` flag to the simulation tool. This flag should execute the simulation N times, ensuring identical inputs for each run. The output should then present a table summarizing the minimum, maximum, and average CPU and memory usage across all repetitions.

AI Summary: This GitHub issue proposes adding a new command-line flag, `--assert-cpu-limit`, to a tool. This flag would allow users to specify a maximum CPU usage value, causing the program to exit with an error code (1) if that limit is exceeded, or successfully (0) if within bounds. Its primary purpose is to facilitate performance regression testing within CI/CD pipelines.

AI Summary: This issue requires implementing a `SourceMapper` to translate WebAssembly (WASM) offsets into their original source code file and line locations using DWARF debug information. The mapper should initialize with WASM bytes, report if debug symbols are present, and provide the source location or fall back to the WASM offset if no symbols are found. A specific test case for the no-symbols scenario is also required.

AI Summary: This issue proposes adding a new `--events-only` flag to the CLI, which will filter the command's output to display solely diagnostic events, suppressing all other non-event information. The implementation must ensure compatibility with the existing `--json` output option and include comprehensive tests to verify the output suppression functionality.

AI Summary: This issue requests the implementation of a simulation feature specifically for `invoke_contract` XDR operations. It involves adding a command-line flag (`--operation <base64-xdr>`) to accept the operation, then decoding and simulating it. The solution requires testing with sample XDRs and adhering to standard Rust formatting and linting practices.

AI Summary: This issue proposes adding a `--verbose` command-line flag to enable a detailed, step-by-step execution trace. When active, the output should log each host function call, display its return value, and be clearly formatted. Standard `cargo fmt` and `cargo clippy` checks are required for the PR.

AI Summary: This GitHub issue requests a new feature for the `stellar-sim` tool: the ability to read WASM contract bytes directly from standard input (stdin). Users should be able to specify `-` as the value for the `--wasm` argument to enable this functionality. Acceptance criteria include successful execution with piped input, proper error handling for empty stdin, and dedicated tests.

AI Summary: The task is to implement a `wipe_ledger_state()` method on `SimHost` that completely resets all its internal storage to an empty state. This involves rebuilding the host from scratch using its existing configuration, with the specific requirement to preserve only the module cache. The implementation needs to ensure storage is cleared, the host remains functional, and pass dedicated tests.

AI Summary: This issue proposes adding a `--source-account` command-line flag to specify the transaction's source Stellar account. The provided account ID must be validated as a Stellar account, stored in the application's context, and its accessibility verified with tests.

AI Summary: This issue proposes adding a `--print-auth` flag to a command-line tool. The flag should display the authentication entries required for a transaction, outputting them in base64 XDR format. Additionally, if the `--verbose` flag is present, these entries should be decoded into a human-readable format, and the feature must be tested with a contract that specifically requires authentication.

AI Summary: This GitHub issue proposes adding a `--footprint` flag to a simulation tool to display the read/write footprint of a transaction after execution. The output should detail specific contract data accessed and modified, be available in a human-readable format and JSON, and requires testing with a contract that performs both read and write operations.

AI Summary: This issue requests the implementation of a function to generate an LCOV coverage report from a simulation. The report should detail which WASM functions were invoked, using an existing `CoverageTracker` which stores function names and their invocation counts. The output needs to follow a specified LCOV format and be written to a `--coverage-output` path, with a dedicated test case.

AI Summary: This issue proposes adding an `--auth` command-line flag to allow users to provide authorization entries. The flag will accept a path to a JSON file containing base64 XDR auth entries, which the application must load and pass to the host. Key requirements include robust error handling for malformed input and comprehensive testing with a contract that specifically requires authorization.

AI Summary: This issue requires implementing a Rust function `extract_missing_key_id` that parses `HostError` strings to extract a LedgerKey ID. The function needs to identify and extract the key from three distinct patterns: `LedgerKey(...)`, `key = "..."`, and `ContractData(...)`, returning `None` if no key is found. Specific test cases are outlined to ensure correct handling of all patterns.

AI Summary: This issue proposes adding a new `--resource-calibration` command-line flag to allow users to provide a JSON configuration file. This file will be used to dynamically tune CPU and memory limits on the host system. Key requirements include robust parsing of the JSON config, clear error handling for invalid inputs, and comprehensive documentation with examples.

AI Summary: This issue proposes implementing a `decode_error` function to translate raw Soroban/WASM error strings into more human-readable English descriptions. It provides examples for common VM traps like "out of bounds" and "integer overflow," as well as authorization failures. The function should handle all common VM trap types, fall back to the raw message for unknown errors, and include specific tests.

AI Summary: This issue proposes adding a `--fee-limit` flag to cap transaction fees, specified in stroops. The acceptance criteria require passing this limit to the transaction simulation, reporting the estimated fee, and displaying a warning if the estimated fee exceeds the set limit.

AI Summary: This issue requests the implementation of a Rust function, `extract_wasm_instruction`, designed to parse WASM instruction names from diagnostic event data. The function should specifically extract instructions (e.g., `i32.add`) from a pattern like `Instruction: i32.add` within the `data` string, but only when the event `topics` indicate a `tick` or `budget` related event. It should return `None` for non-relevant topics or if no instruction is found.

AI Summary: This issue proposes adding a `--ledger-sequence` command-line flag to a simulation context, allowing users to specify a custom ledger sequence number. The acceptance criteria require that this sequence number is set on the host before execution, is accurately reflected when contracts read the ledger sequence, and is verified by a dedicated test. Standard Rust formatting and linting are also required for the pull request.

AI Summary: This issue requests an enhancement to display ScVal return values in a human-readable format, such as `42 (i64)` instead of raw `ScVal::I64(42)`. The solution needs to handle all common ScVal variants, provide a hex string fallback for unknown types, and include comprehensive unit tests for each variant.

AI Summary: This issue proposes adding a new command-line flag, `--assert-return`, which would allow users to specify an expected return value. The program should then compare its actual return value against this assertion, exiting with code 0 on a match and 1 on a mismatch. This feature is primarily intended to facilitate validation in CI environments.

AI Summary: This issue proposes adding a `simulate --batch` command to execute multiple function calls sequentially from a JSON manifest file. The implementation must ensure all invocations run in order, continue processing even if individual calls fail, and present the aggregated results in a table format.

AI Summary: This issue proposes adding a validation step before running Soroban simulations to ensure WASM binaries are compatible. It involves using the existing `vm::enforce_soroban_compatibility` function to reject contracts using features like floats or SIMD, providing clear error messages for non-compliant binaries, and ensuring valid contracts pass through. The task includes integrating this check into the simulation flow and adding specific tests for rejection and acceptance criteria.

AI Summary: This issue requests the implementation of a new helper function, `scval_to_xdr_base64`, which will serialize an `ScVal` (specifically Int, String, and Symbol types) into a base64-encoded XDR string. The function must include unit tests, a round-trip test to verify correct encoding and decoding, and adhere to standard Rust formatting and linting.

AI Summary: This issue requests the implementation of a `contract_id_to_hex` helper function in Rust. Its purpose is to convert a raw contract hash (`&Hash`) into a hexadecimal string for display, specifically for event output. The task includes writing unit tests, ensuring correct hex encoding, and integrating it into the event display.

AI Summary: This GitHub issue proposes adding a new command-line argument, `--ledger snapshot.json`, to load a ledger snapshot from a JSON file into the host storage before a simulation. The JSON file will contain base64-encoded XDR LedgerKey and LedgerEntry pairs. The implementation must ensure correct loading, provide clear error messages for malformed entries, and include tests.

AI Summary: This issue proposes adding a `--json` flag to the `simulate` subcommand, enabling it to output structured JSON data instead of plain text. The existing plain text output must remain unchanged without the flag, and both output modes require testing to ensure validity and correctness.

AI Summary: This GitHub issue requests an enhancement to the `events` subcommand, enabling it to decode base64 XDR `DiagnosticEvents` into a human-readable, plain English format. Key requirements include mapping `ContractEventType` variants to lowercase strings, ensuring `in_successful_contract_call` is the negation of `failed_call`, and robust error handling for malformed input, all validated by integration tests.

AI Summary: This issue proposes adding a `--max-memory` command-line flag to allow users to specify a maximum memory limit in bytes for the application. The system should pass this limit to the host environment, and if the memory usage is exceeded during a simulation, the process must abort with a clear error message. Additionally, the default memory limit should be documented.

AI Summary: This issue proposes adding a new `inspect` subcommand to display the total size of a WASM file and a breakdown of its sections. The output should be presented in a human-readable format (e.g., KB) and tested with a known WASM file.

AI Summary: This issue requests the addition of an `--env KEY=VALUE` command-line flag to allow users to inject environment variables into a simulation. The implementation should support multiple `--env` flags, ensure variables are passed to the host process, and include tests to verify the injection functionality.

AI Summary: This issue requires implementing a new Rust function, `render_summary_table`, which takes a slice of `SimResult` objects and formats them into a text-based summary table. The table should include columns for Function, Status, CPU, and Memory. Acceptance criteria include correct table rendering and a unit test with sample data, along with standard Rust formatting and linting checks.

AI Summary: This issue requests adding `--fn` as a short alias for the existing `--function` flag within the `simulate` subcommand. The acceptance criteria include ensuring both flags are accepted, both appear in the help text, and a new test uses the short form. Standard Rust formatting and linting are required for the PR.

AI Summary: This issue requests the creation of a `Makefile` to standardize common development tasks within the project. The Makefile should include targets for `build`, `test`, `lint`, `fmt`, `clean`, and `docs`, all of which must be functional. Additionally, it requires a `make help` target to list available commands and documentation in the project's `README` file.

AI Summary: This issue proposes adding a `--contract-id` flag to the `simulate` subcommand, allowing users to specify a Stellar account ID to be used as the contract ID within the simulation context. The implementation requires passing this ID to the host, validating it as a valid Stellar account ID, and thorough testing with both valid and invalid inputs.

AI Summary: This issue requests the implementation of structured logging using the `tracing` crate, configured to respect the `RUST_LOG` environment variable for controlling verbosity. Logs should be directed to stderr, with `info` level showing high-level steps and `debug` level providing detailed information.

AI Summary: This issue requests the addition of a `--args-file` flag, enabling the application to read command-line arguments from a specified JSON file instead of inline. The implementation must include error handling for missing or invalid JSON files and be thoroughly tested with a sample arguments file.

AI Summary: Implement a feature to display CPU instruction count and memory usage after each simulation run. The output must be formatted with thousands separators and can be suppressed using a `--quiet` command-line flag. Standard Rust linting and formatting are required for the pull request.

AI Summary: This issue requests the addition of a `--no-color` CLI flag to disable ANSI color output. This flag should function alongside the existing `NO_COLOR` environment variable, and its correct operation must be confirmed with a dedicated test.

AI Summary: This issue requests the creation of standard GitHub issue and pull request templates. Specifically, it asks for `bug_report.md`, `feature_request.md` in the `.github/ISSUE_TEMPLATE/` directory, and `PULL_REQUEST_TEMPLATE.md` in `.github/`. The templates should include specific sections like reproduction steps for bug reports, motivation for feature requests, and a checklist for pull requests.

AI Summary: This GitHub issue proposes adding a `--network` command-line flag to allow users to easily switch between predefined `testnet` and `mainnet` RPC endpoint configurations. The implementation should ensure that custom RPC settings can still override these presets, and proper tests are required to verify the correct URL selection.

AI Summary: This issue proposes adding a validation step to check for WASM magic bytes (`\0asm`) at the beginning of a file before parsing it for simulation. The goal is to provide clear error messages for non-WASM or empty files, ensuring robust input handling. Unit tests for invalid inputs are also required.

AI Summary: This issue requests the addition of a progress spinner, utilizing the `indicatif` crate, for long-running simulations. The spinner should be visible throughout the simulation's execution, automatically stop upon completion, and remain hidden if the `--quiet` command-line flag is enabled.

AI Summary: This issue proposes adding a `--timeout` flag to the simulation command, allowing users to specify a maximum execution time in milliseconds. The simulation should abort with a clear error message if this timeout is exceeded, and a default timeout of 30 seconds should be enforced if no flag is provided.

AI Summary: The issue proposes enhancing the CLI by implementing distinct error exit codes instead of a generic error. It defines specific codes for success, general errors, invalid arguments, missing WASM files, and simulation failures. Acceptance criteria include documenting these new codes and adding tests to verify each one.

AI Summary: This issue proposes extending the `inspect` command to display a list of all imported functions within a WebAssembly (WASM) binary. The output should clearly separate imports from exports, and the new functionality must be validated with a sample WASM file.

AI Summary: This issue proposes adding a `--dry-run` flag to the `simulate` subcommand. When used, it should validate necessary inputs, such as the existence of a WASM file, and then print a summary of the simulation that would occur. Crucially, the flag should prevent the actual simulation from running.

AI Summary: This issue requests that all public functions (`pub fn`) within the codebase be documented using `///` doc comments. The primary goal is to ensure that `cargo doc --no-deps` runs without producing any warnings, indicating that all public functions have been properly documented.

AI Summary: This issue requests the addition of a comprehensive `.gitignore` file for Rust projects. The file should ignore common Rust build artifacts (like the `target/` directory), various 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 in the repository. The file needs to follow the "Keep a Changelog" format and include an initial list of the project's existing features.