Execute Quotes

The ZKsync Easy On-Ramp SDK provides a way to streamline the purchase and swap of tokens for users on-ramping to a network.

Execute quote

Once you've received a list of quotes from the fetchQuotes function, you can execute a quote with executeRoute. A quote becomes a route during this process which is a modified quote object that indicates it is executing as an active transaction.

import { fetchQuotes } from 'zksync-easy-onramp';

// fetching quotes for $25 USD for Ether on ZKsync
const quotes = await fetchQuotes({...});

const selectedQuote = quotes[0];

const quotes = await fetchQuotes({...});
const executedRoute = executeRoute(quotes[0], {
    onUpdateHook: (executingRoute) => {
        // receive the latest state change
        // of the quote that is executing
        console.log(executingRoute)
    }
});

The executeRoute function will then handle the process of managing purchases via on ramp services, tracking order statuses, switching chains, transaction management, execution, and tracking.

Parameters

route (Route | ProviderQuoteOption): The route to be executed.

executionOptions (ExecutionOptions, optional): An object containing settings and callbacks for execution.

Returns

Promise<Route>: Resolves when execution is halted or done and rejects when an error is thrown.

Execution options

All execution options are optional, but we recommend at minimum the onUpdateHook to track a route that is actively running.

onUpdateHook (function)

The callback function is called when the route object changes during execution. This function allows you to track the updates, execution status, etc. Learn more about monitoring the execution in the Monitoring the route execution section below.

executeInBackground (boolean, default: false)

Use this boolean flag to indicate if a route execution should continue in the background until it comes to a step that requires user interaction.

Update route execution

The updateRouteExecution function is used to update the settings of an ongoing route execution.

A common use case for using this function is to change the execution of a route to the background, for example, when a user navigates away from the execution page in your app. With the execution option of executeInBackground set to true with the update function, the execution will continue to run until it requires user interaction.

import { updateRouteExecution } from 'zksync-easy-onramp';

const updatedRoute = updateRouteExecution(route, { executeInBackground: true });

Resume route execution

The resumeRoute function is used to resume any halted or failed route execution. It is crucial that you call the resumeRoute function with the latest state of the route object. The SDK does not store or track any route executions on the server, we expect the developer to manage the state of the routes for users.

Aside from resuming failed route execution, a common use case for resuming execution is to re-start an execution that halted during a background execution with the use of executeInBackground.

import { resumeRouteExecution } from 'zksync-easy-onramp'

const resumedRoute = await resumeRouteExecution(route);

Stop route execution

The stopRouteExecution function is used to stop the ongoing execution of an active route. It will set the route execution state to HALTING and attempt to gracefully shutdown the ongoing execution. If a transaction has already been signed and sent by the user, it will continue to be executed on-chain.

import { stopRouteExecution } from 'zksync-easy-onramp';

const stoppedRoute = await stopRouteExecution(route.id);

Monitoring the route execution

As a route is executing, the onUpdateHook will return the latest state changes to the route.

The main difference between a route object and a quote object is a status and an array of modified steps ( type StepExtended). Each step will have additional metadata tracking any updates of transactions or purchase orders along with an execution object that tracks the execution of that step and its status.

The execution object

Each step in a route has an execution object that details the step's progression. An execution object includes a process array that describes each sequential stage in an execution to complete.

Tracking progress

If an onUpdateHook callback function is provided, the execution progress will be passed as the latest state of the Route. You can check the Route's status to get the overall running state of the execution. To check the state of the latest step in the Route, get the status from the execution object from the latest step. The last process in the execution's process array will also include the status and a message.