[WIP] Refactor phase flow and quote logic for composability. by gianfra-t · Pull Request #1232 · pendulum-chain/vortex

gianfra-t · 2026-06-18T18:30:41Z

Implements an explicit definition of phase flow using an array of phases.
- Modifies all the phases to remove transition-specific logic, as it would be handled by the processor itself, based on the array.
Refactor idea that encompass logic currently in the quote engine.

netlify · 2026-06-18T18:30:47Z

✅ Deploy Preview for vortex-sandbox ready!

Name	Link
🔨 Latest commit	`579f673`
🔍 Latest deploy log	https://app.netlify.com/projects/vortex-sandbox/deploys/6a627f6adffdcc0008df02db
😎 Deploy Preview	https://deploy-preview-1232--vortex-sandbox.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

netlify · 2026-06-18T18:30:47Z

✅ Deploy Preview for vortexfi ready!

Name	Link
🔨 Latest commit	`579f673`
🔍 Latest deploy log	https://app.netlify.com/projects/vortexfi/deploys/6a627f6bb9b8500008c9df60
😎 Deploy Preview	https://deploy-preview-1232--vortexfi.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

    const addressKey = `${token.network}-${token.erc20AddressSourceChain?.toLowerCase()}`;
-    const rawBalance = allEvmBalances.get(addressKey);

+    let balance = "0.00";


-    const rawBalance = allEvmBalances.get(addressKey);

+    let balance = "0.00";
+    let balanceUsd = "0.00";


@@ -1,4 +1,4 @@
-import { AlfredpayFiatPaymentInstructions, ExtrinsicOptions, IbanPaymentData } from "@vortexfi/shared";
+import { AlfredpayFiatPaymentInstructions, ExtrinsicOptions, IbanPaymentData, Networks, RampPhase } from "@vortexfi/shared";


…e checks

netlify · 2026-07-16T13:15:01Z

✅ Deploy Preview for vrtx-dashboard canceled.

Name	Link
🔨 Latest commit	`579f673`
🔍 Latest deploy log	https://app.netlify.com/projects/vrtx-dashboard/deploys/6a627f6abc3dd20008b84e38

Each phase module now declares the presigned transactions its executors consume in a sibling <name>.transactions.ts, ported per-phase from the per-flow route-prep (avenia-to-evm-base.ts, cross-chain path). Phases return nonce-free TxIntents in main/backup/cleanup lanes; Flow.prepareTxs allocates nonces per (network, signer) in flow order and assembles stateMeta, with reuseFirstMainNonce reproducing the backupApprove alias. New invariant in the blocks spec: simulate, executors and prepareTxs must each be hermetic, interfacing with other phases only via input/output state and the phase's own metadata key. Parity-tested tx-for-tx (unsignedTxs + stateMeta deep-equal the production route-prep under identical mocks). Still unwired. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

+
+    await new Promise(resolve => setTimeout(resolve, SQUIDROUTER_INITIAL_DELAY_MS));
+
+    while (!isExecuted) {


+          logger.warn(`SquidRouterPayExecutor: No squidRouter status found for swap hash ${swapHash}.`);
+        } else if (squidRouterStatus.status === "success") {
+          logger.info(`SquidRouterPayExecutor: Transaction ${swapHash} successfully executed on Squidrouter.`);
+          isExecuted = true;


+            logger.info(`SquidRouterPayExecutor: Axelar status not found yet for hash ${swapHash}.`);
+          } else if (axelarScanStatus.status === "executed" || axelarScanStatus.status === "express_executed") {
+            logger.info(`SquidRouterPayExecutor: Transaction ${swapHash} successfully executed on Axelar.`);
+            isExecuted = true;


+import {
+  checkEvmBalanceForToken,
+  EvmClientManager,
+  EvmToken,
+  EvmTokenDetails,
+  evmTokenConfig,
+  getOnChainTokenDetails,
+  Networks,
+  RampDirection,
+  RampPhase
+} from "@vortexfi/shared";


+  RampDirection,
+  RampPhase
+} from "@vortexfi/shared";
+import { Big } from "big.js";


+import {
+  checkEvmBalanceForToken,
+  EvmClientManager,
+  EvmNetworks,
+  EvmToken,
+  EvmTokenDetails,
+  getOnChainTokenDetails,
+  Networks,
+  nativeToDecimal,
+  RampCurrency,
+  RampDirection,
+  RampPhase
+} from "@vortexfi/shared";


Copilot

Pull request overview

This WIP refactors quote creation and ramp execution around composable block flows, persisted phase ordering, and catalog-derived executors.

Changes:

