@keetanetwork/anchor 0.0.69 → 0.0.71

package/lib/chaining.js

@@ -11,6 +11,7 @@ import { isExternalChainAsset } from './asset.js';
 ;
 ;
 ;
+;
 function areBothTokenAndEqual(a, b) {
     try {
         const aParsed = KeetaNet.lib.Account.toAccount(a);
@@ -129,6 +130,11 @@ class AnchorGraph {
             if (!fromEntries) {
                 return (null);
             }
+            const operations = await service.operations('object');
+            if (!operations.createExchange) {
+                this.logger?.debug('AnchorGraph::computeFXNodes', `FX service ${providerID} does not support createExchange operation, skipping`);
+                return (null);
+            }
             const pathNodes = await Promise.all(fromEntries.map(async function (fromEntry) {
                 const pathNodesResult = [];
                 const parsedEntry = await fromEntry('object');
@@ -224,7 +230,33 @@ class AnchorGraph {
         if (!isRail(railResolved)) {
             throw (new Error(`Invalid rail format in extended details: ${railResolved}`));
         }
-        return ({ rail: railResolved });
+        let supportedOperations;
+        if ('supportedOperations' in extendedDetailsResolved && extendedDetailsResolved.supportedOperations) {
+            const opsResolved = await extendedDetailsResolved.supportedOperations('object');
+            if (opsResolved && typeof opsResolved === 'object' && !Array.isArray(opsResolved)) {
+                const parsed = {};
+                if ('createPersistentForwarding' in opsResolved && opsResolved.createPersistentForwarding) {
+                    const val = await opsResolved.createPersistentForwarding('boolean');
+                    if (typeof val === 'boolean') {
+                        parsed.createPersistentForwarding = val;
+                    }
+                }
+                if ('initiateTransfer' in opsResolved && opsResolved.initiateTransfer) {
+                    const val = await opsResolved.initiateTransfer('boolean');
+                    if (typeof val === 'boolean') {
+                        parsed.initiateTransfer = val;
+                    }
+                }
+                if (Object.keys(parsed).length > 0) {
+                    supportedOperations = parsed;
+                }
+            }
+        }
+        const result = { rail: railResolved };
+        if (supportedOperations) {
+            result.supportedOperations = supportedOperations;
+        }
+        return (result);
     }
     async #computeAssetMovementPairSide(pairSideInput) {
         const pairSideResolved = await pairSideInput('object');
@@ -242,13 +274,13 @@ class AnchorGraph {
         const railsResolved = await pairSideResolved.rails('object');
         const rails = {
             common: await Promise.all((await railsResolved.common?.('array'))?.map(async (commonInput) => {
-                return ((await this.#computeAssetRails(commonInput)).rail);
+                return (await this.#computeAssetRails(commonInput));
             }) ?? []),
             inbound: await Promise.all((await railsResolved.inbound?.('array'))?.map(async (commonInput) => {
-                return ((await this.#computeAssetRails(commonInput)).rail);
+                return (await this.#computeAssetRails(commonInput));
             }) ?? []),
             outbound: await Promise.all((await railsResolved.outbound?.('array'))?.map(async (commonInput) => {
-                return ((await this.#computeAssetRails(commonInput)).rail);
+                return (await this.#computeAssetRails(commonInput));
             }) ?? [])
         };
         const id = await pairSideResolved.id('string');
@@ -267,6 +299,7 @@ class AnchorGraph {
             return ([]);
         }
         const providerResults = await Promise.all(Object.entries(assetMovementServices).map(async ([providerID, service]) => {
+            const supportedOperationsMetadata = await service.operations('object');
             const supportedAssetsEntries = await service.supportedAssets('array');
             if (!supportedAssetsEntries) {
                 this.logger?.debug('AnchorGraph::computeAssetMovementNodes', `No supported assets found for provider ${providerID}`);
@@ -282,18 +315,49 @@ class AnchorGraph {
                         this.#computeAssetMovementPairSide(pairResolved[0]),
                         this.#computeAssetMovementPairSide(pairResolved[1])
                     ]);
+                    function getProviderSupportedOperationsForRail(railSpecific) {
+                        const retval = {
+                            createPersistentForwarding: supportedOperationsMetadata.createPersistentForwarding !== undefined,
+                            initiateTransfer: supportedOperationsMetadata.initiateTransfer !== undefined
+                        };
+                        if (railSpecific) {
+                            retval.createPersistentForwarding = railSpecific.createPersistentForwarding ?? false;
+                            retval.initiateTransfer = railSpecific.initiateTransfer ?? false;
+                        }
+                        return (retval);
+                    }
                     const pathNodes = [];
                     for (const [src, dest] of [
                         [fromResolved, toResolved],
                         [toResolved, fromResolved]
                     ]) {
                         for (const inboundRail of [...(src.rails.common ?? []), ...(src.rails.inbound ?? [])]) {
+                            /*
+                             * Drop edges whose source rail explicitly cannot
+                             * initiate a transfer and also cannot create a
+                             * persistent forwarding address.
+                             */
+                            const inboundSupportedOperations = getProviderSupportedOperationsForRail(inboundRail.supportedOperations);
+                            if (inboundSupportedOperations.initiateTransfer === false && inboundSupportedOperations.createPersistentForwarding === false) {
+                                this.logger?.debug('AnchorGraph::computeAssetMovementNodes', `Skipping ${providerID} edge from ${convertAssetLocationToString(src.location)} via rail ${inboundRail.rail}: neither initiateTransfer nor createPersistentForwarding supported`);
+                                continue;
+                            }
                             for (const outboundRail of [...(dest.rails.common ?? []), ...(dest.rails.outbound ?? [])]) {
                                 pathNodes.push({
                                     type: 'assetMovement',
                                     providerID: providerID,
-                                    from: { asset: src.id, location: src.location, rail: inboundRail },
-                                    to: { asset: dest.id, location: dest.location, rail: outboundRail }
+                                    from: {
+                                        asset: src.id,
+                                        location: src.location,
+                                        rail: inboundRail.rail,
+                                        supportedOperations: getProviderSupportedOperationsForRail(inboundRail.supportedOperations)
+                                    },
+                                    to: {
+                                        asset: dest.id,
+                                        location: dest.location,
+                                        rail: outboundRail.rail,
+                                        supportedOperations: getProviderSupportedOperationsForRail(outboundRail.supportedOperations)
+                                    }
                                 });
                             }
                         }
@@ -580,39 +644,35 @@ class AnchorGraph {
             return (result.to);
         }
     }
-    async #attachMetadata(assetInfo, options) {
-        if (!isExternalChainAsset(assetInfo.asset)) {
-            return (assetInfo);
+    async getExternalAssetMetadata(asset, location, providerID) {
+        if (!isExternalChainAsset(asset)) {
+            return (undefined);
         }
-        const providers = await this.getAssetMovementProvidersForAsset(assetInfo.asset, assetInfo.location);
+        const providers = await this.getAssetMovementProvidersForAsset(asset, location);
         if (!providers) {
-            return (assetInfo);
+            return (undefined);
         }
-        if (options?.providerID) {
-            const found = providers[options.providerID];
+        if (providerID) {
+            const found = providers[providerID];
             if (!found) {
-                return (assetInfo);
+                return (undefined);
             }
-            const metadata = found.provider.getAssetMetadataForLocation(assetInfo.location, assetInfo.asset);
-            if (!metadata) {
-                return (assetInfo);
-            }
-            return ({
-                ...assetInfo,
-                metadata
-            });
+            return (found.provider.getAssetMetadataForLocation(location, asset) ?? undefined);
         }
         for (const { provider } of Object.values(providers)) {
-            const metadata = provider.getAssetMetadataForLocation(assetInfo.location, assetInfo.asset);
-            if (!metadata) {
-                continue;
+            const metadata = provider.getAssetMetadataForLocation(location, asset);
+            if (metadata) {
+                return (metadata);
             }
-            return ({
-                ...assetInfo,
-                metadata
-            });
         }
-        return (assetInfo);
+        return (undefined);
+    }
+    async #attachMetadata(assetInfo, options) {
+        const metadata = await this.getExternalAssetMetadata(assetInfo.asset, assetInfo.location, options?.providerID);
+        if (!metadata) {
+            return (assetInfo);
+        }
+        return ({ ...assetInfo, metadata });
     }
     async resolveAssetsWithMetadata(filter = {}, options) {
         const result = await this.resolveAssets(filter);
@@ -773,13 +833,118 @@ export class AnchorChainingPlan extends AnchorChainingPath {
             }
             return (found);
         };
+        const forwardedSteps = new Map();
+        for (let scanIndex = 0; scanIndex < this.path.length; scanIndex++) {
+            const scanStep = this.path[scanIndex];
+            if (!scanStep || scanStep.type !== 'assetMovement') {
+                continue;
+            }
+            /**
+             * PFR is selected in two cases:
+             *   (a) the source rail explicitly cannot accept a managed transfer.
+             *   (b) the prior step is also an asset-movement step (AMP -> AMP
+             *       transition) and the source rail supports PFR.
+             */
+            const priorStep = scanIndex > 0 ? this.path[scanIndex - 1] : null;
+            const isAmpToAmpTransition = priorStep?.type === 'assetMovement';
+            const pfrSupported = scanStep.from.supportedOperations?.createPersistentForwarding === true;
+            const initiateForbidden = scanStep.from.supportedOperations?.initiateTransfer === false;
+            const shouldUsePFR = initiateForbidden || (isAmpToAmpTransition && pfrSupported);
+            if (!shouldUsePFR) {
+                continue;
+            }
+            if (!pfrSupported) {
+                throw (new Error(`Asset movement provider ${scanStep.providerID} source rail ${scanStep.from.rail} at ${convertAssetLocationToString(scanStep.from.location)} declares initiateTransfer:false but does not support createPersistentForwarding`));
+            }
+            if (scanIndex !== this.path.length - 1) {
+                throw (new Error(`Persistent-forwarding (PersistentForwardingRelay-only) asset movement steps are currently only supported as the last step in a chain (step ${scanIndex} of ${this.path.length})`));
+            }
+            const destinationAddress = this.request.destination.recipient;
+            if (typeof destinationAddress !== 'string') {
+                throw (new Error(`Persistent-forwarding step at index ${scanIndex} requires the chain's destination recipient to be a resolved address string`));
+            }
+            const forwardedAssetPair = { from: scanStep.from.asset, to: scanStep.to.asset };
+            const forwardedProviders = await assetMovementClient.getProvidersForTransfer({ asset: forwardedAssetPair, from: scanStep.from.location, to: scanStep.to.location }, { providerIDs: [scanStep.providerID] });
+            if (!forwardedProviders?.[0] || forwardedProviders.length === 0) {
+                throw (new Error(`Could not get asset movement provider ${scanStep.providerID} for persistent-forwarding step at index ${scanIndex}`));
+            }
+            const forwardedProvider = forwardedProviders[0];
+            if (!await forwardedProvider.isOperationSupported('createPersistentForwarding')) {
+                throw (new Error(`Asset movement provider ${scanStep.providerID} does not support createPersistentForwarding, but the source rail ${scanStep.from.rail} at ${convertAssetLocationToString(scanStep.from.location)} requires it (initiateTransfer is unsupported)`));
+            }
+            if (!await forwardedProvider.isOperationSupported('simulateTransfer')) {
+                throw (new Error(`Asset movement provider ${scanStep.providerID} does not support simulateTransfer, which is required to compute valueOut for a persistent-forwarding step at ${convertAssetLocationToString(scanStep.from.location)}`));
+            }
+            const { signer: forwardedSigner } = await this.getAccountsForAction({
+                type: 'assetMovement',
+                providerMethod: 'initiateTransfer',
+                provider: forwardedProvider
+            }, this.#options?.overrides);
+            let persistentAddress;
+            if (await forwardedProvider.isOperationSupported('listPersistentForwarding')) {
+                try {
+                    const existing = await forwardedProvider.listForwardingAddresses({
+                        account: forwardedSigner,
+                        search: [{
+                                sourceLocation: scanStep.from.location,
+                                destinationLocation: scanStep.to.location,
+                                asset: scanStep.from.asset,
+                                destinationAddress
+                            }]
+                    });
+                    /*
+                     * Filter to the exact address this step requires.
+                     */
+                    const sourceLocationString = convertAssetLocationToString(scanStep.from.location);
+                    const destLocationString = convertAssetLocationToString(scanStep.to.location);
+                    const match = existing.addresses.find(addr => {
+                        if (addr.destinationAddress !== destinationAddress) {
+                            return (false);
+                        }
+                        if (!addr.sourceLocation || convertAssetLocationToString(addr.sourceLocation) !== sourceLocationString) {
+                            return (false);
+                        }
+                        if (!addr.destinationLocation || convertAssetLocationToString(addr.destinationLocation) !== destLocationString) {
+                            return (false);
+                        }
+                        return (true);
+                    });
+                    if (match) {
+                        persistentAddress = match;
+                    }
+                }
+                catch (error) {
+                    this.logger?.debug('AnchorChainingPlan::computePlan', `listForwardingAddresses lookup failed for step ${scanIndex}, will create a new address`, error);
+                }
+            }
+            if (!persistentAddress) {
+                persistentAddress = await forwardedProvider.createPersistentForwardingAddress({
+                    account: forwardedSigner,
+                    sourceLocation: scanStep.from.location,
+                    destinationLocation: scanStep.to.location,
+                    destinationAddress,
+                    asset: forwardedAssetPair
+                });
+            }
+            if (typeof persistentAddress.address !== 'string') {
+                throw (new Error(`Persistent forwarding address for step ${scanIndex} is not a resolved string (got ${typeof persistentAddress.address})`));
+            }
+            forwardedSteps.set(scanIndex, { provider: forwardedProvider, persistentAddress });
+        }
         const stepPromises = [];
         const resolvingSteps = new Set();
+        const precomputedValueOuts = new Map();
         const resolveStep = async (index) => {
             const step = this.path[index];
             if (!step) {
                 throw (new Error(`Step ${index} is not defined`));
             }
+            /*
+             * Detect cycles
+             */
+            if (resolvingSteps.has(index)) {
+                throw (new Error(`Cyclic dependency detected in resolveStep: step ${index} is already being resolved`));
+            }
             let promise = stepPromises[index];
             if (!promise) {
                 resolvingSteps.add(index);
@@ -817,6 +982,9 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                             throw (new Error(`Could not get FX quote/estimate for provider ${step.providerID}`));
                         }
                         const result = quotesOrEstimates[0];
+                        if (!result.isQuote && result.estimate.canPerformExchange === false) {
+                            throw (new Error(`FX estimate from provider ${step.providerID} indicates exchange cannot be performed`));
+                        }
                         const convertedAmount = result.isQuote ? result.quote.convertedAmount : result.estimate.convertedAmount;
                         let valueIn;
                         let valueOut;
@@ -834,10 +1002,88 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                         return ({ type: 'fx', step, valueIn, valueOut, result });
                     }
                     else if (step.type === 'assetMovement') {
-                        let recipient;
+                        if (affinity === 'to') {
+                            throw (new Error(`Chaining with affinity 'to' is not currently supported for asset movement steps, as it requires looking up transfer quotes/estimates which is not currently implemented`));
+                        }
+                        let depositValue;
+                        if (index === 0) {
+                            depositValue = affinityAndAmount.amount;
+                        }
+                        else {
+                            const precomputedPrev = precomputedValueOuts.get(index - 1);
+                            if (precomputedPrev !== undefined) {
+                                depositValue = precomputedPrev;
+                            }
+                            else {
+                                const previous = await resolveStep(index - 1);
+                                depositValue = previous.valueOut;
+                            }
+                        }
+                        const assetPair = { from: step.from.asset, to: step.to.asset };
+                        /*
+                         * Forwarded step: prior step deposits into a pre-resolved persistent address.
+                         */
+                        const forwardedInfo = forwardedSteps.get(index);
+                        if (forwardedInfo) {
+                            const { provider: forwardedProvider, persistentAddress } = forwardedInfo;
+                            /*
+                             * Best-effort plan-time valueOut: simulateTransfer if available,
+                             * otherwise assume no rail fee.
+                             */
+                            let estimatedValueOut = depositValue;
+                            if (await forwardedProvider.isOperationSupported('simulateTransfer')) {
+                                try {
+                                    const { signer: forwardedSigner } = await this.getAccountsForAction({
+                                        type: 'assetMovement',
+                                        providerMethod: 'initiateTransfer',
+                                        provider: forwardedProvider
+                                    }, this.#options?.overrides);
+                                    const simulated = await forwardedProvider.simulateTransfer({
+                                        account: forwardedSigner,
+                                        asset: assetPair,
+                                        from: { location: step.from.location },
+                                        to: { location: step.to.location },
+                                        value: depositValue
+                                    });
+                                    const simulatedInstruction = simulated.instructions.find((instr) => instr.type === step.from.rail);
+                                    let simulatedTotalReceive;
+                                    if (simulatedInstruction) {
+                                        simulatedTotalReceive = simulatedInstruction.totalReceiveAmount;
+                                        if (simulatedTotalReceive === undefined && 'value' in simulatedInstruction) {
+                                            simulatedTotalReceive = simulatedInstruction.value;
+                                        }
+                                    }
+                                    if (simulatedTotalReceive !== undefined) {
+                                        estimatedValueOut = BigInt(simulatedTotalReceive);
+                                    }
+                                }
+                                catch (error) {
+                                    this.logger?.debug('AnchorChainingPlan::resolveStep', `simulateTransfer for forwarded step ${index} valueOut estimation failed; falling back to depositValue`, error);
+                                }
+                            }
+                            return ({
+                                type: 'forwarded',
+                                step,
+                                valueIn: depositValue,
+                                valueOut: estimatedValueOut,
+                                persistentAddress,
+                                provider: forwardedProvider
+                            });
+                        }
+                        const providers = await assetMovementClient.getProvidersForTransfer({ asset: assetPair, from: step.from.location, to: step.to.location }, { providerIDs: [step.providerID] });
+                        if (!providers?.[0] || providers.length === 0) {
+                            throw (new Error(`Could not get asset movement provider ${step.providerID}`));
+                        }
+                        const provider = providers[0];
+                        const { signer } = await this.getAccountsForAction({
+                            type: 'assetMovement',
+                            providerMethod: 'initiateTransfer',
+                            provider
+                        }, this.#options?.overrides);
+                        let resolvedRecipient;
                         let sendingToType;
                         if (index === this.path.length - 1) {
-                            recipient = this.request.destination.recipient;
+                            resolvedRecipient = this.request.destination.recipient;
                             sendingToType = 'FINAL_DESTINATION';
                         }
                         else {
@@ -846,91 +1092,99 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                             if (!nextPathStep) {
                                 throw (new Error(`Expected next step at index ${index + 1} for asset movement step at index ${index}`));
                             }
-                            if (nextPathStep.from.location === `chain:keeta:${this.parent['client'].network}`) {
+                            /*
+                             * Next step is forwarded: recipient is its persistent address,
+                             * no need to resolve the next step's instructions.
+                             */
+                            const nextForwardedInfo = forwardedSteps.get(index + 1);
+                            if (nextForwardedInfo) {
+                                const pfiAddress = nextForwardedInfo.persistentAddress.address;
+                                if (typeof pfiAddress !== 'string') {
+                                    throw (new Error(`Persistent forwarding address for next step ${index + 1} is not a resolved string`));
+                                }
+                                resolvedRecipient = pfiAddress;
+                            }
+                            else if (nextPathStep.from.location === `chain:keeta:${this.parent['client'].network}`) {
                                 const { account } = await this.getAccountsForAction({
                                     type: 'assetMovement',
                                     providerMethod: 'initiateTransfer'
                                 }, this.#options?.overrides);
                                 // Store funds in-transit in the account instead of forwarding directly to provider.
-                                recipient = account;
+                                resolvedRecipient = account;
                             }
                             else {
-                                recipient = async () => {
-                                    const nextStep = await resolveStep(index + 1);
-                                    if (nextStep.type === 'assetMovement' || nextStep.type === 'keetaSend') {
-                                        if (nextStep.usingInstruction.type !== step.to.rail) {
-                                            throw (new Error(`Next step's usingInstruction type ${nextStep.usingInstruction.type} does not match expected ${step.to.rail} for recipient resolution`));
-                                        }
-                                        const foundInstruction = nextStep.usingInstruction;
-                                        const isFiatPushRailFoundInstruction = (input) => {
-                                            return (isFiatRail(input.type));
-                                        };
-                                        if (foundInstruction.type === 'KEETA_SEND') {
-                                            throw (new Error(`Cannot currently chain from asset movement to KEETA_SEND step, as this implies multiple keeta locations in the path which is not currently supported`));
-                                        }
-                                        else if (isFiatPushRailFoundInstruction(foundInstruction)) {
-                                            if (foundInstruction.depositMessage) {
-                                                throw (new Error(`Deposit message outbound is not currently supported for chaining`));
-                                            }
-                                            return (foundInstruction.account);
-                                        }
-                                        else {
-                                            throw (new Error(`Unsupported rail for chaining: ${step.to.rail}`));
+                                /**
+                                 * If the provider does not support simulateTransfer,
+                                 * we cannot chain to this step.
+                                 */
+                                if (!await provider.isOperationSupported('simulateTransfer')) {
+                                    throw (new Error(`Asset movement provider ${step.providerID} does not support simulateTransfer, which is required for chaining at non-keeta intermediate location ${convertAssetLocationToString(nextPathStep.from.location)}`));
+                                }
+                                const simulated = await provider.simulateTransfer({
+                                    account: signer,
+                                    asset: assetPair,
+                                    from: { location: step.from.location },
+                                    to: { location: step.to.location },
+                                    value: depositValue
+                                });
+                                const simulatedInstruction = simulated.instructions.find((instr) => instr.type === step.from.rail);
+                                if (!simulatedInstruction) {
+                                    throw (new Error(`Simulated transfer for step ${index} did not return an instruction matching rail ${step.from.rail}`));
+                                }
+                                let simulatedTotalReceive = simulatedInstruction.totalReceiveAmount;
+                                if (simulatedTotalReceive === undefined && 'value' in simulatedInstruction) {
+                                    simulatedTotalReceive = simulatedInstruction.value;
+                                }
+                                if (simulatedTotalReceive === undefined) {
+                                    throw (new Error(`totalReceiveAmount must be defined for simulated transfer when chaining`));
+                                }
+                                precomputedValueOuts.set(index, BigInt(simulatedTotalReceive));
+                                const nextStep = await resolveStep(index + 1);
+                                if (nextStep.type === 'assetMovement' || nextStep.type === 'keetaSend') {
+                                    if (nextStep.usingInstruction.type !== step.to.rail) {
+                                        throw (new Error(`Next step's usingInstruction type ${nextStep.usingInstruction.type} does not match expected ${step.to.rail} for recipient resolution`));
+                                    }
+                                    const foundInstruction = nextStep.usingInstruction;
+                                    const isFiatPushRailFoundInstruction = (input) => {
+                                        return (isFiatRail(input.type));
+                                    };
+                                    if (foundInstruction.type === 'KEETA_SEND') {
+                                        throw (new Error(`Cannot currently chain from asset movement to KEETA_SEND step, as this implies multiple keeta locations in the path which is not currently supported`));
+                                    }
+                                    else if (isFiatPushRailFoundInstruction(foundInstruction)) {
+                                        if (foundInstruction.depositMessage) {
+                                            throw (new Error(`Deposit message outbound is not currently supported for chaining`));
                                         }
+                                        resolvedRecipient = foundInstruction.account;
                                     }
-                                    else if (nextStep.type === 'fx') {
-                                        throw (new Error(`Cannot currently chain from asset movement to fx step, as fx step does not have recipient information`));
+                                    else if (foundInstruction.type === 'EVM_SEND') {
+                                        resolvedRecipient = foundInstruction.sendToAddress;
                                     }
                                     else {
-                                        assertNever(nextStep);
+                                        throw (new Error(`Unsupported rail for chaining: ${step.to.rail}`));
                                     }
-                                };
-                            }
-                        }
-                        const assetPair = { from: step.from.asset, to: step.to.asset };
-                        const providers = await assetMovementClient.getProvidersForTransfer({ asset: assetPair, from: step.from.location, to: step.to.location }, { providerIDs: [step.providerID] });
-                        if (!providers?.[0] || providers.length === 0) {
-                            throw (new Error(`Could not get asset movement provider ${step.providerID}`));
-                        }
-                        let depositValue;
-                        if (affinity === 'to') {
-                            throw (new Error(`Chaining with affinity 'to' is not currently supported for asset movement steps, as it requires looking up transfer quotes/estimates which is not currently implemented`));
-                        }
-                        else {
-                            if (index === 0) {
-                                depositValue = affinityAndAmount.amount;
-                            }
-                            else {
-                                const previous = await resolveStep(index - 1);
-                                depositValue = previous.valueOut;
+                                }
+                                else if (nextStep.type === 'fx') {
+                                    throw (new Error(`Cannot currently chain from asset movement to fx step, as fx step does not have recipient information`));
+                                }
+                                else if (nextStep.type === 'forwarded') {
+                                    throw (new Error(`Internal invariant violation: forwarded step at index ${index + 1} reached simulate-cycle-break path; expected nextForwardedInfo branch to have handled it`));
+                                }
+                                else {
+                                    assertNever(nextStep);
+                                }
                             }
                         }
-                        const { signer } = await this.getAccountsForAction({
-                            type: 'assetMovement',
-                            providerMethod: 'initiateTransfer',
-                            provider: providers[0]
-                        }, this.#options?.overrides);
-                        const transfer = await providers[0].initiateTransfer({
+                        const recipientString = KeetaNet.lib.Account.isInstance(resolvedRecipient)
+                            ? resolvedRecipient.publicKeyString.get()
+                            : resolvedRecipient;
+                        const transfer = await provider.initiateTransfer({
                             account: signer,
                             asset: assetPair,
                             from: { location: step.from.location },
                             to: {
                                 location: step.to.location,
-                                recipient: await (async () => {
-                                    let recipientResolved;
-                                    if (typeof recipient === 'function') {
-                                        recipientResolved = await recipient();
-                                    }
-                                    else {
-                                        recipientResolved = recipient;
-                                    }
-                                    if (KeetaNet.lib.Account.isInstance(recipientResolved)) {
-                                        return (recipientResolved.publicKeyString.get());
-                                    }
-                                    else {
-                                        return (recipientResolved);
-                                    }
-                                })()
+                                recipient: recipientString
                             },
                             value: depositValue
                         });
@@ -942,6 +1196,14 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                         if (totalReceiveAmount === undefined) {
                             throw (new Error(`totalReceiveAmount must be defined for chaining`));
                         }
+                        const actualValueOut = BigInt(totalReceiveAmount);
+                        // If we simulated to break a cycle, the next step's initiateTransfer was
+                        // keyed off the simulated valueOut; a mismatch here means the next step
+                        // is now misaligned, so fail at plan-time instead of letting execute() catch it.
+                        const simulatedValueOut = precomputedValueOuts.get(index);
+                        if (simulatedValueOut !== undefined && simulatedValueOut !== actualValueOut) {
+                            throw (new Error(`Simulated valueOut ${simulatedValueOut} for step ${index} does not match actual ${actualValueOut} from initiateTransfer`));
+                        }
                         return ({
                             type: 'assetMovement',
                             step,
@@ -949,7 +1211,7 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                             usingInstruction: usingInstruction,
                             transfer: transfer,
                             sendingTo: sendingToType,
-                            valueOut: BigInt(totalReceiveAmount)
+                            valueOut: actualValueOut
                         });
                     }
                     else if (step.type === 'keetaSend') {
@@ -1000,9 +1262,6 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                 promise.then(() => resolvingSteps.delete(index), () => resolvingSteps.delete(index));
                 stepPromises[index] = promise;
             }
-            else if (resolvingSteps.has(index)) {
-                throw (new Error(`Cyclic dependency detected in resolveStep: step ${index} is already being resolved`));
-            }
             return (await promise);
         };
         const steps = [];
@@ -1140,6 +1399,9 @@ export class AnchorChainingPlan extends AnchorChainingPath {
         const timeoutMs = options?.timeoutMs ?? 300_000;
         const deadline = Date.now() + timeoutMs;
         while (true) {
+            if (options?.abortSignal?.aborted) {
+                throw (new Error(`Aborted while waiting for transfer ${transfer.transferId} to complete`));
+            }
             const status = await transfer.getTransferStatus();
             if (status.transaction.status === 'COMPLETE') {
                 return (status);
@@ -1150,11 +1412,61 @@ export class AnchorChainingPlan extends AnchorChainingPath {
             await KeetaNet.lib.Utils.Helper.asleep(intervalMs);
         }
     }
+    /**
+     * Wait for the forwarded transfer the bridge creates after observing the
+     * prior step's withdraw deposit in the persistent-forwarding address.
+     */
+    async #pollForwardedTransaction(step, sourceTransaction, options) {
+        const intervalMs = options?.intervalMs ?? 2000;
+        const timeoutMs = options?.timeoutMs ?? 300_000;
+        const deadline = Date.now() + timeoutMs;
+        const { provider, persistentAddress } = step;
+        const pfiAddress = persistentAddress.address;
+        if (typeof pfiAddress !== 'string') {
+            throw (new Error(`Persistent forwarding address must be a resolved string`));
+        }
+        const { account } = await this.getAccountsForAction({
+            type: 'assetMovement',
+            providerMethod: 'initiateTransfer',
+            provider
+        }, this.#options?.overrides);
+        while (true) {
+            if (options?.abortSignal?.aborted) {
+                throw (new Error(`Aborted while waiting for forwarded transaction at ${pfiAddress} correlated to source tx ${sourceTransaction.transaction.id}`));
+            }
+            let transactions = [];
+            try {
+                const response = await provider.listTransactions({
+                    account,
+                    persistentAddresses: [{
+                            location: step.step.from.location,
+                            persistentAddress: pfiAddress
+                        }],
+                    transactions: [sourceTransaction]
+                });
+                transactions = response.transactions;
+            }
+            catch (error) {
+                this.logger?.debug('AnchorChainingPlan::pollForwardedTransaction', `listTransactions failed for PersistentForwardingRelay address ${pfiAddress}`, error);
+            }
+            const candidate = transactions.find(tx => tx.status === 'COMPLETE');
+            if (candidate) {
+                return (candidate);
+            }
+            if (Date.now() >= deadline) {
+                throw (new Error(`Timed out waiting for persistent-forwarding transaction at ${pfiAddress} correlated to source tx ${sourceTransaction.transaction.id}`));
+            }
+            await KeetaNet.lib.Utils.Helper.asleep(intervalMs);
+        }
+    }
     async #pollExchangeStatus(exchange, options) {
         const intervalMs = options?.intervalMs ?? 2000;
         const timeoutMs = options?.timeoutMs ?? 300_000;
         const deadline = Date.now() + timeoutMs;
         while (true) {
+            if (options?.abortSignal?.aborted) {
+                throw (new Error(`Aborted while waiting for FX exchange ${exchange.exchange.exchangeID} to complete`));
+            }
             const status = await exchange.getExchangeStatus();
             if (status.status === 'completed') {
                 return (status);
@@ -1174,11 +1486,23 @@ export class AnchorChainingPlan extends AnchorChainingPath {
         }
         const executedSteps = [];
         this.#setState({ status: 'executing', completedSteps: [], currentStepIndex: 0 });
-        // Actual output value from each completed step, used for equality checking.
+        /*
+         * Actual output value from each completed step, used for equality checking.
+         */
         let prevActualValueOut = null;
+        /**
+         * Source-tx anchor for the next forwarded step's poll. Populated only
+         * when the prior step is an asset-movement transfer that produced a
+         * withdraw transaction on its destination chain; reset for any step
+         * type that cannot deposit into a persistent-forwarding address.
+         */
+        let prevWithdrawTx = null;
         let index = 0;
         try {
             for (index = 0; index < this.plan.steps.length; index++) {
+                if (options?.abortSignal?.aborted) {
+                    throw (new Error(`Execution aborted`));
+                }
                 const onStepCompleted = (step) => {
                     executedSteps.push(step);
                     this.#emit('stepExecuted', step, index);
@@ -1193,16 +1517,32 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                 // different amount than was negotiated in computeSteps.
                 if (index > 0 && prevActualValueOut !== null) {
                     if (prevActualValueOut !== step.valueIn) {
-                        throw (new Error(`Value mismatch at step ${index}: ` +
-                            `expected ${step.valueIn} but previous step produced ${prevActualValueOut}`));
+                        if (prevActualValueOut < step.valueIn) {
+                            throw (new Error(`Execution failed at step ${index} due to value mismatch: expected at least ${step.valueIn} but previous step produced ${prevActualValueOut}`));
+                        }
+                        else {
+                            this.logger?.debug(`AnchorChainingPlan::execute`, `Value mismatch at step ${index} is non-critical since previous step produced more (${prevActualValueOut}) than expected (${step.valueIn}), proceeding with execution`);
+                        }
                     }
                 }
                 if (step.type === 'fx') {
                     const exchange = await step.result.createExchange();
                     await this.#pollExchangeStatus(exchange);
                     prevActualValueOut = step.valueOut;
+                    prevWithdrawTx = null;
                     onStepCompleted({ type: 'fx', plan: step, exchange });
                 }
+                else if (step.type === 'forwarded') {
+                    if (!prevWithdrawTx) {
+                        throw (new Error(`Forwarded step at index ${index} requires the prior step to produce a withdraw transaction on its destination chain`));
+                    }
+                    const observed = await this.#pollForwardedTransaction(step, prevWithdrawTx, {
+                        ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {})
+                    });
+                    prevActualValueOut = BigInt(observed.to.value);
+                    prevWithdrawTx = null;
+                    onStepCompleted({ type: 'forwarded', plan: step, observedTransaction: observed });
+                }
                 else if (step.type === 'assetMovement' || step.type === 'keetaSend') {
                     if (step.usingInstruction.type === 'KEETA_SEND') {
                         await this.#authorizedSend(options, step.usingInstruction.sendToAddress, BigInt(step.usingInstruction.value), KeetaNet.lib.Account.fromPublicKeyString(step.usingInstruction.tokenAddress).assertKeyType(KeetaNet.lib.Account.AccountKeyAlgorithm.TOKEN), step.usingInstruction.external);
@@ -1218,17 +1558,38 @@ export class AnchorChainingPlan extends AnchorChainingPath {
                             }
                         });
                     }
+                    else if (step.usingInstruction.type === 'EVM_SEND') {
+                        /* For EVM Sends for now we assume the last step sent to this address */
+                        this.logger?.debug(`AnchorChainingPlan::execute`, `Executing EVM_SEND instruction for step ${index} by sending to address ${step.usingInstruction.sendToAddress} with value ${step.usingInstruction.value} and token ${step.usingInstruction.tokenAddress}`);
+                    }
                     else {
                         throw (new Error(`Unsupported instruction type ${step.usingInstruction.type} for user-initiated transfer at step ${index}`));
                     }
                     if (step.type === 'assetMovement') {
-                        const status = await this.#pollTransferStatus(step.transfer);
+                        const status = await this.#pollTransferStatus(step.transfer, {
+                            ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {})
+                        });
                         prevActualValueOut = BigInt(status.transaction.to.value);
+                        const withdraw = status.transaction.to.transactions.withdraw;
+                        if (withdraw) {
+                            prevWithdrawTx = {
+                                location: step.step.to.location,
+                                transaction: { id: withdraw.id }
+                            };
+                        }
+                        else {
+                            prevWithdrawTx = null;
+                        }
                         onStepCompleted({ type: 'assetMovement', plan: step });
                     }
                     else if (step.type === 'keetaSend') {
-                        // For a direct Keeta send, we don't have a transfer object to poll, so we optimistically assume it completes successfully after the authorized send. We could optionally add a polling mechanism here if the underlying client provides a way to check the status of a Keeta transfer.
+                        /*
+                         * Direct Keeta send: optimistically treat as completed since
+                         * there is no provider transfer to poll. Cannot feed a forwarded
+                         * step because it does not produce a bridge withdraw.
+                         */
                         prevActualValueOut = step.valueIn;
+                        prevWithdrawTx = null;
                         onStepCompleted({ type: 'keetaSend', plan: step });
                     }
                     else {
@@ -1309,6 +1670,20 @@ export class AnchorChaining {
         else {
             foundPaths = await this.graph.findPaths(input);
         }
+        // Filter out paths with non-chain steps in intermediate positions
+        foundPaths = foundPaths?.filter(path => {
+            for (let i = 0; i < path.length - 1; i++) {
+                const item = path[i];
+                if (!item) {
+                    continue;
+                }
+                const toLocation = toAssetLocation(item.to.location);
+                if (toLocation.type !== 'chain' && i < path.length - 1) {
+                    return (false);
+                }
+            }
+            return (true);
+        });
         if (foundPaths.length === 0) {
             return (null);
         }
@@ -1323,13 +1698,46 @@ export class AnchorChaining {
         if (!paths) {
             return (null);
         }
-        const result = await Promise.allSettled(paths.map(async function (path) {
-            return (await AnchorChainingPlan.create(path, options));
-        }));
+        const limit = options?.limit ?? 3;
+        const sortedPaths = paths.sort((a, b) => a.path.length - b.path.length);
+        let successCount = 0;
+        let lowestStepsSuccessCount = Infinity;
+        let lastAttemptedPathIdx = -1;
+        const maxAttemptLoops = 3;
+        let currentAttemptLoop = 0;
+        const allOutput = [];
+        while (successCount < limit && lastAttemptedPathIdx < sortedPaths.length - 1 && currentAttemptLoop < maxAttemptLoops) {
+            currentAttemptLoop++;
+            const pathsToTry = sortedPaths.slice(lastAttemptedPathIdx + 1, lastAttemptedPathIdx + 1 + (limit - successCount));
+            if (pathsToTry.length === 0 || !pathsToTry[0]) {
+                break;
+            }
+            if (pathsToTry[0].path.length > lowestStepsSuccessCount) {
+                break;
+            }
+            const currentTry = await Promise.allSettled(pathsToTry.map(async function (path) {
+                return (await AnchorChainingPlan.create(path, options));
+            }));
+            allOutput.push(...currentTry);
+            for (let i = 0; i < currentTry.length; i++) {
+                const result = currentTry[i];
+                const path = pathsToTry[i];
+                if (!result || !path) {
+                    continue;
+                }
+                if (result.status === 'fulfilled') {
+                    successCount++;
+                    if (path && path.path.length < lowestStepsSuccessCount) {
+                        lowestStepsSuccessCount = path.path.length;
+                    }
+                }
+            }
+            lastAttemptedPathIdx += pathsToTry.length;
+        }
         const ret = [];
-        for (let i = 0; i < paths.length; i++) {
-            const path = paths[i];
-            const plan = result[i];
+        for (let i = 0; i < allOutput.length; i++) {
+            const path = sortedPaths[i];
+            const plan = allOutput[i];
             if (!path || !plan) {
                 continue;
             }