Skip to content

L-13: Fold admin garbage collection into the expiry choices and add an admin unlock of expired locks - #118

Open
haseebrabbani wants to merge 3 commits into
mainfrom
audit-m1-02-l13
Open

haseebrabbani wants to merge 3 commits into
mainfrom
audit-m1-02-l13

Conversation

@haseebrabbani

@haseebrabbani haseebrabbani commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #97 (L-13).

Problem: *_AdminGC could archive a pending contract while its funding was still locked; on a provider account only owner + provider could then recover it.

Fix

  • Admin expiry reads Splice's expire-lock from extraArgs.context: missing/AV_Bool True releases; AV_Bool False skips the funding after lockExpiresAt, emits nothing, returns TransferInstructionResult_Failed / AllocationResult_Cancelled; any other value fails.
  • TokenTransferInstruction_Expire takes extraArgs; TokenRules_ExpireTransferInstructions takes expireArgs : [(cid, TokenTransferInstruction_Expire)], mirroring cancelArgs.
  • allocationCancelImpl reads the flag only when actors are exactly {admin} (not via actors == executors): read when the admin is the only executor, ignored for executors.
  • New TokenHolding_AdminUnlock (holdingAdminUnlockImpl) and MyHolding_AdminUnlock (freeze check): admin-only, expired locks only, same account, own event reason.
  • Removed *_AdminGC, transferGcImpl, allocationGcImpl. Docs: choices, both READMEs, integration guide, CHANGELOG.

Breaking: removed choices and changed choice args in openzeppelin-token-cip112-v1 (unreleased).

Notes

…n admin unlock of expired locks

- Admin expiries read Splice's `expire-lock` choice-context flag. Missing or
  `AV_Bool True` releases the funding; `AV_Bool False` skips it once
  `lockExpiresAt` has passed and returns the standard failed or cancelled
  result.
- `TokenTransferInstruction_Expire` takes `extraArgs`, and
  `TokenRules_ExpireTransferInstructions` takes one expire argument per
  instruction. `allocationCancelImpl` reads the flag only when the actors are
  exactly the admin, including when the admin is the only executor.
- Remove the `AdminGC` choices and `transferGcImpl` / `allocationGcImpl`.
- Add `TokenHolding_AdminUnlock` (`holdingAdminUnlockImpl`) and
  `MyHolding_AdminUnlock`, which recover an expired lock without the provider.
- Document the flag ordering in the choices, both package READMEs, the
  integration guide and the CHANGELOG; replace the GC tests.

Closes #97
Comment on lines +136 to +145
it with `TokenHolding_AdminUnlock`, without the account's provider. For allocations,
the flag is read whenever the actors are exactly `[admin]`, including when
the admin is the allocation's only executor, and ignored for executors, so
an executor cancel always releases the funding. The test scripts
`testLockGraceAndOwnerUnlock`, `testAllocationExpiryWithFlagCleared`, and
`testAdminUnlockRepairsEarlyClearedFlag` cover these paths.

Authorization: the admin alone expires, clears flags, and runs the admin
unlock; the executors cancel an allocation at any time, always releasing its
funding.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph says an executor cancel always releases the funding. That is wrong when the admin is the allocation's only executor. Its cancel is a cancel by [admin], so it reads the flag, and AV_Bool False ends the allocation without releasing anything.

The Authorization line repeats the claim, and the list of test scripts adds nothing for the reader. Shorter version:

Suggested change
it with `TokenHolding_AdminUnlock`, without the account's provider. For allocations,
the flag is read whenever the actors are exactly `[admin]`, including when
the admin is the allocation's only executor, and ignored for executors, so
an executor cancel always releases the funding. The test scripts
`testLockGraceAndOwnerUnlock`, `testAllocationExpiryWithFlagCleared`, and
`testAdminUnlockRepairsEarlyClearedFlag` cover these paths.
Authorization: the admin alone expires, clears flags, and runs the admin
unlock; the executors cancel an allocation at any time, always releasing its
funding.
it with `TokenHolding_AdminUnlock`, without the account's provider. For
allocations, the flag is read only when the actors are exactly `[admin]`,
including when the admin is the allocation's only executor. A cancel by any
other actor set releases the funding.
Authorization: the admin alone expires, clears flags, and runs the admin
unlock; the executors cancel an allocation at any time.

