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 simulating user and solver actions, managing nonces, sorting solver operations, 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

New

Initializes a new instance of the Atlas SDK with the provided Ethereum clients and chain configurations.

Parameters

Name	Type	Description
rpcClients	[]interface	A slice of Ethereum or RPC clients connected to different blockchain networks.
chainOverrides	map[uint64]map[string]*config.ChainConfig	A map containing chain IDs as keys and their corresponding chain configurations to override defaults.

Returns

Type	Description
*AtlasSdk	The initialized Atlas SDK instance.
error	An error object if the initialization fails.

Example

ethClient, _ := ethclient.Dial("https://rpc.sepolia.org")
defer ethClient.Close()

sdk, err := core.NewAtlasSdk([]interface{}{ethClient}, nil)

Metacall

Calls the Atlas metacall function.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
transactOpts	*bind.TransactOpts	The required data to submit the transaction.
userOp	*types.UserOperation	The user operation.
solverOps	types.SolverOperations	The solver operations.
dAppOp	*types.DAppOperation	The dApp operation.
gasRefundBeneficiary	*common.Address	The gas refund beneficiary (set `nil` for default value).

Returns

Type	Description
*types.Transaction	The generated and submitted transaction.
error	An error object if the call has failed.

GetBalanceOfBondedAtlEth

Retrieves an account bonded atlEth balance for a particular chain ID / Atlas version.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
account	common.Address	The account to get the balance for.

Returns

Type	Description
*big.Int	The bonded atlEth balance for the account.
error	An error object if the call has failed.

Example

account := common.HexToAddress("0x1234567890123456789012345678901234567890")
atlEthBondedBalance, err := sdk.GetBalanceOfBondedAtlEth(11155111, nil, account)

GetDAppCallConfig

Retrieves a dApp control's call config.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
dAppControlAddr	common.Address	The dApp control's address.

Returns

Type	Description
uint32	The call config value.
error	An error object if the call has failed.

Example

dAppControlAddress := common.HexToAddress("0x1234567890123456789012345678901234567890")
callConfig, err := sdk.GetDAppCallConfig(11155111, dAppControlAddress)

GetDAppConfig

Retrieves a dApp control's full config.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
userOp	*types.UserOperation	A user operation.
dAppControlAddr	common.Address	The dApp control's address.

Returns

Type	Description
*dappcontrol.DAppConfig	The full dApp config object.
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
dAppControlAddress := common.HexToAddress("0x1234567890123456789012345678901234567890")
dAppConfig, err := sdk.GetDAppCallConfig(11155111, userOperation, dAppControlAddress)

GetDAppSolverGasLimit

Retrieves the solver gas limit for a particular dApp control.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
dAppControlAddr	common.Address	The dApp control's address.

Returns

Type	Description
*big.Int	The solver gas limit for this dApp control.
error	An error object if the call has failed.

Example

dAppControlAddress := common.HexToAddress("0x1234567890123456789012345678901234567890")
solverGasLimit, err := sdk.GetDAppSolverGasLimit(11155111, dAppControlAddress)

SetUserNonce

Sets the next valid user nonce on the passed user operation.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation to set the nonce for.

Returns

Type	Description
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
err := sdk.SetUserNonce(11155111, nil, userOperation)

GetUserNextNonce

Retrieves the next valid user nonce on the passed user operation.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation to set the nonce for.
callConfig	uint32	The call config for the dApp control.

Returns

Type	Description
*big.Int	The next valid nonce for this user operation.
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
dAppControlAddress := common.HexToAddress("0x1234567890123456789012345678901234567890")
callConfig, _ := sdk.GetDAppCallConfig(11155111, dAppControlAddress)
nextNonce, err := sdk.GetUserNextNonce(11155111, nil, userOperation, callConfig)

GetDAppNextNonce

Retrieves the next valid dApp nonce on the passed dApp control.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
dApp	common.Address	The address of the dApp control.
callConfig	uint32	The call config for the dApp control.

Returns

Type	Description
*big.Int	The next valid nonce for this dApp control.
error	An error object if the call has failed.

Example

dAppControlAddress := common.HexToAddress("0x1234567890123456789012345678901234567890")
callConfig, _ := sdk.GetDAppCallConfig(11155111, dAppControlAddress)
nextNonce, err := sdk.GetDAppNextNonce(11155111, nil, dAppControlAddress, callConfig)

SimulateUserOperation

Simulates a user operation using the Atlas simulator.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation to simulate.

Returns

Type	Description
*UserOperationSimulationError	The details of the failure, or nil if the simulation passed.

Example

userOperation := &types.UserOperation{}
simulationErr := sdk.SimulateUserOperation(11155111, nil, userOperation)

SimulateSolverOperation

Simulates a solver operation using the Atlas simulator.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation to simulate.
solverOp	*types.SolverOperation	The solver operation to simulate.
allowTracing	boolean	Allow call tracing when simulating. This is only relevant for dApp controls that enable exPostBids.

Returns

Type	Description
*big.Int	The solver bid amount
*SolverOperationSimulationError	The details of the failure, or nil if the simulation passed.

Example

userOperation := &types.UserOperation{}
solverOperation := &types.SolverOperation{}
solverBidAmount, simulationErr := sdk.SimulateSolverOperation(11155111, nil, userOperation, solverOperation, false)

SortSolverOperations

Sorts solver operations according to the dApp control rules.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation.
solverOp	*types.SolverOperation	The solver operation to sort.

Returns

Type	Description
types.SolverOperations	The sorted solver operations.
error	An error object if the call has failed.

warning

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

Example

userOperation := &types.UserOperation{}
solverOperation1 := &types.SolverOperation{}
solverOperation2 := &types.SolverOperation{}
sortedSolverOperations, err := sdk.SortSolverOperations(11155111, nil, userOperation, []*types.SolverOperation{solverOperation1, solverOperation2})

UserOperation

type UserOperation struct {
	From         common.Address
	To           common.Address
	Value        *big.Int
	Gas          *big.Int
	MaxFeePerGas *big.Int
	Nonce        *big.Int
	Deadline     *big.Int
	Dapp         common.Address
	Control      common.Address
	CallConfig   uint32
	SessionKey   common.Address
	Data         []byte
	Signature    []byte
}

EncodeToRaw

Returns the serialized version of the user operation.

Parameters

No parameters.

Returns

Type	Description
*types.UserOperationRaw	The serialized user operation.

Example

userOperation := &types.UserOperation{}
serializedUserOperation := userOperation.EncodeToRaw()

Hash

Computes the canonical hash for an Atlas user operation. Note a user operation hash is dependant on chain ID and Atlas version.

Parameters

Name	Type	Description
trusted	boolean	Should the hash be trusted.
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
common.Hash	The hash of the user operation.
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
hash, err := userOperation.Hash(true, 11155111, nil)

AbiEncode

Gets the user operation abi encoded.

Parameters

No parameters.

Returns

Type	Description
[]byte	The user operation abi encoded, as bytes.
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
uoAbiEncoded, err := userOperation.AbiEncode()

ValidateSignature

Validates the user operation signature.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
error	An error object if the call has failed, or nil if the signature is valid.

Example

userOperation := &types.UserOperation{}
err := userOperation.ValidateSignature(11155111, nil)

UserOperationRaw

type UserOperationRaw struct {
	From         common.Address `json:"from"`
	To           common.Address `json:"to"`
	Value        *hexutil.Big   `json:"value"`
	Gas          *hexutil.Big   `json:"gas"`
	MaxFeePerGas *hexutil.Big   `json:"maxFeePerGas"`
	Nonce        *hexutil.Big   `json:"nonce"`
	Deadline     *hexutil.Big   `json:"deadline"`
	Dapp         common.Address `json:"dapp"`
	Control      common.Address `json:"control"`
	CallConfig   *hexutil.Big   `json:"callConfig"`
	SessionKey   common.Address `json:"sessionKey"`
	Data         hexutil.Bytes  `json:"data"`
	Signature    hexutil.Bytes  `json:"signature"`
}

Decode

Deserializes the user operation.

Parameters

No parameters.

Returns

