Auth

object Auth

Helper for signing Soroban authorization entries.

Supports legacy ADDRESS credentials (Protocol 20+), ADDRESS_V2 credentials (Protocol 27+), and ADDRESS_WITH_DELEGATES credentials (Protocol 27+) with recursive delegate trees.

Preimage selection

The hash preimage type is determined by the credential arm:

ADDRESS ->ENVELOPE_TYPE_SOROBAN_AUTHORIZATION (legacy; not address-bound)
ADDRESS_V2 and ADDRESS_WITH_DELEGATES ->ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS

For ADDRESS_WITH_DELEGATES, the address in the preimage is always the top-level credential address, never a delegate address. All signers in the tree (top-level and every delegate at any depth) sign the same hash.

Signature write-back

Signing appends a new {public_key, signature} map element to the node's existing signature vector. A void signature becomes a one-element vector. Existing non-void signatures are never overwritten. Append order is call order; callers are responsible for supplying signatures in ascending public-key order where the host requires it (G-address, medium threshold multi-sig). Calling authorizeEntry twice with the same key on the same node appends a duplicate the host will reject.

Protocol gating

Emitting ADDRESS_V2 or ADDRESS_WITH_DELEGATES on a network below Protocol 27 invalidates the transaction. Legacy ADDRESS is the default everywhere; the new arms are opt-in via the authV2 flag on authorizeInvocation or via attachDelegates.

Types

AuthOptions

data class AuthOptions(val forAddress: String? = null)

Options controlling authorizeEntry behavior.

Signature

data class Signature(val publicKey: String, val signature: ByteArray)

A signature: public key and 64-byte Ed25519 signature bytes.

Signer

fun interface Signer

Signs a HashIDPreimageXdr and returns the resulting Signature.

Functions

attachDelegates

fun attachDelegates(entry: SorobanAuthorizationEntryXdr, validUntilLedgerSeq: Long, delegates: List<DelegateDescriptor>): SorobanAuthorizationEntryXdr

Constructs a WITH_DELEGATES authorization entry from an ADDRESS or ADDRESS_V2 entry, attaching a sorted, validated delegate tree.

authorizeEntry

suspend fun authorizeEntry(entry: SorobanAuthorizationEntryXdr, signer: Auth.Signer, validUntilLedgerSeq: Long, network: Network, options: Auth.AuthOptions = AuthOptions()): SorobanAuthorizationEntryXdr

Authorizes an existing authorization entry using a custom Signer.

suspend fun authorizeEntry(entry: SorobanAuthorizationEntryXdr, signer: KeyPair, validUntilLedgerSeq: Long, network: Network, options: Auth.AuthOptions = AuthOptions()): SorobanAuthorizationEntryXdr

Authorizes an existing authorization entry using a KeyPair.

suspend fun authorizeEntry(entry: String, signer: Auth.Signer, validUntilLedgerSeq: Long, network: Network, options: Auth.AuthOptions = AuthOptions()): SorobanAuthorizationEntryXdr

Authorizes an existing authorization entry (base64) using a custom Signer.

suspend fun authorizeEntry(entry: String, signer: KeyPair, validUntilLedgerSeq: Long, network: Network, options: Auth.AuthOptions = AuthOptions()): SorobanAuthorizationEntryXdr

Authorizes an existing authorization entry (base64) using a KeyPair.

authorizeInvocation

suspend fun authorizeInvocation(signer: KeyPair, validUntilLedgerSeq: Long, invocation: SorobanAuthorizedInvocationXdr, network: Network, authV2: Boolean = false): SorobanAuthorizationEntryXdr

Builds and signs a new authorization entry from scratch using a KeyPair.

suspend fun authorizeInvocation(signer: Auth.Signer, publicKey: String, validUntilLedgerSeq: Long, invocation: SorobanAuthorizedInvocationXdr, network: Network, authV2: Boolean = false): SorobanAuthorizationEntryXdr

Builds and signs a new authorization entry from scratch using a custom Signer.