Cip 0105 with custom templates POC by jonored · Pull Request #6894 · canton-network/splice

jonored · 2026-08-20T20:16:14Z

Implement governance locks with separate templates and not on top of V2 allocations (but do provide the V2 allocation interface for the separate lock templates).

Next steps are to do a proper happy path test and then add a sketch of the token standard V1 interface according to the implementation CIP work-in-progress.

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).

meiersi-da

Nice! Good work and great to see how much simpler the code became with our decision to separate the implementation concerns. Thanks for driving this PoC!

meiersi-da · 2026-08-21T09:57:55Z

+          changeHolding
+
+  -- TODO: implement V2 AllocationFactory in terms of above.
+  -- TODO: find and use binding point for "magic address" V1 token standard to above.


It's here:

splice/daml/splice-amulet/daml/Splice/ExternalPartyAmuletRules.daml

Lines 341 to 346 in 3e4bb9a

amulet_transferFactoryV1_transferImpl

: ExternalPartyAmuletRules

-> [Party]

-> Api.Token.TransferInstructionV1.TransferFactory_Transfer

-> Update Api.Token.TransferInstructionV1.TransferInstructionResult

amulet_transferFactoryV1_transferImpl this actors arg = do

meiersi-da · 2026-08-21T10:05:54Z

+    signatory dso, owner
+    choice GovernanceLock_Unlock : GovernanceLock_UnlockResult
+      with
+        amount : Optional Decimal


I'm not sure it is worth making this optional. In particular when storing the locked amount on the template it is very easy for the caller to select the full amount themselves if they want to do so.

Counterargument: both of the planned main public interfaces to this choice use a "withdraw from this agreement entirely" primitive that does not inherently supply an amount for a partial withdrawal, so an optional amount here avoids a bit of duplication. On the other hand, we could disallow V2 withdrawal without an amount in the metadata, which would make V1 and V2 handling differ enough to invalidate that argument.

I would aim for V2 to be as easy to use as the compatibility mode. So it should support the default. I'm OK either way wrt the defaulting.

I realize that my main concern is about the implementation: there I'd just compute the concrete amount to unlock up front, and make the code work with that.

meiersi-da · 2026-08-21T10:09:28Z

+        require "Only the authorizer may withdraw" $ authorizers == [owner] -- TODO: custom controllers
+        currentAmount <- fetchAmount (ForOwner with dso; owner) holding
+        assertDeadlineExceeded "requestAt must be in the past for withdraw" requestedAt
+        require "withdrawal time must be after the start time" $ requestedAt > startTime


for polish: switch to require' from the TokenStandardUtils, which gives better error messages out of the box. Example usage here:

splice/daml/splice-amulet/daml/Splice/AmuletAllocationV2.daml

Line 122 in 3e4bb9a

require' ("inputAmount", inputAmount) isGreaterOrEqualR ("minimal outputAmount", outputFundingAmount)

There actually seems to be a simpler option available: just compute the funds available for withdrawal at requestedAt given the state of the VestingLock and forbid withdraw in case there are no funds available.

This takes care in a uniform way of delayed unlocks, repeated withdrawals, and the final withdrawal.

Final withdraw probably branches away from this code entirely, as it can just leave the LockedAmulet in place; agreed with regard to just checking that there's anything to withdraw.

meiersi-da · 2026-08-21T10:12:26Z

+    signatory dso, owner
+    choice VestingLock_Withdraw : VestingLock_WithdrawResult
+      with
+        amount : Optional Decimal


When would a caller not want to withdraw the maximal amount? Partial unlocks make sense, but partial withdraws not really. The caller pays the traffic cost anyways, so they want to maximize their flexibility.

I'd suggest we remove this argument.

Fair enough; this is probably not very useful; I'll drop it.

meiersi-da · 2026-08-21T10:45:28Z

