Feat(#591) : add monitor task unfail failed txs (#593)

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: cain4chain

examples/wallet_examples/list_failed_actions/list_failed_actions.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"context"
+	"fmt"
+
+	sdk "github.com/bsv-blockchain/go-sdk/wallet"
+	"github.com/bsv-blockchain/go-wallet-toolbox/examples/internal/example_setup"
+	"github.com/bsv-blockchain/go-wallet-toolbox/examples/internal/show"
+)
+
+var (
+	// DefaultLimit is the default number of actions to retrieve
+	DefaultLimit = uint32(100)
+
+	// DefaultOffset is the default starting position for pagination
+	DefaultOffset = uint32(0)
+
+	// DefaultOriginator specifies the originator domain or FQDN used to identify the source of the request.
+	DefaultOriginator = "example.com"
+
+	// DefaultIncludeLabels determines whether to include labels in the response
+	DefaultIncludeLabels = true
+
+	// DefaultUnfail determines whether to request unfail processing for returned failed actions
+	DefaultUnfail = false
+)
+
+// defaultListFailedActionsArgs creates default arguments for listing failed wallet actions
+func defaultListFailedActionsArgs() sdk.ListActionsArgs {
+	return sdk.ListActionsArgs{
+		Limit:         &DefaultLimit,
+		Offset:        &DefaultOffset,
+		IncludeLabels: &DefaultIncludeLabels,
+	}
+}
+
+// This example demonstrates how to list failed actions for the Alice wallet
+func main() {
+	show.ProcessStart("List Failed Actions")
+
+	ctx := context.Background()
+
+	// Create Alice's wallet instance
+	alice := example_setup.CreateAlice()
+
+	// Create the wallet interface and establish database connection
+	aliceWallet, cleanup := alice.CreateWallet(ctx)
+	defer cleanup()
+
+	show.Step("Alice", "Listing failed actions")
+
+	// Configure pagination and filtering parameters
+	args := defaultListFailedActionsArgs()
+	show.Info("ListFailedActionsArgs", args)
+	show.Info("Unfail", DefaultUnfail)
+	show.Separator()
+
+	// Retrieve paginated list of failed wallet actions
+	actions, err := aliceWallet.ListFailedActions(ctx, args, DefaultUnfail, DefaultOriginator)
+	if err != nil {
+		panic(fmt.Errorf("failed to list failed actions: %w", err))
+	}
+
+	show.Info("FailedActions", actions)
+	show.ProcessComplete("List Failed Actions")
+}

examples/wallet_examples/list_failed_actions/list_failed_actions.md

