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.

Initialization

NewAtlasSdk

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

Parameters

Name	Type	Description
ethClient	[]*ethclient.Client	A slice of Ethereum clients connected to different blockchain networks.
chainOverrides	map[uint64]*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

clients := []*ethclient.Client{client1, client2}
overrides := map[uint64]*config.ChainConfig{
    1: &config.ChainConfig{ /* ... */ },
    4: &config.ChainConfig{ /* ... */ },
}
sdk, err := core.NewAtlasSdk(clients, overrides)
if err != nil {
    log.Fatalf("Failed to initialize Atlas SDK: %v", err)
}

Contract Retrieval

GetAtlasContract

Retrieves the Atlas contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.

Returns

Type	Description
*atlas.Atlas	The Atlas contract instance associated with the chain ID.
error	An error object if the contract is not found or retrieval fails.

Example

atlasContract, err := sdk.GetAtlasContract(1)
if err != nil {
    log.Fatalf("Failed to get Atlas contract: %v", err)
}

GetAtlasVerificationContract

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.

Returns

Type	Description
*atlasverification.AtlasVerification	The Atlas Verification contract instance associated with the chain ID.
error	An error object if the contract is not found or retrieval fails.

Example

atlasVerifContract, err := sdk.GetAtlasVerificationContract(1)
if err != nil {
    log.Fatalf("Failed to get Atlas Verification contract: %v", err)
}

GetSimulatorContract

Retrieves the Simulator contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.

Returns

Type	Description
*simulator.Simulator	The Simulator contract instance associated with the chain ID.
error	An error object if the contract is not found or retrieval fails.

Example

simulatorContract, err := sdk.GetSimulatorContract(1)
if err != nil {
    log.Fatalf("Failed to get Simulator contract: %v", err)
}

GetSorterContract

Retrieves the Sorter contract instance for a specific blockchain network.

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.

Returns

Type	Description
*sorter.Sorter	The Sorter contract instance associated with the chain ID.
error	An error object if the contract is not found or retrieval fails.

Example

sorterContract, err := sdk.GetSorterContract(1)
if err != nil {
    log.Fatalf("Failed to get Sorter contract: %v", err)
}

Simulation Methods

SimulateUserOperation

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
userOp	*types.UserOperation	The user operation to be simulated.

Returns

Type	Description
error	An error object if the simulation fails.

Example

err := sdk.SimulateUserOperation(1, userOperation)
if err != nil {
    log.Fatalf("User operation simulation failed: %v", err)
}

SimulateSolverOperation

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
userOp	*types.UserOperation	The user operation associated with the solver operation.
solverOp	*types.SolverOperation	The solver operation to be simulated.

Returns

Type	Description
error	An error object if the simulation fails.

Example

err := sdk.SimulateSolverOperation(1, userOperation, solverOperation)
if err != nil {
    log.Fatalf("Solver operation simulation failed: %v", err)
}

Configuration Methods

GetDAppCallConfig

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
dAppControlAddr	common.Address	The Ethereum address of the DApp Control contract.

Returns

Type	Description
uint32	The call configuration flags for the DApp.
error	An error object if retrieval fails.

Example

callConfig, err := sdk.GetDAppCallConfig(1, dAppControlAddress)
if err != nil {
    log.Fatalf("Failed to get DApp call config: %v", err)
}

GetDAppConfig

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
userOp	*types.UserOperation	The user operation associated with the DApp configuration.
dAppControlAddr	common.Address	The Ethereum address of the DApp Control contract.

Returns

Type	Description
*dappcontrol.DAppConfig	The configuration settings of the DApp.
error	An error object if retrieval fails.

Example

dAppConfig, err := sdk.GetDAppConfig(1, userOperation, dAppControlAddress)
if err != nil {
    log.Fatalf("Failed to get DApp config: %v", err)
}

Nonce Management

SetUserNonce

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
userOp	*types.UserOperation	The user operation for which the nonce is set.

Returns

Type	Description
error	An error object if setting the nonce fails.

Example

err := sdk.SetUserNonce(1, userOperation)
if err != nil {
    log.Fatalf("Failed to set user nonce: %v", err)
}

GetUserNextNonce

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
user	common.Address	The Ethereum address of the user.
callConfig	uint32	The call configuration flags affecting nonce retrieval.

Returns

Type	Description
*big.Int	The next nonce value for the user.
error	An error object if retrieval fails.

Example

nextNonce, err := sdk.GetUserNextNonce(1, userAddress, callConfig)
if err != nil {
    log.Fatalf("Failed to get user next nonce: %v", err)
}

GetDAppNextNonce

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
dApp	common.Address	The Ethereum address of the DApp.
callConfig	uint32	The call configuration flags affecting nonce retrieval.

Returns

Type	Description
*big.Int	The next nonce value for the DApp.
error	An error object if retrieval fails.

Example

dAppNonce, err := sdk.GetDAppNextNonce(1, dAppAddress, callConfig)
if err != nil {
    log.Fatalf("Failed to get DApp next nonce: %v", err)
}

Operation Sorting

SortSolverOperations

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

Parameters

Name	Type	Description
chainId	uint64	The identifier of the blockchain network.
userOp	*types.UserOperation	The user operation associated with the solver operations.
solverOps	types.SolverOperations	A slice of solver operations to be sorted.

Returns

Type	Description
types.SolverOperations	The sorted slice of solver operations.
error	An error object if sorting fails or the Sorter contract is not found.

Example