Introduces block-based quote simulation, transaction preparation, and execution.
Moves phase transitions into PhaseProcessor using persisted phaseFlow.
Updates clients, shared configuration, tests, and security specifications.

Blocking concerns include incomplete corridor coverage, incompatibility with in-flight legacy ramps, incorrect subsidy cap enforcement, and removal of Nabla preflight simulation.

Reviewed changes

Copilot reviewed 127 out of 127 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`packages/shared/src/tokens/utils/helpers.ts`	Removes Ethereum AXLUSDC fallback.
`packages/shared/src/tokens/freeTokens/config.ts`	Lowers BRL minimum amounts.
`packages/shared/src/tokens/evm/config.ts`	Adds Ethereum AXLUSDC configuration.
`packages/shared/src/services/squidrouter/route-transactions.ts`	Doubles estimated EVM gas fees.
`packages/shared/src/services/squidrouter/offramp.ts`	Uses the selected source EVM client.
`packages/shared/src/helpers/signUnsigned.ts`	Expands supported EVM signing networks.
`packages/shared/src/endpoints/ramp.endpoints.ts`	Extends cleanup and typed-data types.
`packages/sdk/src/services/NetworkManager.ts`	Changes the Hydration endpoint.
`docs/security-spec/05-integrations/mykobo.md`	Documents revised subsidy limits.
`docs/security-spec/05-integrations/brla.md`	Documents revised EVM subsidy limits.
`docs/security-spec/03-ramp-engine/state-machine.md`	Describes catalog-derived registration.
`docs/security-spec/03-ramp-engine/ramp-phase-flows.md`	Documents block-owned phase flows.
`docs/security-spec/03-ramp-engine/quote-lifecycle.md`	Documents block-flow quote lifecycle.
`apps/frontend/src/pages/Onramp.tsx`	Adds fee distribution to on-ramp progress.
`apps/frontend/src/pages/Offramp.tsx`	Adds fee distribution to off-ramp progress.
`apps/frontend/src/components/PhaseProgressBar.tsx`	Adds the fee-distribution phase label.
`apps/dashboard/src/constants/ramp-phases.ts`	Adds fee-distribution phase metadata.
`apps/api/src/api/constants/index.ts`	Defines subsidy floor configuration.
`apps/api/src/api/models/quote.model.ts`	Stores generic block-flow metadata.
`apps/api/src/api/controllers/ramp-status.controller.ts`	Reads block-flow quote metadata.
`apps/api/src/api/services/phases/state.ts`	Adds persisted phase-flow state.
`apps/api/src/api/services/phases/handlers/squid-router-swap-handler.ts`	Removes handler-owned transitions.
`apps/api/src/api/services/phases/handlers/subsidize-post-swap-handler.ts`	Revises subsidy handling and transitions.
`apps/api/src/api/services/phases/handlers/subsidize-pre-swap-handler.ts`	Revises pre-swap subsidy limits.
`apps/api/src/api/services/phases/handlers/nabla-swap-handler.ts`	Removes handler-owned transition logic.
`apps/api/src/api/services/phases/phase-processor.ts`	Resolves transitions from persisted flow order.
`apps/api/src/api/services/phases/index.ts`	Adjusts phase service exports.
`apps/api/src/api/services/phases/register-handlers.ts`	Registers catalog-derived block executors.
`apps/api/src/api/services/quote/types.ts`	Adds block-flow quote types.
`apps/api/src/api/services/quote/index.ts`	Routes quote operations through block flows.
`apps/api/src/api/services/quote/blocks/types.ts`	Defines block interfaces and metadata.
`apps/api/src/api/services/quote/blocks/state.ts`	Defines block execution state.
`apps/api/src/api/services/quote/blocks/simulation/nabla.ts`	Adds shared Nabla simulation support.
`apps/api/src/api/services/quote/blocks/index.ts`	Exports the block-flow subsystem.
`apps/api/src/api/services/quote/blocks/flow/types.ts`	Defines flow contracts.
`apps/api/src/api/services/quote/blocks/flow/index.ts`	Implements flow simulation and assembly.
`apps/api/src/api/services/quote/blocks/flow/simulation-context.ts`	Manages simulation context and metadata.
`apps/api/src/api/services/quote/blocks/combinators/sequence.ts`	Adds sequential block composition.
`apps/api/src/api/services/quote/blocks/combinators/index.ts`	Exports flow combinators.
`apps/api/src/api/services/quote/blocks/combinators/branch.ts`	Adds conditional block composition.
`apps/api/src/api/services/quote/blocks/flows/types.ts`	Defines catalog flow types.
`apps/api/src/api/services/quote/blocks/flows/builders.ts`	Builds supported block flows.
`apps/api/src/api/services/quote/blocks/flows/index.ts`	Exports flow definitions.
`apps/api/src/api/services/quote/blocks/flows/catalog.ts`	Maps requests to currently available flows.
`apps/api/src/api/services/quote/blocks/definitions.ts`	Defines reusable block contracts.
`apps/api/src/api/services/quote/blocks/common.ts`	Adds common block helpers.
`apps/api/src/api/services/quote/blocks/to-evm.ts`	Adds EVM IO conversion helpers.
`apps/api/src/api/services/quote/blocks/phases/types.ts`	Defines phase block types.
`apps/api/src/api/services/quote/blocks/phases/index.ts`	Exports phase blocks.
`apps/api/src/api/services/quote/blocks/phases/fund-ephemeral/simulation.ts`	Simulates ephemeral funding.
`apps/api/src/api/services/quote/blocks/phases/fund-ephemeral/preparation.ts`	Prepares funding transactions.
`apps/api/src/api/services/quote/blocks/phases/fund-ephemeral/execution.ts`	Executes ephemeral funding.
`apps/api/src/api/services/quote/blocks/phases/fund-ephemeral/index.ts`	Defines the funding block.
`apps/api/src/api/services/quote/blocks/phases/destination-transfer/simulation.ts`	Simulates destination transfers.
`apps/api/src/api/services/quote/blocks/phases/destination-transfer/preparation.ts`	Prepares destination transactions.
`apps/api/src/api/services/quote/blocks/phases/destination-transfer/execution.ts`	Executes destination transfers.
`apps/api/src/api/services/quote/blocks/phases/destination-transfer/index.ts`	Defines destination-transfer blocks.
`apps/api/src/api/services/quote/blocks/phases/distribute-fees/simulation.ts`	Simulates fee distribution.
`apps/api/src/api/services/quote/blocks/phases/distribute-fees/preparation.ts`	Prepares fee transactions.
`apps/api/src/api/services/quote/blocks/phases/distribute-fees/execution.ts`	Executes fee distribution.
`apps/api/src/api/services/quote/blocks/phases/distribute-fees/index.ts`	Defines fee-distribution blocks.
`apps/api/src/api/services/quote/blocks/phases/subsidize-pre/simulation.ts`	Simulates pre-swap subsidies.
`apps/api/src/api/services/quote/blocks/phases/subsidize-pre/preparation.ts`	Prepares subsidy transactions.
`apps/api/src/api/services/quote/blocks/phases/subsidize-pre/execution.ts`	Executes pre-swap subsidies.
`apps/api/src/api/services/quote/blocks/phases/subsidize-pre/index.ts`	Defines pre-swap subsidy blocks.
`apps/api/src/api/services/quote/blocks/phases/subsidize-post/simulation.ts`	Simulates post-swap subsidies.
`apps/api/src/api/services/quote/blocks/phases/subsidize-post/execution.ts`	Executes post-swap subsidies.
`apps/api/src/api/services/quote/blocks/phases/subsidize-post/index.ts`	Defines post-swap subsidy blocks.
`apps/api/src/api/services/quote/blocks/phases/squid-router/simulation.ts`	Simulates Squid routes.
`apps/api/src/api/services/quote/blocks/phases/squid-router/preparation.ts`	Prepares Squid transactions.
`apps/api/src/api/services/quote/blocks/phases/squid-router/execution.ts`	Executes and monitors Squid routes.
`apps/api/src/api/services/quote/blocks/phases/squid-router/index.ts`	Defines Squid blocks.
`apps/api/src/api/services/quote/blocks/phases/nabla-swap/simulation.ts`	Simulates Nabla swaps.
`apps/api/src/api/services/quote/blocks/phases/nabla-swap/preparation.ts`	Prepares Nabla swap transactions.
`apps/api/src/api/services/quote/blocks/phases/nabla-swap/execution.ts`	Executes Nabla swaps.
`apps/api/src/api/services/quote/blocks/phases/nabla-swap/index.ts`	Defines Nabla swap blocks.
`apps/api/src/api/services/quote/blocks/phases/nabla-approve/simulation.ts`	Simulates Nabla approvals.
`apps/api/src/api/services/quote/blocks/phases/nabla-approve/preparation.ts`	Prepares approval transactions.
`apps/api/src/api/services/quote/blocks/phases/nabla-approve/execution.ts`	Executes Nabla approvals.
`apps/api/src/api/services/quote/blocks/phases/nabla-approve/index.ts`	Defines Nabla approval blocks.
`apps/api/src/api/services/quote/blocks/phases/final-settlement/simulation.ts`	Captures final-settlement expectations.
`apps/api/src/api/services/quote/blocks/phases/final-settlement/execution.ts`	Verifies final settlement.
`apps/api/src/api/services/quote/blocks/phases/final-settlement/index.ts`	Defines final-settlement blocks.
`apps/api/src/api/services/quote/blocks/phases/block-initial/simulation.ts`	Simulates the initial phase.
`apps/api/src/api/services/quote/blocks/phases/block-initial/execution.ts`	Executes initial phase behavior.
`apps/api/src/api/services/quote/blocks/phases/block-initial/index.ts`	Defines initial blocks.
`apps/api/src/api/services/quote/blocks/phases/alfredpay/onramp-mint/simulation.ts`	Simulates AlfredPay minting.
`apps/api/src/api/services/quote/blocks/phases/alfredpay/onramp-mint/execution.ts`	Executes AlfredPay mint polling.
`apps/api/src/api/services/quote/blocks/phases/alfredpay/onramp-mint/index.ts`	Defines AlfredPay mint blocks.
`apps/api/src/api/services/quote/blocks/phases/brla/onramp-mint/simulation.ts`	Simulates BRLA minting.
`apps/api/src/api/services/quote/blocks/phases/brla/onramp-mint/execution.ts`	Executes BRLA mint polling.
`apps/api/src/api/services/quote/blocks/phases/brla/onramp-mint/index.ts`	Defines BRLA mint blocks.
`apps/api/src/api/services/quote/blocks/execution-helpers.ts`	Adds shared executor helpers.
`apps/api/src/api/services/quote/blocks/register-handlers.ts`	Registers unique catalog executors.
`apps/api/src/api/services/quote/blocks/model-to-state.ts`	Converts persisted models to flow state.
`apps/api/src/api/services/quote/blocks/fee-calculation.ts`	Centralizes block-flow fee calculations.
`apps/api/src/api/services/quote/blocks/validate-block-transaction.ts`	Validates block-generated transactions.
`apps/api/src/api/services/quote/errors.ts`	Adds flow-resolution errors.
`apps/api/src/api/services/quote/types.ts`	Extends quote service contracts.
`apps/api/src/api/services/ramp/ramp.service.ts`	Integrates phase-flow transaction preparation.
`apps/api/src/server.ts`	Registers handlers before workers start.
`apps/api/src/tests/helpers/cleanup.ts`	Updates test cleanup behavior.
`apps/api/src/api/services/quote/blocks/blocks.test.ts`	Tests block composition.
`apps/api/src/api/services/quote/blocks/flow.test.ts`	Tests flow simulation behavior.
`apps/api/src/api/services/quote/blocks/flow-parity.test.ts`	Compares new and legacy flow output.
`apps/api/src/api/services/quote/blocks/flow-wiring.test.ts`	Tests catalog and executor wiring.
`apps/api/src/api/services/quote/blocks/transaction-parity.test.ts`	Compares generated transactions.
`apps/api/src/api/services/phases/phase-processor.cancellation.integration.test.ts`	Updates processor cancellation coverage.

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