Comment on lines +280 to +281
-- | An expiry with the `expire-lock` flag cleared waits until the funding
-- lock has expired, so the sender can always recover the funds first.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"So the sender can always recover the funds first" is not what this guard gives. Owner unlock and a cleared-flag expiry both become possible at lockExpiresAt, and on an account with a provider the sender cannot unlock alone. This is the single-party claim that #97 asks to correct.

Suggested change
-- | An expiry with the `expire-lock` flag cleared waits until the funding
-- lock has expired, so the sender can always recover the funds first.
-- | An expiry with the `expire-lock` flag cleared fails while the funding
-- lock is live.

Comment on lines +131 to +134
The ledger cannot check that the funding is gone, so the automation must
look before it clears a flag. The flag covers every locked holding of the
contract, and an allocation locks one holding per instrument, so the
automation checks each of them. A flag cleared while a holding is still

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph does not cover an allocation whose owner reclaimed only some of its locked holdings. The default expiry fails on the archived holding, and the rule here says not to clear the flag while another holding is still locked. That leaves the automation with no allowed step.

Add one sentence after "checks each of them.":

If the owner reclaimed only some of them, the admin returns the rest with
`TokenHolding_AdminUnlock` and then clears the flag.

Comment on lines +118 to +120
per allocation and `actors = [admin]`. Each argument carries its own
`extraArgs`, whose choice context may hold Splice's `expire-lock` flag, so
automation written for Amulet builds the same batches:

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automation written for Amulet does not build these batches. TokenRules_ExpireTransferInstructions and TokenRules_ExpireAllocations are this package's own choices. Only the flag is shared with Splice, and the sentence already says so. Drop the clause:

Suggested change
per allocation and `actors = [admin]`. Each argument carries its own
`extraArgs`, whose choice context may hold Splice's `expire-lock` flag, so
automation written for Amulet builds the same batches:
per allocation and `actors = [admin]`. Each argument carries its own
`extraArgs`, whose choice context may hold the `expire-lock` flag (this key
has the same function as in Splice):

Comment on lines +287 to +288
mustFailWith "strictly before deadline 'lockExpiresAt'" (actAs admin)
(expireInstructionCmd instrCid (expireLockArgs False))

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No v1 test passes a cleared flag through TokenRules_ExpireTransferInstructions. If the batch dropped each instruction's extraArgs, the suite would still pass.

Sending this expiry through the batch closes the gap. It fails with this message only if the flag reaches TokenTransferInstruction_Expire:

  mustFailWith "strictly before deadline 'lockExpiresAt'" (actAs admin) do
    exerciseCmd rulesCid TokenRules_ExpireTransferInstructions with
      expireArgs = [(fromInterfaceContractId @TokenTransferInstruction instrCid, TokenTransferInstruction_Expire with extraArgs = expireLockArgs False)]
      observers = []

Comment on lines +173 to +179
funding, so a default expiry of a contract still on the ledger releases
it. A `lockGrace` too short for the admin's
expiry automation to act in lets the account parties unlock or spend the
funding first, and the contract then ends only through an expiry with the
`expire-lock` flag cleared. Size `lockGrace` to the automation's reaction
time (minutes to hours), and size `maxTTL` to the longest workflow the
registry accepts.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"A default expiry of a contract still on the ledger" is hard to follow. The README never defines "default expiry", and a contract that is being expired is always still on the ledger. Line 174 also breaks in the middle of a sentence.

Suggested change
funding, so a default expiry of a contract still on the ledger releases
it. A `lockGrace` too short for the admin's
expiry automation to act in lets the account parties unlock or spend the
funding first, and the contract then ends only through an expiry with the
`expire-lock` flag cleared. Size `lockGrace` to the automation's reaction
time (minutes to hours), and size `maxTTL` to the longest workflow the
registry accepts.
funding, so an expiry that does not clear the `expire-lock` flag releases
it. A `lockGrace` too short for the admin's expiry automation to act in
lets the account parties unlock or spend the funding first, and the
contract then ends only through an expiry with the flag cleared. Size
`lockGrace` to the automation's reaction time (minutes to hours), and size
`maxTTL` to the longest workflow the registry accepts.

Comment on lines +38 to +43
- `expireLockFromContext`: how `transferExpireImpl` and `allocationCancelImpl`
read Splice's `expire-lock` flag from the choice context. A missing flag, or
`AV_Bool True`, releases the funding; `AV_Bool False` skips it once
`lockExpiresAt` has passed. `allocationCancelImpl` reads it only when the
actors are exactly the admin, including when the admin is the only
executor.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This item restates the doc comment of allocationCancelImpl. Its copy also reads as if a cleared flag releases the funding before lockExpiresAt, where the expiry fails. It should also be rephrased as an instruction.

