spec: Health Triger Manager by janezpodhostnik · Pull Request #12 · onflow/flow-credit-markets

janezpodhostnik · 2026-04-21T14:04:35Z

No description provided.

holyfuchs · 2026-04-23T14:26:53Z

+
+### Registration
+
+To register a health trigger the caller provides a position ID, a health function $$H(P)$$, and the three fields of a `HealthTrigger` (bounds, callback, provider). If the position already has an entry in the registry, the health function is ignored and the new trigger is appended to the existing entry's trigger list.


Seems dangerous, a malicious actor could register a position with a health function that always returns 1.5, essentially bricking all other callbacks on that position.

I have a solution for this, basically requiring the provider to be a provider: Capability<auth(FungibleToken.Withdraw) &FlowToken.Vault> do you still see a way it could panic?

never mind actually. this could still panic! I will change this altogether

changed in 30cce52

holyfuchs · 2026-04-23T14:36:22Z

+**Validation:** The **HTM** evaluates $$H(P)$$ at registration time. Registration is rejected if:
+
+- $$H(P)$$ returns `nil` (the position does not exist or its health cannot be determined).
+- The position is already out of bounds ($$H(P) < H_{\textbf{min}}$$ or $$H(P) > H_{\textbf{max}}$$, for whichever bounds are specified). This prevents registering triggers that would fire immediately, which would be wasteful and could mask bugs in the caller's logic.


If possible the registration function should not panic, or we would have to wrap any registration from the FYV into a scheduled transaction.
If the health function never panics this is fine.

However in almost all cases this should have been already checked by the calling function and if health has not been checked by the calling function, then it would have to check if after registration.

Is there any reason we shouldn't accept registrations which trigger immediatly?

I can make registration more lax. I just saw no point registering something that will trigger immediately, but maybe it makes the rest of the code easier.

I will see if we can add a guarantee to the Register function that it will not panic.

made registration more lax and added guarantee it wont panic, but I had to add a limitation that you cannot have high priority scheduling. c0f5578

holyfuchs · 2026-04-23T14:52:25Z

+- If $$H_{\textbf{min}} \leq H(P) \leq H_{\textbf{max}}$$ (within bounds) → no action. Continue to the next trigger.
+- The trigger is out of bounds. Validate capabilities:
+  - The `HealthCallback` capability still exists.
+  - The `Provider` capability still exists and has sufficient funds to pay for the callback TX.


Provider is an interface and may panic, disrupting everything indefinitely.

made provider more specific so that it has to have a flow vault underneath.

changed in 30cce52

holyfuchs · 2026-04-23T14:54:23Z

