[spotkorner-dot]

Closes #947
Closes #948
Closes #949
Closes #957

Issues

#947 Optimize math operations

Overview

Use fixed-point arithmetic to reduce compute cost of calculations.

Requirements

• Profile math
• Implement fixed-point
• Validate accuracy
• Benchmark results

Acceptance Criteria

• Math faster
• Accuracy maintained
• Compute reduced
• Benchmarks good
• Tests pass

Definition of Done

All CI checks must pass before the PR is reviewed.

#948 Implement incremental state updates

Overview

Process state changes incrementally instead of rewriting entire entries.

Requirements

• Design incremental
• Implement updates
• Test correctness
• Measure savings

Acceptance Criteria

• Updates incremental
• Correctness verified
• Compute reduced
• Storage optimized
• Tests pass

Definition of Done

All CI checks must pass before the PR is reviewed.

#949 Add storage tier optimization

Overview

Review and optimize storage tier usage across all data.

Requirements

• Analyze tier usage
• Identify inefficiencies
• Optimize placement
• Measure savings

Acceptance Criteria

• Usage optimized
• Tiers balanced
• Compute reduced
• Costs lower
• Tests pass

Definition of Done

All CI checks must pass before the PR is reviewed.

#957 Add guard failure events

Overview

Emit events when release guards prevent operation.

Requirements

• Identify guards
• Emit per guard
• Include guard data
• Test coverage

Acceptance Criteria

• All guards emit
• Data included
• Events clear
• Indexable
• Tests pass

Definition of Done

All CI checks must pass before the PR is reviewed.

Summary

Fixed-point work (#947) must preserve exact accuracy: keep the canonical 7-decimal scale and checked arithmetic, and verify the largest-remainder sum invariant. Incremental updates (#948) should read-modify-write single keys and must be proven equivalent to full rewrites via tests. Storage tier changes (#949) must keep the key-uniqueness tests green and avoid moving hot payment-path data out of instance storage. Guard-failure events (#957) must be emitted before returning errors at every release guard site, with stable topics and payloads for indexers. Run all CI checks (unit, property, fuzz, compute-budget, event-log, storage-rent) before review.

Changes

• Add a fixed-point arithmetic module: define a FixedPoint type (scaled by 10^CANONICAL_DECIMALS) with checked add/sub/mul/div helpers and conversion to/from i128, and route the existing normalize/denormalize helpers through it. Add unit tests for overflow, rounding and round-trip accuracy. This replaces general integer math in the split contract with cheaper fixed-point operations (Optimize math operations #947). (contracts/split/src/math.rs)
• Migrate the split arithmetic in calc.rs (largest-remainder distribution, funding_bps, calc_platform_fee) to use the new fixed-point helpers from math.rs instead of raw integer multiply/divide, keeping the sum(result) == total invariant and exact accuracy. Add unit tests covering rounding and overflow paths. (contracts/split/src/calc.rs)
• Add fixed-point scale constants (e.g. FIXED_POINT_SCALE = 10^CANONICAL_DECIMALS, FIXED_POINT_ONE) and any new TTL/tier constants needed by the incremental-update and storage-tier work, keeping existing MIN/MAX_INVOICE_TTL_LEDGERS values intact. (contracts/split/src/constants.rs)
• Refactor storage.rs so mutations update only changed fields incrementally instead of rewriting whole entries: add per-field set/update helpers (e.g. update_invoice_field, update_recipient_amount, bump_counter) that read-modify-write a single key, and reclassify keys into instance/persistent/temporary tiers with matching TTL bump helpers. Keep save_invoice/save_recipients/save_contributor working for full writes. (contracts/split/src/storage.rs)
• Update the storage key registry: document and, where needed, move keys between instance/persistent/temporary tiers based on access patterns (hot payment-path fields to instance, per-entity state to persistent, ephemeral counters to temporary), and add any new per-field keys required by incremental updates. Keep the uniqueness tests passing. (contracts/split/src/storage_keys.rs)
• Add a structured guard-failure event emitter (e.g. guard_failed(env, guard: Symbol, invoice_id: u64, data)) with topics (split, guard_fail, guard) and payload including guard identifier and relevant data, plus any helper to enumerate guard names. Ensure the event is indexable and documented alongside existing events. (contracts/split/src/events.rs)
• Wire the release path to emit guard-failure events at every release guard site (paused, frozen, timelock, already-released, insufficient funding, etc.) before returning the corresponding ContractError, and route state mutations through the new incremental storage helpers and fixed-point calc functions. Keep all existing entry points and tests working. (contracts/split/src/lib.rs)
• Add any new error variants needed for guard failures or incremental-update validation (appended at the end of the enum to keep discriminants stable), and ensure existing errors remain unchanged. (contracts/split/src/error.rs)
• Add unit tests in test.rs covering: fixed-point math accuracy and overflow, incremental storage updates producing the same final state as full rewrites, storage-tier placement, and guard-failure events emitted with correct topics and payloads for each release guard. (contracts/split/src/test.rs)
• Extend fuzz/property tests to assert fixed-point split arithmetic preserves the sum invariant and accuracy, and that incremental updates converge to the same state as full-entry writes across random mutation sequences. (contracts/split/src/fuzz_tests.rs)
• Update the payment split property tests to exercise the fixed-point allocation path and assert exact accuracy and sum invariants under the new arithmetic. (contracts/split/tests/payment_split_properties.rs)
• Add compute-budget benchmark tests measuring the savings from fixed-point math and incremental state updates, asserting the new paths stay within the documented budget ranges. (tests/test_compute_budget.rs)
• Add event-log tests asserting that each release guard emits a guard-failure event with the expected topics (split, guard_fail, guard) and payload data, and that the events are indexable. (tests/event_log_tests.rs)
• Add storage-rent tests verifying the rebalanced storage tiers reduce rent/compute costs and that incremental updates lower per-mutation storage charges while keeping correctness. (tests/test_storage_rent.rs)
• Document the fixed-point arithmetic design, profiling results and measured compute savings, and update the compute budget ranges table to reflect the optimized math and incremental storage paths. (docs/COMPUTE_BUDGETS.md)
• Update the storage key registry documentation to reflect the new tier assignments (instance/persistent/temporary), list any new per-field keys introduced for incremental updates, and record the measured storage cost savings. (STORAGE_KEY_REGISTRY.md)

[drips-wave]

@spotkorner-dot Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits