Skip to content

Add stablecoin redemption controller quote API #327

Description

@3esmit

Goal

Expose a read-only quote for the next redemption-rate controller tick, using
the pure controller and clamp constants introduced by #312.

Scope

  • Add a pure stablecoin_ffi quote operation backed directly by
    run_controller_tick, INTEGRAL_CLAMP, and RATE_DELTA_CLAMP.
  • Add redemptionRateUpdateQuote() to StablecoinModuleImpl.
  • Read and validate protocol parameters, redemption-price state, the configured
    market-price oracle, and canonical clock.
  • Project the current redemption price before running the tick, matching the
    on-chain update_redemption_rate order.
  • Return canSubmit, machine-readable blockers, current redemption price,
    market price, elapsed milliseconds, next redemption rate, next integral
    term, and clamp metadata. Preserve all fixed-point and signed values as exact
    decimal strings.
  • Treat a not-yet-due interval, stale oracle, or zero oracle price as a
    non-submittable quote, not as a fabricated controller output.
  • Keep this operation read-only. Transaction submission belongs to the feat(stablecoin): add permissionless pokes for the global state #317
    poke API sub-issue.

Acceptance criteria

  • Quote results match run_controller_tick for positive, zero, and negative
    error; proportional-only and PI modes; integral carry-over; both integral
    clamp directions; both rate clamp directions; and worst-case bounded inputs.
  • Sign convention matches the program: error = redemption - market, with no
    extra negation before adding the rate adjustment to fixed-point one.
  • Oracle ID, freshness, non-zero price, and minimum-update-interval gates match
    the host instruction.
  • No floating-point math exists in the FFI or C++ transport layer.
  • nix build .#stablecoin-module and relevant Rust/module tests pass.

Dependencies

Depends on the scaffold, redemption-price-state, and current-global-projections
sub-issues under #321.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions