WIP: FA underlock automation DAML by cgibbard · Pull Request #16 · obsidiansystems/splice

cgibbard · 2026-08-27T07:18:19Z

Pull Request Checklist

Cluster Testing

If a cluster test is required, comment /cluster_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.
If an upgrade test is required, comment /upgrade_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.
If a hard-migration test is required (from the latest release), comment /hdm_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.
If a logical synchronizer upgrade test is required (from canton-3.5), comment /lsu_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.

PR Guidelines

Include any change that might be observable by our partners or affect their deployment in the release notes.
Specify fixed issues with Fixes #n, and mention issues worked on using #n
Include a screenshot for frontend-related PRs - see README or use your favorite screenshot tool

Merge Guidelines

Make the git commit message look sensible when squash-merging on GitHub (most likely: just copy your PR description).

cgibbard · 2026-08-27T07:25:37Z

    nextScheduledLogicalSynchronizerUpgrade: Optional LogicalSynchronizerUpgradeSchedule
+    faDefaultRequiredLockAmount : Optional Decimal -- ^ The amount of amulet required to be locked by an FA to maintain their FeaturedAppRight if its requiredLockAmount is None.
+    faUnderlockGracePeriod : Optional RelTime -- ^ The amount of time after which automatic enforcement will withdraw a FeaturedAppRight if its provider remains underlocked.
+    faUnderlockEnforcementEnabled : Optional Bool -- ^ Whether automatic FA underlock enforcement may now occur, used to support a transitionary period.


This could be a timestamp instead to announce a ledger time

this is coming in 0.8.0: canton-network#6968

Ah, yeah, I was also thinking about that TextMap from my design doc, but just wanted to put something provisional in place for this exploration.

cgibbard · 2026-08-27T07:26:14Z


+-- | This is an enumeration of the transitions in underlocking state that can be caused by DsoRules_UpdateFeaturedAppUnderlock
+data FaUnderlockTransition =
+    FaUnderlockTransition_Open -- ^ Transition to underlocked state


Not sure if we want to put a dummy field here to futureproof against SCU

Depends on what kind of changes we expect. It seems though that we might not need this type at all.

meiersi-da

Thanks. I agree with the direction. For details see my comments.

meiersi-da · 2026-08-27T11:58:09Z

+    firstUnderlockObservedAt : Optional Time
+      -- ^ Ledger time at which the DSO first observed this provider underlocked.
+      -- Some t means suspended since time t, and archivable from t + grace period.
+      -- None means compliant. Never set before enforcement is activated.


Never set before enforcement is activated.

why is that?

I'm thinking here of the transitional period where we begin to allow FAs to properly re-lock their funds (begins as soon as the DARs go out), but before we begin actually starting the timers. Maybe we could say the grace period is all you get, but my impression was that it ought to be a bit longer.

OK, I see. I would probably not note that in the Daml code. The Impl. CIP has this two stage nature built in: https://docs.google.com/document/d/1VGtgNSNHrHnSLggqxlvhCTFrMPgaeCs2OLEJ8Fq9Ar4/edit?tab=t.753u8f9hx8hv#bookmark=id.ck925sjr9rre

meiersi-da · 2026-08-27T12:12:20Z

+        featuredAppRightCid <- create this with
+          firstUnderlockObservedAt = newObservedAt
+        return FeaturedAppRight_UpdateUnderlockResult with
+          featuredAppRightCid


Missing: the immediate loss of the ability to create featured app markers if they are underlocked

meiersi-da · 2026-08-27T12:18:12Z

+    requiredLockAmount : Optional Decimal
+      -- ^ Override of the network-wide minimum lock threshold.
+      -- None means that the default in DsoRulesConfig applies.
+    firstUnderlockObservedAt : Optional Time


I'm inclined to do the join with the grace period at the time where the underlock is observed and not when it is enforced. Something like:

underlockRecoveryDeadline : Optional Time

It has the advantage that an app right can be understood on its own, and we can just add a choice FeaturedApp_EnforceUnderlock that archives the app right.

This also solves the confusion that "first" could refer to the first of all the underlocks, or the first one of the non-recovered underlocks, which actually is the case.

meiersi-da · 2026-08-27T12:18:29Z

      controller provider
      do return FeaturedAppRight_CancelResult

+    choice FeaturedAppRight_UpdateUnderlock : FeaturedAppRight_UpdateUnderlockResult


Suggested change

choice FeaturedAppRight_UpdateUnderlock : FeaturedAppRight_UpdateUnderlockResult

choice FeaturedAppRight_UpdateUnderlockStatus : FeaturedAppRight_UpdateUnderlockResult

Given that you anyways call withdraw directly from DsoRules, I'm wondering whether we shouldn't implement the whole underlock logic in DsoRules, and thus save code.

Also consider introducing a data FeaturedAppUnderlockState to make future changes to the underlock logic easy.

meiersi-da · 2026-08-27T12:27:38Z

    nextScheduledLogicalSynchronizerUpgrade: Optional LogicalSynchronizerUpgradeSchedule
+    faDefaultRequiredLockAmount : Optional Decimal -- ^ The amount of amulet required to be locked by an FA to maintain their FeaturedAppRight if its requiredLockAmount is None.
+    faUnderlockGracePeriod : Optional RelTime -- ^ The amount of time after which automatic enforcement will withdraw a FeaturedAppRight if its provider remains underlocked.
+    faUnderlockEnforcementEnabled : Optional Bool -- ^ Whether automatic FA underlock enforcement may now occur, used to support a transitionary period.


this is coming in 0.8.0: canton-network#6968

meiersi-da · 2026-08-27T12:42:58Z

+        case transition of
+          FaUnderlockTransition_Open -> void $ exercise rightCid FeaturedAppRight_UpdateUnderlock with underlocked = True
+          FaUnderlockTransition_Close -> void $ exercise rightCid FeaturedAppRight_UpdateUnderlock with underlocked = False
+          FaUnderlockTransition_Enforce -> do


This one doesn't require off-ledger validation. wdyt about moving it into its own choice?

meiersi-da · 2026-08-27T12:48:59Z

      -- ^ Weight of the this provider's app activity in the computation of traffic-based app rewards.
      --
      -- If not set, the default weight of 1.0 is used.
+    requiredLockAmount : Optional Decimal


missing: choice to update this amount

I actually realize that we missed an opportunity to make it easy to store additional config parameters on an FA right when we added featured app rights.

Given that we anyways need to add support for instruction contracts to change a featured app right, I suggest to do the following:

-- 1. introduce two new types data FeaturedAppConfig = FeaturedAppConfig with activityWeight : Decimal requiredLockAmount : Optional Decimal data FeaturedAppConfigInternal = FeaturedAppConfigInternal with requiredLockAmount : Optional Decimal -- and use the latter to store a field `config : FeaturedAppConfigInternal` on `FeaturedAppRight` -- 2. introduce choice to update the current config using `patchable`. The trick is to store the config in an exploded form choice FeaturedAppRight_UpdateConfig with baseConfig : FeaturedAppConfig newConfig : FeaturedAppConfig -- 3. introduce an instruction for config changes in DsoRules to solve the stable references problem; and prepare for more config being stored on FeaturedAppRights

meiersi-da · 2026-08-27T12:51:58Z


+    nonconsuming choice DsoRules_UpdateFeaturedAppUnderlock : DsoRules_UpdateFeaturedAppUnderlockResult
+      with
+        rightCid : ContractId FeaturedAppRight


There's a bit of a problem brewing with the approach we are choosing here: the featured app right is referenced by contract-id in DsoRules_UpdateFeaturedAppRight, which in turn is used to execute votes. This only works if concurrent changes to app rights are very seldom.

That will no longer be the case with underlock updates. We have handled this in the past by creating "instruction"-contracts that can then be executed by an SV operator party. See for example https://github.com/canton-network/splice/blob/6e96647fc53583fd3b515c0fb17c1e253364e89e/daml/splice-dso-governance/daml/Splice/DsoRules.daml#L2012-L2020

I suspect that we have to do the same for the featured app rights for both its existing FeaturedAppRight_Update and the new FeaturedAppRight_UpdateUnderlock choice.

meiersi-da · 2026-08-27T13:00:14Z

+                  (observedAt `addRelTime` getFaUnderlockGracePeriod this.config <= now)
+                void $ exercise rightCid FeaturedAppRight_Withdraw with
+                  reason = "CIP-XXX underlock enforcement"
+        return DsoRules_UpdateFeaturedAppUnderlockResult


Generally logic that affects amulet users (e.g., app providers) is captured in AmuletRules and DsoRules only forwards to these choices. It's mostly a code organization principle that we use to ensure that one can reason about amulet related guarantees w/o looking at DsoRules.

I do though have a hard time judging how much extra code that introduces if any at all. If it is a lot, we need to judge whether the change is worth it.

So what I'd suggest is that you first implement the full logic with instructions, and the check how much effort the moving would be.

meiersi-da · 2026-08-27T13:01:18Z


+-- | This is an enumeration of the transitions in underlocking state that can be caused by DsoRules_UpdateFeaturedAppUnderlock
+data FaUnderlockTransition =
+    FaUnderlockTransition_Open -- ^ Transition to underlocked state


Depends on what kind of changes we expect. It seems though that we might not need this type at all.

WIP: FA underlock automation DAML

7c6bb6a

cgibbard commented Aug 27, 2026

View reviewed changes

meiersi-da reviewed Aug 27, 2026

View reviewed changes

	choice FeaturedAppRight_UpdateUnderlock : FeaturedAppRight_UpdateUnderlockResult
	choice FeaturedAppRight_UpdateUnderlockStatus : FeaturedAppRight_UpdateUnderlockResult

Uh oh!

Conversation

cgibbard commented Aug 27, 2026

Pull Request Checklist

Cluster Testing

PR Guidelines

Merge Guidelines

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!

meiersi-da left a comment

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants