OZSmartAccountAuth

public enum OZSmartAccountAuth

Authentication helpers for OpenZeppelin smart-account authorization entries.

Provides functions to attach signatures to authorisation entries and to build the payload hashes and digests that signers must commit to. The helpers cover:

  • Computing the auth digest that binds context rule IDs to a signature payload, in the OZAuthDigestScheme of the code the smart account runs: SHA-256(signaturePayload || contextRuleIds.toXDR()) for stellar-accounts 0.7 and SHA-256(XDR(AuthDigestPreimage)) for stellar-accounts 0.8.0 (computeEntryAuthDigest(entry:expirationLedger:networkPassphrase:contextRuleIds:scheme:)).
  • Building the authorisation payload hash for both address and source-account credentials.
  • Attaching pre-computed signatures to authorisation entries while preserving any existing signatures and ordering map entries deterministically.
  • Adding raw signature map entries (used for delegated-signer placeholders).

Example:

// Compute the digest the wallet's code checks (the WebAuthn challenge).
let digest = try await OZSmartAccountAuth.computeEntryAuthDigest(
    entry: unsignedEntry,
    expirationLedger: currentLedger + 100,
    networkPassphrase: Network.testnet.passphrase,
    contextRuleIds: [0],
    scheme: .preimageV1
)
// ... compute the signature over `digest.authDigest` externally ...
let signedEntry = try await OZSmartAccountAuth.signAuthEntry(
    entry: unsignedEntry,
    signer: webAuthnSigner,
    signature: webAuthnSignature,
    expirationLedger: currentLedger + 100,
    contextRuleIds: [0]
)
  • Computes the stellar-accounts 0.7 auth digest, legacyConcat only.

    The digest is SHA-256(signaturePayload || contextRuleIds.toXDR()) where contextRuleIds.toXDR() is the XDR encoding of ScVal::Vec([ScVal::U32(id), ...]). Binding the rule IDs into the digest prevents replay of a signed payload against a different rule set. A wallet on stellar-accounts 0.8.0 checks the preimageV1 digest instead, which this function cannot produce.

    Throws

    SmartAccountTransactionException.SigningFailed when XDR encoding fails.

    Declaration

    Swift

    @available(*, deprecated, message: "Computes the stellar-accounts 0.7 digest only. Use computeEntryAuthDigest with the OZAuthDigestScheme of the code the wallet runs.")
    public static func buildAuthDigest(
        signaturePayload: Data,
        contextRuleIds: [UInt32]
    ) async throws -> Data

    Parameters

    signaturePayload

    32-byte signature payload hash from buildAuthPayloadHash.

    contextRuleIds

    Context rule IDs to bind into the digest.

    Return Value

    32-byte SHA-256 auth digest.

  • Computes the signature payload, the auth digest and the delegated __check_auth arguments of a smart account auth entry for scheme.

    The signature payload is buildAuthPayloadHash(entry:expirationLedger:networkPassphrase:) of the entry. With legacyConcat the digest is SHA-256(signature_payload || XDR(ScVal::Vec([ScVal::U32(id), ...]))) and Delegated signers authorize Bytes(auth_digest). With preimageV1 the digest is SHA-256(XDR(AuthDigestPreimage)), the preimage binding the entry’s credential address as the smart account, and Delegated signers authorize the preimage itself.

    The scheme must be the one the wallet’s __check_auth checks. A signature over the other digest is rejected by the contract when the transaction is simulated or submitted, after every signer has signed, and nothing executes.

    Example:

    let digest = try await OZSmartAccountAuth.computeEntryAuthDigest(
        entry: authEntry,
        expirationLedger: currentLedger + 100,
        networkPassphrase: Network.testnet.passphrase,
        contextRuleIds: [0],
        scheme: .preimageV1
    )
    // digest.authDigest is the WebAuthn challenge and the message an Ed25519 signer signs.
    

    Throws

    SmartAccountTransactionException.SigningFailed when the credentials are not an address type, when their address is a muxed account (M…) or muxed contract (W…) address, or when XDR encoding fails.

    Declaration

    Swift

    public static func computeEntryAuthDigest(
        entry: SorobanAuthorizationEntryXDR,
        expirationLedger: UInt32,
        networkPassphrase: String,
        contextRuleIds: [UInt32],
        scheme: OZAuthDigestScheme
    ) async throws -> OZEntryAuthDigest

    Parameters

    entry

    The smart account authorization entry. Must carry address credentials (ADDRESS, ADDRESS_V2 or ADDRESS_WITH_DELEGATES).

    expirationLedger

    Ledger number at which the signatures expire.

    networkPassphrase

    Network passphrase.

    contextRuleIds

    Context rule IDs the signatures satisfy, one per auth context.

    scheme

    Digest scheme of the code the smart account runs.

    Return Value

    The signature payload, the auth digest and the delegated __check_auth arguments.

  • Builds the authorisation payload hash for signing.

    Computes the hash that must be signed to authorise a Soroban operation; the hash is used as the WebAuthn challenge when collecting biometric signatures. All three address-credential arms are supported (ADDRESS, ADDRESS_V2, ADDRESS_WITH_DELEGATES). The preimage is built via SorobanAuthorizationEntryXDR.buildPreimage(network:), which selects ENVELOPE_TYPE_SOROBAN_AUTHORIZATION for the legacy ADDRESS arm and ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS (protocol 27) for the V2 and WITH_DELEGATES arms.

    The returned value is SHA-256(XDR_encode(preimage)).

    Throws

    SmartAccountTransactionException.SigningFailed when credentials are not an address type, when their address is a muxed account (M…) or muxed contract (W…) address, or when XDR encoding fails.

    Declaration

    Swift

    public static func buildAuthPayloadHash(
        entry: SorobanAuthorizationEntryXDR,
        expirationLedger: UInt32,
        networkPassphrase: String
    ) async throws -> Data

    Parameters

    entry

    Authorisation entry to build the payload hash for. Must have address credentials.

    expirationLedger

    Ledger number at which the signature expires; stamped into a temporary copy of the credentials before the preimage is built.

    networkPassphrase

    Network passphrase.

    Return Value

    32-byte SHA-256 hash of the authorisation payload.

  • Builds the authorisation payload hash for source-account credentials.

    Used when converting source-account (Void) credentials to fresh address credentials, typically for relayer fee sponsoring.

    useUpgradedAuth selects the credential arm of the replacement credentials, and with it the preimage: true (the default) hashes the address-bound ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage built from address, nonce and expirationLedger combined with the entry’s root invocation; false hashes the legacy ENVELOPE_TYPE_SOROBAN_AUTHORIZATION preimage, which carries no address.

    The host reconstructs the preimage from the submitted credentials, so address must be the address carried by the credentials the resulting signature is attached to, and useUpgradedAuth must match their arm.

    Throws

    SmartAccountTransactionException.SigningFailed when address is a muxed account (M…) or muxed contract (W…) address or when XDR encoding fails.

    Declaration

    Swift

    public static func buildSourceAccountAuthPayloadHash(
        entry: SorobanAuthorizationEntryXDR,
        address: SCAddressXDR,
        nonce: Int64,
        expirationLedger: UInt32,
        networkPassphrase: String,
        useUpgradedAuth: Bool = true
    ) async throws -> Data

    Parameters

    entry

    Authorisation entry whose root invocation is bound into the preimage.

    address

    Address carried by the new address credentials.

    nonce

    Nonce to use for the new address credentials.

    expirationLedger

    Ledger number at which the signature expires.

    networkPassphrase

    Network passphrase.

    useUpgradedAuth

    true (the default) for ADDRESS_V2 replacement credentials, false for the legacy ADDRESS arm.

    Return Value

    32-byte SHA-256 hash of the authorisation payload.

  • Attaches a pre-computed signature to an authorisation entry without mutating the input.

    Does not perform cryptographic signing; the caller must compute the signature over the authDigest that computeEntryAuthDigest(entry:expirationLedger:networkPassphrase:contextRuleIds:scheme:) returns for the same expirationLedger and contextRuleIds. When contextRuleIds is non-empty it overrides any existing context-rule IDs in the payload; otherwise the existing value is preserved.

    Throws

    SmartAccountTransactionException.SigningFailed when credentials are not address type, when the XDR clone fails, or when encoding the signer or signature fails.

    Declaration

    Swift

    public static func signAuthEntry(
        entry: SorobanAuthorizationEntryXDR,
        signer: any OZSmartAccountSigner,
        signature: any OZSmartAccountSignature,
        expirationLedger: UInt32,
        contextRuleIds: [UInt32] = []
    ) async throws -> SorobanAuthorizationEntryXDR

    Parameters

    entry

    Authorisation entry to attach the signature to.

    signer

    Smart-account signer (delegated or external).

    signature

    Pre-computed signature object (WebAuthn, Ed25519, or Policy).

    expirationLedger

    Ledger number at which the signature expires (must match the value used when computing the auth digest).

    contextRuleIds

    Optional override for the bound context rule IDs.

    Return Value

    A new authorisation entry with the signature attached.

  • Adds a raw key/value entry to the auth entry’s signature map.

    Used for delegated-signer placeholders where the value is Bytes (often empty). Uses the AuthPayload format accepted by the OpenZeppelin Smart Account contract.

    When signatureValue is an SCValXDR.bytes value its raw bytes are stored directly; otherwise the value is XDR-encoded and the resulting bytes are stored. The input entry is never mutated; a new entry with the updated payload is returned.

    Throws

    SmartAccountTransactionException.SigningFailed when credentials are not address type or when XDR encoding of the signature value fails.

    Declaration

    Swift

    public static func addRawSignatureMapEntry(
        entry: SorobanAuthorizationEntryXDR,
        signerKey: SCValXDR,
        signatureValue: SCValXDR,
        contextRuleIds: [UInt32] = []
    ) throws -> SorobanAuthorizationEntryXDR

    Parameters

    entry

    Authorisation entry to modify.

    signerKey

    Signer-key ScVal (map key).

    signatureValue

    Raw ScVal value to attach.

    contextRuleIds

    Optional override for the bound context rule IDs.

    Return Value

    A new authorisation entry with the map entry added.