chore: define recipient on withdrawal

[williamrusdyputra]

resolves: https://github.com/trufnetwork/truf-network/issues/1201

Summary by CodeRabbit

• New Features
  • You can now direct token withdrawals/bridges to a specified recipient address, enabling transfers straight to another wallet for payouts or custodial flows. Transaction submission and confirmation remain the same—you’ll still receive and track the transaction hash as before. No changes to confirmation timing or error handling.

[coderabbitai]

Walkthrough

Adds a recipient parameter to withdrawal flow: client withdraw now takes (chain, amount, recipient) and passes it to Action.bridgeTokens, which also updates its signature and payload to include recipient. Existing wait and tx_hash handling remain unchanged.

Changes

Cohort / File(s)	Summary
Client withdraw signature & call src/client/client.ts	Updated withdraw method signature to withdraw(chain, amount, recipient) and forwarded recipient to action.bridgeTokens(chain, amount, recipient); existing tx wait/return unchanged.
Action bridgeTokens signature & payload src/contracts-api/action.ts	bridgeTokens now accepts recipient; payload includes $recipient alongside $amount; maintains amount validation; updates parameter order accordingly.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Client
  participant Action
  participant BridgeRPC as Bridge RPC

  User->>Client: withdraw(chain, amount, recipient)
  Client->>Action: bridgeTokens(chain, amount, recipient)
  Action->>BridgeRPC: bridge_tokens { chain, $amount, $recipient }
  BridgeRPC-->>Action: tx_hash or error
  alt tx_hash present
    Action-->>Client: tx_hash
    Client->>BridgeRPC: waitForTx(tx_hash)
    BridgeRPC-->>Client: confirmation
    Client-->>User: tx_hash
  else missing tx_hash
    Action-->>Client: error
    Client-->>User: error
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• chore: rename bridge action #125 — Touches Action.bridgeTokens implementation; related as it modifies the same method (RPC naming change).
• feat: bridge / withdraw from network to layer-1 #123 — Also adds recipient parameter to withdraw and bridgeTokens; directly overlaps in scope.

Suggested reviewers

• MicBun

Poem

(\/) A hop and a hash, we go!
( ••) New recipient in the flow—
/>🍃 Tokens bridge, tidy and neat,
Await the tx, confirm the feat.
With one more arg, we’re good to roll—
A cheerful hop from chain to goal.

Pre-merge checks and finishing touches

✅ 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 clearly describes the core change of adding a recipient parameter to withdrawal operations, directly reflecting the primary modification in the code while remaining concise and free of extraneous details.
Linked Issues Check	✅ Passed	The added recipient parameter in both the client’s withdraw method and the Action bridgeTokens function directly addresses the inability to withdraw on the website by enabling identification of the withdrawal destination, fulfilling the intent of issue #1201.
Out of Scope Changes Check	✅ Passed	All modifications are focused on extending withdrawal functionality to include a recipient parameter, which aligns with the linked issue and no unrelated code paths or features were introduced.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/define-recipient

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f0c4682 and e7a56f6.

📒 Files selected for processing (2)

• src/client/client.ts (1 hunks)
• src/contracts-api/action.ts (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: test

🔇 Additional comments (1)

src/client/client.ts (1)

268-286: LGTM! Recipient parameter correctly forwarded.

The implementation correctly passes the recipient parameter to action.bridgeTokens(), and the error handling logic remains intact. The method properly waits for transaction confirmation before returning the transaction hash.

---

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

🧪 Early access (Sonnet 4.5): enabled

We are currently testing the Sonnet 4.5 model, which is expected to improve code review quality. However, this model may lead to increased noise levels in the review comments. Please disable the early access features if the noise level causes any inconvenience.

Note:

• Public repositories are always opted into early access features.
• You can enable or disable early access features from the CodeRabbit UI or by updating the CodeRabbit configuration file.

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

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
williamrusdyputra	✅ Submitted	20min	Update time	Sep 30, 2025, 12:01 PM
MicBun	✅ Submitted	10min	Update time	Sep 30, 2025, 12:01 PM

[MicBun]

Lgtm

Waiting CI

[williamrusdyputra]

@MicBun sepolia bridge is not enabled yet on mainnet hence the ERC20 bridge test failed.

[MicBun]

lgtm

[MicBun]

@williamrusdyputra alright, make sure it is backlogged, so we don't forget to fix the test later on