Background / Context
None of the three contracts have any performance/compute-cost testing today — the 16 existing tests (per the README: 8 escrow, 4 milestones, 4 maintenance-pool) are purely correctness-focused. soroban_sdk::Env exposes a budget() API that reports actual CPU-instruction and memory consumption for contract invocations during tests, which is the standard way to measure real Soroban resource cost without needing a live network.
Problem Statement
Given several other issues in this bounty set identify potentially expensive operations (unbounded recipients vectors in release/release_issue, the O(n) Milestone.allocations Map read/write on every allocate/release_issue call, per-call TTL extension), the team has no way to detect a performance regression — a future change that unintentionally makes any entrypoint significantly more expensive — until it's discovered in production as failed/expensive mainnet transactions. This task is to build a proper, ongoing regression benchmark, not a one-off measurement.
Requirements
- For every public entrypoint across all three contracts (
initialize, fund, release, refund, get_escrow/get_admin/get_treasury/get_fee_bps for escrow; the equivalent set for milestones and maintenance-pool), write a benchmark test that invokes it under realistic conditions and captures env.budget()'s reported CPU instruction count and memory/footprint usage.
- Parameterize the benchmarks across relevant size dimensions where applicable:
recipients.len() for release/release_issue (e.g., 1, 5, 10, 20 recipients), allocations.len() at time of call for allocate/release_issue in milestones (e.g., after 1, 50, 200 prior allocations), and deposit_count for maintenance-pool operations — to produce actual cost-vs-size curves, not single data points.
- Establish and document baseline numbers (current measured cost for each entrypoint/size combination) and wire up a mechanism (a
make bench target producing a comparable report, or a test assertion with generous tolerance bounds that fails if cost exceeds e.g. 150% of baseline) that would catch a serious future regression.
- Cross-reference findings with the unbounded-recipients and unbounded-allocations-Map issues tracked separately — this benchmark suite should produce the empirical data those issues call for, so coordinate to avoid duplicate measurement work, and feed findings into setting concrete caps/limits there.
Acceptance Criteria
Technical Notes / Hints
env.budget() — check soroban_sdk's testutils documentation for exact API (Budget::cpu_instruction_cost, .memory_bytes_cost, or similar, depending on SDK version 26.1.0 pinned in this workspace's Cargo.toml).- Consider whether Soroban's
Env::default() test environment's budget accounting is representative enough of real network costs to be trustworthy for this purpose, or whether it needs calibration against actual testnet transaction fee/resource-usage data (the deployed testnet contract IDs in the README could be used to gather real comparison data if stellar-cli/RPC access is available in your environment).
Difficulty Justification
Requires learning and correctly using Soroban-specific, less-commonly-documented budget/metering APIs, designing benchmarks that isolate genuine size-dependent cost scaling from noise, and building durable regression-detection tooling (not just a one-time measurement) — all while producing numbers precise and trustworthy enough to inform real engineering decisions (like the recipient-count cap) in other parts of this bounty set.
Background / Context
None of the three contracts have any performance/compute-cost testing today — the 16 existing tests (per the README: 8 escrow, 4 milestones, 4 maintenance-pool) are purely correctness-focused.
soroban_sdk::Envexposes abudget()API that reports actual CPU-instruction and memory consumption for contract invocations during tests, which is the standard way to measure real Soroban resource cost without needing a live network.Problem Statement
Given several other issues in this bounty set identify potentially expensive operations (unbounded
recipientsvectors inrelease/release_issue, the O(n)Milestone.allocationsMap read/write on everyallocate/release_issuecall, per-call TTL extension), the team has no way to detect a performance regression — a future change that unintentionally makes any entrypoint significantly more expensive — until it's discovered in production as failed/expensive mainnet transactions. This task is to build a proper, ongoing regression benchmark, not a one-off measurement.Requirements
initialize,fund,release,refund,get_escrow/get_admin/get_treasury/get_fee_bpsfor escrow; the equivalent set for milestones and maintenance-pool), write a benchmark test that invokes it under realistic conditions and capturesenv.budget()'s reported CPU instruction count and memory/footprint usage.recipients.len()forrelease/release_issue(e.g., 1, 5, 10, 20 recipients),allocations.len()at time of call forallocate/release_issuein milestones (e.g., after 1, 50, 200 prior allocations), anddeposit_countfor maintenance-pool operations — to produce actual cost-vs-size curves, not single data points.make benchtarget producing a comparable report, or a test assertion with generous tolerance bounds that fails if cost exceeds e.g. 150% of baseline) that would catch a serious future regression.Acceptance Criteria
release/release_issue(by recipient count) and milestones'allocate/release_issue(by prior allocation count)BENCHMARKS.mdor README section)make bench(or equivalent) target added and documentedTechnical Notes / Hints
env.budget()— checksoroban_sdk's testutils documentation for exact API (Budget::cpu_instruction_cost,.memory_bytes_cost, or similar, depending on SDK version26.1.0pinned in this workspace'sCargo.toml).Env::default()test environment's budget accounting is representative enough of real network costs to be trustworthy for this purpose, or whether it needs calibration against actual testnet transaction fee/resource-usage data (the deployed testnet contract IDs in the README could be used to gather real comparison data ifstellar-cli/RPC access is available in your environment).Difficulty Justification
Requires learning and correctly using Soroban-specific, less-commonly-documented budget/metering APIs, designing benchmarks that isolate genuine size-dependent cost scaling from noise, and building durable regression-detection tooling (not just a one-time measurement) — all while producing numbers precise and trustworthy enough to inform real engineering decisions (like the recipient-count cap) in other parts of this bounty set.