feat: add InputSettlerEscrowTron for TRON USDT payouts

[luiz-lvj]

Problem

TRON USDT (TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) returns false from transfer even on a successful transfer (while reverting on real failure — verified on mainnet). InputSettlerEscrow pays out escrowed inputs with OpenZeppelin's SafeERC20.safeTransfer, which reads that false as a failure and reverts — locking USDT in the escrow on finalisation/refund.

The inbound transferFrom used on open is unaffected: USDT's transferFrom correctly returns true.

Change

InputSettlerEscrowTron — a TRON-specific InputSettlerEscrow that:

• takes the USDT address as a constructor immutable (configurable per deployment; address(0) disables the special path);
• pays out inputs with SafeTRC20, routing the configured USDT through SafeTRC20.safeTransferUSDT (which ignores the boolean and verifies the transfer by the recipient's balance delta) and every other token through the regular SafeTRC20.safeTransfer.

Only _resolveLock (used by both finalisation and refunds) is overridden; the reentry guard is preserved.

Dependency

SafeTRC20 is imported from OpenZeppelin's tron-contracts, added as a git submodule pinned to the commit that introduces safeTransferUSDT (OpenZeppelin/tron-contracts@ae352da, OpenZeppelin/tron-contracts#88). Once that PR merges, the submodule should be repointed to tron-contracts master.

Tests

InputSettlerEscrowTron.t.sol (with a MockUSDT that transfers but returns false): the base escrow reverts on USDT, the Tron variant pays out USDT despite the false return, and regular tokens still settle through the standard path.

Summary by CodeRabbit

Release Notes

• New Features

  • Added TRON blockchain support for escrow settlement with specialized handling for USDT token transfers on the TRON network.

• Tests

  • Added comprehensive test suite for TRON escrow functionality, including USDT transfer validation and regular token compatibility testing.

• Chores

  • Added TRON contracts library as a project dependency.

[coderabbitai]

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key: "enabled"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b44cfe90-ddaa-411e-b635-28bb7af8f800

📥 Commits

Reviewing files that changed from the base of the PR and between f94e849 and dce39c4.

📒 Files selected for processing (6)

• .gitmodules
• lib/tron-contracts
• remappings.txt
• src/input/escrow/InputSettlerEscrowTron.sol
• test/input/escrow/InputSettlerEscrowTron.t.sol
• test/mocks/MockUSDT.sol

---

📝 Walkthrough

Walkthrough

This PR introduces TRON network support to the escrow settlement layer by adding a specialized InputSettlerEscrowTron contract that handles TRON's USDT token, which returns false on successful transfers despite executing them. The implementation includes dependency wiring, contract implementation, and comprehensive tests validating both USDT and standard token handling.

Changes

TRON Escrow Settlement Support

Layer / File(s)	Summary
Dependency Setup and Wiring .gitmodules, lib/tron-contracts, remappings.txt	Registers OpenZeppelin's tron-contracts library as a Git submodule, updates broadcaster submodule URL, and adds Solidity remappings to resolve tron-contracts/ imports from lib/tron-contracts/contracts/.
TRON Escrow Settlement Implementation src/input/escrow/InputSettlerEscrowTron.sol	Implements InputSettlerEscrowTron that overrides _resolveLock to handle USDT transfers via SafeTRC20.safeTransferUSDT (which ignores USDT's false return) while routing other tokens through standard SafeTRC20.safeTransfer. Preserves base order-status guard logic for reentrancy safety.
Test Infrastructure and USDT Validation test/mocks/MockUSDT.sol, test/input/escrow/InputSettlerEscrowTron.t.sol	Adds MockUSDT mock that executes transfers but returns false to simulate TRON USDT behavior. Includes harness contracts exposing _resolveLock for testing and a test suite validating that base escrow reverts on USDT, TRON escrow successfully settles USDT, and TRON escrow correctly handles regular tokens.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• pepebndc
• frangio
• reednaa

Poem

🐰 On TRON where transfers misbehave,
A special settler comes to save!
With USDT returning false on success,
SafeTRC20 clears the mess.
Hopping safely through each payout! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly and accurately summarizes the main change: adding InputSettlerEscrowTron, a TRON-specific escrow contract for handling USDT payouts.
Description check	✅ Passed	The description comprehensively explains the problem, solution, dependency, and tests; however, the 'Related Issues' section required by the template is missing.
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.

_{✏️ 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 tron-usdt

---

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

[codecov]

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/input/escrow/InputSettlerEscrowTron.sol	91.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[reednaa]

My personal preference for this implementation is to add a virtual _transfer function to the base contract and then overwrite that here with if (token == USDT) ...

Additionally, Permit2 should also be overwritten.