Type	Description
*types.UserOperation	The deserialized user operation.

Example

serializedUserOperation := &types.UserOperationRaw{}
userOperation := serializedUserOperation.Decode()

UserOperationPartialRaw

type UserOperationPartialRaw struct {
	ChainId *hexutil.Big `json:"chainId"`

	UserOpHash   common.Hash    `json:"userOpHash"`
	To           common.Address `json:"to"`
	Gas          *hexutil.Big   `json:"gas"`
	MaxFeePerGas *hexutil.Big   `json:"maxFeePerGas"`
	Deadline     *hexutil.Big   `json:"deadline"`
	Dapp         common.Address `json:"dapp"`
	Control      common.Address `json:"control"`

	//Exactly one of 1. Hints  2. (Value, Data, From) must be set
	Hints []common.Address `json:"hints,omitempty"`

	Value *hexutil.Big   `json:"value,omitempty"`
	Data  hexutil.Bytes  `json:"data,omitempty"`
	From  common.Address `json:"from,omitempty"`
}

New

Creates a new instance.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).
userOp	*types.UserOperation	The user operation.
hints	[]common.Address	A slice of hints.

Returns

Type	Description
*types.UserOperationPartialRaw	The generated partial user operation, serialized.
error	An error object if the call has failed.

Example

userOperation := &types.UserOperation{}
partialUserOperationSeralized, err := types.NewUserOperationPartialRaw(11155111, nil, userOperation, []common.Address{})

UserOperationWithHintsRaw

type UserOperationWithHintsRaw struct {
	ChainId       *hexutil.Big      `json:"chainId"`
	UserOperation *UserOperationRaw `json:"userOperation"`
	Hints         []common.Address  `json:"hints"`
}

New

Creates a new instance.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
userOp	*types.UserOperation	The user operation.
hints	[]common.Address	A slice of hints.

Returns

Type	Description
*types.UserOperationWithHintsRaw	The generated user operation with hints, serialized.

Example

userOperation := &types.UserOperation{}
userOperationWithHintsSeralized, err := types.NewUserOperationWithHintsRaw(11155111, userOperation, []common.Address{})

Decode

Deserializes the data.

Parameters

No parameters.

Returns

Type	Description
uint64	The chain ID.
*types.UserOperation	The user operation.
[]common.Address	The slice of hints.

Example

userOperationWithHintsSeralized := &types.UserOperationWithHintsRaw{}
chainId, userOperation, hints := userOperationWithHintsSeralized.Decode()

SolverOperation

type SolverOperation struct {
	From         common.Address
	To           common.Address
	Value        *big.Int
	Gas          *big.Int
	MaxFeePerGas *big.Int
	Deadline     *big.Int
	Solver       common.Address
	Control      common.Address
	UserOpHash   common.Hash
	BidToken     common.Address
	BidAmount    *big.Int
	Data         []byte
	Signature    []byte
}

EncodeToRaw

Returns the serialized version of the solver operation.

Parameters

No parameters.

Returns

Type	Description
*types.SolverOperationRaw	The serialized solver operation.

Example

solverOperation := &types.SolverOperation{}
serializedSolverOperation := solverOperation.EncodeToRaw()

Hash

Computes the canonical hash for an Atlas solver operation. Note a solver operation hash is dependant on chain ID and Atlas version.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
common.Hash	The hash of the solver operation.
error	An error object if the call has failed.

Example

solverOperation := &types.SolverOperation{}
hash, err := solverOperation.Hash(11155111, nil)

AbiEncode

Gets the solver operation abi encoded.

Parameters

No parameters.

Returns

Type	Description
[]byte	The solver operation abi encoded, as bytes.
error	An error object if the call has failed.

Example

solverOperation := &types.SolverOperation{}
soAbiEncoded, err := solverOperation.AbiEncode()

ValidateSignature

Validates the solver operation signature.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
error	An error object if the call has failed, or nil if the signature is valid.

Example

solverOperation := &types.SolverOperation{}
err := solverOperation.ValidateSignature(11155111, nil)

SolverOperationRaw

