stellar-sdk/com.soneso.stellar.sdk.sep.sep08/Sep08Service

Sep08Service

class Sep08Service(val tomlData: StellarToml, val regulatedAssets: List<RegulatedAsset>, network: Network, horizonServer: HorizonServer, httpClient: HttpClient? = null, httpRequestHeaders: Map<String, String>? = null)

SEP-8 Regulated Assets service client.

Provides support for regulated assets on the Stellar network. Regulated assets are assets that require issuer approval before transactions involving them can be submitted. The issuer publishes an approval server URL in their stellar.toml file, and all transactions involving the regulated asset must be submitted to the approval server for authorization.

This service handles:

Discovering regulated assets and their approval servers from stellar.toml
Checking whether an issuer account has authorization required and revocable flags set
Submitting transactions to approval servers for regulatory approval
Completing action flows when additional user interaction is required (e.g., KYC)

Typical workflow:

Create service instance via fromDomain
Check available regulated assets via regulatedAssets
Build a transaction involving the regulated asset
Submit the transaction to the approval server via postTransaction
Handle the response (approved, revised, pending, action required, or rejected)
If action required, complete the action via postAction and resubmit

Example - Discover regulated assets:

val sep08 = Sep08Service.fromDomain("example.com")

sep08.regulatedAssets.forEach { asset ->
    println("${asset.code}:${asset.issuer}")
    println("Approval server: ${asset.approvalServer}")
    asset.approvalCriteria?.let { println("Criteria: $it") }
}

Example - Submit transaction for approval:

val sep08 = Sep08Service.fromDomain("example.com")
val asset = sep08.regulatedAssets.first()

// Build and sign a payment transaction involving the regulated asset
val tx = TransactionBuilder(sourceAccount, network)
    .addOperation(PaymentOperation.Builder(destination, asset.toAsset(), "100").build())
    .setTimeout(180)
    .setBaseFee(100)
    .build()
tx.sign(senderKeyPair)

// Submit to approval server
val response = sep08.postTransaction(tx.toEnvelopeXdrBase64(), asset.approvalServer)

when (response) {
    is Sep08PostTransactionResponse.Success -> {
        // Submit response.tx to the Stellar network
        horizonServer.submitTransaction(response.tx)
    }
    is Sep08PostTransactionResponse.Revised -> {
        // Review and sign the revised transaction, then submit
        println("Revised: ${response.message}")
    }
    is Sep08PostTransactionResponse.Pending -> {
        // Wait and retry after response.timeout milliseconds
    }
    is Sep08PostTransactionResponse.ActionRequired -> {
        // Direct user to response.actionUrl
    }
    is Sep08PostTransactionResponse.Rejected -> {
        // Transaction rejected: response.error
    }
}

Example - Handle action required flow:

val actionResponse = sep08.postAction(
    url = response.actionUrl,
    actionFields = mapOf("email_address" to "user@example.com")
)

when (actionResponse) {
    is Sep08PostActionResponse.Done -> {
        // Resubmit the original transaction
        val retryResponse = sep08.postTransaction(tx, asset.approvalServer)
    }
    is Sep08PostActionResponse.NextUrl -> {
        // Direct user to actionResponse.nextUrl
    }
}

Constructors

Sep08Service

constructor(tomlData: StellarToml, regulatedAssets: List<RegulatedAsset>, network: Network, horizonServer: HorizonServer, httpClient: HttpClient? = null, httpRequestHeaders: Map<String, String>? = null)