RegulatedAssetsService
in package
Service for interacting with SEP-0008 Regulated Assets approval servers.
This service facilitates the compliance approval workflow for regulated assets by:
- Loading regulated asset definitions from stellar.toml files (SEP-1)
- Checking if assets require authorization flags
- Submitting transactions to approval servers
- Handling action_required workflows with SEP-9 fields
Regulated assets are assets that require issuer approval for each transaction before it can be submitted to the Stellar network, enabling compliance with securities regulations, KYC/AML requirements, velocity limits, and jurisdiction-based restrictions.
Tags
Table of Contents
Properties
- $network : Network
- $regulatedAssets : array<string|int, RegulatedAsset>
- $sdk : StellarSDK
- $tomlData : StellarToml
Methods
- __construct() : mixed
- Constructs a RegulatedAssetsService instance from stellar.toml data.
- authorizationRequired() : bool
- Checks if authorization is required for the given regulated asset.
- fromDomain() : RegulatedAssetsService
- Creates an instance by loading stellar.toml from the given domain.
- postAction() : SEP08PostActionResponse
- Submits action fields to the approval server when action_required response is received.
- postTransaction() : SEP08PostTransactionResponse
- Submits a transaction to the approval server for compliance evaluation and signing.
Properties
$network
public
Network
$network
$regulatedAssets
public
array<string|int, RegulatedAsset>
$regulatedAssets
= array()
$sdk
public
StellarSDK
$sdk
$tomlData
public
StellarToml
$tomlData
Methods
__construct()
Constructs a RegulatedAssetsService instance from stellar.toml data.
public
__construct(StellarToml $tomlData[, string|null $horizonUrl = null ][, Network|null $network = null ][, Client|null $httpClient = null ]) : mixed
The constructor initializes the service by extracting network configuration and regulated assets information from the provided stellar.toml data. It automatically identifies assets that have the 'regulated' flag set to true and have an approval_server URL configured.
Priority order for configuration:
- Parameters provided to constructor take precedence
- Values from stellar.toml data (NETWORK_PASSPHRASE, HORIZON_URL)
- Default Stellar network URLs for known networks (public, testnet, futurenet)
Parameters
- $tomlData : StellarToml
-
Stellar.toml data obtained via SEP-1 containing currency definitions with regulated asset information
- $horizonUrl : string|null = null
-
(optional) Horizon server URL for checking authorization flags. If not provided, extracted from toml HORIZON_URL or derived from network.
- $network : Network|null = null
-
(optional) Stellar network to use. If not provided, extracted from toml NETWORK_PASSPHRASE field.
- $httpClient : Client|null = null
-
(optional) Guzzle HTTP client for approval server requests. If not provided, a new Client instance is created.
Tags
authorizationRequired()
Checks if authorization is required for the given regulated asset.
public
authorizationRequired(RegulatedAsset $asset) : bool
Per SEP-0008 specification, regulated asset issuers MUST have both Authorization Required and Authorization Revocable flags set on their account. This allows the issuer to grant and revoke authorization to transact the asset at will, which is essential for the per-transaction approval workflow.
This method loads the issuer's account data from the Stellar network and verifies both flags are set. Wallets should call this method before attempting to submit transactions to the approval server to ensure the asset is properly configured.
Parameters
- $asset : RegulatedAsset
-
The regulated asset to check
Tags
Return values
bool —True if both AUTH_REQUIRED and AUTH_REVOCABLE flags are set, false otherwise
fromDomain()
Creates an instance by loading stellar.toml from the given domain.
public
static fromDomain(string $domain[, string|null $horizonUrl = null ][, Network|null $network = null ][, Client|null $httpClient = null ]) : RegulatedAssetsService
This factory method is a convenience wrapper that fetches the stellar.toml file from the specified domain using SEP-1 discovery and initializes the service.
Parameters
- $domain : string
-
Domain to load the stellar.toml file from (e.g., "example.com")
- $horizonUrl : string|null = null
-
(optional) Horizon server URL override
- $network : Network|null = null
-
(optional) Network override
- $httpClient : Client|null = null
-
(optional) HTTP client for requests
Tags
Return values
RegulatedAssetsService —The initialized RegulatedAssetsService instance
postAction()
Submits action fields to the approval server when action_required response is received.
public
postAction(string $url, array<string|int, mixed> $actionFields) : SEP08PostActionResponse
This method is used after receiving a SEP08PostTransactionActionRequired response with action_method set to "POST". It allows the wallet to programmatically provide the requested SEP-9 KYC/AML fields without requiring the user to manually enter them in a browser.
The approval server may respond with:
- no_further_action_required: The provided fields are sufficient; resubmit the transaction
- follow_next_url: Additional action needed; open next_url in browser for user completion
Workflow:
- Receive SEP08PostTransactionActionRequired with action_method "POST"
- If wallet has the requested action_fields, call this method
- If response is SEP08PostActionDone, resubmit original transaction
- If response is SEP08PostActionNextUrl, open next_url in browser
Request Details:
- HTTP Method: POST
- Content-Type: application/json
- Request Body: JSON object with SEP-9 field names as keys
Parameters
- $url : string
-
Action URL from SEP08PostTransactionActionRequired::$actionUrl
- $actionFields : array<string|int, mixed>
-
Associative array of SEP-9 field names to values (e.g., ['email_address' => 'user@example.com'])
Tags
Return values
SEP08PostActionResponse —Either SEP08PostActionDone or SEP08PostActionNextUrl
postTransaction()
Submits a transaction to the approval server for compliance evaluation and signing.
public
postTransaction(string $tx, string $approvalServer) : SEP08PostTransactionResponse
This method sends a signed transaction envelope to the approval server specified in the regulated asset's stellar.toml file. The server evaluates the transaction against its compliance criteria and responds with one of five possible statuses.
Request Details:
- HTTP Method: POST
- Content-Type: application/json
- Request Body: {"tx": "base64_xdr_transaction_envelope"}
- The transaction must be signed by the user before submission
Response Handling:
- HTTP 200 with status success/revised/pending/action_required: Returns appropriate response object
- HTTP 400 with status rejected: Returns SEP08PostTransactionRejected
- Invalid response format: Throws SEP08InvalidPostTransactionResponse
The method automatically parses the response and instantiates the appropriate response class based on the status field. Use instanceof checks to handle different response types.
Parameters
- $tx : string
-
Base64-encoded XDR transaction envelope signed by the user
- $approvalServer : string
-
Full URL of the approval server endpoint (from RegulatedAsset::$approvalServer)
Tags
Return values
SEP08PostTransactionResponse —Concrete response object (Success/Revised/Pending/ActionRequired/Rejected)