Document doubOwedForBuy mutability and TWAP usage

PlasticDigits commented

2026-06-13 07:34:24 +00:00

(Migrated from gitlab.com)

Parent

Gap analysis follow-up from #309.

Current codebase

doubOwedForBuy(uint256 charmWad) external returns (uint256) — not view because _sampleCharmAnchor() may call Kumbaya/TWAP externals (TimeArena.sol L311–318).
TimeArenaBuyRouter.buyViaKumbaya uses this for pricing (TimeArenaBuyRouter.sol L101).
No dedicated Forge test; integrators may expect eth_call staticcall compatibility.

Why needed

Approved: Check when TWAP is needed and document mutability/view semantics for integrators and indexers.

Constraints / guardrails

Prefer view if no state mutation occurs (current code does not write state in preview path).
Document hard-reset boundary behavior vs effectiveCharmPriceWad().
Update docs/integrations/kumbaya.md and router ABI notes.

Relevant files

contracts/src/arena/TimeArena.sol — doubOwedForBuy, _sampleCharmAnchor, _willLastBuyHardReset
contracts/src/arena/TimeArenaBuyRouter.sol
contracts/test/TimeArenaEpochCharmPrice.t.sol
indexer/ decoder if ABI changes
frontend/ buy preview callers

Recommended direction

Audit call graph: if no state writes, change to view (or add doubOwedForBuyView pure preview).
Document TWAP/spot anchor conditions in PARAMETERS.md and integration docs.
Add Forge test matching doubOwedForBuy output to actual buy cost at boundary epochs.

Acceptance criteria

Documented when external calls occur and why.
Integrators have a staticcall-safe preview path (view fn or documented workaround).
Forge test covers hard-reset boundary pricing.

Test plan

cd contracts && forge test --match-contract TimeArenaEpochCharmPrice.
bash scripts/verify-time-arena-buy-router-anvil.sh if router ABI changes.

Attack / abuse test plan

Preview/manipulation: TWAP anchor cannot be sandwiched to underpay in same block (document assumptions).

Verification criteria

NatSpec + PARAMETERS.md explain non-view vs view decision.
Test doubOwedForBuy(charm) == actual DOUB pulled on immediate buy.

## Parent Gap analysis follow-up from [#309](https://gitlab.com/PlasticDigits/yieldomega/-/issues/309). ## Current codebase - `doubOwedForBuy(uint256 charmWad) external returns (uint256)` — not `view` because `_sampleCharmAnchor()` may call Kumbaya/TWAP externals (`TimeArena.sol` L311–318). - `TimeArenaBuyRouter.buyViaKumbaya` uses this for pricing (`TimeArenaBuyRouter.sol` L101). - No dedicated Forge test; integrators may expect `eth_call` staticcall compatibility. ## Why needed Approved: Check when TWAP is needed and document mutability/view semantics for integrators and indexers. ## Constraints / guardrails - Prefer `view` if no state mutation occurs (current code does not write state in preview path). - Document hard-reset boundary behavior vs `effectiveCharmPriceWad()`. - Update `docs/integrations/kumbaya.md` and router ABI notes. ## Relevant files - `contracts/src/arena/TimeArena.sol` — `doubOwedForBuy`, `_sampleCharmAnchor`, `_willLastBuyHardReset` - `contracts/src/arena/TimeArenaBuyRouter.sol` - `contracts/test/TimeArenaEpochCharmPrice.t.sol` - `indexer/` decoder if ABI changes - `frontend/` buy preview callers ## Recommended direction 1. Audit call graph: if no state writes, change to `view` (or add `doubOwedForBuyView` pure preview). 2. Document TWAP/spot anchor conditions in `PARAMETERS.md` and integration docs. 3. Add Forge test matching `doubOwedForBuy` output to actual `buy` cost at boundary epochs. ## Acceptance criteria - [ ] Documented when external calls occur and why. - [ ] Integrators have a staticcall-safe preview path (view fn or documented workaround). - [ ] Forge test covers hard-reset boundary pricing. ## Test plan - `cd contracts && forge test --match-contract TimeArenaEpochCharmPrice`. - `bash scripts/verify-time-arena-buy-router-anvil.sh` if router ABI changes. ## Attack / abuse test plan - Preview/manipulation: TWAP anchor cannot be sandwiched to underpay in same block (document assumptions). ## Verification criteria - NatSpec + `PARAMETERS.md` explain non-view vs view decision. - Test `doubOwedForBuy(charm) ==` actual DOUB pulled on immediate `buy`.

PlasticDigits commented

2026-06-13 07:34:43 +00:00

(Migrated from gitlab.com)