+
+**Return value:** Registration returns success or failure. Failure indicates one of the validation checks above was not met.
+
+**Access control:** Registration is public. Since the registering party pays for callback execution (via the `Provider` capability), there is no execution cost to the protocol and no need for additional permissioning. Storage costs are absorbed by the **HTM** account for now (see [Future Expansions](#7-future-expansions)).


I like to assume that its public for any of the other security considerations to protect against our own misuse.
But I would restrict it at the beginning.

Looking at this again, registration might need to be guarded, but process doesn't need to be... I will check.

registration is now gated and does not accept a provider: 30cce52

jordanschalm · 2026-04-23T20:31:42Z

+
+The registry is keyed by position ID ($$P$$ = `position.id`, i.e. the Position resource's UUID). Each entry contains a list of `HealthTrigger` objects for that position.
+
+Position health is obtained via `FlowALP.Pool.getPositionHealth(positionID)`, which returns `UFix64?`. A `nil` return means the health could not be determined (see [Process](#process) for how this case is handled). The `Registry` holds a single `Capability<&FlowALP.Pool>`, set at init and changeable by admin. This ensures [Process](#process) calls the health function only once per position, regardless of how many triggers are registered for it.


2 thoughts, expanding the Q&A session today:

I think for the immediate term it's fine to just say getPositionHealth will panic if we can't get the health for any reason. We don't expect that to happen, but if it does we'll manually restart the HTM.

When we need to deal with recoverable error conditions, I agree with Alex that we should explicitly encode those in the return value of the fail-able function.

So you are suggesting to just panic in case of nil for now and we can later add the disambiguation?

If that is the case, wouldn't it be simpler/cleaner to just have health return an UFix instead of UFix? for now?

I'm just saying we have the freedom to panic, now, in the implementation, if that simplifies your life.

The spec should be more forward-looking. I think the spec should, when describing how we deal with multiple distinct failure conditions, use Alex's suggestion of enumerating the possible failure modes in the return type. Since we haven't decided on a structure for doing that, I would just say:

getPositionHealth returns either a health value, or an error.

The error structure is TBD, and should be a common pattern across the project, but would be similar to [Either types](https://hackage-content.haskell.org/package/base-4.22.0.0/docs/Data-Either.html

Before this error handling structure is defined, implementations may panic on failure. (if this saves time, or we can just define and implement the structure)

jordanschalm · 2026-04-23T20:51:19Z

+    hMin: UFix64?,
+    hMax: UFix64?,
+    callbackAddress: Address,
+    reason: String


Suggested change

reason: String

reason: TriggerRemovalReason

Maybe define an enum type for reason? Although I guess Cadence probably just puts the raw enum integer value into the event data -- it would be nice to still have the string representation in the actual event.

Not sure about this one! There is noone on chain that will be looking for this info and the offchain processes wont care that this is an enum. Enums also have issues with contract upgrades... so if not really necessary I would say lets just have strings.

jordanschalm

👏 Great work

janezpodhostnik self-assigned this Apr 21, 2026

janezpodhostnik force-pushed the janez/HTM branch from 7f718bc to f0745d8 Compare April 21, 2026 16:01

janezpodhostnik commented Apr 21, 2026

View reviewed changes

Comment thread health-trigger-manager.md Outdated

janezpodhostnik force-pushed the janez/HTM branch from f0745d8 to e459fdc Compare April 21, 2026 18:12

jordanschalm reviewed Apr 21, 2026

View reviewed changes

janezpodhostnik force-pushed the janez/HTM branch 6 times, most recently from 2b48af5 to 3580e0e Compare April 23, 2026 15:02

holyfuchs reviewed Apr 23, 2026

View reviewed changes

spec: Health Triger Manager

5b20a9b

janezpodhostnik force-pushed the janez/HTM branch from 3580e0e to 5b20a9b Compare April 23, 2026 16:04

janezpodhostnik added 2 commits April 23, 2026 18:38

spec: HTM - address review comments

c0f5578

spec: HTM - address review comments 2

30cce52

janezpodhostnik marked this pull request as ready for review April 23, 2026 18:37

janezpodhostnik requested a review from a team as a code owner April 23, 2026 18:37

jordanschalm reviewed Apr 23, 2026

View reviewed changes

jordanschalm approved these changes Apr 24, 2026

View reviewed changes


		### Registration

		To register a health trigger the caller provides a position ID, a health function $$H(P)$$, and the three fields of a `HealthTrigger` (bounds, callback, provider). If the position already has an entry in the registry, the health function is ignored and the new trigger is appended to the existing entry's trigger list.


		Return value: Registration returns success or failure. Failure indicates one of the validation checks above was not met.

		Access control: Registration is public. Since the registering party pays for callback execution (via the `Provider` capability), there is no execution cost to the protocol and no need for additional permissioning. Storage costs are absorbed by the HTM account for now (see [Future Expansions](#7-future-expansions)).


		The registry is keyed by position ID ($$P$$ = `position.id`, i.e. the Position resource's UUID). Each entry contains a list of `HealthTrigger` objects for that position.

		Position health is obtained via `FlowALP.Pool.getPositionHealth(positionID)`, which returns `UFix64?`. A `nil` return means the health could not be determined (see [Process](#process) for how this case is handled). The `Registry` holds a single `Capability<&FlowALP.Pool>`, set at init and changeable by admin. This ensures [Process](#process) calls the health function only once per position, regardless of how many triggers are registered for it.

Conversation

janezpodhostnik commented Apr 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janezpodhostnik Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jordanschalm left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

janezpodhostnik Apr 24, 2026 •

edited

Loading