API Reference

Overview

The Atlas SDK provides a comprehensive set of methods to interact with the Atlas smart contracts deployed on various Ethereum-compatible blockchain networks. It facilitates operations such as creating and managing user and solver operations, signing transactions, sorting solver bids, and executing meta-calls. This documentation outlines the available methods, their parameters, return types, and descriptions to help developers effectively utilize the SDK in their applications.

Initialization

AtlasSdk Constructor

Initializes a new instance of the Atlas SDK with the provided Ethereum provider, chain ID, and backend configuration.

Parameters

Name	Type	Description
provider	AbstractProvider	An Ethereum provider (e.g., JsonRpcProvider from ethers).
chainId	number	The chain ID of the blockchain network.
backend	IBackend	An instance of the backend client implementing the IBackend interface.
hooksControllers	IHooksControllerConstructable[]	Optional array of hooks controllers for custom processing.

Returns

Type	Description
AtlasSdk	The initialized Atlas SDK instance.

Example

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

const chainId = 11155111; // Replace with your network's chain ID
const provider = new JsonRpcProvider("https://rpc.sepolia.org/", chainId);
const backend = new MockBackend(); // Replace with your backend implementation

const sdk = new AtlasSdk(provider, chainId, backend);

Contract Retrieval

getAtlasContract

Retrieves the Atlas contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.

Returns

Type	Description
AtlasContract	The Atlas contract instance associated with chain ID.
Error	If the contract retrieval fails.

Example

const atlasContract = sdk.getAtlasContract(chainId);
if (!atlasContract) {
  throw new Error("Failed to retrieve Atlas contract.");
}

getAtlasVerificationContract

Retrieves the Atlas Verification contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.

Returns

Type	Description
AtlasVerificationContract	The Atlas Verification contract instance.
Error	If the contract retrieval fails.

Example

const atlasVerifContract = sdk.getAtlasVerificationContract(chainId);
if (!atlasVerifContract) {
  throw new Error("Failed to retrieve Atlas Verification contract.");
}

getSimulatorContract

Retrieves the Simulator contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.

Returns

Type	Description
SimulatorContract	The Simulator contract instance associated with chain ID.
Error	If the contract retrieval fails.

Example

const simulatorContract = sdk.getSimulatorContract(chainId);
if (!simulatorContract) {
  throw new Error("Failed to retrieve Simulator contract.");
}

getSorterContract

Retrieves the Sorter contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.

Returns

Type	Description
SorterContract	The Sorter contract instance associated with chain ID.
Error	If the contract retrieval fails.

Example

const sorterContract = sdk.getSorterContract(chainId);
if (!sorterContract) {
  throw new Error("Failed to retrieve Sorter contract.");
}

Simulation Methods

simulateUserOperation

Simulates a user operation by invoking the simulation function of the Simulator contract.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.
userOp	UserOperation	The user operation to be simulated.

Returns

Type	Description
void	If the simulation succeeds.
Error	If the simulation fails.

Example

try {
  await sdk.simulateUserOperation(chainId, userOp);
  console.log("User operation simulation succeeded.");
} catch (error) {
  console.error("User operation simulation failed:", error);
}

simulateSolverOperation

Simulates a solver operation in the context of a user operation by invoking the simulation function of the Simulator contract.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.
userOp	UserOperation	The user operation associated with the solver operation.
solverOp	SolverOperation	The solver operation to be simulated.

Returns

Type	Description
void	If the simulation succeeds.
Error	If the simulation fails.

Example

try {
  await sdk.simulateSolverOperation(chainId, userOp, solverOp);
  console.log("Solver operation simulation succeeded.");
} catch (error) {
  console.error("Solver operation simulation failed:", error);
}

Configuration Methods

getDAppCallConfig

Retrieves the call configuration for a decentralized application (dApp) from the dApp Control contract.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.
dAppControlAddr	string	The Ethereum address of the dApp Control contract.

