INTRODUCTION
SEPs stand for the Stellar Ecosystem Protocol. They help to provide some standards to stick to for the ecosystem built on top of the stellar network.
SEP2 deals with the federation protocol in the stellar network. This protocol maps the stellar public address of a user to his details. It provides an easy way for users to share their details across domains and providers using a standard syntax.
ARCHITECTURE
When sending a payment, we first need to check with the federation server to see which address to pay. Stellar provides us with an inbuilt federation server we can use. But we can also specify and create our stellar federation server.
Overall the architecture of the Stellar application looks something like this:-
We can also create our federation server but the request and response should follow the standard. The implementation of the functionality is up to you.
SYNTAX
Stellar public addresses can be mapped using a user’s name and domain using the following syntax. An address like
GCCVPYFOHY7ZB7557JKENAX62LUAPLMGIWNZJAFV2MITK6T32V37KEJU can be mapped to a user called John using the following syntax.
john*stellar.org
This syntax has two parts,
(i) John is the username
(ii) stellar.org is the domain name
USERNAME
The chosen username should follow some standards which are as follows:-
(i) Username:- The username should be printable UTF-8 with no whitespace and should also not include *,>.
(ii) Email addresses:- Email addresses are allowed to be used as usernames.
(iii) Phone Numbers:- PhoneNumbers may be used for usernames but it should then follow ITU-T recommendations E.123 and E.164.It should be formatted in international notation with a leading + as demonstrated in E.123 Section 2.5 to ensure phone numbers are unique and consistently encoded. Spaces should not be used.
In short, it should follow the following format
Format: +<country code><phone number>
example:+14361550100*stellar.org
(iv) Domains:- The domain could be any valid RFC 1035 domain name.
STANDARD
The federation server functionality can be implemented in any language or platform but to encourage interoperability with client apps all over the world. The request and response from federation servers should follow a specific standard which is mentioned below.
Federation Standard Request
We can use the federation endpoint to check for a user’s details using its stellar address. We can also do a reverse federation request and lookup for a user’s stellar address using its details like account ids or transaction ids.
The Stellar federation server is designed to connect to any SQL database you might have. The server supports PostgreSQL and SQLite3 too.
The stellar federation standard request should be HTTP GET requests and follow the given format
?q=<string to look up>&type=<name,id,txid>
REQUEST PARAMETERS
(i) name:- Using this parameter returns the federation record of given user.Example request: https://FEDERATION_SERVER/federation?q=john*stellar.org&type=name.
(ii) id:- Using this parameter returns the stellar address for the given accountId. In some cases, the response may be ambiguous, for example, if the anchor sends transactions on behalf of its users, then the id will belong to the anchor and the federation server won’t be able to resolve that user who sent the transaction. In that case, we have to use the txid instead of id.
(iii)txid:- Using this parameter returns the federation record of the user that sent this transaction if the user is known by the server. For example, https://YOUR_FEDERATION_SERVER/federation?q=c1b368c00e9852351361e07cc58c54277e7a6366580044ab152b8db9cd8ec52a&type=txid
(iv) forward:- This parameter is used for forwarding the payment to a different network. Your stellar.toml file should specify the parameters required to forward the request to a different network.
If you are unable to do a forward request, then you should return an error to this effect. Example requests:
- https://FEDERATION_SERVER/federation?type=forward&forward_type=bank_account&swift=BOPBPHMM&acct=2382376
- https://FEDERATION_SERVER/federation?type=forward&forward_type=remittance_center&first_name=Jhun&last_name=Matahari&address=17A%20Sales&city=Angeles&postal_code=12121&country=PH&mobile=0911111112 if more information needs to be sent through
Federation Standard Response
The federation server standard response should have an HTTP status code, headers, and JSON response.
You must enable CORS on the federation server so users can send requests from any site.
To do so, you have to set the following header on the federation server.
.
Access-Control-Allow-Origin: *
SUCCESS RESPONSE
A successful response should return status code 200 with the given JSON response.
- stellar_address - stellar address
- account_id - Stellar public key/account ID
- memo_type - a [optional] type of memo to attach to transaction, one of text, id or hash
- memo - [optional] value of memo to attach to the transaction, this should be base64-encoded. It should have a type string (even when memo_type is equal id).
For example, a successful response may look like the following
{
"stellar_address": "john*stellar.org",
"account_id": "GCIBUCGPOHWMMMFPFTDWBSVHQRT4DIBJ7AD6BZJYDITBK2LCVBYW7HUQ",
"memo_type": "id",
"memo": "12345"
}
ERROR RESPONSE
If the requisite record was not found, then the error response should have status code 404 Not Found.
Every other status code would be counted as an error message and should return a status code and an error message like this.
{
"error": "extra details provided by the federation server"
}
Federation responses should not be cached. This is because some institutions may generate random IDs to protect their users’ privacy. Those IDs may change over time and may cause issues if cache memory is used.
Conclusion:-
In this blog, we learned about SEP 2 and its architecture. We also learned about the standard request and response that the federation server should have as per SEP 2.
Reference:-
You can check out the official documentation for SEP 2 HERE.
You can check the documentation for the javascript federation clients HERE.
You can check to go federation HERE.
December 3, 2024 at 05:46 pm
Your comment is awaiting moderation.