-  phaseRegistry.registerHandler(squidRouterPermitExecutionHandler);
-
-  logger.info("Phase handlers registered");
+  registerBlockFlowHandlers();


+  matches(request: FlowRequest): boolean;
+}
+
+const flowDefinitions: FlowDefinition[] = [


+        const subsidyCapFraction = config.subsidy.evmSwapSubsidyQuoteFraction;
+        const percentageCap = Big(quoteOutputUsd).mul(subsidyCapFraction);
+        const subsidyCapUsd = percentageCap.gt("1") ? percentageCap : Big("1");
+        if (Big(subsidyUsd).gt(subsidyCapUsd)) {
+          // Pause for operator intervention without moving the ramp to failed.
+          throw this.createRecoverableError(
+            `SubsidizePostSwapExecutor: Required subsidy $${subsidyUsd} exceeds cap $${subsidyCapUsd.toFixed(2)} (max of $1.00 and ${subsidyCapFraction} of quote output $${quoteOutputUsd}).`


+      const txHash = await baseClient.sendRawTransaction({
+        serializedTransaction: nablaSwapTransaction as `0x${string}`
+      });


@ts-expect-error

The catalog returns bare Flow, so the accumulated Blocks, RegistrationFacts, and RegistrationInput type parameters were erased at the only production consumption point. Drop them and the eight inference helpers that fed them; FlowBuilder now tracks only the output of the most recently composed phase. - start/pipe keep the compile-time adjacency checks, stating them directly in the signature: the next output is inferred from simulate's covariant return position, the input checked contravariantly in place. - Duplicate context keys now throw in build() at module load instead of being rejected by a conditional-type constraint; pinned by a runtime test instead of @ts-expect-error. - Flow-level registration typing is erased (input is Record<string, unknown>, already specified as untrusted and runtime-validated); phases keep their local Registration generics. - Parity tests read typed block metadata via getBlockMetadata with the phase context descriptors instead of the typed Blocks map. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

gianfra-t added 24 commits June 8, 2026 13:11

refactor flow routing logic

c6a2cc6

add morpho deposit flow variant

cc3d30d

check for allowance to await for state sync

6eab26b

Add vault "token" to UI selector

d3e17f9

deposit into destination address, bypass small subsidy cap issue

8a3a5fa

use morphoDeposit as single phase handler

264bd01

adjust dev command

7623656

add bridge step to morpho demo flow

9eec84e

adjust quote service logic

295315f

test flow

92ff6d1

add morpho offramp changes

bb2fd7d

adjust morpho offramp to start from any evm

d69f35c

better permit execution

525707e

fix bug in nabla minimum output calculation

2e7e432

adjust morpho flow from non-base networks

5515a7a

adjust squidrouter pay for Morhpo flow

60d0813

adjust final settlement phase for morpho onramp outside Base

39ee8d2

refactor fund ephemeral handler

3ec7c68

disable intent mocking

5f9fc34

use real ip for intent calling

3795378

first proposal and refactor

b32923e

refactor proposal

049c5a1

update simulation state when subsidizing

6673c75

remove morpho changes

1d3cbac

github-code-quality Bot found potential problems Jun 18, 2026

View reviewed changes

remove opencode config

9dcb75a

gianfra-t changed the title ~~Refactor phase flow and quote logic for composability.~~ [WIP] Refactor phase flow and quote logic for composability. Jun 18, 2026

types improvements, re-implement example flow for refactor, invarianc…

374bff3

…e checks

github-code-quality Bot found potential problems Jul 6, 2026

View reviewed changes

Comment thread apps/api/src/api/services/quote/blocks/phases/squid-router-swap/execution.ts Fixed

Comment thread apps/api/src/api/services/quote/blocks/phases/squid-router-swap/execution.ts Fixed

Comment thread apps/api/src/api/services/quote/blocks/phases/squid-router-swap/execution.ts Fixed

Merge branch 'staging' into refactor-phase-composability

51dab59

gianfra-t and others added 3 commits July 16, 2026 11:15

blocks: add TYPE-SYSTEM.md walkthrough of the FlowBuilder type system

e49e768

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

blocks: split phase layers into directories

3fe45b2

github-code-quality Bot found potential problems Jul 17, 2026

View reviewed changes

gianfra-t added 3 commits July 21, 2026 15:22

blocks: localize simulation metadata ownership

72fe5dd

blocks: add AlfredPay cross-chain flow

4244f39

blocks: wire flow catalog into production

6c87476

Copilot AI review requested due to automatic review settings July 21, 2026 19:35

Copilot started reviewing on behalf of gianfra-t July 21, 2026 19:36 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

gianfra-t and others added 5 commits July 22, 2026 11:43

blocks: add direct onramp flows

e7fdf48

blocks: extend flow core contracts

76dc391

blocks: port remaining ramp corridors

dd4dfcb

blocks: refine cleanup and catalog imports

8353b04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[WIP] Refactor phase flow and quote logic for composability.#1232

[WIP] Refactor phase flow and quote logic for composability.#1232
gianfra-t wants to merge 38 commits into
stagingfrom
refactor-phase-composability

gianfra-t commented Jun 18, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

netlify Bot commented Jul 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,4 +1,4 @@
		import { AlfredpayFiatPaymentInstructions, ExtrinsicOptions, IbanPaymentData } from "@vortexfi/shared";
		import { AlfredpayFiatPaymentInstructions, ExtrinsicOptions, IbanPaymentData, Networks, RampPhase } from "@vortexfi/shared";


		await new Promise(resolve => setTimeout(resolve, SQUIDROUTER_INITIAL_DELAY_MS));

		while (!isExecuted) {

Uh oh!

Conversation

gianfra-t commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vortex-sandbox ready!

Uh oh!

netlify Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vortexfi ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

netlify Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vrtx-dashboard canceled.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gianfra-t commented Jun 18, 2026 •

edited

Loading

netlify Bot commented Jun 18, 2026 •

edited

Loading

netlify Bot commented Jun 18, 2026 •

edited

Loading

netlify Bot commented Jul 16, 2026 •

edited

Loading