Returns

Type	Description
bigint	The call configuration flags for the dApp.
Error	If retrieval fails.

Example

try {
  const callConfig = await sdk.getDAppCallConfig(chainId, dAppControlAddress);
  console.log("DApp Call Config:", callConfig);
} catch (error) {
  console.error("Failed to get DApp call config:", error);
}

getDAppConfig

Retrieves the configuration settings for a decentralized application (dApp) based on a user operation.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.
userOp	UserOperation	The user operation associated with the dApp configuration.
dAppControlAddr	string	The Ethereum address of the dApp Control contract.

Returns

Type	Description
DAppConfig	The configuration settings of the dApp.
Error	If retrieval fails.

Example

try {
  const dAppConfig = await sdk.getDAppConfig(chainId, userOp, dAppControlAddress);
  console.log("DApp Config:", dAppConfig);
} catch (error) {
  console.error("Failed to get DApp config:", error);
}

Nonce Management

setUserNonce

Sets the nonce for a user operation based on the current state of the blockchain.

Parameters

Name	Type	Description
chainId	number	The chain ID of the blockchain network.
userOp	UserOperation	The user operation for which the nonce is set.

Returns

Type	Description
void	If the nonce is set successfully.
Error	If setting the nonce fails.

Example

try {
  await sdk.setUserNonce(chainId, userOp);
  console.log("User nonce set successfully.");
} catch (error) {
  console.error("Failed to set user nonce:", error);
}

getUserNextNonce

Retrieves the next nonce for a user based on the call configuration.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to determine the next nonce.

Returns

Type	Description
bigint	The next nonce value for the user.
Error	If retrieval fails.

Example

try {
  const nextNonce = await sdk.getUserNextNonce(userOp);
  console.log("Next User Nonce:", nextNonce);
} catch (error) {
  console.error("Failed to get user next nonce:", error);
}

getDAppNextNonce

Retrieves the next nonce for a decentralized application (dApp) based on the call configuration.

Parameters

Name	Type	Description
dAppOp	DAppOperation	The dApp operation to determine the next nonce.

Returns

Type	Description
bigint	The next nonce value for the dApp.
Error	If retrieval fails.

Example

try {
  const dAppNonce = await sdk.getDAppNextNonce(dAppOp);
  console.log("Next DApp Nonce:", dAppNonce);
} catch (error) {
  console.error("Failed to get DApp next nonce:", error);
}

Operation Sorting

sortSolverOperations

Sorts solver operations using the Sorter contract to determine the order in which solvers should act.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation associated with the solver operations.
solverOps	SolverOperation[]	An array of solver operations to be sorted.

Returns

Type	Description
SolverOperation[]	The sorted array of solver operations.
Error	If sorting fails or the Sorter contract is not found.

Example

try {
  const sortedSolverOps = await sdk.sortSolverOperations(userOp, solverOps);
  console.log("Sorted Solver Operations:", sortedSolverOps);
} catch (error) {
  console.error("Failed to sort solver operations:", error);
}

Meta-call Execution

metacall

Executes a meta-call that bundles user operations, solver operations, and dApp operations into a single transaction.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to be included in the meta-call.
solverOps	SolverOperation[]	An array of solver operations to be included in the meta-call.
dAppOp	DAppOperation	The dApp operation to be included in the meta-call.

Returns

Type	Description
Transaction	The Ethereum transaction object representing the meta-call.
Error	If the meta-call execution fails.

Example

try {
  const atlasTxHash = await sdk.metacall(userOp, sortedSolverOps, dAppOp);
  console.log("Meta-call Transaction Hash:", atlasTxHash);
} catch (error) {
  console.error("Failed to execute meta-call:", error);
}

Utility Functions

validateAddress

Validates whether a given string is a valid Ethereum address.

Parameters

Name	Type	Description
address	string	The Ethereum address to validate.

Returns

Type	Description
boolean	true if valid, false otherwise.

