OZTransactionOperations

public final class OZTransactionOperations : OZManagerHelpers, @unchecked Sendable

Transaction-pipeline operations for OpenZeppelin Smart Accounts.

Builds, signs, and submits transactions for a connected smart account wallet. Drives the full simulate / sign / re-simulate / submit pipeline, including WebAuthn auth-entry signing, relayer-vs-RPC submission selection, and transaction-result polling.

When a relayer is configured, submission mode is auto-selected: Mode 1 (host function + auth entries, envelope unsigned) when all auth entries use Address credentials; Mode 2 (signed envelope XDR forwarded to the relayer) when any auth entry carries sourceAccount credentials. The forceMethod parameter overrides auto-detection per call.

The transaction is re-simulated after the signing pass so that resource fees reflect the real WebAuthn signature payload size.

Instances are constructed by OZSmartAccountKit and accessed through kit.transactionOperations.

Show on GitHub

Initialization


                    
                    
                    transfer(tokenContract:recipient:amount:decimals:forceMethod:)

Asynchronous

Transfers tokens from the connected smart account to a recipient.

Compatible with any SEP-41 token (native asset via the Stellar Asset Contract, or custom Soroban tokens). The decimal amount is converted to the token’s base units before submission: the decimals value is used when supplied, otherwise the token’s on-chain decimals() is fetched automatically via fetchTokenDecimals(tokenContract:). Delegates to contractCall(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:) to drive the full simulate / sign / submit pipeline.

Throws

NotConnected when no wallet is connected; SmartAccountValidationException for invalid inputs or self-transfer; SmartAccountTransactionException for simulation, signing, or submission failures; WebAuthnException for biometric-authentication failures.

Declaration

Swift