type SolverOperationRaw struct {
	From         common.Address `json:"from"`
	To           common.Address `json:"to"`
	Value        *hexutil.Big   `json:"value"`
	Gas          *hexutil.Big   `json:"gas"`
	MaxFeePerGas *hexutil.Big   `json:"maxFeePerGas"`
	Deadline     *hexutil.Big   `json:"deadline"`
	Solver       common.Address `json:"solver"`
	Control      common.Address `json:"control"`
	UserOpHash   common.Hash    `json:"userOpHash"`
	BidToken     common.Address `json:"bidToken"`
	BidAmount    *hexutil.Big   `json:"bidAmount"`
	Data         hexutil.Bytes  `json:"data"`
	Signature    hexutil.Bytes  `json:"signature"`
}

Decode

Deserializes the solver operation.

Parameters

No parameters.

Returns

Type	Description
*types.SolverOperation	The deserialized solver operation.

Example

serializedSolverOperation := &types.SolverOperationRaw{}
solverOperation := serializedSolverOperation.Decode()

DAppOperation

type DAppOperation struct {
	From          common.Address
	To            common.Address
	Nonce         *big.Int
	Deadline      *big.Int
	Control       common.Address
	Bundler       common.Address
	UserOpHash    common.Hash
	CallChainHash common.Hash
	Signature     []byte
}

EncodeToRaw

Returns the serialized version of the dApp operation.

Parameters

No parameters.

Returns

Type	Description
*types.DAppOperationRaw	The serialized dApp operation.

Example

dAppOperation := &types.DAppOperation{}
serializedDAppOperation := dAppOperation.EncodeToRaw()

Hash

Computes the canonical hash for an Atlas dApp operation. Note a dApp operation hash is dependant on chain ID and Atlas version.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
common.Hash	The hash of the dApp operation.
error	An error object if the call has failed.

Example

dAppOperation := &types.DAppOperation{}
hash, err := dAppOperation.Hash(11155111, nil)

ValidateSignature

Validates the dApp operation signature.

Parameters

Name	Type	Description
chainId	uint64	The targeted chain ID.
version	*string	The targeted Atlas version (set `nil` for latest).

Returns

Type	Description
error	An error object if the call has failed, or nil if the signature is valid.

Example

dAppOperation := &types.DAppOperation{}
err := dAppOperation.ValidateSignature(11155111, nil)

DAppOperationRaw

type DAppOperationRaw struct {
	From          common.Address `json:"from"`
	To            common.Address `json:"to"`
	Nonce         *hexutil.Big   `json:"nonce"`
	Deadline      *hexutil.Big   `json:"deadline"`
	Control       common.Address `json:"control"`
	Bundler       common.Address `json:"bundler"`
	UserOpHash    common.Hash    `json:"userOpHash"`
	CallChainHash common.Hash    `json:"callChainHash"`
	Signature     hexutil.Bytes  `json:"signature"`
}

Decode

Deserializes the dApp operation.

Parameters

No parameters.

Returns

Type	Description
*types.DAppOperation	The deserialized dApp operation.

Example

serializedDAppOperation := &types.DAppOperationRaw{}
dAppOperation := serializedDAppOperation.Decode()

Bundle

type Bundle struct {
	ChainId          uint64
	UserOperation    *types.UserOperation
	SolverOperations types.SolverOperations
	DAppOperation    types.*DAppOperation
}

EncodeToRaw

Returns the serialized version of the bundle.

Parameters

No parameters.

Returns

Type	Description
*types.BundleRaw	The serialized bundle.

Example

bundle := &types.Bundle{}
serializedBundle := bundle.EncodeToRaw()

BundleRaw

type BundleRaw struct {
	ChainId          *hexutil.Big        `json:"chainId"`
	UserOperation    *types.UserOperationRaw   `json:"userOperation"`
	SolverOperations types.SolverOperationsRaw `json:"solverOperations"`
	DAppOperation    *types.DAppOperationRaw   `json:"dAppOperation"`
}

Decode

Deserializes the bundle.

Parameters

No parameters.

Returns

Type	Description
*types.Bundle	The deserialized bundle.

Example

serializedBundle := &types.BundleRaw{}
bundle := serializedBundle.Decode()

