OZPolicyManager

public final class OZPolicyManager : OZManagerHelpers, @unchecked Sendable

Manager for policy operations on OpenZeppelin Smart Accounts.

Adds and removes policies on context rules. A context rule may carry up to maxPolicies policies; every attached policy must be satisfied for a transaction to authorize.

Built-in conveniences: addSimpleThreshold, addWeightedThreshold, addSpendingLimit. For custom policy contracts, pass encoded SCValXDR install params to addPolicy(contextRuleId:policyAddress:installParams:selectedSigners:forceMethod:).

All state-changing methods accept an optional selectedSigners list. An empty list routes through the single-signer path (connected passkey); a non-empty list routes through the multi-signer ceremony coordinator.

Example:

let result = try await kit.policyManager.addSimpleThreshold(
    contextRuleId: 0,
    policyAddress: "CBCD1234...",
    threshold: 2
)

Show on GitHub

Initialization


                    
                    
                    addSimpleThreshold(contextRuleId:policyAddress:threshold:selectedSigners:forceMethod:)

Asynchronous

Adds a simple threshold policy to the supplied context rule.

A simple threshold policy authorizes when at least threshold of the context rule’s signers have signed. All signers carry equal weight (one vote each); for weighted voting use addWeightedThreshold(contextRuleId:policyAddress:signerWeights:threshold:selectedSigners:forceMethod:).

Encodes the parameters and delegates to addPolicy(contextRuleId:policyAddress:installParams:selectedSigners:forceMethod:).

Throws

SmartAccountValidationException when validation fails; SmartAccountWalletException when no wallet is connected; SmartAccountTransactionException for simulation, signing, or submission failures.

Declaration

Swift

