docs(tbtcpg,spv): document wallet-action package roles

[piotr-roslaniec]

Summary

Neither pkg/tbtcpg nor pkg/maintainer/spv had a package doc comment, and
nothing documented that they are the two halves of the tBTC wallet-action
domain:

• pkg/tbtcpg generates wallet-action proposals for the coordinator.
• pkg/maintainer/spv submits SPV proofs for the transactions those actions
  produce.

Their mirrored file names (deposit_sweep.go, redemptions.go,
moving_funds.go, moved_funds_sweep.go) are intentional but undocumented.
This adds a package doc to each stating its role and the mirror convention, so
the split is discoverable and future code has a stated rule for where each
concern lives.

Docs-only; no code changes.

Verification

• go build ./... and go vet ./... clean; gofmt clean.

Summary by CodeRabbit

• New Features
  • Added automated proposal generation for tBTC wallet actions, including deposits, redemptions, heartbeats, fund transfers, and sweep operations.
  • The system now evaluates requested actions in order and returns the first successfully generated proposal.
  • Unsupported actions are skipped, while failed supported actions are collected for retry handling.
  • Added no-op proposal handling when no actionable proposal can be generated.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds the pkg/tbtcpg proposal-generation package, defining task contracts, wiring wallet-action tasks, forwarding redemption metrics, and generating proposals from coordination action checklists. Documents the related SPV maintainer package.

Changes

tBTC proposal generation

Layer / File(s)	Summary
Proposal task contract and generator wiring pkg/tbtcpg/tbtcpg.go, pkg/maintainer/spv/spv.go	Adds package documentation, the ProposalTask interface, ProposalGenerator, redemption metrics forwarding, and initialization of concrete wallet-action tasks.
Checklist-driven proposal generation pkg/tbtcpg/tbtcpg.go	Matches requested actions to tasks, returns successful proposals immediately, aggregates task errors, skips unsupported actions, and returns an error or no-op proposal when no proposal is generated.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ProposalGenerator
  participant ProposalTask
  Caller->>ProposalGenerator: Generate(request)
  ProposalGenerator->>ProposalTask: Run(request)
  ProposalTask-->>ProposalGenerator: proposal, ok, error
  ProposalGenerator-->>Caller: proposal or aggregated error/no-op

Loading

Suggested reviewers: lionakhnazarov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the docs-focused change to the two wallet-action package role comments.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/wallet-action-package-roles

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

pkg/tbtcpg/tbtcpg.go (1)

144-164: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not swallow task errors when another task returns no result.

If one task fails transiently and a later supported task returns (ok=false, err=nil), this condition returns NoopProposal instead of propagating the error. That bypasses the coordination retry path and can permanently skip a valid action for the window. Return the aggregated error whenever no proposal was generated and taskErrors is non-empty.

Proposed fix

-	if len(taskErrors) > 0 && len(taskErrors) == len(request.ActionsChecklist)-len(unsupportedActions) {
+	if len(taskErrors) > 0 {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pkg/tbtcpg/tbtcpg.go` around lines 144 - 164, The no-op proposal path
currently requires every supported task to fail before propagating errors, so it
swallows errors when another task returns no result. Update the condition before
the “all proposal tasks completed without result” log to return the aggregated
task error whenever no proposal was generated and taskErrors is non-empty,
regardless of other task outcomes; preserve the existing error aggregation and
no-op behavior when taskErrors is empty.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@pkg/tbtcpg/tbtcpg.go`:
- Around line 144-164: The no-op proposal path currently requires every
supported task to fail before propagating errors, so it swallows errors when
another task returns no result. Update the condition before the “all proposal
tasks completed without result” log to return the aggregated task error whenever
no proposal was generated and taskErrors is non-empty, regardless of other task
outcomes; preserve the existing error aggregation and no-op behavior when
taskErrors is empty.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8a99a71d-e5e1-4243-95ce-ffe3c215dbb0

📥 Commits

Reviewing files that changed from the base of the PR and between 5245f66 and d69809f.

📒 Files selected for processing (2)

• pkg/maintainer/spv/spv.go
• pkg/tbtcpg/tbtcpg.go