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 that signers must commit to. The helpers cover:

  • Computing the auth digest that binds context rule IDs to a signature payload.
  • 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:

let payloadHash = try await OZSmartAccountAuth.buildAuthPayloadHash(
    entry: unsignedEntry,
    expirationLedger: currentLedger + 100,
    networkPassphrase: Network.testnet.passphrase
)
// ... compute the signature over `payloadHash` externally ...
let signedEntry = try await OZSmartAccountAuth.signAuthEntry(
    entry: unsignedEntry,
    signer: webAuthnSigner,
    signature: webAuthnSignature,
    expirationLedger: currentLedger + 100
)
Show on GitHub

  • Computes the auth digest that binds context rule IDs to the signature payload.

    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.

    Throws

    SmartAccountTransactionException.SigningFailed when XDR encoding fails.

    Declaration

    Swift

    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.

    Show on GitHub

  • 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. The entry must have address credentials.

    The preimage is constructed as HashIDPreimage::SorobanAuthorization { networkId, nonce, signatureExpirationLedger, invocation } and the returned value is SHA-256(XDR_encode(preimage)).

    Throws

    SmartAccountTransactionException.SigningFailed when credentials are not address type 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.
    expirationLedger

    Ledger number at which the signature expires.
    networkPassphrase

    Network passphrase.

    Return Value

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

    Show on GitHub

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

    Used when converting source-account credentials to address credentials, typically for relayer fee sponsoring. The preimage is constructed identically to buildAuthPayloadHash but uses the supplied nonce and expirationLedger instead of reading them from existing credentials.

    Throws

    SmartAccountTransactionException.SigningFailed when XDR encoding fails.

    Declaration

    Swift

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

    Parameters

    entry

    Authorisation entry whose root invocation is bound into the preimage.
    nonce

    Nonce to use for the new address credentials.
    expirationLedger

    Ledger number at which the signature expires.
    networkPassphrase

    Network passphrase.

    Return Value

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

    Show on GitHub

  • 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 hash returned by buildAuthPayloadHash using the same expirationLedger. 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 payload hash).
    contextRuleIds

    Optional override for the bound context rule IDs.

    Return Value

    A new authorisation entry with the signature attached.

    Show on GitHub

  • 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.

    Show on GitHub