SorobanClient

public final class SorobanClient : Sendable

High-level client for interacting with deployed Soroban smart contracts.

SorobanClient provides a simplified interface for common contract operations:

  • Installing contract WebAssembly code
  • Deploying contracts with constructor arguments
  • Invoking contract methods (both read-only and write operations)
  • Automatic transaction construction, simulation, and submission

The client automatically handles:

  • Transaction building with correct parameters
  • Simulation to get resource requirements
  • Distinguishing between read and write calls
  • Return value extraction from transaction results

Use this class when you want a streamlined experience for contract interaction. For more control over transaction construction, use AssembledTransaction directly.

Example usage:

// Connect to an existing contract
let clientOptions = ClientOptions(
    sourceAccountKeyPair: sourceKeyPair,
    contractId: "CCONTRACT123...",
    network: Network.testnet,
    rpcUrl: "https://soroban-testnet.stellar.org"
)
let client = try await SorobanClient.forClientOptions(options: clientOptions)

// Invoke a read-only method
let balance = try await client.invokeMethod(
    name: "balance",
    args: [try SCValXDR.address(userAddress)]
)

// Invoke a write method
let result = try await client.invokeMethod(
    name: "transfer",
    args: [fromAddr, toAddr, amount]
)
print("Transfer result: \(result)")

See also:

  • [AssembledTransaction] for lower-level transaction control
  • [ContractSpec] for contract interface parsing
  • Stellar developer docs
Show on GitHub

  • spec entries of the contract represented by this client.

    Declaration

    Swift

    public let specEntries: [SCSpecEntryXDR]
    Show on GitHub

  • method names of the represented contract.

    Declaration

    Swift

    public let methodNames: [String]
    Show on GitHub

  • Loads the contract info for the contractId provided by the options, and the constructs a SorobanClient by using the loaded contract info.

    Declaration

    Swift

    public static func forClientOptions(options: ClientOptions) async throws -> SorobanClient

    Parameters

    options

    Client options.
    Show on GitHub
  • deploy(deployRequest:) Asynchronous

    Deploys a smart contract to the Stellar network.

    Contract deployment involves:

    1. Installing the contract WASM code (use install method first)
    2. Creating a contract instance with a unique contract ID
    3. Optionally invoking the contract’s constructor function

    The contract must be installed before deployment. Use SorobanClient.install to upload the contract code and obtain a wasm hash, then use that hash in the deploy request.

    Throws

    SorobanClientError if deployment fails

    Example:

    // First install the contract
let installRequest = InstallRequest(
    sourceAccountKeyPair: keyPair,
    wasmBytes: contractWasmBytes,
    network: Network.testnet,
    rpcUrl: "https://soroban-testnet.stellar.org"
)
let wasmHash = try await SorobanClient.install(installRequest: installRequest)

