Tranfr — Programmable Recovery for CKB

Second boundary: ordinary owner spending must commit the exact effect before expiry

The remaining owner-side boundary is ordinary spending.

The proposal currently requires all three of the following:

  1. while active, the owner retains normal spending authority;
  2. an ordinary spend does not reset the inactivity timer;
  3. after expiry, the owner path is irreversibly frozen.

Those requirements are consistent only if an ordinary spend is no longer a single-step owner-signature path. A transaction signed before D but committed after D cannot be treated as timely, and since cannot provide an upper-validity bound.

The safe construction is to separate owner authorization from value release:

ACTIVE
  -> owner-signed BEGIN_SPEND
       -> PENDING_SPEND
            -> SETTLE_SPEND   if begin_epoch < old_deadline
            -> RECOVER        if begin_epoch >= old_deadline

BEGIN_SPEND does not transfer protected value to the intended recipient. It only places the exact intended spend effect on-chain.

Pending state

For a minimal v1 transfer profile, the pending state should contain the previous policy together with a complete, canonical spend plan:

PendingSpend {
    version

    previous_state_hash
    previous_deadline_epoch
    inactivity_period_epochs

    owner_lock_hash
    recovery_lock_hash
    state_nonce

    spend_plan_hash
    protected_value_commitment
}

SpendPlan {
    domain_separator          // TRANFR_SPEND_V1
    source_state_hash
    source_state_nonce

    ordered_outputs           // full CellOutput + outputs_data
    residual_output_index     // optional
    exact_fee_capacity
}

The full SpendPlan must remain available from the pending state itself, or from an immutable Cell whose outpoint and data hash are committed by PENDING_SPEND. Storing only a hash is not sufficient: if the owner disappears after BEGIN_SPEND, the recovery recipient or another executor must still be able to reconstruct and settle the authorized effect without obtaining an off-chain preimage from the owner.

The output commitment must cover the complete serialized output objects:

capacity
lock script
type script
output data
ordering

Committing only to a recipient and amount would leave room to substitute type state, change data, alter residual ownership, or move value through an uncommitted output.

BEGIN_SPEND rules

BEGIN_SPEND must enforce:

owner signature is valid

exactly one PENDING_SPEND successor exists

previous policy is copied exactly
previous deadline is copied exactly
state identity and nonce are bound

all protected capacity and typed value remain inside the pending state
no protected value is released in BEGIN_SPEND

the complete SpendPlan is canonical and available on-chain
spend_plan_hash matches the canonical plan bytes

the plan is satisfiable from the protected input
the fee is exact, not open-ended
any residual output preserves the Tranfr policy and old deadline

no heartbeat effect occurs
no recipient update occurs
no deadline extension occurs

For v1, the safest transfer profile is deliberately narrow:

one pending Tranfr input
no mutable external input dependency
no uncommitted output
no arbitrary callback
fee funded from the committed plan
exact output set

This gives the second phase a deterministic result that any party can submit.

Commitment-bound time decision

When PENDING_SPEND is consumed, the lock loads the header associated with that exact input Cell:

ckb_load_header(..., input_index, CKB_SOURCE_INPUT)

Then:

begin_epoch = epoch of the block that committed PENDING_SPEND
timely      = epoch_less(begin_epoch, previous_deadline_epoch)

As in the heartbeat/update path, the comparison must use CKB epoch-number-with-fraction semantics.

The signature time and broadcast time are irrelevant. The only deciding fact is when the pending state entered the canonical chain.

Timely spend

If:

begin_epoch < old_deadline

the owner committed the spend while authority still existed.

The second transaction may therefore execute only the exact committed plan:

SETTLE_SPEND:
    spend_plan_hash matches
    outputs match ordered_outputs exactly
    outputs_data match exactly
    protected value allocation matches exactly
    transaction fee equals exact_fee_capacity
    no additional protected route is introduced

The second phase should not require another owner signature. The owner already authorized the exact effect in BEGIN_SPEND. Making settlement permissionless prevents the protected value from becoming stuck if the owner disappears immediately after committing the pending state.

This does not preserve discretionary owner authority after expiry. It preserves only one already-fixed transition.

Any residual Tranfr output must carry:

same owner
same recovery recipient
same inactivity period
same old deadline
next state nonce

An ordinary spend therefore does not reset activity. If settlement occurs after the old deadline, the residual state is already recovery-eligible.

Late spend

If:

begin_epoch >= old_deadline

the spend plan has no effect.

The late pending state must not be able to:

release value
change a recipient
reduce the recoverable amount
change the recovery lock
extend the deadline
create a new owner-controlled residual

Only recovery under the previous policy is valid:

recovery signer = previous_recovery_lock
input since      = absolute epoch equal to old_deadline
recovered value  = the complete protected value

A transaction signed before D but kept offline and committed after D therefore cannot reserve a spend.

Recovery from a timely pending spend

A timely PENDING_SPEND must not expose a competing branch that allows the recovery recipient to ignore the committed outputs and redirect the full value.

The deterministic rule is:

timely pending spend
    -> exact committed spend must settle first
    -> only the residual remains under the old recovery policy

Because settlement is permissionless and the full plan is available on-chain, the recovery recipient can settle the plan themselves and then recover any residual whose old deadline has already passed.

This removes destination ambiguity:

before D:
    owner may commit one exact spend effect

after D:
    nobody may replace that effect with a different one

Scope boundary for Fiber and DeFi

A deterministic CKB transfer and an arbitrary Fiber or DeFi interaction are not the same transaction class.

A general application interaction may depend on:

other live Cells
changing liquidity
slippage bounds
counterparty inputs
callbacks
application-specific state transitions
mutable route composition

Those effects cannot safely be represented by an unconstrained generic SPEND flag.

For the POC, I would define ordinary spending as a canonical deterministic transfer profile. Broader Fiber/DeFi support should use a separate, integration-specific action commitment layer—potentially compatible with CoBuild-style action messages—where every integration defines exactly which fields may vary and which final invariants must remain fixed.

Until that layer exists, unsupported composable routes should fail closed rather than silently inherit ordinary owner authority.

Minimum blocking tests

TEST 01
BEGIN_SPEND committed before D
SETTLE_SPEND committed before D
-> exact outputs are accepted
-> residual keeps old deadline

TEST 02
BEGIN_SPEND committed before D
SETTLE_SPEND committed after D
-> exact committed outputs are still accepted
-> residual is immediately recovery-eligible
-> deadline is not reset

TEST 03
BEGIN_SPEND signed before D but committed after D
-> spend plan has no effect
-> full protected value remains recoverable

TEST 04
recipient, capacity, type script, lock script, output data, or output order is changed
-> settlement fails

TEST 05
fee differs from the committed fee
-> settlement fails

TEST 06
an extra protected output, input, callback, or uncommitted route is introduced
-> settlement fails

TEST 07
owner disappears after BEGIN_SPEND
-> a third party can settle the exact on-chain plan without an owner signature

TEST 08
recovery attempts to bypass a timely spend plan and take the full value
-> recovery fails
-> committed spend must settle first

TEST 09
residual state changes recovery policy or derives a new deadline
-> settlement fails

TEST 10
the same SpendPlan is replayed against a later Tranfr state
-> source_state_hash / state_nonce binding fails

The core invariant is:

Before expiry, the owner may commit an exact value transition. After expiry, the owner retains no open-ended authority to choose or modify a transaction.

And the recovery invariant is:

Recovery may claim the residual value, but it may not overwrite an exact spend effect that entered the canonical chain before expiry.

This should be fixed in the protocol model before ordinary spending is treated as a transparent owner operation in the lock script or SDK.

References

2 Likes