Skip to main content

Atlas SDK Backend Documentation

This document provides detailed information about the backend classes and interfaces used in the Atlas SDK. The backend is responsible for handling communication with the Atlas network's backend services, including submitting user operations, retrieving solver operations, and submitting bundles for execution.

Introduction​

The backend component of the Atlas SDK facilitates interaction with the backend services required for processing user operations. It abstracts the complexities of network communication and provides a clean interface for the SDK to submit operations and retrieve results.

Interfaces​

IBackend​

The IBackend interface defines the methods that any backend implementation must provide. It ensures consistency across different backend implementations.

export interface IBackend {
  addHooksControllers(hooksControllers: IHooksController[]): void;

  /**
   * Submits a user operation to the backend.
   * @param userOp - The user operation to submit.
   * @param hints - Hints for solvers.
   * @param extra - Extra parameters (optional).
   * @returns A promise that resolves to the hash of the user operation.
   */
  submitUserOperation(
    userOp: UserOperation,
    hints: string[],
    extra?: any
  ): Promise<string>;

  /**
   * Retrieves solver operations for a previously submitted user operation.
   * @param userOp - The original user operation.
   * @param userOpHash - The hash of the user operation.
   * @param wait - Whether to wait for a response if not immediately available.
   * @param extra - Extra parameters (optional).
   * @returns A promise that resolves to an array of `SolverOperation` instances.
   */
  getSolverOperations(
    userOp: UserOperation,
    userOpHash: string,
    wait?: boolean,
    extra?: any
  ): Promise<SolverOperation[]>;

  /**
   * Submits a bundle of operations to the backend for bundling.
   * @param bundle - The bundle containing user, solver, and dApp operations.
   * @param extra - Extra parameters (optional).
   * @returns A promise that resolves to a result message.
   */
  submitBundle(bundle: Bundle, extra?: any): Promise<string>;

  /**
   * Retrieves the Atlas transaction hash for a previously submitted bundle.
   * @param userOpHash - The hash of the user operation.
   * @param wait - Whether to wait for a response if not immediately available.
   * @param extra - Extra parameters (optional).
   * @returns A promise that resolves to the Atlas transaction hash.
   */
  getBundleHash(
    userOpHash: string,
    wait?: boolean,
    extra?: any
  ): Promise<string>;
}

Classes​

BaseBackend​

The BaseBackend class provides a base implementation of the IBackend interface, including hooks management. It is intended to be extended by concrete backend implementations.

export abstract class BaseBackend implements IBackend {
  protected hooksControllers: IHooksController[] = [];

  constructor(protected params: { [k: string]: string } = {}) {}

  addHooksControllers(hooksControllers: IHooksController[]): void {
    this.hooksControllers.push(...hooksControllers);
  }

  async submitUserOperation(
    userOp: UserOperation,
    hints: string[],
    extra?: any
  ): Promise<string> {
    // Pre-hooks processing
    for (const hooksController of this.hooksControllers) {
      [userOp, hints] = await hooksController.preSubmitUserOperation(
        userOp,
        hints
      );
    }

    // Implemented by subclass
    let userOpHash = await this._submitUserOperation(userOp, hints, extra);

    // Post-hooks processing
    for (const hooksController of this.hooksControllers) {
      [userOp, userOpHash] = await hooksController.postSubmitUserOperation(
        userOp,
        userOpHash
      );
    }

    return userOpHash;
  }

  // Other methods (getSolverOperations, submitBundle, getBundleHash) follow the same pattern

  protected abstract _submitUserOperation(
    userOp: UserOperation,
    hints: string[],
    extra?: any
  ): Promise<string>;

  protected abstract _getSolverOperations(
    userOp: UserOperation,
    userOpHash: string,
    wait?: boolean,
    extra?: any
  ): Promise<SolverOperation[]>;

  protected abstract _submitBundle(bundle: Bundle, extra?: any): Promise<string>;

  protected abstract _getBundleHash(
    userOpHash: string,
    wait?: boolean,
    extra?: any
  ): Promise<string>;
}

Notes:​

  • The methods starting with an underscore (e.g., _submitUserOperation) are abstract methods that need to be implemented by subclasses.
  • The base class handles hooks before and after each operation.

FastlaneBackend​

The FastlaneBackend class is a concrete implementation of the BaseBackend class. It uses HTTP requests to communicate with the backend services.

Notes:​

  • The FastlaneBackend class uses isomorphic-fetch to make HTTP requests.
  • It relies on helper functions to create the appropriate fetch parameters (FastlaneApiFetchParamCreator).

Usage Examples​

Initializing the Backend​

import { FastlaneBackend } from "atlas-sdk/backend";
import { JsonRpcProvider } from "ethers";

// Parameters for the backend (e.g., base URL)
const backendParams = {
  basePath: "https://backend.atlas.network/api",
};

// Initialize the backend
const backend = new FastlaneBackend(backendParams);

Submitting a User Operation​

import { UserOperation } from "atlas-sdk/operation";

// Assume userOp is a UserOperation instance
const hints = []; // Optional hints for solvers
const userOpHash = await backend.submitUserOperation(userOp, hints);

// Retrieve solver operations
const solverOps = await backend.getSolverOperations(userOp, userOpHash, true);

Submitting a Bundle​

import { Bundle } from "atlas-sdk/operation";

// Assume bundle is a Bundle instance containing userOp, solverOps, and dAppOp
const result = await backend.submitBundle(bundle);

// Get the Atlas transaction hash
const atlasTxHash = await backend.getBundleHash(bundle.userOperation.hash(), true);

Error Handling​

The backend methods throw errors in cases such as:

  • Network failures or timeouts.
  • HTTP response status codes indicating an error (non-2xx).
  • Backend service errors with messages provided in the response body.

Ensure to handle these errors appropriately in your application, possibly using try-catch blocks or promise rejection handlers.

try {
  const userOpHash = await backend.submitUserOperation(userOp, hints);
} catch (error) {
  console.error("Error submitting user operation:", error);
}

Support​

For further assistance, please refer to the GitHub repository or contact the support team at support@example.com.

Disclaimer: This documentation is provided "as is" without warranty of any kind. Use at your own risk.