Suggested change
- `expireLockFromContext`: how `transferExpireImpl` and `allocationCancelImpl`
read Splice's `expire-lock` flag from the choice context. A missing flag, or
`AV_Bool True`, releases the funding; `AV_Bool False` skips it once
`lockExpiresAt` has passed. `allocationCancelImpl` reads it only when the
actors are exactly the admin, including when the admin is the only
executor.
- `expireLockFromContext`: reads Splice's `expire-lock` flag from the choice
context for `transferExpireImpl` and `allocationCancelImpl`. Set it to
`AV_Bool False` only for a contract whose locked holdings are archived.
A flag cleared earlier leaves them locked until the admin unlock returns
them.

Comment on lines +34 to +38
-- the admin is the only executor. It reads the `expire-lock` flag from
-- `extraArgs.context`: missing or set releases the funding, and
-- `AV_Bool False` skips it once `lockExpiresAt` has passed. Clear the
-- flag only after finding the locked holdings no longer active:
-- `TokenHolding_AdminUnlock` repairs a flag cleared too early.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

allocationCancelImpl already documents the flag values, and the rule about when to clear the flag is in the README.md caveats. This comment only needs to say what an admin expiry is:

Suggested change
-- the admin is the only executor. It reads the `expire-lock` flag from
-- `extraArgs.context`: missing or set releases the funding, and
-- `AV_Bool False` skips it once `lockExpiresAt` has passed. Clear the
-- flag only after finding the locked holdings no longer active:
-- `TokenHolding_AdminUnlock` repairs a flag cleared too early.
-- the admin is the only executor. It reads the `expire-lock` flag as
-- `allocationCancelImpl` describes.

expireLockArgs : Bool -> ExtraArgs
expireLockArgs = expireLockEntry . AV_Bool

-- | An admin expiry of a transfer instruction, with the given `ExtraArgs`.

@0xNeshi 0xNeshi Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These three doc comments (here, line 70 and line 77) only repeat the helper's name and signature. Delete them.

Comment on lines +167 to +168
-- automation written for Amulet works unchanged.
expireLockKey : Text

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
-- automation written for Amulet works unchanged.
expireLockKey : Text
-- automation written for Amulet works unchanged.
--
-- https://github.com/canton-network/splice/blob/8460154135f39019b8bb370c9c1321ff13c9bb10/daml/splice-amulet/daml/Splice/Amulet/TokenApiUtils.daml#L180-L181
expireLockKey : Text

Comment on lines +171 to +182
-- | Read the `expire-lock` flag of an admin expiry. A missing entry or
-- `AV_Bool True` releases the funding. `AV_Bool False` clears the flag: the
-- expiry skips the funding, which it allows only once the funding lock has
-- expired. Any other value fails. A mistyped key reads as missing, so the
-- expiry releases, which fails loudly when the funding is already gone.
--
-- Clear the flag only after finding the locked holdings no longer active.
-- The ledger cannot check this, because fetching an archived holding aborts.
-- A flag cleared while the funding is still locked ends the pending contract
-- and leaves the holding locked; the holding template's admin unlock
-- (`holdingAdminUnlockImpl`) returns it.
expireLockFromContext : ChoiceContext -> Update Bool

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment is verbose. Doc comments should state what the function/choice itself does and potential security caveats, not what the surrounding code should do unrelated to the function/choice.

The "Clear the flag only after finding the locked..." note is important, but out of place on this function. It should be placed in utils README.md.

Suggested change
-- | Read the `expire-lock` flag of an admin expiry. A missing entry or
-- `AV_Bool True` releases the funding. `AV_Bool False` clears the flag: the
-- expiry skips the funding, which it allows only once the funding lock has
-- expired. Any other value fails. A mistyped key reads as missing, so the
-- expiry releases, which fails loudly when the funding is already gone.
--
-- Clear the flag only after finding the locked holdings no longer active.
-- The ledger cannot check this, because fetching an archived holding aborts.
-- A flag cleared while the funding is still locked ends the pending contract
-- and leaves the holding locked; the holding template's admin unlock
-- (`holdingAdminUnlockImpl`) returns it.
expireLockFromContext : ChoiceContext -> Update Bool
-- | Reads the `expire-lock` flag from the choice context of an admin expiry.
-- A missing entry reads as `True`. On `True` the expiry returns the locked
-- holdings to their account, and on `False` it ends the contract without
-- touching them. This function does not check the time, so a caller acting
-- on `False` must first check that the funding lock has expired.
expireLockFromContext : ChoiceContext -> Update Bool

