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.
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.
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.
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.
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.
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.
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.
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 dependant on the dApp control parameters.
This method is async
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.
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.
This method is async
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.
This method is async
Parameters
| Name | Type | Description |
|---|---|---|
| userOp | UserOperation | The user operation to submit. |
| hints | string[] | An optional array of hints, to be shared with solvers. |
| options | Map | An optional map of options, to fine tune the auctioneer's behavior. |
Available options
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 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.
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. |
The returned array could be empty, if none of the submitted solver operations passed minimal 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.
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). |
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);
getExecutionEnvironment
Gets the execution environment address for a given user and dApp control.
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"
);