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.

AtlasSdk

create

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

note

This method is async

Parameters

Name	Type	Description
provider	ethers.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.
atlasVersion	AtlasVersion	Optional version of Atlas to use (defaults to latest).

Returns

Type	Description
AtlasSdk	The initialized Atlas SDK instance.

Example

import { AtlasSdk, FastlaneBackend } from "@fastlane-labs/atlas-sdk";
import { JsonRpcProvider } from "ethers";

// The following values must be adjusted
const chainId = 11155111;
const rpcUrl = "https://rpc.sepolia.org";
const atlasAuctioneerUrl = "https://auctioneer.atlas.fastlane.xyz";

// Create the SDK instance
const sdk = await AtlasSdk.create(
  new JsonRpcProvider(rpcUrl, chainId),
  chainId,
  new FastlaneBackend({endpoint: atlasAuctioneerUrl})
);

getAtlasAddress

Retrieves the Atlas contract address for this instance chain ID / Atlas version.

note

This method is async

Parameters

No parameter.

Returns

Type	Description
string	The Atlas contract address.

Example

const atlasAddress = await sdk.getAtlasAddress();

getAtlasVerificationAddress

Retrieves the Atlas Verification contract address for this instance chain ID / Atlas version.

note

This method is async

Parameters

No parameter.

Returns

Type	Description
string	The Atlas Verification contract address.

Example

const atlasVerificationAddress = await sdk.getAtlasVerificationAddress();

getSorterAddress

Retrieves the Sorter contract address for this instance chain ID / Atlas version.

note

This method is async

Parameters

No parameter.

Returns

Type	Description
string	The Sorter contract address.

Example

const sorterAddress = await sdk.getSorterAddress();

getSimulatorAddress

Retrieves the Simulator contract address for this instance chain ID / Atlas version.

note

This method is async

Parameters

No parameter.

Returns

Type	Description
string	The Simulator contract address.

Example

const simulatorAddress = await sdk.getSimulatorAddress();

newUserOperation

Creates a new Atlas user operation.

note

This method is async

Parameters

Name	Type	Description
userOpParams	UserOperationParams	The parameters of the user operation.
generateSessionKey	boolean	Optionally generate a session key for the user operation (defaults to false).

Returns

Type	Description
UserOperation	The generated user operation.

Example

const userOperation = await sdk.newUserOperation({
  from: "0x1234567890123456789012345678901234567890",
  value: 0n,
  gas: 150000n,
  maxFeePerGas: 1000000n,
  deadline: 0n,
  dapp: "0x1234567890123456789012345678901234567890",
  control: "0x1234567890123456789012345678901234567890",
  data: "0x123456"
});

getUserOperationHash

Computes the canonical hash for an Atlas user operation. Note that a user operation hash is dependent on the instance chain ID and Atlas version used.

note

This method is async

Parameters

Name	Type	Description
userOp	UserOperation	The user operation.

Returns

Type	Description
string	The user operation hash.

Example

const userOperation = await sdk.newUserOperation({...});
const hash = await sdk.getUserOperationHash(userOperation);

setUserOperationNonce

Sets the next valid nonce for a user operation. Note nonce validity is dependent on the dApp control parameters.

note

This method is async

info

This method is internally called by newUserOperation when a nonce is not provided. It is typically not required to directly call setUserOperationNonce.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to set the nonce for.

Returns

Type	Description
UserOperation	The user operation with updated nonce.

Example

let userOperation = await sdk.newUserOperation({...});
userOperation = await sdk.setUserOperationNonce(userOperation);

generateSessionKey

Generates and sets a session key for a user operation.

info

This method is internally called by newUserOperation when the optional generateSessionKey parameter is set to true. It is typically not required to directly call generateSessionKey.

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to generate/set the session key for.

Returns

Type	Description
UserOperation	The user operation with updated session key.

Example

let userOperation = await sdk.newUserOperation({...});
userOperation = sdk.generateSessionKey(userOperation);

signUserOperation

Signs a user operation.

note

This method is async

info

In a browser environment, this method will trigger a user operation signature prompt (like MetaMask).

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to sign.
signer	ethers.AbstractSigner	An abstract signer.

Returns

Type	Description
UserOperation	The user operation with updated signature.

Example

import { HDNodeWallet } from "ethers";

const signer = HDNodeWallet.createRandom();
let userOperation = await sdk.newUserOperation({...});
userOperation = await sdk.signUserOperation(userOperation);

submitUserOperation

Submits a user operation to the Atlas auctioneer.

note

This method is async

Parameters

Name	Type	Description
userOp	UserOperation	The user operation to submit.
hints	object	An map of hints, to be shared with solvers.
options	object	An optional map of options, to fine tune the auctioneer's behavior.

Available options

warning