Comment on lines 142 to 156
-- | `allocation_cancelImpl`. Executors may cancel any time; the admin only
-- once `expiresAt` has passed (checked by the vendored default, which reads
-- the interface value of the contract being exercised).
--
-- A cancel whose actors are exactly the admin is an admin expiry, and reads
-- the `expire-lock` flag from `arg.extraArgs.context` (see
-- `expireLockFromContext`). Missing or set, the funding is released.
-- Cleared, it is skipped once `lockExpiresAt` has passed, and the result
-- carries no holdings. The flag is read also when the admin is the
-- allocation's only executor. The vendored default then treats the cancel as
-- an executor cancel and checks no expiry, so the `lockExpiresAt` check is
-- the only time guard. For every other actor set the flag is ignored and the
-- funding is released, so executors cannot end an allocation without
-- releasing its funding.
allocationCancelImpl

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment gets two things wrong.

First, it says the lockExpiresAt check guards every cancel by the admin. It only guards the AV_Bool False path. If the admin is the allocation's only executor, the vendored default checks no expiry, so the admin can cancel at any time.

Second, it says executors cannot end an allocation without releasing its funding. An admin that is the only executor can, by passing AV_Bool False.

Here is a shorter version that keeps only what the vendored default hides:

Suggested change
-- | `allocation_cancelImpl`. Executors may cancel any time; the admin only
-- once `expiresAt` has passed (checked by the vendored default, which reads
-- the interface value of the contract being exercised).
--
-- A cancel whose actors are exactly the admin is an admin expiry, and reads
-- the `expire-lock` flag from `arg.extraArgs.context` (see
-- `expireLockFromContext`). Missing or set, the funding is released.
-- Cleared, it is skipped once `lockExpiresAt` has passed, and the result
-- carries no holdings. The flag is read also when the admin is the
-- allocation's only executor. The vendored default then treats the cancel as
-- an executor cancel and checks no expiry, so the `lockExpiresAt` check is
-- the only time guard. For every other actor set the flag is ignored and the
-- funding is released, so executors cannot end an allocation without
-- releasing its funding.
allocationCancelImpl
-- | `allocation_cancelImpl`. Executors may cancel at any time, and the admin
-- once `expiresAt` has passed. The vendored default checks both.
--
-- A cancel by exactly the admin reads the `expire-lock` flag. On `False` it
-- ends the allocation without touching its locked holdings, and only once
-- `lockExpiresAt` has passed. Every other actor set releases the holdings,
-- so executors other than the admin cannot end an allocation without
-- releasing its funding. When the admin is the only executor, the vendored
-- default treats its cancel as an executor cancel and checks no expiry.
allocationCancelImpl

Comment on lines +115 to +121
-- | Body of a consuming admin-expiry choice, once the storage bound has
-- passed. It reads the `expire-lock` flag from `extraArgs.context` (see
-- `expireLockFromContext`). Missing or set, the locked funds return to the
-- sender. Cleared, the funding is skipped: this needs `lockExpiresAt` to
-- have passed too, and it creates nothing and emits no event, since the
-- funding's owner already logged its end. Either way the instruction ends
-- with `TransferInstructionResult_Failed`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment repeats what expireLockFromContext documents and gives a wrong reason for the missing event. Shorter version that says only what this body does:

Suggested change
-- | Body of a consuming admin-expiry choice, once the storage bound has
-- passed. It reads the `expire-lock` flag from `extraArgs.context` (see
-- `expireLockFromContext`). Missing or set, the locked funds return to the
-- sender. Cleared, the funding is skipped: this needs `lockExpiresAt` to
-- have passed too, and it creates nothing and emits no event, since the
-- funding's owner already logged its end. Either way the instruction ends
-- with `TransferInstructionResult_Failed`.
-- | Body of a consuming admin-expiry choice. It fails before `expiresAt`,
-- then reads the `expire-lock` flag. On `True` it returns the locked funds
-- to the sender. On `False` it ends the instruction without touching them,
-- and only once `lockExpiresAt` has passed. Both end with
-- `TransferInstructionResult_Failed`.

