[0xDEnYO]

Which Linear task belongs to this PR?

EXSC-382 (sub-task EXSC-383) — Frax bridge SC implementation.

Why did I implement it this way?

FraxFacet bridges through Frax HopV2, a LayerZero V2 OFT hub-and-spoke bridge (Fraxtal chainId 252 is the hub; every other chain is a spoke sharing one CREATE2 address). It calls HopV2.sendOFT(oft, dstEid, recipient, amountLd, 0, "") for the six Frax OFTs (frxUSD, sfrxUSD, WFRAX, frxETH, sfrxETH, FPI).

One facet source for every chain, incl. Tempo. Tempo's LayerZero EndpointV2Alt rejects native msg.value and charges the messaging fee in a TIP20 ERC20 gas token. Rather than a second contract, the fee mode is selected by a constructor immutable (TIP_FEE_MANAGER, non-zero only on Tempo, with PATH_USD as the default gas token) read from config/frax.json at deploy time. This keeps one @custom:version, one audit surface, and one Deploy script; the standard-chain runtime cost is an immutable read + one branch (≈ free), the only price being a few-k gas of one-time deploy bloat for the unused branch on 26 chains.

Money flow (the crux of the review):

• Excess native fee — the LI.FI/Frax API quotes the native fee with a ~10% buffer; HopV2 refunds the excess to the caller (the diamond) synchronously, and the facet forwards it to refundRecipient via refundExcessNative. This is a hot path, not an edge case.
• Dust — HopV2 floors the amount to the OFT's decimalConversionRate multiple and only pulls the floored amount. The facet floors up front, bridges exactly that, returns the dust remainder to refundRecipient in-tx, and emits LiFiTransferStarted.minAmount = the bridged (floored) amount. The diamond retains zero token and zero native after every bridge (asserted in tests).
• No positive slippage / no intent semantics — minAmountLD == amountLD; destination funds go straight to the recipient. No LI.FI contract ever holds funds on the destination.
• Tempo — msg.value == 0; the fee token is resolved (TIP_FEE_MANAGER.userTokens(diamond) → PATH_USD), pulled from the caller, approved to the hop, and any unpulled remainder is swept back to refundRecipient (invariant holds even across a HopV2 proxy upgrade).

Plain transfers only. hasDestinationCall == true reverts (doesNotContainDestinationCalls); no receiver periphery, and CalldataVerificationFacet is unchanged (no compose message to validate on-chain — same as PaxosTransitFacet).

Trust assumptions (documented in docs/FraxFacet.md):

• dstEid (the LayerZero routing target) is cross-checked against bridgeData.destinationChainId via an owner-governed on-chain chainId → EID mapping (initFrax/setFraxChainIdToEid/getFraxChainIdToEid, diamond storage com.lifi.facets.frax, mirroring SupersetFacet): the facet requires getFraxChainIdToEid(destinationChainId) == dstEid, reverting UnsupportedChainId when the destination is unmapped and InformationMismatch on eid mismatch. Every destination a route targets must be seeded before it is usable — EIDs live in the shared config/layerzero.json (single source of truth for all LZ facets), from which the frax.json mappings are generated and applied by the UpdateFraxFacet cut init. This is stricter than the analytics-only model of AcrossFacetV4/PaxosTransitFacet.

EID single-sourcing (config). config/layerzero.json is now the one place chainId → LayerZero EID is defined; frax.json/superset.json mappings are generated from it (tasks/syncLayerZeroEids.ts) and AcrossV4SwapFacet's hardcoded values are pinned to it by script/tasks/layerZeroEids.test.ts — so a wrong/stale EID fails CI, not on-chain. The reconciliation caught and corrected two wrong Frax EIDs (sei 30300→30280, xLayer 30196→30274, which disagreed with the audited AcrossV4 values); unverified abstract was dropped pending confirmation. No facet .sol changed (SupersetFacet/AcrossV4 bytecode unchanged — config/test/docs only).

