Skip to content

Expose stablecoin position health through stablecoin_module #343

Description

@3esmit

Goal

Expose a deterministic, read-only position-health quote through
stablecoin_module, using the collateralization invariant added by #336 and
live fee/redemption projections.

Scope

  • Add a pure stablecoin_ffi quote operation that evaluates a decoded
    Position with the current stability-fee accumulator, redemption price, and
    minimum collateralization ratio.

  • Add positionHealth(request) to StablecoinModuleImpl, accepting ownerId
    and exact decimal-string positionNonce.

  • Reuse the Position and Vault derivation/validation from Expose stablecoin position resolution and decoding #325.

  • Read ProtocolParameters for minimum_collateralization_ratio and reuse the
    current global projections from Expose current stablecoin global projections #326. Callers must not supply trusted
    protocol values.

  • Preserve the exact feat(stablecoin): add collateralization-check helper #336 calculation:

    • nominal_debt = normalized_debt_amount * current_accumulator / FIXED_POINT_ONE
    • collateral_value = collateral_amount * FIXED_POINT_ONE^2
    • required_collateral_value = nominal_debt * current_redemption_price * minimum_collateralization_ratio
    • the Position is collateralized when collateral_value >= required_collateral_value
  • Return Position/Vault IDs, source Position amounts, projected protocol
    operands, nominalDebt, collateralValue, requiredCollateralValue, and
    isCollateralized. Encode every integer as an exact decimal string.

  • Treat zero debt as collateralized, matching feat(stablecoin): add collateralization-check helper #336.

  • Use checked wide-integer arithmetic and return stable errors for overflow,
    missing accounts, malformed state, ownership/PDA mismatches, and projection
    failures.

  • Share a non-panicking calculation/predicate with the program invariant where
    practical. Do not catch the assertion helper's panic as normal quote flow.

Acceptance criteria

  • Quote results match the program invariant for zero debt, comfortable surplus,
    exact equality, one unit below the boundary, and accumulator-driven health
    deterioration.
  • Fixed vectors pin rounding at the single nominal-debt division used by feat(stablecoin): add collateralization-check helper #336.
  • Maximum-width request/state values cross the Rust/C++/Logos boundary without
    precision loss; checked U256 overflow becomes a stable error.
  • Position lookup rejects malformed data, wrong program ownership, wrong PDA,
    and stored owner/nonce/vault mismatches.
  • Protocol reads reject missing or malformed parameters, accumulator,
    redemption-state, and clock accounts.
  • No floating-point values appear in request or response contracts.
  • Relevant Rust/module tests and nix build .#stablecoin-module pass.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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