URIScheme
in package
Implements SEP-7 URI Scheme to facilitate delegated signing.
This class provides utility methods for generating, signing, validating, and submitting SEP-7 compliant URI requests for delegated transaction signing. The URIs enable wallets to sign transactions on behalf of applications without exposing secret keys.
Key features:
- Generate URI for transaction signing (tx operation)
- Generate URI for payment requests (pay operation)
- Sign URIs with origin domain verification
- Validate URI signatures against stellar.toml
- Submit signed transactions to network or callback URLs
Tags
Table of Contents
Constants
- amountParameterName : mixed = 'amount'
- Amount parameter name for payment amount
- assetCodeParameterName : mixed = 'asset_code'
- Asset code parameter name
- assetIssuerParameterName : mixed = 'asset_issuer'
- Asset issuer parameter name
- callbackParameterName : mixed = 'callback'
- Callback parameter name for transaction submission URL
- chainParameterName : mixed = 'chain'
- Chain parameter name for nested SEP-7 URI
- destinationParameterName : mixed = 'destination'
- Destination parameter name for payment recipient
- memoParameterName : mixed = 'memo'
- Memo parameter name
- memoTypeParameterName : mixed = 'memo_type'
- Memo type parameter name
- messageParameterName : mixed = 'msg'
- Message parameter name for user-facing message
- networkPassphraseParameterName : mixed = 'network_passphrase'
- Network passphrase parameter name
- originDomainParameterName : mixed = 'origin_domain'
- Origin domain parameter name for request verification
- payOperation : mixed = 'pay?'
- Payment request operation type
- publicKeyParameterName : mixed = 'pubkey'
- Public key parameter name for signing account specification
- replaceParameterName : mixed = 'replace'
- Replace parameter name for field replacement (SEP-11 format)
- signatureParameterName : mixed = 'signature'
- Signature parameter name for URI signing
- signOperation : mixed = 'tx?'
- Transaction signing operation type
- uriSchemeName : mixed = 'web+stellar:'
- SEP-7 URI scheme prefix
- uriSchemePrefix : mixed = 'stellar.sep.7 - URI Scheme'
- SEP-7 signature payload prefix
- xdrParameterName : mixed = 'xdr'
- XDR parameter name for transaction envelope
Methods
- __construct() : mixed
- Creates a new URIScheme instance.
- checkUIRSchemeIsValid() : bool
- Validates a signed SEP-7 URI by verifying signature and origin domain.
- generatePayOperationURI() : string
- Generates a SEP-7 URI for the 'pay' operation to request payment.
- generateSignTransactionURI() : string
- Generates a SEP-7 URI for the 'tx' operation to request transaction signing.
- getParameterValue() : string|null
- Extracts a parameter value from a SEP-7 URI.
- setMockHandlerStack() : mixed
- Sets a mock HTTP handler stack for testing.
- signAndSubmitTransaction() : SubmitUriSchemeTransactionResponse
- Signs a transaction from a SEP-7 URI and submits it to network or callback URL.
- signURI() : string
- Signs a SEP-7 URI with a keypair and appends the signature parameter.
Constants
amountParameterName
Amount parameter name for payment amount
public
mixed
amountParameterName
= 'amount'
assetCodeParameterName
Asset code parameter name
public
mixed
assetCodeParameterName
= 'asset_code'
assetIssuerParameterName
Asset issuer parameter name
public
mixed
assetIssuerParameterName
= 'asset_issuer'
callbackParameterName
Callback parameter name for transaction submission URL
public
mixed
callbackParameterName
= 'callback'
chainParameterName
Chain parameter name for nested SEP-7 URI
public
mixed
chainParameterName
= 'chain'
destinationParameterName
Destination parameter name for payment recipient
public
mixed
destinationParameterName
= 'destination'
memoParameterName
Memo parameter name
public
mixed
memoParameterName
= 'memo'
memoTypeParameterName
Memo type parameter name
public
mixed
memoTypeParameterName
= 'memo_type'
messageParameterName
Message parameter name for user-facing message
public
mixed
messageParameterName
= 'msg'
networkPassphraseParameterName
Network passphrase parameter name
public
mixed
networkPassphraseParameterName
= 'network_passphrase'
originDomainParameterName
Origin domain parameter name for request verification
public
mixed
originDomainParameterName
= 'origin_domain'
payOperation
Payment request operation type
public
mixed
payOperation
= 'pay?'
publicKeyParameterName
Public key parameter name for signing account specification
public
mixed
publicKeyParameterName
= 'pubkey'
replaceParameterName
Replace parameter name for field replacement (SEP-11 format)
public
mixed
replaceParameterName
= 'replace'
signatureParameterName
Signature parameter name for URI signing
public
mixed
signatureParameterName
= 'signature'
signOperation
Transaction signing operation type
public
mixed
signOperation
= 'tx?'
uriSchemeName
SEP-7 URI scheme prefix
public
mixed
uriSchemeName
= 'web+stellar:'
uriSchemePrefix
SEP-7 signature payload prefix
public
mixed
uriSchemePrefix
= 'stellar.sep.7 - URI Scheme'
xdrParameterName
XDR parameter name for transaction envelope
public
mixed
xdrParameterName
= 'xdr'
Methods
__construct()
Creates a new URIScheme instance.
public
__construct([Client|null $httpClient = null ]) : mixed
The HTTP client fetches the stellar.toml of an origin domain and posts signed transactions to callback URLs. An injected Guzzle client sends these requests, so its options apply to them: timeouts, proxies, and handler middleware such as retries or logging. Requests go to absolute URLs, so the client needs no base_uri. Without an injected client, a Guzzle client with default options is built, which sets no request timeout. A transaction without a callback is submitted through the StellarSDK Horizon client, not through this client.
Parameters
- $httpClient : Client|null = null
-
Optional Guzzle client for the stellar.toml and callback requests, for example new Client(['timeout' => 30, 'connect_timeout' => 5])
checkUIRSchemeIsValid()
Validates a signed SEP-7 URI by verifying signature and origin domain.
public
checkUIRSchemeIsValid(string $url) : bool
Performs complete validation workflow per SEP-7 security requirements:
- Verifies origin_domain parameter exists and is valid FQDN
- Verifies signature parameter exists
- Fetches stellar.toml from origin domain
- Extracts URI_REQUEST_SIGNING_KEY from stellar.toml
- Cryptographically verifies signature against signing key
Security Warning: Always validate signed URIs before displaying origin_domain to users or processing transactions. This prevents homograph attacks and unauthorized transaction requests. Consider implementing stellar.toml caching to improve performance and reduce network requests.
Note: Method name contains typo (UIR instead of URI). Maintained for backward compatibility.
Parameters
- $url : string
-
Complete SEP-7 URI with origin_domain and signature parameters
Tags
Return values
bool —Returns true if validation succeeds
generatePayOperationURI()
Generates a SEP-7 URI for the 'pay' operation to request payment.
public
generatePayOperationURI(string $destinationAccountId[, string|null $amount = null ][, string|null $assetCode = null ][, string|null $assetIssuer = null ][, string|null $memo = null ][, string|null $memoType = null ][, string|null $callback = null ][, string|null $message = null ][, string|null $networkPassphrase = null ][, string|null $originDomain = null ][, string|null $signature = null ]) : string
Creates a web+stellar:pay URI requesting payment to a destination account. Unlike the tx operation, pay allows wallets to choose the payment method (direct payment or path payment) and source asset, providing flexibility.
Parameters
- $destinationAccountId : string
-
Stellar account ID or payment address for payment recipient
- $amount : string|null = null
-
Amount to send (omit to let user specify donation amount)
- $assetCode : string|null = null
-
Asset code (XLM if omitted)
- $assetIssuer : string|null = null
-
Asset issuer account ID (XLM if omitted)
- $memo : string|null = null
-
Transaction memo value (base64 encode MEMO_HASH/MEMO_RETURN, URL encode all types)
- $memoType : string|null = null
-
Memo type: MEMO_TEXT, MEMO_ID, MEMO_HASH, or MEMO_RETURN
- $callback : string|null = null
-
URL-encoded callback URL (prefix with "url:") for signed transaction submission
- $message : string|null = null
-
Optional message for wallet user (max 300 characters before encoding)
- $networkPassphrase : string|null = null
-
Network passphrase (omit for public network)
- $originDomain : string|null = null
-
Fully qualified domain name of request originator (requires signature)
- $signature : string|null = null
-
Base64 URL-encoded signature of URI (generated via signURI method)
Tags
Return values
string —Complete SEP-7 URI string (web+stellar:pay?...)
generateSignTransactionURI()
Generates a SEP-7 URI for the 'tx' operation to request transaction signing.
public
generateSignTransactionURI(string $transactionEnvelopeXdrBase64[, string|null $replace = null ][, string|null $callback = null ][, string|null $publicKey = null ][, string|null $chain = null ][, string|null $message = null ][, string|null $networkPassphrase = null ][, string|null $originDomain = null ][, string|null $signature = null ]) : string
Creates a web+stellar:tx URI that requests a wallet to sign a specific transaction. The transaction is encoded as XDR and URL-encoded. Optional parameters enable field replacement, callbacks, signature chaining, and origin verification.
Parameters
- $transactionEnvelopeXdrBase64 : string
-
Base64-encoded XDR TransactionEnvelope to be signed
- $replace : string|null = null
-
URL-encoded Txrep field replacement specification (SEP-11 format)
- $callback : string|null = null
-
URL-encoded callback URL (prefix with "url:") for signed transaction submission
- $publicKey : string|null = null
-
Stellar public key specifying which account should sign
- $chain : string|null = null
-
URL-encoded nested SEP-7 URI for transaction chaining (max 7 levels)
- $message : string|null = null
-
Optional message for wallet user (max 300 characters before encoding)
- $networkPassphrase : string|null = null
-
Network passphrase (omit for public network)
- $originDomain : string|null = null
-
Fully qualified domain name of request originator (requires signature)
- $signature : string|null = null
-
Base64 URL-encoded signature of URI (generated via signURI method)
Tags
Return values
string —Complete SEP-7 URI string (web+stellar:tx?...)
getParameterValue()
Extracts a parameter value from a SEP-7 URI.
public
getParameterValue(string $parameterName, string $url) : string|null
Utility method for parsing query parameters from SEP-7 URIs. Handles standard URL parsing and returns null if parameter not found.
Parameters
- $parameterName : string
-
Name of the query parameter to extract
- $url : string
-
Complete SEP-7 URI containing query parameters
Return values
string|null —Parameter value if found, null otherwise
setMockHandlerStack()
Sets a mock HTTP handler stack for testing.
public
setMockHandlerStack(HandlerStack $handlerStack) : mixed
Replaces the HTTP client with a mock handler for unit testing. Allows testing of stellar.toml fetching and callback URL submissions without making actual HTTP requests.
Parameters
- $handlerStack : HandlerStack
-
Guzzle mock handler stack
signAndSubmitTransaction()
Signs a transaction from a SEP-7 URI and submits it to network or callback URL.
public
signAndSubmitTransaction(string $url, KeyPair $signerKeyPair[, Network|null $network = null ]) : SubmitUriSchemeTransactionResponse
This method extracts the transaction from the URI, signs it with the provided keypair, and submits it either to a callback URL (if specified) or directly to the Stellar network.
Security Warning: This method performs actual transaction signing and submission. Always validate the URI using checkUIRSchemeIsValid() and obtain explicit user consent before calling this method. Never auto-submit transactions without user review.
Parameters
- $url : string
-
Complete SEP-7 URI containing transaction XDR
- $signerKeyPair : KeyPair
-
Keypair used to sign the transaction
- $network : Network|null = null
-
Stellar network (defaults to public network if omitted)
Tags
Return values
SubmitUriSchemeTransactionResponse —Response containing either submitTransactionResponse or callBackResponse
signURI()
Signs a SEP-7 URI with a keypair and appends the signature parameter.
public
signURI(string $url, KeyPair $signerKeyPair) : string
Generates a cryptographic signature of the URI request using the SEP-7 signing algorithm (36-byte prefix with signature of "stellar.sep.7 - URI Scheme" + URL). The signature enables wallets to verify the URI originated from the specified domain.
Security Warning: Only sign URIs that you have generated and validated. Signing untrusted URIs could enable phishing attacks. The signature will be verified against the URI_REQUEST_SIGNING_KEY in your domain's stellar.toml file.
Parameters
- $url : string
-
SEP-7 URI to sign (must include origin_domain parameter)
- $signerKeyPair : KeyPair
-
Keypair for signing (public key must match stellar.toml URI_REQUEST_SIGNING_KEY)
Tags
Return values
string —Signed URI with appended signature parameter