[Depo-dev]

Summary

Measures and publishes Soroban resource costs for the Shade hub operations, with maximum safe batch sizes and a reproducible way to regenerate them.

Type of Change

• Documentation update
• Test improvements

Linked Issue

Fixes #497

Changes Made

• docs/reference/resource-costs.md: measured cost tables for register_merchant, create_invoice, pay_invoice, pay_invoices_batch and get_invoices, alongside the existing process_billing_cycle table; safe batch sizes; measurement caveats; most-expensive-operations summary
• contracts/shade/tests/resource_costs.rs: harness using env.cost_estimate().resources()
• scripts/resource-costs/measure-shade.sh: regenerates the numbers
• CHANGELOG entry

Results: pay_invoices_batch max safe batch is 17 invoices (event bytes bind first); get_invoices fails on read entries beyond 98 stored invoices; pay_invoice is the heaviest single call (about 0.56M instructions).

Important caveat

The shade crate does not compile on current main (KYC and campaign-royalty code was merged without its DataKey, ContractError and event definitions; vesting structs and mod lines are duplicated). The Shade numbers are therefore measured on the last compiling commit (4c97ca0) in a temporary worktree, with a small patch applying the same pay_invoices_batch single-auth fix that main already has. The script runs in place once main builds again. purchase_tickets_bulk is not measured (it does not exist in that snapshot) and the testnet fee range is not published (no testnet measurement); both are stated in the doc.

Test Evidence

• scripts/resource-costs/measure-shade.sh run end to end; all 3 harness tests pass on the snapshot
• markdownlint-cli2 clean on the doc
• make test / make lint cannot run for shade because of the pre-existing compile failure on main; the harness file is rustfmt-clean
• No test_snapshots/ file is staged in this PR

Documentation Updates

• This PR adds/changes a docs/ page

Changelog

• Update CHANGELOG

[lmduy2612]

Reviewed contracts/shade/tests/resource_costs.rs, scripts/resource-costs/measure-shade.sh, and docs/reference/resource-costs.md. Resetting the Soroban environment budget to unlimited before each single top-level batch invocation and reading env.cost_estimate().resources() is a clean way to capture linear scaling past per-transaction ledger limits.