• HopV2 is an upgradeable proxy with an admin recover(); the facet grants it the standard maxApproveERC20 allowance.

⚠️ Open item for BE / SC review — Tempo fee funding (EXP-514). On Tempo the diamond must possess the TIP20 fee token for the hop's transferFrom pull; the facet pulls it from the caller via depositAsset, so the caller must make the fee token available to the diamond. This is my best reversible inference from the verified RemoteHopV2Tempo source and needs BE confirmation — it does not change the facet ABI, so it can be adjusted without a redesign.

Testing: test/solidity/Facets/FraxFacet.t.sol — 53 tests, 100% function + effectively full line/statement coverage on FraxFacet.sol (the only uncovered lines under forge coverage --ir-minimum are the inline-assembly _getStorage() body and the TIP_FEE_MANAGER branch that is exercised by both suites — known instrumentation artifacts, same as SupersetFacet). Standard path uses an Arbitrum mainnet fork against the real HopV2 + frxUSD self-OFT with live fee quoting; the Tempo path uses MockFraxHopV2Tempo (rule 400: Tempo's TIP20/endpoint are precompile-backed and cannot be forked). Facet + deploy scripts compile clean under the deploy toolchain (solc 0.8.17 + london).

Follow-ups (out of scope here): SC peer review → BE integration (EXP-514) → external audit → staging then production rollout (multisig + diamondCut + diamond-log update). Aurora is excluded (absent from config/networks.json; needs /add-network) — tracked separately.

Peer review round (@gvladika)

Three review findings resolved (commit 7a19f30bb), plus the staging diamond brought in line with the rename (4daf2f1e9):

1. Selector collision with SupersetFacet — setChainIdToEid/getChainIdToEid shared byte-identical selectors with SupersetFacet, so cutting one facet onto a diamond holding the other silently uninstalled the other's selectors. Renamed to setFraxChainIdToEid/getFraxChainIdToEid (+ event FraxChainIdToEidSet); added rule 102-facets [CONV:FACET-SELECTORS]. The collision had already fired on arbitrum staging (Superset was at 0 selectors), so I redeployed the renamed FraxFacet (→ 0xCDFE2fc28F6f824F9E619728A52363bd558aB4d0, old selectors removed from the diamond) and re-cut SupersetFacet (→ 0x962125b0b3c2329EAd744a0ad383D37F78C608e9). Loupe-verified: zero selector overlap, both bridges live.
2. Tempo unusedFee underflow — guarded the fee-sweep subtraction so a HopV2 over-pull degrades to "no refund" instead of an arithmetic panic; added regression test test_Tempo_FeeOverPullDegradesToNoRefundInsteadOfReverting.
3. _bridgeData memory → calldata on the non-swap startBridgeTokensViaFrax (swap entrypoint stays memory — it mutates minAmount).

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 — see .agents/commands/pr-ready.md
• I have added tests that cover the functionality / test the bug
• For new facets: I have checked all points from this list: https://www.notion.so/lifi/New-Facet-Contract-Checklist-157f0ff14ac78095a2b8f999d655622e
• 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

Walkthrough

Changes

FraxFacet adds standard and Tempo Frax HopV2 bridging with direct and swap-assisted entrypoints, destination routing validation, dust and fee refunds, deployment configuration, LayerZero mapping synchronization, tests, documentation, a runnable demo, and clear-signing metadata.

Frax bridging integration

Layer / File(s)	Summary
FraxFacet bridge contract src/Facets/FraxFacet.sol, src/Interfaces/IFraxHopV2.sol	Adds Frax HopV2 interfaces and standard or Tempo bridging entrypoints with validation, dust handling, refunds, and swap support.
Configuration and deployment wiring config/frax.json, script/deploy/..., script/deploy/resources/deployRequirements.json, deployments/*.json	Adds chain-specific Frax addresses, deployment/update scripts, and staging deployment entries.
LayerZero mapping synchronization config/layerzero.json, tasks/syncLayerZeroEids.ts, script/tasks/layerZeroEids.test.ts, config/superset.json	Adds the authoritative EID mapping, deterministic mapping generation, Superset configuration updates, and consistency tests.
Tempo mock environment test/solidity/utils/MockFraxHopV2Tempo.sol	Adds mock OFT, fee manager, ERC20 behavior, HopV2 fee quoting, dust flooring, and token transfers.
Bridge and Tempo test coverage test/solidity/Facets/FraxFacet.t.sol	Tests fork-based bridging, swaps, validation failures, dust and native refunds, constructor checks, and Tempo ERC20 fee handling.
Demo, signing metadata, and documentation script/demoScripts/demoFrax.ts, config/clearSigningProposal.json, docs/FraxFacet.md	Adds a staging Frax bridge demo, signing definitions for both entrypoints, and documentation with route, fee, validation, and quote examples.

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

Suggested labels: AuditRequired, requires-types

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% 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
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.
Title check	✅ Passed	The title clearly summarizes the main change: adding the Frax HopV2 bridge facet.
Description check	✅ Passed	The description follows the template and includes the task, rationale, and checklists.

✨ 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-382-frax-sc-implementation

---

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: 4

🧹 Nitpick comments (1)

src/Interfaces/IFraxHopV2.sol (1)

72-92: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move the auxiliary interfaces into dedicated files.

Place ITipFeeManager and IFraxOFT in src/Interfaces/ITipFeeManager.sol and src/Interfaces/IFraxOFT.sol, respectively.

As per coding guidelines, “Solidity interfaces should be placed in separate files with the I prefix naming convention.”

🤖 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 `@src/Interfaces/IFraxHopV2.sol` around lines 72 - 92, The auxiliary interfaces
ITipFeeManager and IFraxOFT should not remain in IFraxHopV2.sol. Move each
interface into its own dedicated file, src/Interfaces/ITipFeeManager.sol and
src/Interfaces/IFraxOFT.sol, preserving their declarations and documentation,
and update any imports or references to use the new locations.

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 `@config/clearSigningProposal.json`:
- Around line 806-872: Update both Frax clear-signing entries to display
_fraxData.dstEid as the destination and _fraxData.refundRecipient as the refund
recipient, replacing the descriptive _bridgeData.destinationChainId presentation
where appropriate. Add visible field definitions for both _fraxData paths in
each entry, using suitable destination and address formatting while preserving
the existing bridge fields.

In `@docs/FraxFacet.md`:
- Around line 127-134: Update the “LiFi Data” documentation to clarify that
BridgeData is not strictly for analytics: explain that fields such as
sendingAssetId, receiver, and minAmount affect transfer behavior, while limiting
the analytics description to metadata such as transaction ID, integrator, and
referrer.

In `@script/demoScripts/demoFrax.ts`:
- Around line 243-283: Replace the warning-only sanity checks in the quote
mapping flow with validation that aborts before sending funds when any external
quote field mismatches expectations: oft, dstEid, recipient, amountLd,
approvalAddress, or transactionRequest.to. Derive the expected Hop target as
FRAX_HOP_SPOKE for both routes because Arbitrum is always the source, and
compare addresses and numeric values using appropriate normalized
representations. Preserve the existing API-derived values only after all
validations pass.

In `@src/Facets/FraxFacet.sol`:
- Line 229: Update the Tempo fee refund logic surrounding _sendViaTempo in
FraxFacet so the refund baseline accounts for the bridged token when feeToken
equals _bridgeData.sendingAssetId. Exclude _amount from the pre-snapshot or
otherwise track only the fee-funded deposit, preventing balanceOf(address(this))
- feeTokenBalanceBefore from underflowing after sendOFT transfers the bridged
tokens.

---

Nitpick comments:
In `@src/Interfaces/IFraxHopV2.sol`:
- Around line 72-92: The auxiliary interfaces ITipFeeManager and IFraxOFT should
not remain in IFraxHopV2.sol. Move each interface into its own dedicated file,
src/Interfaces/ITipFeeManager.sol and src/Interfaces/IFraxOFT.sol, preserving
their declarations and documentation, and update any imports or references to
use the new locations.

🪄 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: 93c6ffc8-add5-49b0-9067-b1b2bb107c25

📥 Commits

Reviewing files that changed from the base of the PR and between 6949564 and 42bfa17.

📒 Files selected for processing (13)

• config/clearSigningProposal.json
• config/frax.json
• docs/FraxFacet.md
• script/demoScripts/demoFrax.ts
• script/deploy/facets/DeployFraxFacet.s.sol
• script/deploy/facets/UpdateFraxFacet.s.sol
• script/deploy/resources/deployRequirements.json
• script/deploy/zksync/DeployFraxFacet.zksync.s.sol
• script/deploy/zksync/UpdateFraxFacet.zksync.s.sol
• src/Facets/FraxFacet.sol
• src/Interfaces/IFraxHopV2.sol
• test/solidity/Facets/FraxFacet.t.sol
• test/solidity/utils/MockFraxHopV2Tempo.sol

[lifi-action-bot]

Test Coverage Report

Line Coverage: 90.44% (3437 / 3800 lines)
Function Coverage: 93.68% ( 519 / 554 functions)
Branch Coverage: 75.76% ( 672 / 887 branches)
Test coverage (90.44%) is above min threshold (89%). Check passed.

[0xDEnYO]

Bot-review triage

Applied (pushed):

• CodeRabbit — demoFrax.ts routing: fixed. The source-chain Hop is always the arbitrum spoke for both routes (arbitrum is the source), and the demo now validates oft/dstEid/recipient/amount/approvalAddress/transactionRequest.to and throws on mismatch instead of warning.
• CodeRabbit — docs "BridgeData is strictly analytics": fixed. Clarified that sendingAssetId/receiver/minAmount are enforced; only transactionId/integrator/referrer/destinationChainId are descriptive.

Rejected (with reason):

• CodeRabbit — show _fraxData.dstEid/refundRecipient in the clear-signing entries: config/clearSigningProposal.json is generated by tasks/buildClearSigningProposal.ts, which emits only the standard _bridgeData/_swapData descriptors — no facet displays facet-specific struct fields. A manual edit would be inconsistent with every other facet, get overwritten on regeneration, and fail the verify-clear-signing CI that asserts committed == generated. The clear-signing surface is intentionally generator-driven.
• Olympix — "reentrancy: event emitted after external call" (FraxFacet.sol, LiFiTransferStarted): intentional and mandated by [CONV:EVENTS] (emit at the end of _startBridge after the bridge call), and the entrypoints are nonReentrant. Same pattern as every LI.FI facet.
• Olympix — "unsafe downcast": false positive. The flagged expression is bytes32(uint256(uint160(receiver))) — all widening; there is no narrowing cast in the facet.

Note: audit-verification failing + the auto-draft / AuditRequired label are the expected new-facet gate; the external audit is a downstream step (SC review → BE → audit → prod rollout).

[coderabbitai]

🧹 Nitpick comments (2)

tasks/syncLayerZeroEids.ts (1)

21-24: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use readonly for properties that should not be modified.

As per coding guidelines, use readonly for interface properties that do not require reassignment after initialization.

💡 Proposed refactor

 export interface IChainIdConfig {
-  chainId: number
-  lzEid: number
+  readonly chainId: number
+  readonly lzEid: number
 }

🤖 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 `@tasks/syncLayerZeroEids.ts` around lines 21 - 24, Update the IChainIdConfig
interface so its chainId and lzEid properties are readonly, preventing
reassignment after initialization.

Source: Coding guidelines

script/tasks/layerZeroEids.test.ts (1)

25-27: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reuse the centralized LIFI_CHAIN_ID_SOLANA constant.

To avoid duplication and maintain a single source of truth, consider importing LIFI_CHAIN_ID_SOLANA from the demoScriptHelpers module instead of redefining it as a literal here.

♻️ Proposed refactor

 } from '../../tasks/syncLayerZeroEids'
+import { LIFI_CHAIN_ID_SOLANA } from '../demoScripts/utils/demoScriptHelpers'
 
 const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '../..')
-const LIFI_CHAIN_ID_SOLANA = '1151111081099710'

Additionally, update the test assertion around line 66 since the imported constant is a BigInt:

    expect(eids[LIFI_CHAIN_ID_SOLANA.toString()]).toBe(Number(solana[1]))

🤖 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/tasks/layerZeroEids.test.ts` around lines 25 - 27, Remove the local
LIFI_CHAIN_ID_SOLANA literal and import the centralized constant from
demoScriptHelpers. In the test assertion using this key, convert the imported
BigInt to a string for eids lookup while preserving the numeric comparison
against solana[1].

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

Nitpick comments:
In `@script/tasks/layerZeroEids.test.ts`:
- Around line 25-27: Remove the local LIFI_CHAIN_ID_SOLANA literal and import
the centralized constant from demoScriptHelpers. In the test assertion using
this key, convert the imported BigInt to a string for eids lookup while
preserving the numeric comparison against solana[1].

In `@tasks/syncLayerZeroEids.ts`:
- Around line 21-24: Update the IChainIdConfig interface so its chainId and
lzEid properties are readonly, preventing reassignment after initialization.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 883efe7b-862a-4a80-a182-b652462a4a65

📥 Commits

Reviewing files that changed from the base of the PR and between 9efefa0 and 047a4d6.

📒 Files selected for processing (9)

• config/frax.json
• config/layerzero.json
• config/superset.json
• deployments/arbitrum.diamond.staging.json
• deployments/arbitrum.staging.json
• docs/FraxFacet.md
• script/demoScripts/demoFrax.ts
• script/tasks/layerZeroEids.test.ts
• tasks/syncLayerZeroEids.ts

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

• config/frax.json
• script/demoScripts/demoFrax.ts
• docs/FraxFacet.md

[lifi-action-bot]

🤖 GitHub Action: Security Alerts Review 🔍

🟢 Dismissed Security Alerts with Comments
The following alerts were dismissed with proper comments:

🟢 View Alert - File: src/Facets/FraxFacet.sol
🔹 Performing a narrowing downcast may result in silent overflow due to bit truncation. For more information, visit: http://detectors.olympixdevsectools.com/article/web3-vulnerability/unsafe-downcast
🔹 Dismiss Reason: False positive
🔹 Dismiss Comment: Not a narrowing downcast: address(160b)->uint160 is same-width (no truncation), then widened to uint256 and reinterpreted as bytes32. Standard LI.FI address->bytes32 recipient encoding; no value can be truncated.

🟢 View Alert - File: src/Facets/FraxFacet.sol
🔹 Reentrant functions which emit events after making an external call may lead to out-of-order events. For more information, visit: http://detectors.olympixdevsectools.com/article/web3-vulnerability/reentrancy-events
🔹 Dismiss Reason: Won't fix
🔹 Dismiss Comment: Intentional and safe: the function is nonReentrant, and emitting LiFiTransferStarted at the end of _startBridge (after the external bridge call) is the mandated CONV:EVENTS pattern used by every LI.FI facet. The reentrancy guard prevents any out-of-order-event scenario.

✅ No unresolved security alerts! 🎉

[lifi-qa-agent]

QA Pass confirmed — merge-from-main (36fff99) is non-substantive for FraxFacet; selector collision re-checked against SupersetFacet v1.1.0 (no new collision); clearSigningProposal.json FraxFacet entries intact. AuditRequired remains in force.

[lifi-qa-agent]

QA Pass (post-pass re-review) — PR #2138 merge confirmed carries Run #30 approval; LibBytes.toBytes32 refactor is semantically equivalent to prior cast (verified against library source). No new issues. AuditRequired gate and requires-types CI remain active and own their own enforcement.