@@ -0,0 +1,84 @@
+# List Failed Actions Example
+
+This example demonstrates how to retrieve a paginated list of failed wallet actions and optionally request recovery ("unfail") in the Go Wallet Toolbox SDK. Failed actions are transactions or actions that did not complete successfully.
+
+## Overview
+
+The process involves several steps:
+1. Creating a wallet instance and establishing database connection.
+2. Configuring pagination and display parameters.
+3. Calling the wallet's `ListFailedActions` method with the configured arguments and an `unfail` flag.
+4. Processing and displaying the returned failed actions, including total count and details.
+
+When `unfail` is set to true, the call requests recovery for the returned failed actions, promoting them to be reprocessed by the unfail workflow.
+
+## Code Walkthrough
+
+### Configuration Parameters
+
+The example uses the following configurable constants:
+
+- **`DefaultLimit`**: Maximum number of actions to return per request (default: `100`)
+- **`DefaultOffset`**: Starting position for pagination (default: `0`)
+- **`DefaultOriginator`**: The originator domain or FQDN allowed to use this permission (default: `"example.com"`)
+- **`DefaultIncludeLabels`**: Whether to include labels in the response (default: `true`)
+- **`DefaultUnfail`**: Whether to request promotion of the listed failed actions to "unfail" (default: `false`)
+
+### Request Parameters
+
+`ListFailedActions` reuses `ListActionsArgs` for pagination and inclusion flags:
+
+- **`Limit`**: Controls how many actions to retrieve in a single request
+- **`Offset`**: Specifies the starting position for pagination
+- **`IncludeLabels`**: Include action labels in the response
+
+### Behavior Notes
+
+- The wallet injects a reserved spec-op label for "failed actions" so storage filters by status = failed.
+- If `unfail = true`, a control label is also included; after fetching results, storage promotes those TXIDs for the unfail processing flow (best-effort).
+
+## Running the Example
+
+To run this example:
+
+```bash
+go run ./examples/wallet_examples/list_failed_actions/list_failed_actions.go
+```
+
+## Expected Output
+
+```text
+🚀 STARTING: List Failed Actions
+============================================================
+Using remote storage: http://localhost:8100
+CreateWallet: 02a675b6767bf17f8d37755d4afb8dcea49f79c0ae696f0f59c0b38154e482520f
+
+=== STEP ===
+Alice is performing: Listing failed actions
+--------------------------------------------------
+ListFailedActionsArgs: {Labels:[] LabelQueryMode: IncludeLabels:0x7ff7033e34e0 IncludeInputs:<nil> IncludeInputSourceLockingScripts:<nil> IncludeInputUnlockingScripts:<nil> IncludeOutputs:<nil> IncludeOutputLockingScripts:<nil> Limit:0x7ff7033e3548 Offset:0x7ff7042fee4c SeekPermission:<nil>}
+Unfail: true
+============================================================
+FailedActions: &{TotalActions:2 Actions:[{Txid:225cc7b2be25be0c3cc032d09fd8035128c9d8e2f0d32db6ab7d875648263bb4 Satoshis:-38 Status:failed IsOutgoing:true Description:mintPushDropToken Labels:[mintPushDropToken] Version:1 LockTime:0 Inputs:[] Outputs:[]} {Txid:568f51aa28dca612ee18351695c6a7e3f22a4a468909a5493442ed01e68e922f Satoshis:-38 Status:failed IsOutgoing:true Description:mintPushDropToken Labels:[mintPushDropToken] Version:1 LockTime:0 Inputs:[] Outputs:[]}]}
+============================================================
+🎉 COMPLETED: List Failed Actions
+```
+
+## Integration Steps
+
+To integrate failed-action listing into your application:
+
+1. **Configure pagination parameters** based on your UI needs (page size, starting offset).
+2. **Set the originator identifier** to your application's domain or identifier.
+3. **Choose label inclusion** if you need metadata for display or filtering.
+4. **Decide on `unfail` behavior**: set to `true` to request recovery of the listed failed actions.
+5. **Call `ListFailedActions`** on your wallet instance with the arguments and `unfail` flag.
+6. **Handle the response** and show failed actions to the user.
+7. **Monitor recovery**: when `unfail` is requested, the background unfail flow will attempt to move those actions forward.
+
+## Additional Resources
+
+- [List Failed Actions Code](./list_failed_actions.go) - Complete code example for listing failed actions
+- [List Actions Documentation](../list_actions/list_actions.md) - General action listing doc
+
+

infra-config.example.yaml

@@ -52,6 +52,10 @@ monitor:
             enabled: true
             interval_seconds: 300
             start_immediately: true
+        un_fail:
+            enabled: true
+            interval_seconds: 600
+            start_immediately: false
 name: go-storage-server
 server_private_key: ""
 synchronize_tx_statuses:

pkg/defs/monitor.go

@@ -22,11 +22,14 @@ const (
 
 	// FailAbandonedMonitorTask marks transactions as failed if they have been abandoned or not processed within a set period.
 	FailAbandonedMonitorTask MonitorTask = "fail_abandoned"
+
+	// UnFailMonitorTask is a monitoring task that checks for failed transactions and reverifies failed tx statuses.
+	UnFailMonitorTask MonitorTask = "un_fail"
 )
 
 // ParseMonitorTaskStr parses a string to a MonitorTask or returns an error
 func ParseMonitorTaskStr(task string) (MonitorTask, error) {
-	return parseEnumCaseInsensitive(task, CheckForProofsMonitorTask, SendWaitingMonitorTask, FailAbandonedMonitorTask)
+	return parseEnumCaseInsensitive(task, CheckForProofsMonitorTask, SendWaitingMonitorTask, FailAbandonedMonitorTask, UnFailMonitorTask)
 }
 
 // TaskConfig defines configuration parameters for a monitoring task
@@ -48,6 +51,7 @@ type TasksConfig struct {
 	CheckForProofs TaskConfig `mapstructure:"check_for_proofs"`
 	SendWaiting    TaskConfig `mapstructure:"send_waiting"`
 	FailAbandoned  TaskConfig `mapstructure:"fail_abandoned"`
+	UnFail         TaskConfig `mapstructure:"un_fail"`
 }
 
 func (t *TasksConfig) all() iter.Seq2[MonitorTask, TaskConfig] {
@@ -135,6 +139,10 @@ func DefaultMonitorConfig() Monitor {
 				Enabled:         true,
 				IntervalSeconds: must.ConvertToUInt((5 * time.Minute).Seconds()),
 			},
+			UnFail: TaskConfig{
+				Enabled:         true,
+				IntervalSeconds: must.ConvertToUInt((10 * time.Minute).Seconds()),
+			},
 		},
 	}
 }

