Speedy brl flow

[gianfra-t]

Issue: #1112

Description

Adds new transactions creators, phases and quote logic to handle BRLA onramps / offramps on Base.

New flow can be seen at the journey and fees diagram.

Review focus

Changes are focused on:

• The quote engine logic files, starting with the two new strategies for onramp and offramp.

• Transaction creation routes: onramp and offramp.

• Phases logic modifications, and additions.

[netlify]

✅ Deploy Preview for vortexfi ready!

Name	Link
🔨 Latest commit	86caa8d
🔍 Latest deploy log	https://app.netlify.com/projects/vortexfi/deploys/69f1d2c1ec623500087b9b9a
😎 Deploy Preview	https://deploy-preview-1118--vortexfi.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for vortex-sandbox ready!

Name	Link
🔨 Latest commit	86caa8d
🔍 Latest deploy log	https://app.netlify.com/projects/vortex-sandbox/deploys/69f1d2c1fa23730008e6120d
😎 Deploy Preview	https://deploy-preview-1118--vortex-sandbox.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gianfra-t]

Caveat: not currently doing a swap simulation first.

[Copilot]

Pull request overview

This PR introduces a new “speedy” BRL ramp path by moving BRLA flows onto Base, adding EVM-native Nabla swap + updated quote routing/strategies, and extending transaction/phases handling (including new EVM fee distribution and subsidy steps) to support BRLA onramps/offramps on Base.

Changes:

• Add BRLA token + Base/BaseSepolia network support across shared token/network config and EVM client management.
• Add Base-specific quote strategies/engines and new/updated transaction creation routes for BRL onramp/offramp via Base (including EVM Nabla swap).
• Extend ramp phases/handlers for EVM-specific subsidy/fee distribution steps and update docs/frontend pieces to reflect the new journey.

Reviewed changes

