Skip to content

Latest commit

 

History

History
176 lines (121 loc) · 6.43 KB

sep-0024.md

File metadata and controls

176 lines (121 loc) · 6.43 KB
Raw

SEP-0024 - TransferServerSEP24Service

Helps clients to interact with anchors in a standard way defined by SEP-0024: Hosted Deposit and Withdrawal.

Create a TransferServerSEP24Service instance

By providing the domain hosting the stellar.toml file

final transferService = await TransferServerSEP24Service.fromDomain("place.domain.com");

This will automatically load and parse the stellar.toml file. It will then create the TransferServerSEP24Service instance by using the transfer server url provided in the stellar.toml file.

Or by providing the service url

Alternatively one can create a TransferServerSEP24Service instance by providing the transfer server url directly via the constructor:

final transferService = TransferServerSEP24Service("http://api.stellar-anchor.org/transfer");

Get Anchor Information

First, let's get the information about the anchor's support for SEP-24. This request doesn't require authentication, and will return generic info, such as supported currencies, and features supported by the anchor. You can get a full list of returned fields in the SEP-24 specification.

SEP24InfoResponse infoResponse = await transferService.info();

Fee

If there is a fee and the fee schedule is not complex, the info response already contains the fee data for a given asset.

double? feeFixed = infoResponse.depositAssets?["USDC"]?.feeFixed;
double? feePercent = infoResponse.depositAssets?["USDC"]?.feePercent;
double? feeMinimum = infoResponse.depositAssets?["USDC"]?.feeMinimum;
print("USDC fixed fee for deposit: $feeFixed");
print("USDC percentage fee for deposit: $feePercent");
print("USDC minimum fee for deposit: $feeMinimum");

Otherwise, one can check if the fee endpoint of the anchor is enabled and if so, request the fee from there.

bool feeEndpointEnabled = infoResponse.feeEndpointInfo?.enabled == true;
if (feeEndpointEnabled) {
    SEP24FeeRequest feeRequest = SEP24FeeRequest();
    feeRequest.operation = "deposit";
    feeRequest.type = "SEPA";
    feeRequest.assetCode = "USD";
    feeRequest.amount = 2034.09;
    feeRequest.jwt = jwtToken;
    
    SEP24FeeResponse feeResponse = await transferService.fee(feeRequest);
    double? fee = feeResponse.fee;
    print("fee : $fee");
}

Interactive Flows

Before getting started, make sure you have connected to the anchor and received an authentication token, by using the SDKs WebAuthService. We will use the jwt token in the examples below as the SEP-10 authentication token, obtained earlier.

Deposit

To initiate an operation, we need to know the asset code.

SEP24DepositRequest request = new SEP24DepositRequest();
request.assetCode = "USDC";
request.jwt = jwtToken;

SEP24InteractiveResponse response = await transferService.deposit(request);

As a result, you will get an interactive response from the anchor. Open the received URL in an iframe and deposit the transaction ID for future reference:

String url = response.url;
String id = response.id;

Withdraw

Similarly to the deposit flow, a basic withdrawal flow has the same method signature and response type:

SEP24WithdrawRequest request = new SEP24WithdrawRequest();
request.assetCode = "USDC";
request.type = "bank_account";
request.jwt = jwtToken;

SEP24InteractiveResponse response = await transferService.withdraw(request);

As a result, you will get an interactive response from the anchor. Open the received URL in an iframe and deposit the transaction ID for future reference:

String url = response.url;
String id = response.id;

Providing KYC Info

To improve the user experience, the SEP-24 standard supports passing user KYC to the anchor via SEP-9. In turn, the anchor will pre-fill this information in the interactive popup.

SEP24DepositRequest request = new SEP24DepositRequest();
request.assetCode = "USDC";
request.jwt = jwtToken;

StandardKYCFields kycFields = StandardKYCFields();
kycFields.naturalPersonKYCFields = NaturalPersonKYCFields();
kycFields.naturalPersonKYCFields!.emailAddress = "mail@example.com";
kycFields.naturalPersonKYCFields!.photoIdFront = await Util.readFile(path);

request.kycFields = kycFields;

SEP24InteractiveResponse response = await transferService.deposit(request);

Changing Stellar Transfer Account

By default, the Stellar transfer will be sent to the authenticated account (with a memo) that initiated the deposit.

While in most cases it's acceptable, some wallets may split their accounts. To do so, pass additional account (and optionally a memo):

SEP24DepositRequest request = new SEP24DepositRequest();
request.assetCode = "USDC";
request.account = "G...";
request.memo = "my memo";
request.memoType = "text";
request.jwt = jwtToken;


SEP24InteractiveResponse response = await transferService.deposit(request);

Similarly, for a withdrawal, the origin account of the Stellar transaction could be changed.

Getting Transaction Info

On the typical flow, the wallet would get transaction data to notify users about status updates. This is done via the SEP-24 GET /transaction and GET /transactions endpoint.

SEP24TransactionsRequest request = SEP24TransactionsRequest();
request.assetCode = "ETH";
request.jwt = jwtToken;

SEP24TransactionsResponse response = await transferService.transactions(request);
List<SEP24Transaction> transactions = response.transactions;

Single Transaction:

SEP24TransactionRequest request = SEP24TransactionRequest();
request.stellarTransactionId = "17a670bc424ff5ce3b386dbfaae9990b66a2a37b4fbe51547e8794962a3f9e6a";
request.jwt = jwtToken;

SEP24TransactionResponse response = await transferService.transaction(request);
SEP24Transaction transaction  = response.transaction;

Further readings

For more info, see also the class documentation of TransferServerSEP24Service and the SDK's SEP-24 test cases.