Comment on lines +132 to +138
-- | Body of a consuming admin-unlock choice on a holding template, controlled
-- by the admin alone: as `holdingOwnerUnlockImpl`, with its own event reason.
-- It returns funding that an expiry with the `expire-lock` flag cleared left
-- locked, without the account parties, so an account with a distinct
-- provider recovers without it. It moves no value: the holding returns
-- unlocked to the same account, and only once its lock has expired, when
-- `consumeUnlockedHolding` already accepts it as funding.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The middle sentence explains why the admin unlock exists, which the README.md covers. The comment only needs what the body does and why it is safe:

Suggested change
-- | Body of a consuming admin-unlock choice on a holding template, controlled
-- by the admin alone: as `holdingOwnerUnlockImpl`, with its own event reason.
-- It returns funding that an expiry with the `expire-lock` flag cleared left
-- locked, without the account parties, so an account with a distinct
-- provider recovers without it. It moves no value: the holding returns
-- unlocked to the same account, and only once its lock has expired, when
-- `consumeUnlockedHolding` already accepts it as funding.
-- | Body of a consuming admin-unlock choice on a holding template, controlled
-- by the admin alone. It does what `holdingOwnerUnlockImpl` does, with its
-- own event reason. It moves no value: the holding returns unlocked to the
-- same account, and only once its lock has expired.

Comment on lines +46 to +48
-- the cancel implementation. Each `Allocation_Cancel` carries its own
-- `extraArgs`, so each allocation has its own `expire-lock` flag (see
-- `allocationCancelImpl`).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The added sentence restates the argument type. This function does not read the flag. Drop it:

Suggested change
-- the cancel implementation. Each `Allocation_Cancel` carries its own
-- `extraArgs`, so each allocation has its own `expire-lock` flag (see
-- `allocationCancelImpl`).
-- the cancel implementation.

Comment on lines +42 to +45
-- the funding is skipped instead, which needs `lockExpiresAt` to have
-- passed too. Clear the flag only after finding the locked holdings no
-- longer active: `TokenHolding_AdminUnlock` repairs a flag cleared too
-- early.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rule about when to clear the flag is for the admin's automation, and the README.md caveats and integration-guide.md already state it. The choice comment only needs the consequence:

Suggested change
-- the funding is skipped instead, which needs `lockExpiresAt` to have
-- passed too. Clear the flag only after finding the locked holdings no
-- longer active: `TokenHolding_AdminUnlock` repairs a flag cleared too
-- early.
-- the expiry leaves them untouched and fails before `lockExpiresAt`.
-- Funds still locked then stay locked until `TokenHolding_AdminUnlock`.

#97 asks for this rule on the expiry choices. I think it belongs only in the README.md caveats and integration-guide.md, where the admin's automation is described, so this departs from the issue on purpose.

Comment on lines +67 to +71
-- has `actors = [admin]` and carries its own `expire-lock` flag, which
-- is read even when the admin is the allocation's only executor. Clear
-- a flag only after finding that allocation's locked holdings no
-- longer active: `TokenHolding_AdminUnlock` repairs one cleared too
-- early.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This choice only passes each cancel argument through. The flag rules are documented on allocationCancelImpl and in the README.md:

Suggested change
-- has `actors = [admin]` and carries its own `expire-lock` flag, which
-- is read even when the admin is the allocation's only executor. Clear
-- a flag only after finding that allocation's locked holdings no
-- longer active: `TokenHolding_AdminUnlock` repairs one cleared too
-- early.
-- has `actors = [admin]` and carries its own `expire-lock` flag.

#97 asks for this rule on the expiry choices. I think it belongs only in the README.md caveats and integration-guide.md, where the admin's automation is described, so this departs from the issue on purpose.

Comment on lines +189 to +191
path that does not need the provider: the admin alone returns the holding,
unlocked, to its account, which moves no value, since an expired lock no
longer keeps the account parties from spending it.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rest of the sentence repeats the TokenHolding_AdminUnlock comment. End it here:

Suggested change
path that does not need the provider: the admin alone returns the holding,
unlocked, to its account, which moves no value, since an expired lock no
longer keeps the account parties from spending it.
path that does not need the provider.