Copilot reviewed 76 out of 77 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
packages/shared/src/tokens/types/evm.ts	Adds BRLA to EVM token enum.
packages/shared/src/tokens/evm/config.ts	Adds BRLA config for Base + BaseSepolia.
packages/shared/src/tokens/constants/misc.ts	Adds Base Nabla router address constant.
packages/shared/src/services/squidrouter/route.ts	Tweaks getRoute overload formatting/signature.
packages/shared/src/services/squidrouter/route-cache.ts	Adjusts cached route field ordering.
packages/shared/src/services/squidrouter/onramp.ts	Adds Base→EVM onramp route builder + refactors param type.
packages/shared/src/services/squidrouter/config.ts	Adds Base swap min value constant.
packages/shared/src/services/nabla/transactions/index.ts	Adds EVM (Base) Nabla approve/swap tx creation.
packages/shared/src/services/index.ts	Re-exports contracts via services index.
packages/shared/src/services/evm/clientManager.ts	Adds BaseSepolia to configured EVM networks.
packages/shared/src/helpers/signUnsigned.ts	Adjusts EVM fee multiplier + includes Base in EVM tx grouping.
packages/shared/src/helpers/networks.ts	Adds Networks.BaseSepolia + metadata.
packages/shared/src/endpoints/ramp.endpoints.ts	Extends RampPhase union with Base/EVM-specific phases.
packages/shared/src/contracts/index.ts	New barrel export for contract ABIs.
docs/architecture/ramp-journey-and-fees.md	Updates journey/fees diagram for Base BRL flow.
contracts/relayer/typechain-types/contracts/TokenRelayer.ts	Typechain output tweak (event output object typing).
bun.lock	Moves cobe to workspace catalog usage.
apps/frontend/src/pages/progress/phaseMessages.ts	Adds baseTransfer message mapping (phase messaging).
apps/frontend/src/pages/progress/index.tsx	Adds baseTransfer duration entry.
apps/frontend/src/machines/kyc.states.ts	Updates avenia KYC done-event typing/output access.
apps/frontend/src/machines/brlaKyc.machine.ts	Adjusts machine output typing to return full context.
apps/api/src/models/subsidy.model.ts	Adds ETH as a subsidy token.
apps/api/src/models/partner.model.ts	Adds optional payoutAddressEvm field.
apps/api/src/database/migrations/025-add-payout-address-evm-to-partners.ts	Migration to add payout_address_evm column.
apps/api/src/constants/constants.ts	Adds Base ephemeral starting balance constant export.
apps/api/src/api/services/transactions/validation.ts	Adds EVM-phase mapping + logs for validation.
apps/api/src/api/services/transactions/onramp/routes/monerium-to-evm.ts	Adds isAddress import for destination validation.
apps/api/src/api/services/transactions/onramp/routes/avenia-to-evm.ts	Validates destination EVM address + adds EVM fee distribution helper import.
apps/api/src/api/services/transactions/onramp/routes/avenia-to-evm-base.ts	New Avenia(BRL)→Base→EVM onramp transaction route.
apps/api/src/api/services/transactions/onramp/routes/alfredpay-to-evm.ts	Validates destination EVM address.
apps/api/src/api/services/transactions/onramp/index.ts	Switches Avenia→EVM onramp to Base-based route.
apps/api/src/api/services/transactions/onramp/common/validation.ts	Adds Base-specific Avenia onramp validation (BRLA input token).
apps/api/src/api/services/transactions/onramp/common/transactions.ts	Adds Base Nabla swap tx builder + bumps EVM fee multipliers.
apps/api/src/api/services/transactions/offramp/routes/evm-to-brl-base.ts	New EVM→Base→BRL offramp transaction route.
apps/api/src/api/services/transactions/offramp/index.ts	Switches EVM→BRL offramp to Base-based route.
apps/api/src/api/services/transactions/offramp/common/validation.ts	Temporarily relaxes/changes BRL offramp metadata validation.
apps/api/src/api/services/transactions/common/feeDistribution.ts	Adds EVM fee distribution tx builder + unsigned tx helper.
apps/api/src/api/services/ramp/ramp.service.ts	Updates error messaging for missing EVM ephemeral (Base).
apps/api/src/api/services/quote/routes/strategies/onramp-avenia-to-evm.strategy.ts	Makes BRL fee engine network/token configurable (Moonbeam axlUSDC).
apps/api/src/api/services/quote/routes/strategies/onramp-avenia-to-evm.strategy-base.ts	New Base strategy for BRL onramp to EVM.
apps/api/src/api/services/quote/routes/strategies/offramp-to-stellar.strategy.ts	Uses renamed Moonbeam EVM-initialize engine.
apps/api/src/api/services/quote/routes/strategies/offramp-to-pix.strategy.ts	Updates EVM initialize engine naming/usage.
apps/api/src/api/services/quote/routes/strategies/offramp-to-pix-base.strategy.ts	New Base EVM strategy for PIX offramps.
apps/api/src/api/services/quote/routes/strategies/offramp-evm-to-alfredpay.strategy.ts	Uses generic EVM-initialize engine parameterized by network.
apps/api/src/api/services/quote/routes/route-resolver.ts	Routes BRL onramp to Base strategy and PIX offramps to new EVM strategy.
apps/api/src/api/services/quote/engines/squidrouter/onramp-base-to-evm.ts	New squidrouter engine for Base USDC→destination quoting.
apps/api/src/api/services/quote/engines/squidrouter/index.ts	Adds subsidy merge helpers for squidrouter engines.
apps/api/src/api/services/quote/engines/nabla-swap/onramp-evm.ts	New EVM Nabla swap engine for onramp (BRLA→USDC).
apps/api/src/api/services/quote/engines/nabla-swap/offramp-evm.ts	New EVM Nabla swap engine for offramp (USDC→BRLA).
apps/api/src/api/services/quote/engines/nabla-swap/base-evm.ts	Base class implementing EVM Nabla quoting/ctx assignment.
apps/api/src/api/services/quote/engines/merge-subsidy/offramp-evm.ts	Adds offramp subsidy merge stage for EVM nabla outputs.
apps/api/src/api/services/quote/engines/initialize/onramp-avenia.ts	Skips Moonbeam→Pendulum XCM assignment when not needed.
apps/api/src/api/services/quote/engines/initialize/offramp-from-evm.ts	Renames Moonbeam-specific EVM initialize engine.
apps/api/src/api/services/quote/engines/initialize/offramp-from-evm-alfredpay.ts	Generalizes EVM initialize engine to accept target network.
apps/api/src/api/services/quote/engines/finalize/onramp.ts	Includes BRL in EURC-style finalize path (EVM output).
apps/api/src/api/services/quote/engines/finalize/offramp.ts	Allows PIX offramp amount from nablaSwapEvm for Base path.
apps/api/src/api/services/quote/engines/fee/onramp-brl-to-evm.ts	Parameterizes fee engine by fromNetwork/fromToken (Moonbeam vs Base).
apps/api/src/api/services/quote/engines/fee/offramp-avenia.ts	Allows fee computation from nablaSwapEvm output.
apps/api/src/api/services/quote/engines/discount/onramp.ts	Extends onramp discount to handle Base-USDC flows via squidrouter rate probe.
apps/api/src/api/services/quote/engines/discount/offramp.ts	Extends offramp discount to accept nablaSwapEvm.
apps/api/src/api/services/quote/core/types.ts	Adds MergeSubsidy stage + nablaSwapEvm context.
apps/api/src/api/services/quote/core/nabla.ts	Adds EVM Nabla quoting + (currently) BaseSepolia routing/addresses.
apps/api/src/api/services/phases/register-handlers.ts	Registers Base payout + EVM subsidy handlers.
apps/api/src/api/services/phases/meta-state-types.ts	Adds brlaPayoutTxHash to state metadata.
apps/api/src/api/services/phases/handlers/subsidize-pre-swap-evm-handler.ts	New handler to subsidize pre-swap token balance on Base.
apps/api/src/api/services/phases/handlers/subsidize-post-swap-evm-handler.ts	New handler to subsidize post-swap outputs on Base.
apps/api/src/api/services/phases/handlers/squid-router-phase-handler.ts	Adds Base client selection for BRL squidrouter phases.
apps/api/src/api/services/phases/handlers/squid-router-pay-phase-handler.ts	Adds Base gas payment execution path and subsidy token selection.
apps/api/src/api/services/phases/handlers/nabla-swap-handler.ts	Adds EVM execution path for BRL-involved Nabla swaps.
apps/api/src/api/services/phases/handlers/nabla-approve-handler.ts	Adds EVM execution path for BRL-involved Nabla approvals.
apps/api/src/api/services/phases/handlers/initial-phase-handler.ts	Disables sandbox short-circuit (commented out).
apps/api/src/api/services/phases/handlers/helpers.ts	Fixes Moonbeam helper typo + adds Base funding check helper.
apps/api/src/api/services/phases/handlers/fund-ephemeral-handler.ts	Adds Base ephemeral funding path and updates BRL flow transitions.
apps/api/src/api/services/phases/handlers/distribute-fees-handler.ts	Adds EVM fee distribution submission/wait path.
apps/api/src/api/services/phases/handlers/brla-payout-base-handler.ts	New Base payout handler that triggers BRLA payout + sends Base tx.
apps/api/src/api/services/phases/handlers/brla-onramp-mint-handler.ts	Switches BRLA mint destination from Moonbeam to Base.
apps/api/src/api/controllers/brla.controller.ts	Adjusts KYB endpoint typing + passes redirect URL to service.