Options should be edited only when indicated during integration. In most cases, default values fits perfectly.

Name	Type	Description
onlyWhitelistedSolvers	boolean	Only allow whitelisted solvers to participate in the auction (the whitelist is maintained by the auctioneer). Defaults to false.
auctionDurationInMillis	number	Auction duration. Defaults to 300ms.
maxSolutions	number	Max solver operations allowed. Defaults to 10.
solverPrioritySlots	number	Number of solver operations slots reserved for whitelisted solvers. Defaults to 0.
disableSimulations	boolean	Disable auctioneer's simulations. Defaults to false.
disableTracing	boolean	Disable tracing during auctioneer's simulations. Defaults to false.
earlyReturn	boolean	Returns with the appropriate error if no solver is available at the end of the auction. Defaults to false.
enableBundling	boolean	Enables the atlas bundler. If false, the call returns all generated operations for self-bundling. Defaults to false.
bundlerAddress	string	Enforce the bundler address on the generated dApp operation. Only allowed when enableBundling is set to false. Defaults to address(0).
minSolverBidAmount	string	Enforce minimum bid amount for solvers. Must be hex-encoded and start with "0x". Defaults to 0.
signature	string	Signature of the keccak256 of the user operation with hints + the full options map. This is only required when enableBundling is set to true. Only whitelisted signers are allowed to use the Fastlane Atlas bundler. Defaults to empty.

Returns

Type	Description
string[] | Bundle	Returned value depends on the enableBundling option. If false, the generated bundle (type Bundle) is returned. If true, an array of raw transactions is returned. The returned array (typically contains only 1 element) are hex encoded raw transactions that were generated and submitted to the blockchain by the Atlas bundler.

Example

const userOperation = await sdk.newUserOperation({...});
const bundle = await sdk.submitUserOperation(userOperation);

sortSolverOperations

Sorts the solver operations according to dApp control rules.

note

This method is async

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.

warning

The returned array could be empty, if none of the submitted solver operations passed minimum validation.

Example

const userOperation = await sdk.newUserOperation({...});
const bundle = await sdk.submitUserOperation(userOperation);
const sortedSolverOperations = await sdk.sortSolverOperations(bundle.userOperation, bundle.solverOperations);

createDAppOperation

Generates a dApp operation.

note

This method is async

Parameters

Name	Type	Description
userOp	UserOperation	The user operation.
solverOps	SolverOperation[]	An array of solver operations.
bundler	string	Optional bundler address to enforce on the dApp operation. Defaults to address(0).

warning

In order to generate a valid dApp operation, the user operation must have a valid session key, generated by the SDK beforehand. If the user operation was created using the newUserOperation method, the generateSessionKey optional parameter should have been set to true, or the session key should have been manually set by calling the generateSessionKey method.

Returns

Type	Description
DAppOperation	The generated dApp operation, signed by the session key.

Example

const userOperation = await sdk.newUserOperation({...}, true);
const bundle = await sdk.submitUserOperation(userOperation);
const dAppOperation = await sdk.createDAppOperation(bundle.userOperation, bundle.solverOperations);

getMetacallCalldata

Generates the calldata needed to call the Atlas function metacall.

Parameters

Name	Type	Description
userOp	UserOperation	A user operation.
solverOps	SolverOperation[]	An array of solver operations.
dAppOp	DAppOperation	A dApp operation.
gasRefundBeneficiary	string	Optional gas refund beneficiary. Defaults to address(0) (beneficiary is the bundler).

Returns

Type	Description
string	The calldata necessary to call the Atlas metacall function, for the given bundle.

Example

const userOperation = await sdk.newUserOperation({...});
const bundle = await sdk.submitUserOperation(userOperation);
const calldata = sdk.getMetacallCalldata(bundle.userOperation, bundle.solverOperations, bundle.dAppOperation);

getMetacallGasLimit

Calculates the optimal gas limit for calling the Atlas function metacall.

Parameters

Name	Type	Description
userOp	UserOperation	A user operation.
solverOps	SolverOperation[]	An array of solver operations.

Returns

Type	Description
bigint	The calculated limit.

Example

const userOperation = await sdk.newUserOperation({...});
const bundle = await sdk.submitUserOperation(userOperation);
const gasLimit = sdk.getMetacallGasLimit(bundle.userOperation, bundle.solverOperations);

getExecutionEnvironment

Gets the execution environment address for a given user and dApp control.

note

This method is async

Parameters

Name	Type	Description
userAddress	string	The address of the user.
dAppControlAddress	string	The address of the dApp control.

Returns

Type	Description
string	The address of the execution environment contract.

Example

const eeAddress = await sdk.getExecutionEnvironment(
  "0x1234567890123456789012345678901234567890",
  "0x1234567890123456789012345678901234567890"
);