pkg/internal/specops/spec_ops.go

@@ -0,0 +1,9 @@
+package specops
+
+// ListActionsSpecOpFailedActionsLabel indicates that listActions should return only actions with status 'failed'.
+const ListActionsSpecOpFailedActionsLabel = "97d4eb1e49215e3374cc2c1939a7c43a55e95c7427bf2d45ed63e3b4e0c88153"
+
+// IsListActionsSpecOp returns true if the provided label is a reserved listActions spec-op.
+func IsListActionsSpecOp(label string) bool {
+	return label == ListActionsSpecOpFailedActionsLabel
+}

pkg/internal/validate/validate_list_failed_actions_args.go

@@ -0,0 +1,39 @@
+package validate
+
+import (
+	"fmt"
+
+	"github.com/bsv-blockchain/go-wallet-toolbox/pkg/wdk"
+)
+
+func ListFailedActionsArgs(args *wdk.ListFailedActionsArgs) error {
+	if args == nil {
+		return fmt.Errorf("args cannot be nil")
+	}
+
+	if args.Limit > MaxPaginationLimit {
+		return fmt.Errorf("limit must be less than or equal to %d", MaxPaginationLimit)
+	}
+	if args.Offset > MaxPaginationOffset {
+		return fmt.Errorf("offset must be less than or equal to %d", MaxPaginationOffset)
+	}
+
+	if !args.SeekPermissions.Value() {
+		return fmt.Errorf("operation not allowed without permission (seekPermissions=false)")
+	}
+
+	if !args.IncludeInputs.Value() {
+		if args.IncludeInputUnlockingScripts.Value() {
+			return fmt.Errorf("includeInputUnlockingScripts cannot be true when includeInputs is false")
+		}
+		if args.IncludeInputSourceLockingScripts.Value() {
+			return fmt.Errorf("includeInputSourceLockingScripts cannot be true when includeInputs is false")
+		}
+	}
+
+	if !args.IncludeOutputs.Value() && args.IncludeOutputLockingScripts.Value() {
+		return fmt.Errorf("includeOutputLockingScripts cannot be true when includeOutputs is false")
+	}
+
+	return nil
+}

pkg/monitor/all_tasks.go

@@ -18,5 +18,8 @@ func (d *Daemon) allTasksFactories() map[defs.MonitorTask]taskFactoryFunc {
 		defs.FailAbandonedMonitorTask: func() tasks.TaskInterface {
 			return tasks.NewFailAbandonedTask(d.storage)
 		},
+		defs.UnFailMonitorTask: func() tasks.TaskInterface {
+			return tasks.NewUnFailTask(d.storage)
+		},
 	}
 }

pkg/monitor/interface.go

@@ -10,4 +10,5 @@ type MonitoredStorage interface {
 	SynchronizeTransactionStatuses(ctx context.Context) error
 	SendWaitingTransactions(ctx context.Context, minTransactionAge time.Duration) error
 	AbortAbandoned(ctx context.Context) error
+	UnFail(ctx context.Context) error
 }

pkg/monitor/internal/tasks/check_failed_transactions.go

@@ -0,0 +1,22 @@
+package tasks
+
+import (
+	"context"
+	"fmt"
+)
+
+// UnFailTask iterates failed transactions and re-checks their on-chain status.
+type UnFailTask struct {
+	storage UnFailChecker
+}
+
+func NewUnFailTask(storage UnFailChecker) TaskInterface {
+	return &UnFailTask{storage: storage}
+}
+
+func (t *UnFailTask) Run(ctx context.Context) error {
+	if err := t.storage.UnFail(ctx); err != nil {
+		return fmt.Errorf("check failed transactions failed: %w", err)
+	}
+	return nil
+}

pkg/monitor/internal/tasks/check_for_proofs.go

@@ -9,6 +9,11 @@ type TransactionStatusesSynchronizer interface {
 	SynchronizeTransactionStatuses(ctx context.Context) error
 }
 
+// UnFailChecker checks failed transactions against the chain and updates their status if they are found.
+type UnFailChecker interface {
+	UnFail(ctx context.Context) error
+}
+
 type CheckForProofsTask struct {
 	storage TransactionStatusesSynchronizer
 }