+calculateAvailableWithdrawAmount : Decimal -> Time -> VestingLock -> Optional Decimal -- None indicates the _full_ amount is available
+calculateAvailableWithdrawAmount currentAmount currentTime VestingLock{ .. }
+    | currentTime > (startTime `addRelTime` unlockPeriod) = None
+    | otherwise = Some $ initialAmount * fractionElapsed - (initialAmount - currentAmount)
+  where
+    fractionElapsed = (currentTime `subTime` startTime) `divRelTime` unlockPeriod
+    divRelTime = \a b -> (intToDecimal $ convertRelTimeToMicroseconds a) `div` (intToDecimal $ convertRelTimeToMicroseconds b)


wdyt about untangling the concerns in here by separating out the function that computes the vested amount as of a particular time from subtracting the amount that was already withdrawn.

Reasonable; good to have the overall total available as a loose function anyways.

You didn't do that yet though, did you?

Not yet; it'll go with changing the VestingLock representation.

meiersi-da · 2026-08-21T10:47:33Z

+
+lockAmulet : ForOwner -> [Decimal] -> [ContractId Holding] -> ExternalPartyTransferContext -> Update ([ContractId LockedAmulet], Optional (ContractId Amulet))
+lockAmulet forOwner@ForOwner {..} amounts inputHoldingCids context = do
+  let lockContext = "governance"


polish: encode type of lock here, and whether it is vesting

Still WIP; addressing tomorrow, this was a little messier in the helpers than I had time for today.

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonored@gmail.com>

And one fix for a non-nonconsuming choice.

This probably doesn't matter in actual use, but it _does_ cause more numbers in the test suite to yield obviously correct round numeric results, which is useful to make correctness obvious, and does not seem to have significantly impaired the readability of the implementation.

meiersi-da · 2026-08-24T07:09:05Z

+  AmuletRegistryV2.tapFaucet registriesEnv.amuletV2 alice 180000.0
+  AmuletRegistryV2.tapFaucet registriesEnv.amuletV2 bob 10000.0
+
+  aliceLock <- governanceLockRawChoice env alice 180000.0 someSvSpec


Good call to test directly on the raw choices. They are easier to work with and have a faster feedback loop.

Consider later just making it an env parameter what API interface is used to execute an action. This way it becomes easy to run the same test code with raw or TSv2 APIs

This was also required to test before one of the interfaces is implemented, and getting tests ASAP was priority. Factoring out helpers we can switch between the interfaces seems sensible.

meiersi-da · 2026-08-24T07:14:13Z

+  let dso = env.instrId.admin
+  [(glfCid, _glf)] <- query @GovernanceLockFactory dso
+  disc <- queryDisclosure' dso glfCid
+  inputs <- fmap fst <$> query @Amulet owner -- Excessive, check how the normal registry does it.


use one of:

splice/token-standard/splice-token-standard-v2-test/daml/Splice/Testing/TokenStandard/WalletClientV2.daml

Lines 13 to 17 in 8bc2e07

listHoldings,

listVisibleHoldings,

listHoldingCids,

listLockedHoldings,

listUnlockedHoldingCidsFor,

I was mostly wanting to check whether we had any that trimmed the input list to the required amount like I expect production to do, but it seems we don't do that in the tests.

meiersi-da · 2026-08-24T07:39:41Z

+        require "Only the authorizer may withdraw" $ authorizers == [owner] -- TODO: custom controllers
+        currentAmount <- fetchAmount (ForOwner with dso; owner) holding
+        assertDeadlineExceeded "requestAt must be in the past for withdraw" requestedAt
+        require "withdrawal time must be after the start time" $ requestedAt > startTime


There actually seems to be a simpler option available: just compute the funds available for withdrawal at requestedAt given the state of the VestingLock and forbid withdraw in case there are no funds available.

This takes care in a uniform way of delayed unlocks, repeated withdrawals, and the final withdrawal.

meiersi-da · 2026-08-24T07:41:36Z

