unroll: Make VTXO reliving evidence-based

Treat legacy started checkpoints and ambiguous broadcast failures as
unsafe. Only an explicit no-broadcast proof may clear the relive guard,
so a failed exit cannot restore a coin that may have crossed the chain
boundary.

Author: ellemouton

txconfirm/messages.go

@@ -171,6 +171,12 @@ type EnsureConfirmedResp struct {
 	// Created is true when the request created a new tracking entry and
 	// false when it attached to existing state.
 	Created bool
+
+	// DefinitelyNotBroadcast is true only when the responder can prove
+	// that no broadcast attempt crossed the chain boundary. Callers may
+	// use this to distinguish a locally rejected request from an ambiguous
+	// broadcast failure. The conservative default is false.
+	DefinitelyNotBroadcast bool
 }
 
 // MessageType returns the stable message type identifier.

unroll/AGENTS.md

@@ -71,8 +71,9 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/unroll.<
   `ExitOutcomeRecoverable` (roll back to live), a completed exit →
   `ExitOutcomeConfirmed` (retire to spent). The live actor sets
   `ReliveUnsafe` before every chain-boundary attempt; only objective
-  canonical-absence evidence may clear it. A mere rejection, absence, or
-  timeout therefore leaves the VTXO held in unilateral exit.
+  canonical-absence evidence or an explicit `DefinitelyNotBroadcast`
+  response may clear it. An ambiguous rejection, absence, or timeout
+  therefore leaves the VTXO held in unilateral exit.
   `UnrollTerminatedMsg` carries `HadOnChainFootprint`, computed by
   `jobHadOnChainFootprint` (any confirmed/in-flight proof node or a
   non-pending sweep), and the durable `ReliveUnsafe` guard. It also carries

unroll/CLAUDE.md

@@ -71,8 +71,9 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/unroll.<
   `ExitOutcomeRecoverable` (roll back to live), a completed exit →
   `ExitOutcomeConfirmed` (retire to spent). The live actor sets
   `ReliveUnsafe` before every chain-boundary attempt; only objective
-  canonical-absence evidence may clear it. A mere rejection, absence, or
-  timeout therefore leaves the VTXO held in unilateral exit.
+  canonical-absence evidence or an explicit `DefinitelyNotBroadcast`
+  response may clear it. An ambiguous rejection, absence, or timeout
+  therefore leaves the VTXO held in unilateral exit.
   `UnrollTerminatedMsg` carries `HadOnChainFootprint`, computed by
   `jobHadOnChainFootprint` (any confirmed/in-flight proof node or a
   non-pending sweep), and the durable `ReliveUnsafe` guard. It also carries

unroll/actor.go