public func addSimpleThreshold(
    contextRuleId: UInt32,
    policyAddress: String,
    threshold: UInt32,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	The context-rule identifier the policy is being added to (zero is the default rule).
`policyAddress`	Policy contract address (`C…` strkey). Must be a valid contract address — Stellar account `G…` addresses are rejected.
`threshold`	Minimum number of signers that must authorize. Must be greater than zero.
`selectedSigners`	Optional list of signers participating in the authorization ceremony. Empty (default) routes through single-signer submission with the connected passkey; non-empty routes through the multi-signer path.
`forceMethod`	Optional submission-method override. When `nil` the kit’s configured default is used.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    addWeightedThreshold(contextRuleId:policyAddress:signerWeights:threshold:selectedSigners:forceMethod:)

Asynchronous

Adds a weighted threshold policy to the supplied context rule.

A weighted threshold policy authorizes when the sum of weights of every authorizing signer meets or exceeds threshold. Each signer in signerWeights contributes its assigned vote weight when it authorizes.

Encodes the parameters and delegates to addPolicy(contextRuleId:policyAddress:installParams:selectedSigners:forceMethod:).

Throws

SmartAccountValidationException for invalid input; SmartAccountWalletException for missing connection; SmartAccountTransactionException for submission failures.

Declaration

Swift

public func addWeightedThreshold(
    contextRuleId: UInt32,
    policyAddress: String,
    signerWeights: [OZSignerWeightEntry],
    threshold: UInt32,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	The context-rule identifier the policy is being added to (zero is the default rule).
`policyAddress`	Policy contract address (`C…` strkey).
`signerWeights`	One `OZSignerWeightEntry` per signer with its assigned vote weight. Must contain at least one entry.
`threshold`	Minimum summed weight required to authorize. Must be greater than zero.
`selectedSigners`	Optional multi-signer participants list (see `addSimpleThreshold(contextRuleId:policyAddress:threshold:selectedSigners:forceMethod:)`).
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    addSpendingLimit(contextRuleId:policyAddress:spendingLimit:periodLedgers:decimals:selectedSigners:forceMethod:)

Asynchronous

Adds a spending limit policy to the supplied context rule.

A spending limit policy caps the cumulative spend within a rolling periodLedgers-ledger window (Stellar produces a ledger approximately every five seconds; ledgersPerHour supplies the canonical hour count, and ~17 280 ledgers approximates one day).

The amount is supplied as a positive decimal string and converted to the token’s base units using decimals (default 7).

Throws

SmartAccountValidationException for invalid input; SmartAccountWalletException for missing connection; SmartAccountTransactionException for submission failures.

Declaration

Swift

public func addSpendingLimit(
    contextRuleId: UInt32,
    policyAddress: String,
    spendingLimit: String,
    periodLedgers: UInt32,
    decimals: Int = 7,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	Context-rule identifier the policy is being added to (zero is the default rule).
`policyAddress`	Policy contract address (`C…` strkey).
`spendingLimit`	Maximum cumulative amount per period as a positive decimal string (for example `"100"` or `"0.5"`). Converted to the token’s base units internally using `decimals`; up to `decimals` fractional digits are accepted.
`periodLedgers`	Rolling-window length in ledgers. Must be greater than zero.
`decimals`	The token’s decimal scale used to convert `spendingLimit` to base units. Defaults to 7. This method has no token-contract parameter and therefore does not fetch the scale automatically.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    removePolicy(contextRuleId:policyId:selectedSigners:forceMethod:)

Asynchronous

Removes a policy from a context rule by its on-chain numeric id.

The id is assigned by the smart-account contract when the policy is installed and surfaces on the parsed context rule’s policyIds field. Use removePolicyByAddress(contextRuleId:policyAddress:selectedSigners:forceMethod:) when only the policy contract address is known — that overload resolves the id internally with one extra RPC round trip.

Throws

SmartAccountWalletException for missing connection; SmartAccountTransactionException for submission failures.

Declaration

Swift

public func removePolicy(
    contextRuleId: UInt32,
    policyId: UInt32,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	Context-rule identifier the policy is being removed from (zero is the default rule).
`policyId`	Numeric policy identifier assigned at installation time.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    removePolicyByAddress(contextRuleId:policyAddress:selectedSigners:forceMethod:)

Asynchronous

Removes a policy from a context rule by matching the policy contract address.

Convenience overload that resolves the on-chain numeric policy id internally before delegating to removePolicy(contextRuleId:policyId:selectedSigners:forceMethod:). One extra RPC round trip is performed to fetch the context rule and locate the policy address within the rule’s policies list.

Throws

SmartAccountWalletException for missing connection; SmartAccountValidationException when policyAddress is malformed or absent from the rule; SmartAccountTransactionException for submission failures.

Note

The Swift name differs from the underlying contract method to distinguish this overload at the call site from the id-based removePolicy(contextRuleId:policyId:selectedSigners:forceMethod:). The byAddress suffix keeps the call site self-documenting.

Declaration

Swift

public func removePolicyByAddress(
    contextRuleId: UInt32,
    policyAddress: String,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	Context-rule identifier the policy is being removed from.
`policyAddress`	Policy contract address (`C…` strkey) to match against the rule’s installed policies.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    addPolicy(contextRuleId:policyAddress:installParams:selectedSigners:forceMethod:)

Asynchronous

Adds a policy to a context rule with caller-supplied installation parameters.

This is the generic method that addSimpleThreshold(contextRuleId:policyAddress:threshold:selectedSigners:forceMethod:), addWeightedThreshold(contextRuleId:policyAddress:signerWeights:threshold:selectedSigners:forceMethod:), and addSpendingLimit(contextRuleId:policyAddress:spendingLimit:periodLedgers:selectedSigners:forceMethod:) delegate to. Use this method directly when installing a custom policy contract that is not covered by the convenience methods.

Throws

SmartAccountWalletException for missing connection; SmartAccountValidationException when policyAddress is malformed; SmartAccountTransactionException for submission failures.

Declaration

Swift

public func addPolicy(
    contextRuleId: UInt32,
    policyAddress: String,
    installParams: SCValXDR,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextRuleId`	Context-rule identifier the policy is being added to.
`policyAddress`	Policy contract address (`C…` strkey).
`installParams`	Policy-specific installation parameters encoded as `SCValXDR`. The structure depends on the target policy contract; for the three built-in policy types use `toScVal()` on the matching enum case.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub

ScMap key sorting


                    
                    
                    sortMapByKeyXdr(_:)

Sorts a list of SCMapEntryXDR entries into the Soroban host’s ScMap key order.

The host stores and validates ScMap keys in a semantic order (see compareScValHostOrder) and rejects a map materialized from an out-of-order SCVal argument. Use this helper whenever a dynamically-keyed map is built from caller-supplied data so the on-chain shape is deterministic regardless of insertion order.

The supplied list is not mutated; a new sorted list is returned. Two entries with equal keys preserve their relative input order (stable sort), but equal keys signal a duplicate-key bug and the on-chain host rejects such maps at simulation time.

Declaration

Swift

public static func sortMapByKeyXdr(
    _ entries: [SCMapEntryXDR]
) -> [SCMapEntryXDR]

Parameters


                                entries

Entries to sort.

Return Value

A new array of entries whose keys are in the host’s ScMap key order.

Show on GitHub