+            unlockResult <- exercise holding LockedAmulet_UnlockV2
+            pure VestingLock_WithdrawResult with
+              vestingLock = None
+              unlocked = unlockResult.amuletCid
+          Some partial -> do -- We have a fraction that is not the whole being withdrawn, do a partial unlock.
+            (locked, unlocked) <- partialUnlock (ForOwner with dso; owner) holding partial context
+            vestingLock <- Some <$> create this with
+              holding = locked
+            pure VestingLock_WithdrawResult with
+              vestingLock
+              unlocked


if you implement splitLock such that it returns Optional (ContractId LockedAmulet) for the remainder, then you can just use that here as well; and you get a simpler implementation of _Unlock as well.

I tried to get that to be simpler but I'm not really happy with it; what we need here is the change from executeExternalPartyTransfer and the amount we aren't relocking, and what we need for Unlock is a new LockedAmulet with the same info that it creates from a TransferOutput and the remainder after the new allocation we create; I didn't see any particularly elegant or straightforward way to merge those paths much more than they already are in the lockAmulet helper.

I think the complete withdrawal branch of this choice actually ends up equivalent to (and probably with a shared implementation with) the Expire choice once the holding has the shorter deadline, anyways; I don't see a reason to disturb it if it's directly usable.

meiersi-da · 2026-08-24T07:44:29Z

+calculateAvailableWithdrawAmount : Decimal -> Time -> VestingLock -> Optional Decimal -- None indicates the _full_ amount is available
+calculateAvailableWithdrawAmount currentAmount currentTime VestingLock{ .. }
+    | currentTime > (startTime `addRelTime` unlockPeriod) = None
+    | otherwise = Some $ initialAmount * fractionElapsed - (initialAmount - currentAmount)
+  where
+    fractionElapsed = (currentTime `subTime` startTime) `divRelTime` unlockPeriod
+    divRelTime = \a b -> (intToDecimal $ convertRelTimeToMicroseconds a) `div` (intToDecimal $ convertRelTimeToMicroseconds b)


You didn't do that yet though, did you?

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

meiersi-da · 2026-08-25T05:49:09Z

+      subject : GovernanceLockSubject
+  deriving (Eq, Show, Serializable)
+
+-- FIXME: move the choices of this factory into `ExternalPartyAmuletRules` once we're happy with them


let's do this as part of polishing this PR

meiersi-da · 2026-08-25T06:04:15Z

+      controller actors
+      do
+        checkActors actors [[owner]] -- ^ TODO: custom controllers
+        currentAmount <- fetchAmount (ForOwner with dso; owner) holding


do we still need this if we structure the code such that a vesting lock stores the amount that is still vesting?

OK, saw below that you plan to change the structure of the vesting lock repr. I'll skip reviewing the body of this choice.

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

…e to make it allowed. Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored added 2 commits August 20, 2026 19:22

Custom templates for governance locks, first cut of update.

3de83f8

Comments and wording tweaks.

6d9e32c

jonored had a problem deploying to ci-forks August 20, 2026 20:16 — with GitHub Actions Error

canton-network-da assigned isegall-da, martinflorian-da, rautenrieth-da and ray-roestenburg-da Aug 20, 2026

dbzguy56 mentioned this pull request Aug 20, 2026

Cip 0105 basic sv locks #6815

Draft

8 tasks

meiersi-da reviewed Aug 21, 2026

View reviewed changes

Update daml/splice-amulet/daml/Splice/GovernanceLocks.daml

fb68cac

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonored@gmail.com>

jonored had a problem deploying to ci-forks August 21, 2026 14:55 — with GitHub Actions Error

Update daml/splice-amulet/daml/Splice/GovernanceLocks.daml

7e714ee

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonored@gmail.com>

jonored had a problem deploying to ci-forks August 21, 2026 14:55 — with GitHub Actions Error

Update daml/splice-amulet/daml/Splice/GovernanceLocks.daml

3d178d8

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonored@gmail.com>

jonored had a problem deploying to ci-forks August 21, 2026 14:55 — with GitHub Actions Error

jonored had a problem deploying to ci-forks August 21, 2026 21:11 — with GitHub Actions Error

cgibbard reviewed Aug 21, 2026

View reviewed changes

