feat: transfer token inside the network

[MicBun]

resolves: https://github.com/truflation/website/issues/3849

Summary by CodeRabbit

Release Notes

• New Features

  • Added token transfer capability to send TRUF/USDC through in-network wallet bridge actions with built-in validation and error handling.

• Documentation

  • Updated API reference with new Transfer method documentation and refill bot pattern examples.

• Tests

  • Added integration tests covering transfer functionality, input validation, and error scenarios.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	4h	Update time	May 8, 2026, 9:21 AM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[coderabbitai]

Warning

Rate limit exceeded

@MicBun has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 43 minutes and 33 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 49eb4eaa-c947-4eaf-9831-76e59edc5f03

📥 Commits

Reviewing files that changed from the base of the PR and between a641fd5 and 8f868d9.

📒 Files selected for processing (3)

• core/contractsapi/bridge_actions.go
• docs/api-reference.md
• tests/integration/bridge_actions_test.go

📝 Walkthrough

Walkthrough

This PR adds a new Transfer method to the Bridge Actions API, enabling in-network token transfers via on-chain bridge actions. The method is added across interface definitions, core implementation, client wiring, documentation, and integration tests, with input validation, decimal parsing, and error handling throughout.

Changes

Transfer Feature Implementation

Layer / File(s)	Summary
Interface Contracts core/types/stream.go, core/types/tsn_client.go	IAction and Client interfaces gain Transfer(ctx, bridgeIdentifier, recipient, amount) returning (string, error).
Core Implementation core/contractsapi/bridge_actions.go	Action.Transfer validates inputs, parses amount as decimal via apd.NewFromString, constructs action name bridgeIdentifier + "_transfer", executes via s.execute, and returns transaction hash. Extraneous artifact lines removed.
Client Wiring core/tnclient/client.go, core/tnclient/actions_transport.go	Client.Transfer loads actions and delegates; TransportAction.Transfer stub returns not-implemented error.
Documentation & Tests docs/api-reference.md, tests/integration/bridge_actions_test.go	API reference documents signature, parameters, and example usage. Integration tests cover async write semantics, input validation (empty bridge/recipient/amount, invalid amount format), and execution.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• pr-time-tracker
• outerlook

Poem

🐰 Hops with glee, a transfer flows,
From bridge to wallet, onward goes!
TRUF and USDC in flight so free,
Validated, parsed, and executed with spree! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: transfer token inside the network' clearly and concisely summarizes the main change—adding a Transfer method to send tokens via in-network bridges across multiple files.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch transferTruf

---

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 and usage tips.}

[MicBun]

@holdex pr submit-time 4h

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@core/contractsapi/bridge_actions.go`:
- Around line 81-89: The Transfer handler currently only checks non-empty
recipient and parseable amount; update it to validate recipient format and
require amount > 0 before proceeding: after parsing amount with
apd.NewFromString(amount) check that the resulting decimal is positive (compare
to zero) and return a clear error (e.g., "amount must be > 0") if not, and
validate the recipient string against your canonical address format (use the
project's address validation helper or implement checks for length/hex/prefix)
and return a descriptive error (e.g., "invalid recipient address format") if it
fails; keep the existing parse step (apd.NewFromString) and return wrapped
errors using fmt.Errorf to preserve context.

In `@docs/api-reference.md`:
- Around line 2616-2628: Update the Transfer docs to explicitly state that
Client.Transfer (func (c *Client) Transfer) is not implemented for custom
transports and currently returns a runtime error when used with a custom
transport; also replace the multiple action-name examples with one canonical set
of bridgeIdentifier examples (e.g. "eth_truf" and "eth_usdc" for mainnet,
"sepolia" for dev/test) and remove alternative/generated action names to avoid
confusion, and add a short note near the signature that callers must use
supported bridgeIdentifier values and handle the runtime error when using custom
transports.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ea9449ea-eb4c-473a-97ce-2869eeb987dd

📥 Commits

Reviewing files that changed from the base of the PR and between edc0cff and a641fd5.

📒 Files selected for processing (7)

• core/contractsapi/bridge_actions.go
• core/tnclient/actions_transport.go
• core/tnclient/client.go
• core/types/stream.go
• core/types/tsn_client.go
• docs/api-reference.md
• tests/integration/bridge_actions_test.go