economic-design-audit

name	economic-design-audit
description	Trigger Pattern MONETARY_PARAMETER flag (fee, rate, emission, cap, bps values) - Inject Into Breadth agents (merged via M4 hierarchy)

ECONOMIC_DESIGN_AUDIT Skill (Soroban)

Trigger Pattern: MONETARY_PARAMETER flag (required) Inject Into: Breadth agents (merged via M4 hierarchy) Finding prefix: [EDA-N] Rules referenced: R2, R10, R13, R14

rate|rebase|supply|burn|emission|inflation|peg|price_cap|price_floor|
fee|reward_rate|basis_points|bps|fee_bps|spread

Soroban arithmetic context: All numeric values use i128 (signed 128-bit). No floating-point. Fee/rate formulas use integer multiply-then-divide. Overflow panics unless checked_* used; unchecked release-mode i128 wraps silently. Division truncates toward zero.

---

1. Parameter Boundary Analysis

For every monetary parameter setter (rate, fee, reward rate, emission, cap, floor, BPS values):

Parameter	Setter Function	Min Value	Max Value	Enforced?	Impact at Min	Impact at Max

For each: substitute min and max into ALL consuming functions. Tag: [BOUNDARY:param=val -> outcome]

Soroban-specific boundary checks:

• Does MAX cause i128 overflow in multiply-then-divide? (amount * rate_bps overflows before division if both are large; check for checked_mul)
• Does 0 cause division-by-zero? (panic aborts entire transaction — verify .checked_div() or explicit guard)
• Does 10_000 BPS (100%) cause user to receive 0 tokens or go negative with fees-on-fees?
• Does a negative i128 value cause unexpected behavior? (signed type allows negative rates if not bounds-checked)

---

2. Economic Invariant Identification

List all economic invariants the protocol must maintain:

Invariant	Parameters Involved	Can Admin Break It?	Functions That Assume It

For each setter: can changing this parameter break an invariant that user-facing functions depend on? If yes → finding.

Soroban-specific invariants:

• i128 conservation: Total tracked must equal sum of individual claims. Verify no rounding loss accumulates across many users.
• No negative balances: i128 allows negative values — if subtraction underflows without checked math, balance can go negative silently.
• TTL-gated invariants: If a key expires and returns None, unwrap() panics; unwrap_or(0) may silently break the invariant.

---

3. Rate/Supply Interaction Matrix

For protocols with multiple monetary parameters that interact:

Parameter A	Parameter B	Interaction	Can A x B Produce Extreme Output?

Check: can two independently-valid settings combine to create an extreme economic state? (Rule 14 constraint coherence)

---

4. Fee Formula Verification at Normal Values

4a. Concrete Example Computation

Pick 3 representative fee rates and trace through the actual code formula:

Fee Param	Value	Formula	Input Amount (i128)	Expected Output	Actual Output	Match?

Tag: [BOUNDARY:fee_bps={val} -> effective_rate={computed_rate}]

Note: XLM uses 7 decimal places (1 XLM = 10_000_000 stroops). Verify formulas account for correct denomination.

Red flags:

• Gross-up formulas: amount * MAX / (MAX - fee) charges higher effective rate than fee/MAX
• Fee-on-fee: fee A's output feeds fee B's input — combined rate is not A + B
• Rounding direction: i128 division truncates toward zero — verify intended direction
• Division order: amount * rate / MAX vs amount / MAX * rate — second loses precision for small amounts

4d. Fee-Base Consistency

For every fee computation, trace the base amount through ALL subsequent code paths:

Fee Site	Base Amount Variable	Modified After Fee?	Modified How	Fee Recomputed?	Overcharge?

Methodology: Identify fee base variable → trace FORWARD → if variable reduced (capped, slippage-adjusted) AFTER fee computed → fee charged on larger base than processed.

4b. Fee Interaction Matrix

For protocols with multiple fee types:

Fee A	Fee B	A Output Feeds B Input?	Combined Effective Rate	Independent Rate Sum	Discrepancy?

4c. Fee Impact on Share Price

If share-based accounting: does fee deduction change share price? Does it create deposit-vs-immediate-withdrawal spread? With i128 rounding, does deposit vs withdraw favor one direction consistently?

---

5. Emission/Inflation Sustainability

For protocols with emission/inflation/reward distribution:

• Maximum emission rate over 1 ledger / 1 day / 1 year?
• Can emissions exceed reward vault's token balance?
• Supply cap? Can admin bypass it?
• What happens when reward vault depleted? (panic on transfer? zero rewards? proportional reduction?)

Emission Parameter	Max Rate	Vault Balance Required	Ledgers to Depletion at Max	Cap Exists?

---

6. Resource Metering and Cost Economics

Soroban meters resources across CPU instructions, memory (bytes), and ledger I/O (entries read + written) — all per-transaction budgeted and network-configurable.

For batch operations (mass distributions, multi-user updates, bulk settlements):

Operation	Ledger Entries Read	Ledger Entries Written	Memory Growth	Scales With N?	DoS via Large N?

Key cost considerations:

• Persistent storage reads cost more than Instance — avoid iterating Persistent keys in hot paths
• Writing new ledger entries increases fees; if protocol absorbs cost, check for griefing
• TTL extension fees: size_bytes * fee_rate * extension_ledgers — unbounded extensions can drain operational budget
• Loops over Vec in Instance storage consume proportional CPU/memory — check for unbounded iteration

---

7. TTL Cost Economics (Soroban-Specific)

Storage Entry	Storage Type	Current TTL Strategy	Who Pays to Extend	Risk if Expired

Checks:

• Instance storage expiry → ALL instance().get() with unwrap() panic — contract unusable
• User's Persistent entry expires → position data archived; who pays restoration fee?
• Temporary storage (allowances, nonces) expiry → DoS on normal operations?
• Admin function for bulk TTL extension? Resource cost at max user count?
• Can attacker let entries expire to avoid obligations (debt, locked collateral)?

---

Finding Template

**ID**: [EDA-N]
**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: (see checklist below)
**Rules Applied**: [R2:___, R10:___, R13:___, R14:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: src/{file}.rs:LineN
**Title**: {parameter boundary violation / invariant break / economic unsustainability / TTL expiry DoS}
**Description**: {specific issue with code reference and numerical example using i128 values}
**Impact**: {quantified at worst-state operational parameters — Rule 10}

---

Step Execution Checklist (MANDATORY)

Section	Required	Completed?	Notes
1. Parameter Boundary Analysis	YES
2. Economic Invariant Identification	YES
3. Rate/Supply Interaction Matrix	IF >1 monetary param
4. Fee Formula Verification at Normal Values	IF fee parameters detected
5. Emission/Inflation Sustainability	IF emission/reward detected
6. Resource Metering and Cost Economics	YES
7. TTL Cost Economics	YES		Soroban-specific — never skip

If any step skipped, document valid reason (N/A, single parameter, no emissions, no TTL-sensitive keys).