Stellar PHP SDK API Documentation

SorobanAuthorizationEntry
in package

Soroban authorization entry for smart contract invocations.

Each entry grants permission to execute a specific contract invocation tree. Credentials select which signing scheme applies; the rootInvocation tree identifies the authorized calls.

Three credential arms support active signing:

  • ADDRESS (legacy): preimage is ENVELOPE_TYPE_SOROBAN_AUTHORIZATION (not address-bound).
  • ADDRESS_V2 (Protocol 27, CAP-71): preimage is ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS (address-bound). Invalid on networks below Protocol 27.
  • ADDRESS_WITH_DELEGATES (Protocol 27, CAP-71): ADDRESS_V2 with a recursive delegate tree. All nodes (top-level and every delegate at any depth) sign the same payload hash. Invalid on networks below Protocol 27.

Signature write-back: sign() appends to the existing signature vector; a void signature becomes a one-element vec. Calling sign() twice on the same node with the same key appends a duplicate that the host will reject. Callers are responsible for call order; the SDK does not sort signatures.

For G-address verification the host requires signatures to be in ascending public-key order. The SDK appends in call order; callers must sign in ascending key order for multi-sig nodes.

Tags
see
SorobanCredentials
SorobanAuthorizedInvocation

Table of Contents

Properties

$credentials  : SorobanCredentials
$rootInvocation  : SorobanAuthorizedInvocation

Methods

__construct()  : mixed
Creates a new Soroban authorization entry.
buildPreimage()  : XdrHashIDPreimage
Builds the XdrHashIDPreimage for this entry based on its credential arm.
carriesSignature()  : bool
Reports whether a credential node's signature value carries a signature.
fromBase64Xdr()  : SorobanAuthorizationEntry
Creates SorobanAuthorizationEntry from base64-encoded XDR.
fromXdr()  : SorobanAuthorizationEntry
Creates SorobanAuthorizationEntry from its XDR representation.
getCredentials()  : SorobanCredentials
Returns the credentials for this authorization entry.
getRootInvocation()  : SorobanAuthorizedInvocation
Returns the root authorized invocation.
resolveSignatureExpirationLedger()  : int|null
Resolves expiration while preserving every existing signature on the entry.
setCredentials()  : void
Sets the credentials for this authorization entry.
setRootInvocation()  : void
Sets the root authorized invocation.
sign()  : void
Signs the authorization entry with the given keypair.
toBase64Xdr()  : string
Encodes this authorization entry as base64 XDR.
toXdr()  : XdrSorobanAuthorizationEntry
Converts this object to its XDR representation.
withDelegates()  : SorobanAuthorizationEntry
Constructs an ADDRESS_WITH_DELEGATES entry from an existing ADDRESS or ADDRESS_V2 entry.

Properties

Methods

buildPreimage()

Builds the XdrHashIDPreimage for this entry based on its credential arm.

public buildPreimage(Network $network) : XdrHashIDPreimage

Preimage selection:

  • ADDRESS arm: ENVELOPE_TYPE_SOROBAN_AUTHORIZATION (not address-bound, legacy preimage).
  • ADDRESS_V2 and ADDRESS_WITH_DELEGATES arms: ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS (address-bound preimage; the address is always the top-level credential address, never a delegate address).

signatureExpirationLedger must be set on the credentials before calling this method; the network reconstructs the same preimage from the submitted credentials.

Parameters
$network : Network

the network whose passphrase is included in the preimage

Tags
throws
RuntimeException

if the credentials are source-account or have no address credentials

Return values
XdrHashIDPreimage —

the preimage ready for SHA-256 hashing

carriesSignature()

Reports whether a credential node's signature value carries a signature.

public static carriesSignature(XdrSCVal $signature) : bool

A void value and a vector that is empty or absent are unsigned placeholders; every other value is a signature payload. js-stellar-sdk 17.2.1 writes an empty vector with expiration ledger 0 into the unsigned entries it builds (src/base/auth.ts, lines 482 to 487) and treats a void value and an empty vector alike as unsigned (signaturePresent, lines 1108 to 1122), so entries from either SDK are classified the same way.

The check classifies placeholders and does not judge whether a payload authorizes the address. A custom account contract whose policy needs no signer can accept an empty vector as a valid payload; such a node is reported as unsigned.

Parameters
$signature : XdrSCVal

the signature value of a top-level or delegate credential node

Tags
see
https://github.com/stellar/js-stellar-sdk/blob/v17.2.1/src/base/auth.ts
Return values
bool —

