feat(MayanFacet): route native ETH via swapAndForwardEth (EXSC-364) [MayanFacet v2.0.0, IMayan v1.1.0]

[0xDEnYO]

Which Linear task belongs to this PR?

https://linear.app/lifi-linear/issue/EXSC-364/sc-mayanfacet-route-between-forwardeth-and-swapandforwardeth-by

Also closes EXSC-606 (route refunds to an explicit refundRecipient instead of msg.sender) — folded in here to avoid a second MayanData ABI break, per the refund-routing convention call (agreed by Daniela, Goran, Max).

Unblocks BE EXBE-355 — this PR defines the MayanData calldata shape the backend consumes.

Why did I implement it this way?

MayanFacet previously routed all native-ETH sends through the Mayan forwarder's forwardEth. A Mayan Swift v2 order takes a specific ERC20 input token, not native ETH, so to offer native ETH as a sending token the forwarder exposes swapAndForwardEth, which performs a source-side swap (via swapProtocol/swapData) converting the native input into the order's input token (middleToken) before creating the order. The middleToken is chosen by Mayan per route/quote — it may be WETH or another token such as a stablecoin — and the conversion is a real DEX swap, not a fixed 1:1 wrap. (The verified staging run below used USDT as middleToken for an ETH→Polygon-USDT route.)

Design — extend MayanData, discriminate at the native branch. Four swap-layer fields are appended to MayanData for the native path, plus one refund field (see below). The full struct:

struct MayanData {
    bytes32 nonEVMReceiver;
    address mayanProtocol;
    bytes    protocolData;      // inner Mayan order → _parseReceiver reads this — UNCHANGED
    address swapProtocol;       // NEW (EXSC-364)
    bytes    swapData;          // NEW (EXSC-364)
    address middleToken;        // NEW (EXSC-364)
    uint256  minMiddleAmount;   // NEW (EXSC-364)
    address refundRecipient;    // NEW (EXSC-606)
}

_startBridge native branch:

• ERC20 → forwardERC20 (unchanged)
• native + swapProtocol != address(0) → swapAndForwardEth(minAmount, swapProtocol, swapData, middleToken, minMiddleAmount, mayanProtocol, protocolData)
• native + swapProtocol == address(0) → forwardEth (retained)

The backend selects the path per-quote by populating (or not) the swap-layer fields — the facet needs no knowledge of Mayan's ETH/WETH order semantics. _parseReceiver/_parseHypercoreReceiver are byte-for-byte unchanged, so on-chain receiver validation (derived from protocolData, run before the branch) still gates every path. The new opaque swapData/swapProtocol only govern the source-side conversion executed inside the immutable, trusted MAYAN forwarder (which itself allowlists swapProtocol). No EIP-712 gate is required — unlike rule 102's opaque-receiver case, the final receiver stays on-chain-validatable.

Refund routing (EXSC-606, folded in). Both entrypoints previously refunded excess native and swap leftovers to msg.sender. Per .agents/rules/102-facets.md [CONV:FACET-REFUNDS], msg.sender is the relayer (or the Permit2Proxy on gasless flows), never assumed to be the user, so user-owned refunds get stranded. This PR adds an explicit refundRecipient to MayanData, zero-address-checked on both entrypoints (revert InvalidCallData), and routes both refundExcessNative(payable(refundRecipient)) and the _depositAndSwap leftover receiver there. The backend sets refundRecipient to the owner of the source-side input per order (relayer when the relayer fronts the native, user when the user funds it). Since we were already breaking the MayanData ABI for EXSC-364, folding this in adds one struct field with no additional selector churn.

Versioning. Appending struct fields changes both entrypoint selectors, a breaking ABI change for existing callers → MAJOR bump 1.3.0 → 2.0.0 (one MAJOR bump covers the whole PR):

• startBridgeTokensViaMayan 0xb621b032 → 0xa2eff2da
• swapAndStartBridgeTokensViaMayan → 0x2abf2290

IMayan 1.0.0 → 1.1.0 (genuinely new swapAndForwardEth function).

Testing. forge test --match-contract MayanFacet → 39 pass, incl. new tests for the native swapAndForwardEth path (arg pass-through against a recorder etched onto the real MAYAN immutable), the swapAndStartBridge double-swap edge (proves _replaceInputAmount stays skipped for native), a receiver-mismatch revert on the new path, and the EXSC-606 refund tests (zero-refundRecipient reverts on both entrypoints; excess native lands on refundRecipient, not msg.sender).

