An Introduction to SEP 6 on Stellar Blockchain

Posted By : Abhishek

May 27, 2020

SEP 6 

 

INTRODUCTION

 

SEP 6 provides a standard way for anchors and wallets to interact on behalf of its users. For non-interactive components, SEP 6 provides a way for users to interact with anchors programmatically. The interactive components of SEP 6 are deprecated in favor of SEP 24. 

 

SEP 6 provides a standard protocol for the following

 

(i) Deposit external assets to anchor.

 

(ii) Withdraw assets from an anchor

(iii)Display deposit & withdrawal fee structure for an anchor to the user

(iv)Handle anchor KYC needs, including transmitting KYC information about the user to the anchor via SEP-12

(v)Check the status of current deposits or withdrawals.

(vi)Show a history of deposits and withdrawals.

 

Prerequisites

 

(i) An anchor must define the location of their TRANSFER_SERVER in their stellar.toml. This helps a wallet find the anchor's server.

(ii) Anchors and clients may support SEP-10 web authentication to enable authenticated withdrawals and deposits.

 

API ENDPOINTS

To support this protocol an anchor acts as a server and implements some  API endpoints, while a wallet acts as a client that consumes these API endpoints. The following are the endpoints that should be implemented by an anchor for SEP 6.

 

(i) GET /deposit :- REQUIRED

(ii) GET /withdraw :- REQUIRED

(iii) GET /info :- REQUIRED

(iv) GET /fee :- OPTIONAL (only needed for complex fee structures)

(v) GET /transactions :- REQUIRED

(vi) GET /transaction :- REQUIRED

 

AUTHENTICATION

An anchor may support SEP 10 for authentication so that users can be verified while depositing or withdrawing assets and even for checking transaction history.

 

For implementing authentication, the anchor should

(i) set the authentication_required field at their info endpoint.

(ii) Provide JWT obtained from SEP 10 to all endpoints.

 

Interactive authentication

For interactive flow, authentication can be achieved by including JWT obtained from SEP 10 as a header like this

Authorization: Bearer <JWT>

 

Non-interactive authentication

For non-interactive authentication, JWT should be passed as a query parameter like this 

?jwt=<token>

 

CORS Permissions

To allow clients from any site to access the endpoint, we have to enable CORS by enabling the following header in the server.

 

Access-Control-Allow-Origin: *

 

HTTPS only

Since this protocol involves deposit and withdrawal of assets that have value, hence https is required for all the endpoints.

 

ENDPOINTS DESCRIPTION

 

(i) DEPOSIT

 

The deposit endpoint helps the user initiate the deposit process to an anchor. The user deposits some currency be it fiat or crypto and the anchor provides the equivalent stellar assets to the user. This endpoint provides all the info that a user may need regarding the deposit.

 

Deposit Request

GET TRANSFER_SERVER/deposit

Request parameters

The request parameters contain a lot of fields that you can check out HERE.

Deposit Response

For the JSON response, you can check out the official documentation HERE.


 

SPECIAL CASES

There are some special cases that anchors must handle for the deposit endpoint. 

(i) The stellar account does not exist:- If the stellar accountId provided by the user does not exist, then anchor may create the account on the user's behalf with enough balance to issue trustline for deposit asset. If the anchor doesn't support this create new account operation, then the response should be 404 BAD REQUEST error.

 

(ii)The stellar account doesn't trust the asset:- Since the secret for stellar address remains with the user, an anchor cannot issue trustline on behalf of the user. That's why anchor should do the following 

When the anchor gets the deposit request, it starts listening to check if the user address has enough balance to issue a trustline for the deposited asset. If not, then anchor listens for the account to get a minimum balance to issue a trustline for the deposit address. 

Once the user gets enough balance, then the anchor listens to keep checking if the user has issued a trustline for the given asset. If yes, then anchor sends the asset to the user, otherwise, the anchor keeps listening for users to issue trust lines.

 

(ii) WITHDRAW

Withdraw operation allows to user to send the asset it holds back to the anchor to redeem the asset it originally deposited.

 

The withdraw endpoint gives the user all the info it needs to perform the withdrawal operation.

 

REQUEST

GET TRANSFER_SERVER/to withdraw

REQUEST PARAMETERS

There is a whole list of request parameters to get info about withdrawing assets from an anchor. You can check out the whole list of request parameters in the official docs HERE.

WITHDRAW RESPONSE

You can check out the whole list of parameters that the anchor returns in the official docs HERE.

HANDLING SPECIAL CASES FOR DEPOSIT AND WITHDRAW

There are some scenarios shared by deposit and withdraw endpoints which must be handled by the anchor to implement SEP 6.

            (a) Customer Information needed (Non-interactive flow) 

     If the anchor needs more info about the user and that can info can be received non-interactively via SEP-12. Then the response code should be 403 Forbidden.

               The response should contain  the following fields

          

NAME

TYPE

DESCRIPTION

type

string

Always set to non_interactive_customer_info_needed.

fields

list of strings

List of field names that should be deposited to anchor via SEP12 before proceeding with deposit or withdrawal.

 

         The field names specified in fields must be drawn from the list defined in SEP-9.

   Sample response in this scenario may look like this 