sortedSolverOps, err := sdk.SortSolverOperations(1, userOperation, solverOperations)
if err != nil {
    log.Fatalf("Failed to sort solver operations: %v", err)
}

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
chainId	uint64	The identifier of the blockchain network where the meta-call will be executed.
transactOpts	*bind.TransactOpts	Transaction options, including gas price, gas limit, and the sender's address.
userOp	*types.UserOperation	The user operation to be included in the meta-call.
solverOps	types.SolverOperations	A slice of solver operations to be included in the meta-call.
dAppOp	*types.DAppOperation	The DApp operation to be included in the meta-call.

Returns

Type	Description
*gethTypes.Transaction	The Ethereum transaction object representing the meta-call.
error	An error object if the meta-call execution fails.

Example

tx, err := sdk.Metacall(chainId, transactOpts, userOperation, solverOperations, dAppOperation)
if err != nil {
    log.Fatalf("Failed to execute meta-call: %v", err)
}
fmt.Printf("Meta-call transaction sent: %s", tx.Hash().Hex())

Utility Functions

CallChainHash

Calculates the hash of a chain of user and solver operations using Keccak256.

Parameters

Name	Type	Description
userOp	*types.UserOperation	The user operation for which the chain hash is calculated.
solverOps	types.SolverOperations	A slice of solver operations involved in the chain hash.

Returns

Type	Description
common.Hash	The resulting Keccak256 hash of the operation chain.
error	An error object if encoding fails.

Example

chainHash, err := sdk.CallChainHash(userOperation, solverOperations)
if err != nil {
    log.Fatalf("Failed to calculate chain hash: %v", err)
}
fmt.Printf("Chain Hash: %s", chainHash.Hex())

Testing

TestCallChainHashWithSolverOperations

Tests the CallChainHash function with multiple solver operations to ensure correct hash computation.

Example

func TestCallChainHashWithSolverOperations(t *testing.T) {
    t.Parallel()

    userOp := generateUserOperation()
    solverOp := generateSolverOperation()
    solverOps := []*types.SolverOperation{solverOp, solverOp, solverOp}

    want := common.HexToHash("0x8a71f907fe61688772ede6e7bb91efa992fe86c27917862adf533984dd56a2b8")

    result, err := CallChainHash(userOp, solverOps)
    if err != nil {
        t.Errorf("CallChainHash() error = %v", err)
    }

    if result != want {
        t.Errorf("CallChainHash() = %v, want %v", result, want)
    }
}

TestCallChainHashWithoutSolverOperations

Tests the CallChainHash function without any solver operations to ensure correct hash computation.

Example

func TestCallChainHashWithoutSolverOperations(t *testing.T) {
    t.Parallel()

    userOp := generateUserOperation()
    solverOps := []*types.SolverOperation{}

    want := common.HexToHash("0x1feca496343f60c6fd5bfa97ec935fed62285b814ef720ac633dabb1c6e25777")

    result, err := CallChainHash(userOp, solverOps)
    if err != nil {
        t.Errorf("CallChainHash() error = %v", err)
    }

    if result != want {
        t.Errorf("CallChainHash() = %v, want %v", result, want)
    }
}

Error Handling

All methods in the Atlas SDK return an error type as the last return value. It is essential to handle these errors appropriately to ensure the robustness of your application. Always check for errors after invoking SDK methods and implement necessary fallback or retry mechanisms as needed.

Example

result, err := sdk.SomeMethod(params)
if err != nil {
    // Handle the error accordingly
    log.Printf("An error occurred: %v", err)
    // Implement fallback or retry logic if applicable
    return handleError(err)
}

When handling errors, consider the following best practices:

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

log.Printf("Failed to execute operation %s: %v", operationName, err)

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

type NetworkError struct {
    Err error
}

func (e NetworkError) Error() string {
    return fmt.Sprintf("Network error: %v", e.Err)
}

// Usage
if err, ok := err.(NetworkError); ok {
    // Handle network-specific error
}

Implement retry mechanisms: For transient errors, implement a retry mechanism with backoff.

func retryOperation(operation func() error, maxRetries int) error {
    var err error
    for i := 0; i < maxRetries; i++ {
        err = operation()
        if err == nil {
            return nil
        }
        time.Sleep(time.Second * time.Duration(1<<uint(i))) // Exponential backoff
    }
    return fmt.Errorf("operation failed after %d retries: %v", maxRetries, err)
}

Provide meaningful error messages: Ensure that error messages are clear and actionable.

if err != nil {
    return fmt.Errorf("failed to process transaction: %w", err)
}

Remember to tailor your error handling approach to the specific needs of your application and the criticality of each operation within the Atlas SDK.

Overview​

Initialization​

NewAtlasSdk​

Contract Retrieval​

GetAtlasContract​

GetAtlasVerificationContract​

GetSimulatorContract​

GetSorterContract​

Simulation Methods​

SimulateUserOperation​

SimulateSolverOperation​

Configuration Methods​

GetDAppCallConfig​

GetDAppConfig​

Nonce Management​

SetUserNonce​

GetUserNextNonce​

GetDAppNextNonce​

Operation Sorting​

SortSolverOperations​

Meta-call Execution​

Metacall​

Utility Functions​

CallChainHash​

Testing​

TestCallChainHashWithSolverOperations​

TestCallChainHashWithoutSolverOperations​

Error Handling​

Overview

Initialization

NewAtlasSdk

Contract Retrieval

GetAtlasContract

GetAtlasVerificationContract

GetSimulatorContract

GetSorterContract

Simulation Methods

SimulateUserOperation

SimulateSolverOperation

Configuration Methods

GetDAppCallConfig

GetDAppConfig

Nonce Management

SetUserNonce

GetUserNextNonce

GetDAppNextNonce

Operation Sorting

SortSolverOperations

Meta-call Execution

Metacall

Utility Functions

CallChainHash

Testing

TestCallChainHashWithSolverOperations

TestCallChainHashWithoutSolverOperations

Error Handling