Feature/compute budget estimation

[whiteghost0001]

Here is a breakdown of the architectural changes and implementation details for Issue #351: Compute Budget Estimation API

Architectural Overview
We designed and integrated a simulation-only compute budget estimation engine into the split contract (contracts/split/src/lib.rs). This provides off-chain SDKs and callers with deterministic resource pre-flight checks (cpu_insns, mem_bytes, fee_stroops) for transaction sizing without incurring state mutations or unnecessary on-chain execution overhead.

Key Technical Deliverables

1. Data Model Refactoring (

types.rs
Replaced legacy budget placeholders with exact host resource primitives:

rust
#[contracttype]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ComputeEstimate {
pub cpu_insns: u64,
pub mem_bytes: u64,
pub fee_stroops: i128,

2. Read-Only Estimation Engine (

lib.rs

Implemented the estimate_compute(env, operation, params) entry point with full dispatch support across the 6 major contract operations:

create_invoice ("create_invoice", "create", "create_i"): Evaluates linear instruction scaling against recipient array counts ($1.2\text{M} - 5.0\text{M}$ CPU instructions).
pay ("pay", "pay_dlgt"): Accounts for base payment routing, multi-shard storage mutations, and optional auto-release transfer overhead when fully funded.
release ("release"): Models transfer iteration, fee-tier platform deductions, and recipient distribution.
refund ("refund"): Computes multi-shard payer iteration and proportional token refund transfers.
open_dispute ("open_dispute", "raise_dispute", "dispute"): Estimates audit trail append and dispute state isolation.
approve_release ("approve_release", "approve", "approve_invoice"): Estimates multi-sig governance approval state updates.
3. Defensive Parameter Extraction & Error Handling
Added robust parameter parsing helpers (Self::get_u64_param, Self::get_recipients_len, Self::load_invoice_opt) supporting canonical key aliases (invoice_id, id, recipients, recipient_count).

Returns contract-native error codes (ContractError::InvalidRecipients, ContractError::InvoiceNotFound, ContractError::InvalidStatus) rather than unhandled panics when passed unexpected types or missing fields.
Strictly read-only: inspects state via env.storage().persistent().get without writing or mutating keys.
4. Dynamic Fee Calculation & Budget Threshold Alerts
Fee Formula: Calculates transaction fee estimates in Stroops: $$\text{fee_stroops} = \left(\frac{\text{cpu_insns}}{10,000}\right) \times \text{STROOPS_PER_10K_INSTRUCTIONS}$$
High-Resource Warning: Emits topic event ("split", "bdgt_w", operation) if an estimated execution exceeds 80% of the Soroban instruction budget ceiling (80,000,000 CPU instructions).
5. Documentation & Technical Reference (

docs/COMPUTE_BUDGETS.md

Updated the repository compute reference with operation matrices, resource ranges, fee calculation formulas, and operational assumptions.

Verification & Quality Assurance
Unit Test Suite (

test.rs
): Added integration tests verifying accurate estimation within 10% tolerance against env.cost_estimate().budget(), repeated call determinism, missing parameter handling, and state immutability.
Workspace Status:
cargo fmt: Clean formatting across workspace.
cargo clippy --all-targets -- -D warnings: 0 warnings, 0 errors.
cargo test --workspace: 270/270 unit tests passing.

closes #351