Comment thread daml/splice-amulet-test/daml/Splice/Scripts/TestGovernanceLocks.daml Outdated

jonored added 2 commits August 22, 2026 00:38

Happy path test, basic test fixtures for direct contract choices

b0c5e9f

And one fix for a non-nonconsuming choice.

jonored force-pushed the cip-0105-custom-templates branch from ea6c7be to d584c7c Compare August 22, 2026 00:42

jonored had a problem deploying to ci-forks August 22, 2026 00:42 — with GitHub Actions Error

meiersi-da reviewed Aug 24, 2026

View reviewed changes

jonored had a problem deploying to ci-forks August 24, 2026 16:27 — with GitHub Actions Error

jonored force-pushed the cip-0105-custom-templates branch from 34e743d to a04de0a Compare August 24, 2026 17:06

jonored had a problem deploying to ci-forks August 24, 2026 17:06 — with GitHub Actions Error

Apply suggestions from code review

1514a92

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored force-pushed the cip-0105-custom-templates branch from a04de0a to 1514a92 Compare August 24, 2026 17:18

jonored had a problem deploying to ci-forks August 24, 2026 17:18 — with GitHub Actions Error

jonored added 2 commits August 24, 2026 17:28

Add comments about the arithmetic

b61dafd

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

Tidiness updates to the test script.

c65305a

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored had a problem deploying to ci-forks August 24, 2026 18:12 — with GitHub Actions Error

Simplify vesting withdraw

8e2cd62

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored had a problem deploying to ci-forks August 24, 2026 22:56 — with GitHub Actions Error

Remove redundant check on start time.

ba991f8

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored had a problem deploying to ci-forks August 24, 2026 23:09 — with GitHub Actions Error

meiersi-da reviewed Aug 25, 2026

View reviewed changes

jonored had a problem deploying to ci-forks August 25, 2026 10:20 — with GitHub Actions Error

Apply suggestions from code review

1d29830

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored force-pushed the cip-0105-custom-templates branch from 7f4655f to 1d29830 Compare August 25, 2026 11:08

jonored had a problem deploying to ci-forks August 25, 2026 11:08 — with GitHub Actions Error

jonored had a problem deploying to ci-forks August 25, 2026 11:10 — with GitHub Actions Error

Apply suggestions from code review

59b4db2

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored force-pushed the cip-0105-custom-templates branch from 0f26d35 to 59b4db2 Compare August 25, 2026 12:21

jonored had a problem deploying to ci-forks August 25, 2026 12:21 — with GitHub Actions Error

jonored added 2 commits August 25, 2026 13:56

Move governance lock creation to ExternalPartyAmuletRules.

55aea8b

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

Map "unlockAmount = Some amount" case to the "unlock full amount" cas…

8ed7acc

…e to make it allowed. Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored had a problem deploying to ci-forks August 25, 2026 13:57 — with GitHub Actions Error

Ensure clauses

84c8450

Signed-off-by: Jonathan D.K. Gibbons <jonathan.gibbons@obsidian.systems>

jonored requested a deployment to ci-forks August 25, 2026 14:42 — with GitHub Actions Waiting

jonored mentioned this pull request Aug 26, 2026

Initial governance locks implementation canton-network/splice-sv-fa-locking#1

Open

8 tasks

	amulet_transferFactoryV1_transferImpl
	: ExternalPartyAmuletRules
	-> [Party]
	-> Api.Token.TransferInstructionV1.TransferFactory_Transfer
	-> Update Api.Token.TransferInstructionV1.TransferInstructionResult
	amulet_transferFactoryV1_transferImpl this actors arg = do

	listHoldings,
	listVisibleHoldings,
	listHoldingCids,
	listLockedHoldings,
	listUnlockedHoldingCidsFor,

Uh oh!

Conversation

jonored commented Aug 20, 2026

Pull Request Checklist

Cluster Testing

PR Guidelines

Merge Guidelines

Uh oh!

meiersi-da left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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!

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!

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!

Choose a reason for hiding this comment

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