Example

const isValid = validateAddress("0xYourAddressHere");
console.log("Is Valid Address:", isValid);

abiEncodeUserOperation

Encodes a UserOperation using ABI encoding standards.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to encode.

Returns

Type	Description
string	The ABI-encoded user operation as a hex string.

Example

const encodedUserOp = abiEncodeUserOperation(userOp);
console.log("Encoded User Operation:", encodedUserOp);

getCallChainHash

Computes the call chain hash for a sequence of user and solver operations to ensure operation integrity.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation for which the chain hash is calculated.
solverOps	SolverOperation[]	An array of solver operations involved in the chain hash.
requirePreOps	boolean	Whether pre-operations are required.
dAppControl	string	The dApp control address.

Returns

Type	Description
string	The resulting Keccak256 hash of the operation chain as a hex string.
Error	If encoding fails.

Example

try {
  const callChainHash = getCallChainHash(userOp, solverOps, true, dAppControlAddress);
  console.log("Call Chain Hash:", callChainHash);
} catch (error) {
  console.error("Failed to calculate call chain hash:", error);
}

Error Handling

All methods in the Atlas SDK throw errors when operations fail. It is essential to handle these errors appropriately to ensure the robustness of your application. Always use try-catch blocks or handle promise rejections when invoking SDK methods.

Example

try {
  const atlasTxHash = await sdk.metacall(userOp, sortedSolverOps, dAppOp);
  console.log("Meta-call Transaction Hash:", atlasTxHash);
} catch (error) {
  console.error("Failed to execute meta-call:", error);
  // Implement additional error handling logic as needed
}

Best Practices for Error Handling

1. Log Errors: Always log errors with sufficient context to aid in debugging.

try {
  // Some SDK method
} catch (error) {
  console.error("Error in methodName:", error);
}

2. Categorize Errors: Implement custom error types to categorize different kinds of errors.

class NetworkError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "NetworkError";
  }
}

// Usage
try {
  // Some SDK method
} catch (error) {
  if (error instanceof NetworkError) {
    // Handle network-specific error
  } else {
    // Handle other errors
  }
}

3. Retry Mechanisms: For transient errors, implement a retry mechanism with exponential backoff.

async function retryOperation(operation: () => Promise<any>, retries: number = 3): Promise<any> {
  let lastError;
  for (let i = 0; i < retries; i++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      await new Promise(res => setTimeout(res, 2 ** i * 1000)); // Exponential backoff
    }
  }
  throw lastError;
}

// Usage
try {
  const result = await retryOperation(() => sdk.someMethod(params));
  console.log("Operation succeeded:", result);
} catch (error) {
  console.error("Operation failed after retries:", error);
}

4. Meaningful Error Messages: Ensure that error messages are clear and actionable.

try {
  // Some SDK method
} catch (error) {
  throw new Error(`Failed to execute someMethod: ${error.message}`);
}

5. Graceful Degradation: When possible, implement fallback mechanisms to provide partial functionality.

try {
  const result = await sdk.primaryMethod();
} catch (error) {
  console.warn("Primary method failed, falling back to secondary method:", error);
  const result = await sdk.secondaryMethod();
}

6. Context-aware Error Handling: Use context to provide more information about where and why an error occurred.

import { createLogger } from "some-logging-library";

const logger = createLogger();

try {
  // Some SDK method
} catch (error) {
  logger.error("Failed to execute someMethod", { error, context: "Initializing user operation" });
  throw error; // or handle accordingly
}

By implementing these error handling strategies, you can create more robust applications that gracefully handle failures and provide better debugging information when issues occur.

Summary

This Methods documentation provides detailed information about the primary functions available in the Atlas SDK, including their usage, parameters, and return types. By following the examples and understanding the method functionalities, developers can effectively integrate the Atlas SDK into their applications to interact with the Atlas protocol.

For more detailed explanations and additional methods, refer to the Quickstart section.