Comments suppressed due to low confidence (2)

apps/api/src/api/services/transactions/offramp/common/validation.ts:101

• validateBRLOfframp returns a placeholder offrampAmountBeforeAnchorFeesRaw: "200" (with TODOs). This will make downstream calculations/payout amounts incorrect. Replace the hard-coded value with the correct amount derived from quote metadata for the new Base BRL flow, and restore/adjust the required metadata validation.
  apps/api/src/api/services/phases/handlers/brla-payout-base-handler.ts:131
• BrlaPayoutOnBasePhaseHandler currently uses a hard-coded payOutTicketId = "mocked-ticket-id-for-now" and comments out the actual createPixOutputTicket call. This makes the BRL payout flow non-functional and prevents real settlement. Please remove the mock, call the BRLA API to create the ticket, and persist the returned id for recovery.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ebma]

@copilot please address all the remaining/unresolved comments of this PR (review + code quality comments) with best effort and the solution that seems most sensical to you. For the comment about the fee distribution in the 'distribute-fees-handler.ts', the correct approach is to submit the presigned transaction and not submit if with the servers funding account, just to make clear which solution is the desired one.

[Copilot]

@copilot please address all the remaining/unresolved comments of this PR (review + code quality comments) with best effort and the solution that seems most sensical to you. For the com...

Addressed all remaining unresolved comments in commit d5594ce:

1. distribute-fees-handler.ts - Changed to submit presigned raw EVM transactions via sendRawTransactionWithRetry instead of signing with the server funding account. Also fixed the presigned tx lookup to use "distributeFeesEvm" phase key for EVM flows (was incorrectly using "distributeFees"). Removed unused EvmTransactionData, privateKeyToAccount, and MOONBEAM_FUNDING_PRIVATE_KEY imports.
2. distribute-fees-handler.ts - checkEvmTransactionStatus now requires explicit network parameter (removed default Networks.Base), and the caller passes it correctly.
3. nabla.ts - Removed hard-coded NABLA_ROUTER_BASE and NABLA_QUOTER_BASE addresses. Both are now imported from @vortexfi/shared (added NABLA_QUOTER_BASE to shared constants alongside the existing NABLA_ROUTER_BASE).
4. route-resolver.ts - Restored AssetHub→PIX routing bifurcation: OfframpToPixStrategy for ctx.from === Networks.AssetHub, OfframpToPixEvmStrategy for EVM sources.

The fee splitting concern (all fees going to vortex payout address) is left as-is since it's a design decision that would require additional partner payout infrastructure on EVM.