// Then deploy it
let deployRequest = DeployRequest(
    sourceAccountKeyPair: keyPair,
    wasmHash: wasmHash,
    network: Network.testnet,
    rpcUrl: "https://soroban-testnet.stellar.org",
    constructorArgs: [arg1, arg2]  // Constructor arguments if needed
)
let client = try await SorobanClient.deploy(deployRequest: deployRequest)
print("Contract deployed at: \(client.contractId)")

    See also:

    Declaration

    Swift

    public static func deploy(deployRequest: DeployRequest) async throws -> SorobanClient

    Parameters

    deployRequest

    Deployment parameters including wasm hash, constructor arguments, and network settings

    Return Value

    SorobanClient instance connected to the newly deployed contract

    Show on GitHub

  • Deploys a new contract instance from a CAP-85 external reference (protocol >= 28) and creates a SorobanClient for it.

    The executable of the new instance names an owner contract and a tag; the owner’s persistent entry under that tag holds the hash of the wasm the instance runs. The tag is matched byte for byte as the request carries it. Nothing is installed as part of the deployment.

    The create operation uses the CREATE_CONTRACT_V2 host function form with the given constructor arguments (an empty vector when none are given), as deploy does. For the plain CREATE_CONTRACT form, build the operation directly with InvokeHostFunctionOperation.forCreatingContractFromExternalRef.

    The reference is resolved before the transaction is built, so an unresolvable reference fails here with a SorobanClientError.deployFailed naming the owner and the tag and carrying the resolver’s message.

    The returned client’s spec comes from the wasm the tag names at deployment time. Re-pointing the tag later changes the code the instance runs, not the spec this client loaded.

    Throws

    SorobanClientError if the reference does not resolve or deployment fails

    Declaration

    Swift

    public static func deployFromExternalRef(deployRequest: DeployFromExternalRefRequest) async throws -> SorobanClient

    Parameters

    deployRequest

    Deployment parameters including the executable owner, the tag, constructor args, and salt

    Return Value

    The client for the newly deployed contract

    Show on GitHub

  • Installs (uploads) contract WebAssembly code to the Stellar network.

    Installing a contract is the first step in contract deployment. This operation uploads the compiled WebAssembly bytecode to the network and returns a unique hash identifier. The same WASM code can be used to deploy multiple contract instances.

    The installation process:

    1. Uploads the WASM bytecode to the network
    2. This hash is then used when deploying contract instances

    Note: If the code is already installed, this operation will detect it during simulation and can return the existing hash without submitting a transaction (unless force is true).

    Throws

    SorobanClientError if installation fails

    Example:

    // Load contract WASM file
let wasmBytes = try Data(contentsOf: contractWasmUrl)

// Install the contract
let installRequest = InstallRequest(
    sourceAccountKeyPair: keyPair,
    wasmBytes: wasmBytes,
    network: Network.testnet,
    rpcUrl: "https://soroban-testnet.stellar.org"
)
let wasmHash = try await SorobanClient.install(installRequest: installRequest)
print("Contract code installed with hash: \(wasmHash)")

// Use this hash to deploy contract instances

    See also:

    Declaration

    Swift

    public static func install(installRequest: InstallRequest, force: Bool = false) async throws -> String

    Parameters

    installRequest

    Installation parameters including WASM bytes, source account, and network settings
    force

    If true, always submit transaction even if code is already installed. Default is false.

    Return Value

    Hex-encoded hash of the installed WASM code

    Show on GitHub

  • contract id of the contract represented by this client.

    Declaration

    Swift

    public var contractId: String { get }
    Show on GitHub

  • Invokes a contract method. It can be used for read only calls and for read/write calls. Returns the result of the invocation. If it is read only call it will return the result from the simulation. If you want to force signing and submission even if it is a read only call set forceto true.

    Declaration

    Swift

    public func invokeMethod(name: String, args: [SCValXDR]? = nil, force: Bool = false, methodOptions: MethodOptions? = nil) async throws -> SCValXDR

    Parameters

    name

    the name of the method to invoke. Will throw an exception if the method does not exist.
    args

    the arguments to pass to the method call.
    force

    force singing and sending the transaction even if it is a read call. Default false.
    methodOptions

    method options for fine-tuning the call.
    Show on GitHub

  • Creates an AssembledTransaction for invoking the given method. This is usefully if you need to manipulate the transaction before signing and sending.

    Declaration

    Swift

    public func buildInvokeMethodTx(name: String, args: [SCValXDR]? = nil, methodOptions: MethodOptions? = nil, enableServerLogging: Bool? = nil) async throws -> AssembledTransaction

    Parameters

    name

    the name of the method to invoke. Will throw an exception if the method does not exist.
    args

    the arguments to pass to the method call.
    methodOptions

    method options for fine-tuning the call.
    Show on GitHub

  • Gets the spec entries of the contract represented by this client.

    Declaration

    Swift

    public func getSpecEntries() -> [SCSpecEntryXDR]

    Return Value

    Array of SCSpecEntryXDR objects

    Show on GitHub

  • Creates a ContractSpec instance for this contract.

    Declaration

    Swift

    public func getContractSpec() -> ContractSpec

    Return Value

    ContractSpec instance that can be used for type conversions

    Show on GitHub