public func transfer(
    tokenContract: String,
    recipient: String,
    amount: String,
    decimals: Int? = nil,
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`tokenContract`	SEP-41 token contract address (`C…` strkey).
`recipient`	Recipient address (`G…` account or `C…` contract).
`amount`	Decimal amount string (for example `"10"` or `"100.5"`).
`decimals`	The token’s decimal scale used to convert `amount` to base units. When `nil` (default) the value is fetched on-chain via `fetchTokenDecimals(tokenContract:)`. Supply it to avoid the extra RPC round trip when the scale is already known.
`forceMethod`	Optional submission-method override.

Return Value

OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    fetchTokenDecimals(tokenContract:)

Asynchronous

Reads the decimals() value from a SEP-41 token contract.

Simulates the token contract’s decimals function and returns the reported u32 scale.

Throws

SmartAccountValidationException when tokenContract is not a valid contract address; SmartAccountTransactionException when the simulation fails or the contract does not return a valid u32 value.

Declaration

Swift

public func fetchTokenDecimals(tokenContract: String) async throws -> Int

Parameters


                                tokenContract

SEP-41 token contract address (C… strkey).

Return Value

The token’s decimal scale.

Show on GitHub


                    
                    
                    contractCall(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:)

Asynchronous

Calls an arbitrary function on an external contract directly from the smart account.

The smart account authorizes the call via Soroban’s require_auth mechanism triggered by the target contract. Use this for any external contract interaction (token approvals, token transfers, DeFi protocol calls) where the smart account is the authorized party.

Throws

NotConnected, SmartAccountValidationException, SmartAccountTransactionException, WebAuthnException, SmartAccountCredentialException.

Declaration

Swift

public func contractCall(
    target: String,
    targetFn: String,
    targetArgs: [SCValXDR] = [],
    forceMethod: OZSubmissionMethod? = nil,
    resolveContextRuleIds: OZResolveContextRuleIds? = nil
) async throws -> OZTransactionResult

Parameters

`target`	Target contract address (`C…` strkey).
`targetFn`	Function name to invoke on the target contract.
`targetArgs`	Pre-encoded SCVal arguments forwarded to the function.
`forceMethod`	Optional submission-method override.
`resolveContextRuleIds`	Optional override of the automatic context-rule resolution performed during the signing loop.

Return Value

OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    executeAndSubmit(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:)

Asynchronous

Executes an arbitrary function via the smart account contract’s execute entry point.

Calls execute(target, target_fn, target_args) on the smart account contract; the contract dispatches the inner call on behalf of the smart account after evaluating its context rules and policies.

Throws

NotConnected, SmartAccountValidationException, SmartAccountTransactionException, WebAuthnException, SmartAccountCredentialException.

Declaration

Swift

public func executeAndSubmit(
    target: String,
    targetFn: String,
    targetArgs: [SCValXDR] = [],
    forceMethod: OZSubmissionMethod? = nil,
    resolveContextRuleIds: OZResolveContextRuleIds? = nil
) async throws -> OZTransactionResult

Parameters

`target`	Target contract address (`C…` strkey).
`targetFn`	Function name to invoke on the target contract.
`targetArgs`	Pre-encoded SCVal arguments forwarded to the inner call.
`forceMethod`	Optional submission-method override.
`resolveContextRuleIds`	Optional context-rule resolver override.

Return Value

OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    submit(hostFunction:auth:forceMethod:resolveContextRuleIds:)

Asynchronous

Submits a host function through the full simulate / sign / re-simulate / submit pipeline.

This is the low-level entry point used by transfer(tokenContract:recipient:amount:forceMethod:), contractCall(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:), and executeAndSubmit(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:). Callers that need to construct a host function manually use this method directly. The auth-entry signing pass writes the OpenZeppelin AuthPayload Map directly into the credentials’ signature field; the transaction is re-simulated after signing because WebAuthn signatures are larger than the placeholders the initial simulation used.

Throws

NotConnected, SmartAccountValidationException, SmartAccountTransactionException, WebAuthnException, SmartAccountCredentialException.

Declaration

Swift

public func submit(
    hostFunction: HostFunctionXDR,
    auth: [SorobanAuthorizationEntryXDR],
    forceMethod: OZSubmissionMethod? = nil,
    resolveContextRuleIds: OZResolveContextRuleIds? = nil
) async throws -> OZTransactionResult

Parameters

`hostFunction`	Host function to execute.
`auth`	Authorization entries supplied as input to the simulation (typically empty — the simulation discovers them).
`forceMethod`	Optional submission-method override.
`resolveContextRuleIds`	Optional context-rule resolver override.

Return Value

OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    fundWallet(nativeTokenContract:forceMethod:)

Asynchronous

Funds the connected smart account wallet using Friendbot (testnet only).

Generates a fresh temporary keypair, funds it via Friendbot, queries its XLM balance via the native token contract, and transfers the surplus (balance minus the protocol minimum-balance reserve) to the smart account contract. Source-account authorization entries from the transfer simulation are converted to classical Ed25519 Address credentials so the relayer can substitute its own channel accounts for fee sponsoring.

The conversion uses the classical Stellar Ed25519 signature shape (Vec([Map({public_key, signature})])), NOT the OpenZeppelin AuthPayload Map written by the smart-account signing path — the temp keypair is a classical Stellar account, not a smart account.

Throws

NotConnected, SmartAccountValidationException, SmartAccountTransactionException.

Declaration

Swift

public func fundWallet(
    nativeTokenContract: String,
    forceMethod: OZSubmissionMethod? = nil
) async throws -> String

Parameters

`nativeTokenContract`	Native token contract address (`C…` strkey).
`forceMethod`	Optional submission-method override.

Return Value

Funded amount as a decimal XLM string (for example "100" or "12.34567"). Trailing zeroes in the fractional component are trimmed.

Show on GitHub

Static helpers


                    
                    
                    amountToBaseUnits(_:decimals:)

Converts a positive decimal amount string to its base-units representation scaled by decimals decimal places.

Rejects scientific notation, empty or non-numeric strings, values less than or equal to zero, and values carrying more fractional digits than decimals allows. Accepted shape: ^[0-9]+(\.[0-9]+)?$ with at most decimals fractional digits and a result greater than zero.

Throws

InvalidAmount when the input is invalid or out of the i128 representable range.

Declaration

Swift

public static func amountToBaseUnits(_ amount: String, decimals: Int) throws -> String

Parameters

`amount`	Positive decimal string (for example `"10"` or `"100.5"`).
`decimals`	The token’s decimal scale. Must be in `0...maxTokenDecimals`. A value of `0` accepts only integer amounts and rejects any fractional digit.

Return Value

The base-units amount as a non-negative decimal integer string with no leading zeros (except the single digit "0").

Show on GitHub