true when the value is neither void nor an empty or absent vector

fromBase64Xdr()

Creates SorobanAuthorizationEntry from base64-encoded XDR.

public static fromBase64Xdr(string $base64Xdr) : SorobanAuthorizationEntry
Parameters
$base64Xdr : string

the base64-encoded XDR string

Tags
throws
InvalidArgumentException

if base64 or XDR decoding fails, or the depth guard trips

Return values
SorobanAuthorizationEntry —

the decoded authorization entry

resolveSignatureExpirationLedger()

Resolves expiration while preserving every existing signature on the entry.

public resolveSignatureExpirationLedger(int|null $expirationLedger) : int|null

Every node that carries a signature (see carriesSignature()) commits to the shared expiration, including nodes receiving an additional signature.

Parameters
$expirationLedger : int|null

the requested expiration, or null to reuse a committed value

Tags
throws
InvalidArgumentException

if the requested and committed expirations differ

Return values
int|null —

the resolved expiration, or null when a default is needed

sign()

Signs the authorization entry with the given keypair.

public sign(KeyPair $signer, Network $network[, int|null $signatureExpirationLedger = null ][, string|null $forAddress = null ]) : void

Applies to all three address arms (ADDRESS, ADDRESS_V2, ADDRESS_WITH_DELEGATES). Source-account credentials throw RuntimeException.

Expiration is shared by all credential nodes. A non-null expiration must match the stored value when any node carries a signature (see carriesSignature()). Null keeps the stored value.

Routing: when $forAddress is null, the signature is written to the top-level credentials. When non-null (strkey, G- or C-prefixed), the signature is written to EVERY node (top-level and delegate, depth-first) whose address matches. If no node matches, InvalidArgumentException is thrown. Muxed account (M...) and muxed contract (W...) addresses are not valid Soroban auth addresses: such a $forAddress is rejected, and so is an entry whose credential address is one of them, before any signing work.

Append semantics: the new signature element is appended to the existing signature vector. A void top-level signature is valid and is not rejected. Calling sign() twice with the same key appends a duplicate; the SDK does not deduplicate or sort.

Parameters
$signer : KeyPair

the keypair to sign with

$network : Network

the network this authorization is for

$signatureExpirationLedger : int|null = null

when non-null, sets expiration before hashing

$forAddress : string|null = null

strkey (G- or C-prefixed) routing to a specific address node; null signs the top-level credentials

Tags
throws
RuntimeException

if no address credentials are found or the credential arm is unsupported

InvalidArgumentException

if expiration conflicts, $forAddress matches no node, or $forAddress or the credential address is a muxed account or muxed contract address

toBase64Xdr()

Encodes this authorization entry as base64 XDR.

public toBase64Xdr() : string
Return values
string —

the base64-encoded XDR representation

withDelegates()

Constructs an ADDRESS_WITH_DELEGATES entry from an existing ADDRESS or ADDRESS_V2 entry.

public static withDelegates(SorobanAuthorizationEntry $source, int $signatureExpirationLedger[, array<string|int, SorobanDelegateDescriptor> $delegates = [] ]) : SorobanAuthorizationEntry

The input entry must use ADDRESS or ADDRESS_V2 credentials. A WITH_DELEGATES input throws. The resulting entry:

  • Copies the top-level address and nonce from the source entry.
  • Sets signatureExpirationLedger to $signatureExpirationLedger.
  • Defaults the top-level signature to void.
  • Attaches the provided delegate descriptors, sorted by their XDR-encoded address bytes.
  • Preserves the rootInvocation from the source entry.

Delegate sorting: each array (top-level delegates and every nestedDelegates) is sorted ascending by the complete XDR-encoded bytes of XdrSCAddress. This is not strkey order; accounts (XdrSCAddressType 0) sort before contracts (XdrSCAddressType 1) in XDR encoding.

Duplicate rejection: no two delegates in the same array may share an address. The same address at different nesting levels is allowed.

Parameters
$source : SorobanAuthorizationEntry

the ADDRESS or ADDRESS_V2 entry to wrap

$signatureExpirationLedger : int

the expiration ledger for the resulting entry

$delegates : array<string|int, SorobanDelegateDescriptor> = []

delegate descriptors for top-level delegates

Tags
throws
InvalidArgumentException

if source is already WITH_DELEGATES, contains duplicate addresses, or the source credential address or a delegate address is a muxed account (M...) or muxed contract (W...) address

Return values
SorobanAuthorizationEntry —

the new ADDRESS_WITH_DELEGATES entry

On this page

Search results