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
OZAuthDigestSchemeof the code the smart account runs:SHA-256(signaturePayload || contextRuleIds.toXDR())for stellar-accounts 0.7 andSHA-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]
)
-
buildAuthDigest(signaturePayload:AsynchronouscontextRuleIds: ) Computes the stellar-accounts 0.7 auth digest,
legacyConcatonly.The digest is
SHA-256(signaturePayload || contextRuleIds.toXDR())wherecontextRuleIds.toXDR()is the XDR encoding ofScVal::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 thepreimageV1digest instead, which this function cannot produce.Throws
SmartAccountTransactionException.SigningFailedwhen 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 -> DataParameters
signaturePayload32-byte signature payload hash from
buildAuthPayloadHash.contextRuleIdsContext rule IDs to bind into the digest.
Return Value
32-byte SHA-256 auth digest.
-
computeEntryAuthDigest(entry:AsynchronousexpirationLedger: networkPassphrase: contextRuleIds: scheme: ) Computes the signature payload, the auth digest and the delegated
__check_autharguments of a smart account auth entry forscheme.The signature payload is
buildAuthPayloadHash(entry:expirationLedger:networkPassphrase:)of the entry. WithlegacyConcatthe digest isSHA-256(signature_payload || XDR(ScVal::Vec([ScVal::U32(id), ...])))and Delegated signers authorizeBytes(auth_digest). WithpreimageV1the digest isSHA-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_authchecks. 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.SigningFailedwhen 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 -> OZEntryAuthDigestParameters
entryThe smart account authorization entry. Must carry address credentials (
ADDRESS,ADDRESS_V2orADDRESS_WITH_DELEGATES).expirationLedgerLedger number at which the signatures expire.
networkPassphraseNetwork passphrase.
contextRuleIdsContext rule IDs the signatures satisfy, one per auth context.
schemeDigest scheme of the code the smart account runs.
Return Value
The signature payload, the auth digest and the delegated
__check_autharguments. -
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 viaSorobanAuthorizationEntryXDR.buildPreimage(network:), which selectsENVELOPE_TYPE_SOROBAN_AUTHORIZATIONfor the legacyADDRESSarm andENVELOPE_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.SigningFailedwhen 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 -> DataParameters
entryAuthorisation entry to build the payload hash for. Must have address credentials.
expirationLedgerLedger number at which the signature expires; stamped into a temporary copy of the credentials before the preimage is built.
networkPassphraseNetwork passphrase.
Return Value
32-byte SHA-256 hash of the authorisation payload.
-
buildSourceAccountAuthPayloadHash(entry:Asynchronousaddress: nonce: expirationLedger: networkPassphrase: useUpgradedAuth: ) 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.useUpgradedAuthselects the credential arm of the replacement credentials, and with it the preimage:true(the default) hashes the address-boundENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESSpreimage built fromaddress,nonceandexpirationLedgercombined with the entry’s root invocation;falsehashes the legacyENVELOPE_TYPE_SOROBAN_AUTHORIZATIONpreimage, which carries no address.The host reconstructs the preimage from the submitted credentials, so
addressmust be the address carried by the credentials the resulting signature is attached to, anduseUpgradedAuthmust match their arm.Throws
SmartAccountTransactionException.SigningFailedwhenaddressis 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 -> DataParameters
entryAuthorisation entry whose root invocation is bound into the preimage.
addressAddress carried by the new address credentials.
nonceNonce to use for the new address credentials.
expirationLedgerLedger number at which the signature expires.
networkPassphraseNetwork passphrase.
useUpgradedAuthtrue(the default) forADDRESS_V2replacement credentials,falsefor the legacyADDRESSarm.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
authDigestthatcomputeEntryAuthDigest(entry:expirationLedger:networkPassphrase:contextRuleIds:scheme:)returns for the sameexpirationLedgerandcontextRuleIds. WhencontextRuleIdsis non-empty it overrides any existing context-rule IDs in the payload; otherwise the existing value is preserved.Throws
SmartAccountTransactionException.SigningFailedwhen 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 -> SorobanAuthorizationEntryXDRParameters
entryAuthorisation entry to attach the signature to.
signerSmart-account signer (delegated or external).
signaturePre-computed signature object (WebAuthn, Ed25519, or Policy).
expirationLedgerLedger number at which the signature expires (must match the value used when computing the auth digest).
contextRuleIdsOptional 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
signatureValueis anSCValXDR.bytesvalue 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.SigningFailedwhen 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 -> SorobanAuthorizationEntryXDRParameters
entryAuthorisation entry to modify.
signerKeySigner-key ScVal (map key).
signatureValueRaw ScVal value to attach.
contextRuleIdsOptional override for the bound context rule IDs.
Return Value
A new authorisation entry with the map entry added.
View on GitHub
Install in Dash