{

  "type": "non_interactive_customer_info_needed",

  "fields" : ["family_name", "given_name", "address", "tax_id"]

}

The user can retry deposit or withdrawal transactions once the given info is given to the anchor.

(b) CUSTOMER INFORMATION STATUS

 In this scenario, the customer has given the requisite information to the anchor but the request is still being processed or may be rejected due to some reason. In this case, if the user tries to do a deposit or withdraw, then they should get response code 403 Forbidden.

The JSON response object, in this case, would contain the following fields

 

Name

Type

Description

type

string

Always set to customer_info_status.

status

string

Status of customer info being processed. It can either be pending or denied.

more_info_url

string

(OPTIONAL) A URL to show users more info about why their request failed

eta

int

(OPTIONAL) Time (in seconds), in which the customer info will be updated.

 

Sample response in this scenario would look something like this.

{

  "type": "customer_info_status",

  "status": "denied",

  "more_info_url": "https://api.example.com/kycstatus?account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI"

}

 

(c)  Authentication Required

If the endpoint is accessed without any authentication i.e a jwt, then the status code to be returned is 403 Forbidden.

{

  "type": "authentication_required"

}

 

(d) Error

In any other scenario, the response would be deemed as an error, the returned JSON response should contain the reason for the error in a human-readable format.

{

   "error": "This anchor doesn't support the given currency: BTC"

}

 

 

(iii) INFO

This endpoint allows an anchor to convey info about the TRANSFER_SERVER to wallets and clients.

 

REQUEST PARAMETERS

This endpoint takes a single parameter called "lang" which tells the anchor which language the response data should be in. It is optional and defaults to en (English).

 

RESPONSE

The response for info endpoint looks like THIS.

 

The response for info endpoint contains two objects, deposit and withdraw. Both these objects contain a list of assets that anchor supports and their deposit and withdraw details respectively.

 

Each asset in deposit object contains the following details

  1. enabled:- This is set to true if anchor supports deposit for this asset.
  2. authentication_required:-  This is set to true if the client needs authentication to access the endpoints. False if not specified.
  3. min_amount:-(OPTIONAL) min amount of asset to be deposit/withdraw. No limit if not specified.
  4. max_amount:-(OPTIONAL) max amount of asset to be deposited/withdrawn. No limit if not specified.
  5. fee_fixed:-  (OPTIONAL) fixed fee that would be deduced while deposit/withdraws in terms of the deposited/withdrawn asset.
  6. fee_percent:- (OPTIONAL) fee as a percentage of deposited/withdrawn amount that would be deducted from the amount deposited/withdrawn.
  7. fields:-  It's a JSON object that contains the following fields.
  • description:- A description of field to show to user.
  • optional:-  true if a field is optional. Defaults to false.
  • choices:- a list of possible values for the field.


 

The response for the info endpoint should also contain if they support other endpoints like fees, transactions and transactions. For each of these endpoints, the response should specify the following.

  1. enabled:- true if the endpoint is available on the anchor.
  2. authentication_required:-  true if the client must be authenticated before accessing the endpoint.

 



 

(iv) FEE

This endpoint allows an anchor to show the details about the fee that would be deducted during the deposit and withdrawal. The fee may be fixed in terms of the deposited or withdrawn asset or the fee may be a percentage fee which is directly proportional to the amount of asset deposited or withdrawn asset.

NOTE:- If the details for this endpoint can be shown in the info endpoint, then anchor should not implement this endpoint at all.

 

REQUEST

GET TRANSFER_SERVER/fee

 

REQUEST PARAMETERS

The request parameters that this endpoint takes can be found HERE.

RESPONSE 

 The response for this endpoint looks like HERE.

 

(v) TRANSACTION HISTORY

This endpoint shows a history of transactions that the user has performed with the anchor in the past. These transactions are either deposit or withdrawal.

 

REQUEST

GET TRANSFER_SERVER/transactions

 

REQUEST PARAMETERS

The parameter list for this endpoint can be found HERE.

 

RESPONSE

The JSON response to this endpoint looks something like THIS.

 

(vi) SINGLE TRANSACTION

This endpoint gives the user details about a specific transaction.

 

REQUEST 

GET TRANSFER_SERVER/transaction

REQUEST PARAMETERS

The parameters list for this endpoint can be found HERE.

 

RESPONSE

The JSON response for this endpoint looks something like THIS.


 

CONCLUSION

In this blog, we learned about SEP 6, the endpoint it supports, the standard request and response for these endpoints.

REFERENCE

The official documentation for SEP 6 can be found HERE.

For implementing authentication, you can refer to SEP 10 documentation HERE.






 

 

 

           

Leave a

Comment

Name is required

Invalid Name

Comment is required

Recaptcha is required.

blog-detail

March 7, 2024 at 09:30 pm

Your comment is awaiting moderation.

By using this site, you allow our use of cookies. For more information on the cookies we use and how to delete or block them, please read our cookie notice.

Chat with Us
Contact Us

Oodles | Blockchain Development Company

Name is required

Please enter a valid Name

Please enter a valid Phone Number

Please remove URL from text