Stellar PHP SDK API Documentation

ContractChallengeRequestBuilder extends RequestBuilder
in package

Builder for constructing SEP-45 contract challenge request URLs and executing challenge requests.

This builder follows the builder pattern to construct properly formatted GET requests to the SEP-45 authentication endpoint for obtaining contract account authentication challenges. It handles URL parameter encoding and provides a fluent interface for setting request parameters.

Purpose: Simplifies the construction of contract challenge requests by providing type-safe methods for each parameter. Ensures proper URL encoding and parameter validation before making requests to the authentication server.

Usage Pattern:

$builder = new ContractChallengeRequestBuilder($authEndpoint, $httpClient);
$response = $builder
    ->forAccountId("CCXXX...")                  // Required: contract account
    ->forHomeDomain("example.com")              // Required: home domain
    ->forClientDomain("wallet.com")             // Optional: client domain verification
    ->execute();

SEP-45 Parameters:

  • account: The client contract account (C... address) requesting authentication (required)
  • home_domain: The home domain of the service (required)
  • client_domain: Optional domain for client domain verification (non-custodial wallets)

The builder constructs URLs like: https://auth.example.com?account=CCXXX...&home_domain=example.com&client_domain=wallet.com

Account Validation: The account parameter must be a valid contract address (C... prefix). Other address types (G... or M...) are not supported for SEP-45 and should use SEP-10 instead.

Tags
see
https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md

SEP-45 Challenge Request

see
WebAuthForContracts

For the high-level authentication flow

Table of Contents

Constants

HEADERS  = ["X-Client-Name" => "stellar_php_sdk", "X-Client-Version" => \Soneso\StellarSDK\StellarSDK::VERSION_NR]

Properties

$httpClient  : Client
$queryParameters  : array<string|int, mixed>
$segments  : array<string|int, mixed>

Methods

__construct()  : mixed
Creates a new contract challenge request builder.
buildUrl()  : string
Builds the complete URL for the challenge request.
cursor()  : RequestBuilder
Sets <code>cursor</code> parameter on the request.
execute()  : ContractChallengeResponse
Builds and executes the challenge request.
executeRequest()  : Response
Executes an HTTP request to Horizon and returns a parsed response object
forAccountId()  : ContractChallengeRequestBuilder
Sets the contract account ID to authenticate.
forClientDomain()  : ContractChallengeRequestBuilder
Sets the client domain for verification.
forHomeDomain()  : ContractChallengeRequestBuilder
Sets the home domain for the challenge request.
forQueryParameters()  : ContractChallengeRequestBuilder
Sets additional custom query parameters.
getAndStream()  : void
Streams Server-Sent Events from Horizon to a callback function
limit()  : RequestBuilder
Sets <code>limit</code> parameter on the request.
order()  : RequestBuilder
Sets <code>order</code> parameter on the request.
request()  : ContractChallengeResponse
Requests the specified URL and returns the challenge response.
setSegments()  : RequestBuilder
Sets the URL path segments for this request

Constants

HEADERS

public mixed HEADERS = ["X-Client-Name" => "stellar_php_sdk", "X-Client-Version" => \Soneso\StellarSDK\StellarSDK::VERSION_NR]

Properties

$queryParameters

protected array<string|int, mixed> $queryParameters

Methods

__construct()

Creates a new contract challenge request builder.

public __construct(string $authEndpoint, Client $httpClient) : mixed
Parameters
$authEndpoint : string

the WEB_AUTH_FOR_CONTRACTS_ENDPOINT from stellar.toml

$httpClient : Client

the HTTP client to use for requests

buildUrl()

Builds the complete URL for the challenge request.

public buildUrl() : string
Return values
string —

the complete URL with query parameters

cursor()

Sets <code>cursor</code> parameter on the request.

public cursor(string $cursor) : RequestBuilder

A cursor is a value that points to a specific location in a collection of resources. The cursor attribute itself is an opaque value meaning that users should not try to parse it.

Parameters
$cursor : string
Tags
see
https://developers.stellar.org

Stellar developer docs Pagination documentation

Return values
RequestBuilder

executeRequest()

Executes an HTTP request to Horizon and returns a parsed response object

public executeRequest(string $url, string $requestType[, string|null $requestMethod = "GET" ]) : Response

This method sends the HTTP request to the Horizon server, handles errors, and parses the JSON response into the appropriate response type.

Parameters
$url : string

The complete request URL to fetch

$requestType : string

The expected response type for parsing

$requestMethod : string|null = "GET"

The HTTP method to use (default: "GET")

Tags
throws
HorizonRequestException

If the request fails or response cannot be parsed

Return values
Response —

The parsed response object of the specified type

forClientDomain()

Sets the client domain for verification.

public forClientDomain(string $clientDomain) : ContractChallengeRequestBuilder

When provided, the server may include an additional authorization entry for the client domain that must be signed by the client domain's signing key. This proves the client is associated with the specified domain.

Parameters
$clientDomain : string

the client's domain for verification

Return values
ContractChallengeRequestBuilder —

this builder for method chaining

getAndStream()

Streams Server-Sent Events from Horizon to a callback function

public getAndStream(string $relativeUrl, callable $callback[, bool $retryOnServerException = true ]) : void

This method establishes a persistent connection to Horizon's streaming endpoints using Server-Sent Events (SSE). It processes each event and passes the parsed data to the provided callback function. The stream automatically reconnects on server exceptions if retryOnServerException is true.

Horizon streaming uses SSE to push real-time updates. The stream sends:

  • "hello" message on connection
  • "byebye" message on disconnection
  • JSON data objects for actual events
Parameters
$relativeUrl : string

The relative URL to stream from

$callback : callable

Function to receive parsed event data

$retryOnServerException : bool = true

If true, automatically retry on server errors (default: true)

Tags
throws
GuzzleException

If a network error occurs and retryOnServerException is false

Return values
void —

This method runs indefinitely until interrupted

limit()

Sets <code>limit</code> parameter on the request.

public limit(int $number) : RequestBuilder

It defines maximum number of records to return. For range and default values check documentation of the endpoint requested.

Parameters
$number : int

Maximum number of records to return

Return values
RequestBuilder

setSegments()

Sets the URL path segments for this request

protected setSegments(string ...$segments) : RequestBuilder

This method constructs the URL path by combining multiple segments. Can only be called once per request builder instance.

Parameters
$segments : string

Variable number of URL path segments

Tags
throws
RuntimeException

If segments have already been set

Return values
RequestBuilder —

This instance for method chaining


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results