Utils

CallChainHash

Compute the call chain hash of the given operations.

Parameters

Name	Type	Description
userOp	*types.UserOperation	A user operation.
solverOps	types.SolverOperations	A slice of solver operations.

Returns

Type	Description
common.Hash	The computed call chain hash.
error	An error object if the call has failed, or nil if the signature is valid.

Example

import "github.com/FastLane-Labs/atlas-sdk-go/core"

userOperation := &types.UserOperation{}
solverOperation1 := &types.SolverOperation{}
solverOperation2 := &types.SolverOperation{}
callChainHash, err := core.CallChainHash(userOperation, []*types.SolverOperation{solverOperation1, solverOperation2})

CallConfigFlags

Collection of functions returning booleans, indicating if dApp control flags are enabled/disabled, given a dApp call config.

import "github.com/FastLane-Labs/atlas-sdk-go/utils"

var enabled bool
var callConfig uint32

enabled = utils.FlagUserNoncesSequential(callConfig)
enabled = utils.FlagDappNoncesSequential(callConfig)
enabled = utils.FlagRequirePreOps(callConfig)
enabled = utils.FlagTrackPreOpsReturnData(callConfig)
enabled = utils.FlagTrackUserReturnData(callConfig)
enabled = utils.FlagDelegateUser(callConfig)
enabled = utils.FlagRequirePreSolver(callConfig)
enabled = utils.FlagRequirePostSolver(callConfig)
enabled = utils.FlagRequirePostOps(callConfig)
enabled = utils.FlagZeroSolvers(callConfig)
enabled = utils.FlagReuseUserOp(callConfig)
enabled = utils.FlagUserAuctioneer(callConfig)
enabled = utils.FlagSolverAuctioneer(callConfig)
enabled = utils.FlagUnknownAuctioneer(callConfig)
enabled = utils.FlagVerifyCallChainHash(callConfig)
enabled = utils.FlagForwardReturnData(callConfig)
enabled = utils.FlagRequireFulfillment(callConfig)
enabled = utils.FlagTrustedOpHash(callConfig)
enabled = utils.FlagInvertBidValue(callConfig)
enabled = utils.FlagExPostBids(callConfig)
enabled = utils.FlagAllowAllocateValueFailure(callConfig)

Overview​

AtlasSdk​

New​

Metacall​

GetBalanceOfBondedAtlEth​

GetDAppCallConfig​

GetDAppConfig​

GetDAppSolverGasLimit​

SetUserNonce​

GetUserNextNonce​

GetDAppNextNonce​

SimulateUserOperation​

SimulateSolverOperation​

SortSolverOperations​

UserOperation​

EncodeToRaw​

Hash​

AbiEncode​

ValidateSignature​

UserOperationRaw​

Decode​

UserOperationPartialRaw​

New​

UserOperationWithHintsRaw​

New​

Decode​

SolverOperation​

EncodeToRaw​

Hash​

AbiEncode​

ValidateSignature​

SolverOperationRaw​

Decode​

DAppOperation​

EncodeToRaw​

Hash​

ValidateSignature​

DAppOperationRaw​

Decode​

Bundle​

EncodeToRaw​

BundleRaw​

Decode​

Utils​

CallChainHash​

CallConfigFlags​

Overview

AtlasSdk

New

Metacall

GetBalanceOfBondedAtlEth

GetDAppCallConfig

GetDAppConfig

GetDAppSolverGasLimit

SetUserNonce

GetUserNextNonce

GetDAppNextNonce

SimulateUserOperation

SimulateSolverOperation

SortSolverOperations

UserOperation

EncodeToRaw

Hash

AbiEncode

ValidateSignature

UserOperationRaw

Decode

UserOperationPartialRaw

New

UserOperationWithHintsRaw

New

Decode

SolverOperation

EncodeToRaw

Hash

AbiEncode

ValidateSignature

SolverOperationRaw

Decode

DAppOperation

EncodeToRaw

Hash

ValidateSignature

DAppOperationRaw

Decode

Bundle

EncodeToRaw

BundleRaw

Decode

Utils

CallChainHash

CallConfigFlags