OZPolicyInstallParams

public enum OZPolicyInstallParams : Sendable

Installation parameters for the three built-in OpenZeppelin policy types.

Policies are authorization rules attached to context rules. A context rule can hold up to maxPolicies policies, and every attached policy must be satisfied for a transaction to authorize. Three built-in policy contracts ship with the OZ smart-account suite:

  • simpleThreshold(threshold:) — M-of-N authorization with equal weight per signer.
  • weightedThreshold(signerWeights:threshold:) — weighted voting with a configurable per-signer weight.
  • spendingLimit(spendingLimit:periodLedgers:) — maximum spend amount per rolling time window expressed in ledgers.

Each arm encodes its parameters into the Map-shaped SCValXDR value the installation contract expects. Inner key ordering is normalized to satisfy the Soroban host’s strict map-key ordering requirement.

Most callers should prefer the convenience methods on OZPolicyManager (addSimpleThreshold(contextRuleId:policyAddress:threshold:selectedSigners:forceMethod:), addWeightedThreshold(contextRuleId:policyAddress:signerWeights:threshold:selectedSigners:forceMethod:), OZPolicyManager/addSpendingLimit(contextRuleId:policyAddress:spendingLimit:periodLedgers:selectedSigners:forceMethod:)) which build the matching OZPolicyInstallParams value internally. Callers that need to install a custom policy contract construct the SCValXDR directly and pass it to addPolicy(contextRuleId:policyAddress:installParams:selectedSigners:forceMethod:).

Example:

// 2-of-3 simple threshold.
let simple = OZPolicyInstallParams.simpleThreshold(threshold: 2)

// Weighted vote with a single Stellar-account-backed signer.
let signer = try OZDelegatedSigner(address: "GAAZI4TCR3TY...")
let weighted = OZPolicyInstallParams.weightedThreshold(
    signerWeights: [OZSignerWeightEntry(signer: signer, weight: 50)],
    threshold: 50
)

// Spend at most one XLM per ledger day.
let spending = OZPolicyInstallParams.spendingLimit(
    spendingLimit: "1",
    periodLedgers: 17_280
)
Show on GitHub

  • Simple threshold policy requiring at least threshold of the context rule’s signers to authorize. All signers carry equal weight (one vote each).

    Declaration

    Swift

    case simpleThreshold(threshold: UInt32)

    Parameters

    threshold

    Minimum number of distinct signers required to authorize. Must be greater than zero.
    Show on GitHub

  • Weighted threshold policy requiring authorizing signers’ summed weights to meet or exceed threshold.

    Declaration

    Swift

    case weightedThreshold(signerWeights: [OZSignerWeightEntry], threshold: UInt32)

    Parameters

    signerWeights

    One OZSignerWeightEntry per signer with its assigned vote weight. Must contain at least one entry. Order is normalized internally — callers may supply any insertion order.
    threshold

    Minimum summed weight required to authorize. Must be greater than zero.
    Show on GitHub

  • Spending limit policy capping cumulative spend within a rolling periodLedgers-ledger window.

    Declaration

    Swift

    case spendingLimit(spendingLimit: String, periodLedgers: UInt32)

    Parameters

    spendingLimit

    Maximum cumulative amount in the token’s base units as a non-negative integer string (digits only, no decimal point). This is the raw on-chain amount already scaled by the token’s decimals; the caller is responsible for that scaling.
    periodLedgers

    Rolling window length in ledgers (Stellar produces a ledger approximately every five seconds). Must be greater than zero.
    Show on GitHub

  • Encodes the installation parameters into the Map-shaped SCValXDR value the installation contract expects.

    Inner key ordering is normalized via sortMapByKeyXdr(_:) where dynamic keys are present (only weightedThreshold(signerWeights:threshold:) has a dynamic-key inner map). Outer struct-shaped keys (signer_weights, threshold, period_ledgers, spending_limit) are inserted in alphabetical order to satisfy the Soroban Rust #[contracttype] derive convention.

    Throws

    InvalidInput when the variant’s parameters are invalid (zero threshold, empty signer weights, non-positive spending limit, zero period, or malformed spending-limit string).

    Declaration

    Swift

    public func toScVal() throws -> SCValXDR

    Return Value

    The encoded SCValXDR map suitable for passing as the installParams argument of the smart-account contract’s add_policy method.

    Show on GitHub