wallet module sweep functionalities 1/2

[rouzwelt]

Motivation

⚠️ Do NOT merge before #348

part of #341
Adds sweep functionalities to WalletManager for transferring erc20 and gas tokens from worker wallet back to main wallet to WalletManager class (1/2)

Solution

Checks

By submitting this for review, I'm confirming I've done the following:

• made this PR as small as possible
• unit-tested any new functionality
• linked any relevant issues or PRs
• included screenshots (if this involves a front-end change)

Summary by CodeRabbit

• New Features

  • Introduces a wallet sweep action to move all watched tokens and remaining gas from worker wallets to a destination.
  • Provides detailed sweep reports with per-asset outcomes, transaction links, and clear success/error statuses.
  • Enhances API surface to expose token metadata for integrations.

• Tests

  • Adds comprehensive unit and end-to-end coverage for the sweep flow, including success paths, token-only failures, gas-only failures, combined failures, and empty-token scenarios.
  • Verifies correct invocation and argument handling for transfer wrappers and sweep operations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds wallet sweeping functionality and tests. Introduces sweep helpers to transfer ERC-20 balances and remaining gas, integrates them into WalletManager with new public methods (transferTokenFrom, transferRemainingGasFrom, sweepWallet), exports TokenDetails, and adds end-to-end and unit tests covering success and failure scenarios.

Changes

Cohort / File(s)	Summary
Wallet sweep helpers src/wallet/sweep.ts, src/wallet/sweep.test.ts	New module with transferTokenFrom and transferRemainingGasFrom. Handles balance checks, gas estimation, optional funding, transfers, receipt waits, and structured errors. Comprehensive unit tests for success/failure and edge cases.
WalletManager sweep orchestration src/wallet/index.ts, src/wallet/index.test.ts	Adds WalletManager methods: transferTokenFrom, transferRemainingGasFrom (wrappers), and sweepWallet to iterate watched tokens, record outcomes, transfer remaining gas, and assemble an instrumented report with explorer links and aggregated status. E2E-style tests cover multiple success/failure paths and wrapper invocation.
State type export src/state.ts	Exports TokenDetails type: { address: `0x${string}`, symbol: string, decimals: number }.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Operator
  participant WalletManager
  participant From as Worker Wallet (from)
  participant To as Destination Wallet (to)
  participant Chain as Chain/Explorer

  Operator->>WalletManager: sweepWallet(from)
  activate WalletManager

  rect rgb(240,248,255)
    note over WalletManager: For each watched token
    WalletManager->>From: read token balance
    alt balance > 0
      WalletManager->>From: estimate gas for ERC-20 transfer
      alt from gas insufficient
        WalletManager->>To: send funding tx to from
        To->>Chain: broadcast funding tx
        Chain-->>WalletManager: funding receipt (wait 4 conf)
        alt funding reverted
          WalletManager--x Operator: token transfer error (with txHash)
        end
      end
      WalletManager->>From: writeContract transfer(token, to, amount)
      From->>Chain: broadcast token tx
      Chain-->>WalletManager: token receipt (wait 4 conf)
      alt token reverted
        WalletManager-->>Operator: record token error (with txHash)
      else token success
        WalletManager-->>Operator: record token success (amount, txHash, explorer URL)
      end
    else balance == 0
      WalletManager-->>Operator: record zero-amount token
    end
  end

  rect rgb(245,255,250)
    note over WalletManager: Sweep remaining gas
    WalletManager->>From: getSelfBalance
    alt balance > totalCost
      WalletManager->>From: sendTx(to, value = balance - totalCost)
      From->>Chain: broadcast gas tx
      Chain-->>WalletManager: gas receipt (wait 4 conf)
      alt gas reverted
        WalletManager-->>Operator: record gas error (with txHash)
      else
        WalletManager-->>Operator: record gas success (amount, txHash, explorer URL)
      end
    else
      WalletManager-->>Operator: record zero-amount gas
    end
  end

  WalletManager-->>Operator: final report (statuses, amounts, hashes, URLs)
  deactivate WalletManager

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 2025-06-02-sweep-module-1

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6abc26d and 51430d5.

📒 Files selected for processing (4)

• src/wallet/index.test.ts (5 hunks)
• src/wallet/index.ts (3 hunks)
• src/wallet/sweep.test.ts (1 hunks)
• src/wallet/sweep.ts (1 hunks)

---

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