OZContextRuleManager

public final class OZContextRuleManager : OZContextRuleManagerProtocol, OZManagerHelpers, @unchecked Sendable

Manages context rules for an OpenZeppelin Smart Account.

Context rules define authorization requirements per operation category. Each rule specifies a context type (default, callContract, or createContract), a name, signers, optional policies, and an optional expiration ledger. The smart-account contract evaluates inbound transactions against the rule set to determine which signers must sign and which policy contracts must approve.

Contract limits enforced at validation time: maxSigners signers and maxPolicies policies per rule.

All state-changing methods accept an optional selectedSigners list. An empty list routes through the single-signer path; a non-empty list routes through the kit’s multi-signer manager.

Example:

let result = try await kit.contextRuleManager.addContextRule(
    contextType: .callContract(contractAddress: tokenContractAddress),
    name: "TokenTransfers",
    signers: [signer1, signer2, signer3],
    policies: [policyAddress: installParamsScVal]
)

Show on GitHub

Public API


                    
                    
                    addContextRule(contextType:name:validUntil:signers:policies:selectedSigners:forceMethod:)

Asynchronous

Adds a new context rule to the connected smart account.

Validates the inputs, builds the matching add_context_rule invocation, and routes the resulting host function through either the single-signer or the multi-signer submission path.

Contract limits enforced before submission:

Maximum maxSigners signers per rule.
Maximum maxPolicies policies per rule.

Throws

Throws:

NotConnected when no wallet is connected.
InvalidInput when validation fails.
InvalidAddress when a policy address is malformed.
SmartAccountTransactionException for simulation, signing, or submission failures.

Declaration

Swift

public func addContextRule(
    contextType: OZContextRuleType,
    name: String,
    validUntil: UInt32? = nil,
    signers: [any OZSmartAccountSigner],
    policies: [String: SCValXDR] = [:],
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`contextType`	Operation-matching type for the rule.
`name`	Human-readable rule name (must be non-empty).
`validUntil`	Optional ledger number when this rule expires; `nil` means the rule never expires.
`signers`	Signers authorized by this rule. Either `signers` or `policies` must be non-empty.
`policies`	Map of policy contract addresses (`C…` strkey) to their installation parameters encoded as `SCValXDR`. Keys are sorted by XDR-byte order before submission to satisfy Soroban’s `SCMap` ordering invariant.
`selectedSigners`	Optional multi-signer participants list. Empty routes through single-signer submission; non-empty routes through the multi-signer collaborator.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    getContextRule(id:)

Asynchronous

Returns the raw SCValXDR payload for the rule with the given id. For a typed view, parse with parseContextRule(scVal:) or use listContextRules().

Throws

NotConnected, SimulationFailed.

Declaration

Swift

public func getContextRule(id: UInt32) async throws -> SCValXDR

Parameters

`id`	The context-rule identifier to look up.

Return Value

The raw SCValXDR returned by the contract.

Show on GitHub

getContextRulesCount() Asynchronous
Retrieves the number of context rules currently configured on the connected smart account.

This is a read-only operation that issues a simulated invocation against the connected contract.
Throws

NotConnected when no wallet is connected.

SmartAccountTransactionException when the simulation fails.

InvalidInput when the on-chain result is not a U32.
Declaration
Swift

public func getContextRulesCount() async throws -> UInt32
Return Value

The active rule count parsed as UInt32.

Show on GitHub


                    
                    
                    getAllContextRules(maxScanId:)

Asynchronous

Retrieves every active context rule on the connected contract as raw SCValXDR map payloads, with an optional per-call scan upper bound override.

When maxScanId is non-nil the supplied value is used as the scan upper bound in place of the kit-level default (maxContextRuleScanId). Pass nil to use the kit default.

The contract assigns monotonically increasing identifiers; when a rule is removed its slot becomes empty but the identifier is never reused, creating gaps. This method iterates identifiers from zero upward, skipping gaps reported as SimulationFailed by the underlying simulation, until either the active rule count has been collected or the effective scan upper bound is reached.

Throws

NotConnected when no wallet is connected.
SmartAccountTransactionException for non-gap simulation failures.
SmartAccountValidationException when getContextRulesCount() returns a non-U32 value.

Declaration

Swift

public func getAllContextRules(maxScanId: UInt32? = nil) async throws -> [SCValXDR]

Parameters


                                maxScanId

Per-call scan upper bound override. When nil, the kit configuration’s maxContextRuleScanId is used.

Return Value

One raw SCValXDR per active context rule in ascending id order.

Show on GitHub


                    
                    
                    listContextRules(maxScanId:)

Asynchronous

Returns the parsed view of every active context rule on the connected smart account contract, with an optional per-call scan upper bound override.

When maxScanId is non-nil the supplied value is used as the scan upper bound in place of the kit-level default (maxContextRuleScanId). Pass nil to use the kit default.

Fetches the raw payloads through getAllContextRules(maxScanId:) and parses each via parseContextRule(scVal:).

Throws

NotConnected when no wallet is connected.
SmartAccountTransactionException for simulation failures.
SmartAccountValidationException when a payload cannot be parsed or the count is malformed.

Declaration

Swift

public func listContextRules(maxScanId: UInt32? = nil) async throws -> [OZParsedContextRule]

Parameters


                                maxScanId

Per-call scan upper bound override. When nil, the kit configuration’s maxContextRuleScanId is used.

Return Value

Parsed context rules in ascending rule-id order.

Show on GitHub

Private helpers


                    
                    
                    updateName(id:name:selectedSigners:forceMethod:)

Asynchronous

Updates the human-readable name of an existing context rule.

The on-chain name field is metadata only — it has no effect on rule matching or enforcement.

Throws

NotConnected, InvalidInput, SmartAccountTransactionException.

Declaration

Swift

public func updateName(
    id: UInt32,
    name: String,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`id`	The context-rule identifier to update.
`name`	The new name (must be non-empty).
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    updateValidUntil(id:validUntil:selectedSigners:forceMethod:)

Asynchronous

Updates the expiration ledger of an existing context rule.

Pass nil to clear the expiration (the rule becomes non-expiring). On chain the field is Option<u32>, encoded as Void for None and U32 for Some.

Throws

NotConnected, SmartAccountTransactionException.

Declaration

Swift

public func updateValidUntil(
    id: UInt32,
    validUntil: UInt32?,
    selectedSigners: [OZSelectedSigner] = [],
    forceMethod: OZSubmissionMethod? = nil
) async throws -> OZTransactionResult

Parameters

`id`	The context-rule identifier to update.
`validUntil`	The new expiration ledger, or `nil` to clear.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub


                    
                    
                    removeContextRule(id:selectedSigners:forceMethod:)

Asynchronous

Removes a context rule from the connected smart account.

Removed rules leave a numeric gap in the identifier sequence that getAllContextRules() skips during enumeration.

Throws

NotConnected, SmartAccountTransactionException.

Declaration

Swift

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

Parameters

`id`	The context-rule identifier to remove.
`selectedSigners`	Optional multi-signer participants list.
`forceMethod`	Optional submission-method override.

Return Value

An OZTransactionResult describing the on-chain outcome.

Show on GitHub