Staging E2E (real Mayan data). script/demoScripts/demoMayan.ts was rewritten to exercise the native swapAndForwardEth path end-to-end with a live Mayan quote (previously it only covered the ERC20 path). This required bumping @mayanfinance/swap-sdk 8.5.0 → 15.0.0 (the pinned SDK is rejected by Mayan's quote API: SDK_VERSION_TOO_OLD). Verified run on Arbitrum staging: 0.001 ETH → ~1.8388 USDT delivered to the receiver on Polygon, Mayan status ORDER_SETTLED. Source tx: 0xa67bb19b…dd1f6c.

Review. Local CodeRabbit (/pr-ready) bypassed per the sanctioned interim (rate limits — see #2020); an independent adversarial code-reviewer pass was run instead (correctness + rule-102 opaque-swapData lens; IMayan verified byte-exact against the live forwarder ABI) with no findings. Cloud CodeRabbit + Aikido run on this PR.

Deploy. MayanFacet v2.0.0 deployed + verified on the Arbitrum staging diamond at 0x9923249c1f14E4BB68F71C689C3fCC323E5410aC and cut in (selectors startBridgeTokensViaMayan 0xa2eff2da, swapAndStartBridgeTokensViaMayan 0x2abf2290, MAYAN() 0xce90a721). Note: an earlier staging deploy in this PR predated the refundRecipient field, so it carried the pre-refundRecipient selectors; the diamond has now been re-cut to the current build (confirmed via DiamondLoupe).

Follow-up. EXSC-604 (signed arbitrary destination-call payloads, EIP-712) has been descoped / cancelled (PR #2043 closed) — it is no longer stacked on this branch. The remaining Mayan hardening item is EXSC-605 (reject a non-empty customPayload on the unsigned bridge path), tracked separately; it is a pre-existing surface not widened by this PR.

Checklist before requesting a review

• I have performed a self-review of my code
• This pull request is as small as possible and only tackles one problem
• I have run /pr-ready (local CodeRabbit) on this branch and resolved (or explicitly documented) all findings — bypassed per the sanctioned interim (rate limits); independent adversarial review done instead, documented above
• I have added tests that cover the functionality / test the bug
• For new facets: I have checked all points from this list — N/A (existing facet, not a new one)
• I have updated any required documentation

Checklist for reviewer (DO NOT DEPLOY and contracts BEFORE CHECKING THIS!!!)

• I have checked that any arbitrary calls to external contracts are validated and or restricted
• I have checked that any privileged calls (i.e. storage modifications) are validated and or restricted
• I have ensured that any new contracts have had AT A MINIMUM 1 preliminary audit conducted on by <company/auditor>

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 65521174-c887-4312-8bd0-914caf19eb9f

📥 Commits

Reviewing files that changed from the base of the PR and between b7cbdca and 29a2b8f.

📒 Files selected for processing (5)

• config/clearSigningProposal.json
• deployments/arbitrum.diamond.staging.json
• deployments/arbitrum.staging.json
• package.json
• script/demoScripts/demoMayan.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• package.json
• deployments/arbitrum.staging.json
• config/clearSigningProposal.json
• deployments/arbitrum.diamond.staging.json
• script/demoScripts/demoMayan.ts

---

Walkthrough

Mayan bridging now accepts native swap parameters and explicit refund recipients, conditionally routes native assets through Mayan’s swap forwarder, updates deployment and signing metadata, and adds native and ERC20 demo flows with expanded tests.

Changes

Mayan native swap forwarding

Layer / File(s)	Summary
Mayan data and native routing src/Facets/MayanFacet.sol, src/Interfaces/IMayan.sol, docs/MayanFacet.md	Expands MayanData, adds swapAndForwardEth, validates refundRecipient, and routes native bridging through direct or swap forwarding based on swapProtocol.
Native swap test coverage test/solidity/Facets/MayanFacet.t.sol, test/solidity/Facets/CalldataVerificationFacet.t.sol	Adds forwarding-call recording and tests native swap arguments, receiver validation, refunds, and updated data fixtures.
Integration metadata and demo updates config/clearSigningProposal.json, deployments/*.json, script/demoScripts/demoMayan.ts, package.json	Updates signing schemas, staging facet addresses and versions, the Mayan demo modes, and the Mayan swap SDK version.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• lifinance/contracts#2063: Updates Mayan clear-signing generator fields related to recipient-aware bridge flows.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the MayanFacet native-ETH routing change and the key new path, matching the PR's main objective.
Description check	✅ Passed	The description covers the required Linear task, rationale, and both reviewer/developer checklists with the needed implementation details.
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 feature/exsc-364-sc-mayanfacet-route-between-forwardeth-and-swapandforwardeth

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

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]

Actionable comments posted: 2

🧹 Nitpick comments (1)

test/solidity/Facets/MayanFacet.t.sol (1)

619-630: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert mayanProtocol forwarding too.

The recorder stores lastMayanProtocol, but this test never verifies it. Assert it equals data.mayanProtocol to cover every newly forwarded destination argument.

🤖 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 `@test/solidity/Facets/MayanFacet.t.sol` around lines 619 - 630, Extend the
assertions in the Mayan forwarding test to verify forwarder.lastMayanProtocol()
equals data.mayanProtocol, alongside the existing checks for the other forwarded
destination arguments. Use the recorder and input symbols already present in
this test.

🤖 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 `@src/Facets/MayanFacet.sol`:
- Around line 53-67: Add a nonzero refundRecipient field to MayanData and use it
instead of msg.sender for excess-native refund handling in both entrypoints and
for leftover refunds passed to _depositAndSwap. Validate the recipient before
processing, and update the associated ABI metadata and documentation to reflect
the new tuple field.

In `@src/Interfaces/IMayan.sol`:
- Around line 21-29: Add NatSpec documentation above swapAndForwardEth
describing its purpose and include an `@param` entry for amountIn, swapProtocol,
swapData, middleToken, minMiddleAmount, mayanProtocol, and mayanData, with clear
descriptions that identify the trust-sensitive protocol and calldata inputs.

---

Nitpick comments:
In `@test/solidity/Facets/MayanFacet.t.sol`:
- Around line 619-630: Extend the assertions in the Mayan forwarding test to
verify forwarder.lastMayanProtocol() equals data.mayanProtocol, alongside the
existing checks for the other forwarded destination arguments. Use the recorder
and input symbols already present in this test.

🪄 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: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ae30449d-67c6-46e2-909d-b658c367e6e5

📥 Commits

Reviewing files that changed from the base of the PR and between 1457988 and afb39aa.

📒 Files selected for processing (9)

• config/clearSigningProposal.json
• deployments/arbitrum.diamond.staging.json
• deployments/arbitrum.staging.json
• docs/MayanFacet.md
• script/demoScripts/demoMayan.ts
• src/Facets/MayanFacet.sol
• src/Interfaces/IMayan.sol
• test/solidity/Facets/CalldataVerificationFacet.t.sol
• test/solidity/Facets/MayanFacet.t.sol

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

script/demoScripts/demoMayan.ts (1)

83-86: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add explicit return types to the new async functions.

Declare Promise<...> return types for the quote finder, both runners, and main.

As per coding guidelines, “Use explicit return types for functions in TypeScript.”

Also applies to: 127-130, 217-220, 302-302

🤖 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 `@script/demoScripts/demoMayan.ts` around lines 83 - 86, Update
findNativeSwapAndForwardEthQuote, the two runner functions, and main with
explicit Promise<...> return type annotations, using each function’s actual
resolved return value; do not alter their existing behavior.

Source: Coding guidelines

🤖 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 `@script/demoScripts/demoMayan.ts`:
- Around line 310-319: Validate the normalized mode in the demo entrypoint
before creating the provider, signer, or invoking either transaction flow.
Accept only the supported values used by runErc20ForwardErc20 and
runNativeSwapAndForwardEth (erc20 and native); reject any other value, including
typos, with an error rather than defaulting to native.
- Around line 99-116: Update the catch around getSwapFromEvmTxPayload to retain
and surface the failure before continuing, including the relevant route or quote
context in the log. Preserve the existing continue behavior so failed payload
generation still skips to the next candidate instead of reaching the generic “No
native-ETH SWIFT quote” path.
- Around line 249-251: Validate the decoded transaction method immediately after
iface.parseTransaction in the Mayan transaction flow, and reject any method
other than forwardERC20 before accessing parsed.args.amountIn or protocolData.
Keep the existing amount derivation unchanged for valid forwardERC20
transactions.

---

Nitpick comments:
In `@script/demoScripts/demoMayan.ts`:
- Around line 83-86: Update findNativeSwapAndForwardEthQuote, the two runner
functions, and main with explicit Promise<...> return type annotations, using
each function’s actual resolved return value; do not alter their existing
behavior.

🪄 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: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 63fd72c7-d3ab-4b09-b192-5283ec9f75c0

📥 Commits

Reviewing files that changed from the base of the PR and between 2d6d97a and 35aa9c3.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• deployments/arbitrum.diamond.staging.json
• deployments/arbitrum.staging.json
• package.json
• script/demoScripts/demoMayan.ts
• src/Facets/MayanFacet.sol

[gvladika]

minMiddleAmount is forwarded straight through as the only slippage guard on the native ETH→middleToken source swap, but the facet never requires it to be > 0. At zero, the forwarder's middleAmount >= minMiddleAmount check is a no-op and the intermediate swap can be fully sandwiched — the order gets created for a dust amount and the user receives almost nothing on the destination chain.

This is a new value-at-risk surface introduced by the swapAndForwardEth path. It's caller/backend-supplied per the aggregator pattern, so this may be an accepted "backend responsibility" — but if so, please state that explicitly in the audit notes, and consider whether a require(minMiddleAmount > 0) (or a receiver-derived floor) is warranted here given the source swap executes with the user's native value.

[gvladika]

This diamond staging map now lists MayanFacet 2.0.0 at two addresses — 0x6b380169… here and 0x9923249c… a few lines below — while the flat arbitrum.staging.json registers only 0x9923249c…. The same hunk also adds CalldataVerificationFacet / PolymerCCTPFacet / SymbiosisFacet addresses that don't match the flat file's entries for those facets.

The PR body explains a re-cut happened after the refundRecipient field was added, so 0x6b380169… is most likely a stale pre-refundRecipient artifact. Please reconcile the two deployment logs before merge — deploy/verify tooling that iterates the diamond facets map (verify-contracts, multisig-rollout) could otherwise act on a facet address that was never cut into the live diamond, or report a spurious mismatch that blocks the staging rollout.