Comment on lines +35 to +37
template exposes both. The admin unlock is how funding left locked by an
expiry with the `expire-lock` flag cleared returns to its account without
the account's provider.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The expireLockFromContext item below already says the admin unlock returns holdings that a cleared flag left locked. Drop the last sentence:

Suggested change
template exposes both. The admin unlock is how funding left locked by an
expiry with the `expire-lock` flag cleared returns to its account without
the account's provider.
template exposes both.

Comment on lines +127 to +129
nothing, and it fails before `lockExpiresAt`. Use it only for a contract
whose locked holdings the automation has found no longer active, after the
owner unlocked or spent them once the lock expired.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The next paragraph already tells the automation to check the holdings first. The bullet only needs to say when the value applies:

Suggested change
nothing, and it fails before `lockExpiresAt`. Use it only for a contract
whose locked holdings the automation has found no longer active, after the
owner unlocked or spent them once the lock expired.
nothing, and it fails before `lockExpiresAt`. Use it only for a contract
whose funding the owner already unlocked or spent.

Comment thread CHANGELOG.md Outdated
Comment on lines +67 to +71
the types and utils packages with holdings with expiring locks that the
owner or the admin alone recovers, admin expiry of transfer instructions
and allocations that releases their funding or, with Splice's `expire-lock`
flag cleared, skips funding already reclaimed and returns the standard
result, one-step and two-step transfers, allocations with exact-cover

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The added clause is a full description inside a feature list, which makes the sentence hard to read. Name the feature and leave the details to the README.md:

Suggested change
the types and utils packages with holdings with expiring locks that the
owner or the admin alone recovers, admin expiry of transfer instructions
and allocations that releases their funding or, with Splice's `expire-lock`
flag cleared, skips funding already reclaimed and returns the standard
result, one-step and two-step transfers, allocations with exact-cover
the types and utils packages with holdings with expiring locks that the
account parties or the admin alone unlock, admin expiry of transfer
instructions and allocations under Splice's `expire-lock` flag, one-step
and two-step transfers, allocations with exact-cover

Comment on lines +688 to +691
-- After the grace window the owner recovers the funding. On this
-- single-party account the owner's parties suffice. An account with a
-- distinct provider needs the provider too, or the admin unlock
-- (`testAdminUnlockRepairsEarlyClearedFlag`).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two lines say the same thing, and the comment does not need to name another test:

Suggested change
-- After the grace window the owner recovers the funding. On this
-- single-party account the owner's parties suffice. An account with a
-- distinct provider needs the provider too, or the admin unlock
-- (`testAdminUnlockRepairsEarlyClearedFlag`).
-- After the grace window the owner recovers the funding. An account with
-- a distinct provider needs the provider too, or the admin unlock.

…flag

- Route the cleared-flag guard test through
  `TokenRules_ExpireTransferInstructions`, so the suite fails if the batch
  drops an instruction's `extraArgs`.
- Correct the claims that an executor cancel always releases the funding
  (not when the admin is the only executor), that the sender can always
  recover first, and that Amulet automation builds these batches.
- Document the partly reclaimed allocation: the admin unlocks the rest,
  then clears the flag.
- Keep the clear-flag rule in the READMEs and the integration guide only;
  trim the choice and function comments to what each body does.
- Link Splice's `expire-lock` key at release 0.8.3.
@haseebrabbani

Copy link
Copy Markdown
Collaborator Author

@0xNeshi feedback addressed in c11f825.

  1. Guard test now goes through TokenRules_ExpireTransferInstructions; checked that it fails if the batch drops extraArgs.
  2. Applied the doc and comment suggestions, plus the partial-reclaim sentence.
  3. expireLockKey: kept the link, dropped "works unchanged": Amulet's expiry takes expireLock as a choice argument (AmuletAllocation_DsoExpire), not through the context.
  4. A holding left locked after a cleared-flag expiry has an expired lock, which consumeUnlockedHolding already accepts, so it says "spend or unlock" instead of "stays locked until TokenHolding_AdminUnlock".
  5. Guide bullet now says "whose funding is already unlocked or spent", so it no longer contradicts the admin-unlock step for a partial reclaim.
  6. The clear-flag rule is only in the READMEs and the integration guide, not on the choices, which departs from [M1: Audit 2: L-13]: Fold admin garbage collection into the expiry choices and give the admin an expired-lock unlock on holdings #97 as you suggested.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[M1: Audit 2: L-13]: Fold admin garbage collection into the expiry choices and give the admin an expired-lock unlock on holdings

2 participants