@@ -1002,6 +1002,8 @@ func (b *behavior) ensureNodeConfirmed(ctx context.Context,
 
 		return b.driveEvent(ctx, ax, &TxFailedEvent{
 			Txid: txid,
+			DefinitelyNotBroadcast: ensureResp.
+				DefinitelyNotBroadcast,
 			Reason: b.failureReasonForTx(
 				txid, "txconfirm returned failed state",
 			),

unroll/actor_test.go

@@ -137,10 +137,11 @@ func (m *mockVTXOStore) DeleteVTXO(context.Context, wire.OutPoint) error {
 type fakeTxConfirmRef struct {
 	mu sync.Mutex
 
-	requests       []*txconfirm.EnsureConfirmedReq
-	responseStates map[chainhash.Hash]txconfirm.TxState
-	confirmHeights map[chainhash.Hash]int32
-	failureReasons map[chainhash.Hash]string
+	requests               []*txconfirm.EnsureConfirmedReq
+	responseStates         map[chainhash.Hash]txconfirm.TxState
+	confirmHeights         map[chainhash.Hash]int32
+	failureReasons         map[chainhash.Hash]string
+	definitelyNotBroadcast map[chainhash.Hash]bool
 
 	// onAsk, when set, is invoked with each EnsureConfirmedReq as it is
 	// recorded (outside the store lock). Tests use it to assert ordering
@@ -188,6 +189,8 @@ func (f *fakeTxConfirmRef) Ask(_ context.Context,
 	f.requests = append(f.requests, req)
 	state := f.responseStates[req.Tx.TxHash()]
 	height := f.confirmHeights[req.Tx.TxHash()]
+	definitelyNotBroadcast :=
+		f.definitelyNotBroadcast[req.Tx.TxHash()]
 	onAsk := f.onAsk
 	f.mu.Unlock()
 
@@ -226,9 +229,10 @@ func (f *fakeTxConfirmRef) Ask(_ context.Context,
 	promise.Complete(
 		fn.Ok[txconfirm.Resp](
 			&txconfirm.EnsureConfirmedResp{
-				Txid:    req.Tx.TxHash(),
-				State:   state,
-				Created: true,
+				Txid:                   req.Tx.TxHash(),
+				State:                  state,
+				Created:                true,
+				DefinitelyNotBroadcast: definitelyNotBroadcast,
 			},
 		),
 	)
@@ -343,6 +347,23 @@ func (f *fakeTxConfirmRef) setImmediateFailed(txid chainhash.Hash,
 	f.failureReasons[txid] = reason
 }
 
+// setImmediateDefiniteNoBroadcast configures one txid to fail before any
+// broadcast attempt crosses the chain boundary.
+func (f *fakeTxConfirmRef) setImmediateDefiniteNoBroadcast(txid chainhash.Hash,
+	reason string) {
+
+	f.setImmediateFailed(txid, reason)
+
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	if f.definitelyNotBroadcast == nil {
+		f.definitelyNotBroadcast = make(map[chainhash.Hash]bool)
+	}
+
+	f.definitelyNotBroadcast[txid] = true
+}
+
 // emitConfirmed delivers a txconfirm success notification to the subscriber.
 func (f *fakeTxConfirmRef) emitConfirmed(t *testing.T, index int,
 	txid chainhash.Hash, height int32) {
@@ -2965,6 +2986,35 @@ func TestProofTxFailureTransitionsToFailed(t *testing.T) {
 			" failed: txconfirm returned failed state",
 		checkpoint.Fail,
 	)
+	require.True(t, checkpoint.ReliveUnsafe)
+}
+
+// TestDefiniteNoBroadcastClearsReliveGuard proves that an explicit local
+// rejection may recover the VTXO while an ambiguous TxStateFailed response
+// remains fail-closed.
+func TestDefiniteNoBroadcastClearsReliveGuard(t *testing.T) {
+	proof := buildLinearProof(t)
+	desc := testDescriptor(t, proof.TargetOutpoint(), proof.CSVDelay())
+	rootTxid := proof.RootTxids()[0]
+	unrollActor, _, txconfirmRef, store := newActorHarness(t, proof, desc)
+	txconfirmRef.setImmediateDefiniteNoBroadcast(rootTxid, "rejected")
+
+	mustAsk(t, unrollActor.Ref(), &StartUnrollRequest{
+		Height:  100,
+		Trigger: TriggerManual,
+	})
+
+	require.Eventually(t, func() bool {
+		stateResp, ok := mustAsk(
+			t, unrollActor.Ref(), &GetStateRequest{},
+		).(*GetStateResp)
+		require.True(t, ok)
+
+		return stateResp.Phase == PhaseFailed
+	}, testTimeout, 10*time.Millisecond)
+
+	checkpoint := mustDecodeCheckpoint(t, store, "unroll-test")
+	require.False(t, checkpoint.ReliveUnsafe)
 }
 
 // TestResumeReissuesSweepConfirmation verifies that resume reattaches

unroll/fsm_logic.go

@@ -501,6 +501,9 @@ func applyFailedEvent(job *JobState, event *TxFailedEvent) {
 	job.DeferredCheckpoints = removeDeferredCheckpoint(
 		job.DeferredCheckpoints, event.Txid,
 	)
+	if event.DefinitelyNotBroadcast {
+		job.ReliveUnsafe = false
+	}
 
 	job.FailReason = event.Reason
 }

unroll/fsm_types.go

@@ -235,6 +235,11 @@ type TxFailedEvent struct {
 
 	// Reason is the stable human-readable failure reason.
 	Reason string
+
+	// DefinitelyNotBroadcast proves that the failed transaction never
+	// crossed the chain boundary. Only this explicit evidence may clear
+	// the fail-closed relive guard.
+	DefinitelyNotBroadcast bool
 }
 
 // eventSealed marks TxFailedEvent as an FSM event.

unroll/reorg_safety_test.go

@@ -214,6 +214,12 @@ func (r *recordingRegistryRef) Tell(_ context.Context, msg RegistryMsg) error {
 	return nil
 }
 
+func (r *recordingRegistryRef) TryTell(ctx context.Context,
+	msg RegistryMsg) error {
+
+	return r.Tell(ctx, msg)
+}
+
 // terminatedCount returns how many UnrollTerminatedMsg messages have
 // been delivered so far.
 func (r *recordingRegistryRef) terminatedCount() int {

unroll/snapshot.go

@@ -121,10 +121,11 @@ const (
 	// recoverable failure.
 	checkpointExternalSpendFinalizedRecordType tlv.Type = 27
 
-	// checkpointReliveUnsafeRecordType is optional; present (value 1)
-	// before a job issues or reissues chain-boundary work. Until
-	// authoritative negative evidence clears the guard, a later failure
-	// must hold the VTXO in exit rather than relive it.
+	// checkpointReliveUnsafeRecordType is present for every checkpoint
+	// whose actor has started. A value of 1 means chain-boundary work may
+	// have escaped; 0 records an explicit clear by authoritative negative
+	// evidence. Started checkpoints written before this record existed
+	// omit it and decode fail-closed as unsafe.
 	checkpointReliveUnsafeRecordType tlv.Type = 29
 )
 
@@ -329,8 +330,11 @@ func encodeCheckpoint(value *actorCheckpoint) ([]byte, error) {
 		)
 	}
 
-	if value.ReliveUnsafe {
-		unsafe := uint8(1)
+	if value.Started {
+		unsafe := uint8(0)
+		if value.ReliveUnsafe {
+			unsafe = 1
+		}
 		records = append(
 			records, tlv.MakePrimitiveRecord(
 				checkpointReliveUnsafeRecordType, &unsafe,
@@ -514,6 +518,12 @@ func decodeCheckpoint(raw []byte) (*actorCheckpoint, error) {
 
 	if _, ok := parsed[checkpointReliveUnsafeRecordType]; ok {
 		checkpoint.ReliveUnsafe = reliveUnsafe != 0
+	} else if checkpoint.Started {
+		// Checkpoints written before the guard was added have no
+		// record. A started job may already have crossed a chain
+		// boundary, so absence cannot be treated as evidence that
+		// reliving is safe.
+		checkpoint.ReliveUnsafe = true
 	}
 
 	return checkpoint, nil

unroll/snapshot_test.go

@@ -222,6 +222,33 @@ func TestCheckpointCodecVersionMismatch(t *testing.T) {
 	require.ErrorContains(t, err, "unsupported checkpoint version")
 }
 
+// TestCheckpointCodecLegacyStartedDefaultsReliveUnsafe proves an in-flight
+// checkpoint written before the relive guard existed cannot decode fail-open
+// at the upgrade boundary.
+func TestCheckpointCodecLegacyStartedDefaultsReliveUnsafe(t *testing.T) {
+	checkpoint := &actorCheckpoint{
+		Version: checkpointVersion,
+		Started: true,
+		Trigger: TriggerManual,
+	}
+	raw, err := encodeCheckpoint(checkpoint)
+	require.NoError(t, err)
+
+	// Record type 29 is the final canonical record and uses one-byte TLV
+	// type/length encodings. Removing it reproduces the pre-field wire
+	// shape while retaining Started=true.
+	reliveRecord := []byte{
+		byte(checkpointReliveUnsafeRecordType), 1, 0,
+	}
+	require.True(t, bytes.HasSuffix(raw, reliveRecord))
+	raw = raw[:len(raw)-len(reliveRecord)]
+
+	decoded, err := decodeCheckpoint(raw)
+	require.NoError(t, err)
+	require.True(t, decoded.Started)
+	require.True(t, decoded.ReliveUnsafe)
+}
+
 // TestCheckpointCodecCorruptDataRejected asserts that malformed input (empty,
 // truncated, random garbage) is rejected with an error rather than panicking
 // or returning a zero-value checkpoint.