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

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

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: when $signatureExpirationLedger is non-null it is applied to the top-level credentials before the preimage is built. When null, the already-set value is used unchanged. Set expiration before signing — the network reconstructs the preimage from the submitted credentials including expiration.

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 M-addresses are rejected as they are not valid Soroban auth addresses.

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 $forAddress matches no node, or is a muxed M-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, or contains duplicate addresses

Return values
SorobanAuthorizationEntry —

the new ADDRESS_WITH_DELEGATES entry

On this page

Search results