Skip to content

sep-0002.md

Latest commit

 

History

History
166 lines (125 loc) · 6.46 KB

sep-0002.md

File metadata and controls

166 lines (125 loc) · 6.46 KB

Preamble

SEP: 0002
Title: Federation protocol
Author: stellar.org
Status: Final
Created: 2017-10-30
Updated: 2019-10-10
Version 1.1.0

Simple Summary

The Stellar federation protocol maps Stellar addresses to more information about a given user. It’s a way for Stellar client software to resolve email-like addresses such as name*yourdomain.com into account IDs like: GCCVPYFOHY7ZB7557JKENAX62LUAPLMGIWNZJAFV2MITK6T32V37KEJU. Stellar addresses provide an easy way for users to share payment details by using a syntax that interoperates across different domains and providers.

Specification

Stellar addresses are divided into two parts separated by *, the username and the domain.

For example: bob*stellar.org:

  • bob is the username,
  • stellar.org is the domain.

Username

The username is limited to printable UTF-8 with whitespace and the following characters excluded: * ,>. Although of course the domain administrator can place additional restrictions on usernames of its domain.

Email Addresses

Email addresses may be used as the username as the @ symbol is allowed in the username. This allows for using email addresses as the username of an address when the users username is their email address.

For example: maria@gmail.com*stellar.org.

Phone Numbers

Phone numbers may be used as the username. When encoding a phone number as the username the ITU-T recommendations E.123 and E.164 should be followed. The phone number should be formatted in international notation with a leading + as demonstrated in E.123 Section 2.5 to ensure phone numbers are consistently encoded and are globally unique. Spaces should be omitted.

Format: +<country code><phone number>

For example: +14155550100*stellar.org.

Domain

The domain can be any valid RFC 1035 domain name.

Federation Request

You can use the federation endpoint to look up an account id if you have a stellar address. You can also do reverse federation and look up a stellar addresses from account ids or transaction ids. This is useful to see who has sent you a payment.

Federation requests are HTTP GET requests with the following form:

?q=<string to look up>&type=<name,id,txid>

Supported types:

  • name: returns the federation record for the given Stellar address. Example request: https://FEDERATION_SERVER/federation?q=bob*stellar.org&type=name
  • forward: Used for forwarding the payment on to a different network or different financial institution. The other parameters of the query will vary depending on what kind of institution is the ultimate destination of the payment and what you as the forwarding anchor supports. Your stellar.toml file should specify what parameters you expect in a forward federation request. If you are unable to forward or the other parameters in the request are incorrect 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
  • id: returns the federation record of the Stellar address associated with the given account ID. In some cases this is ambiguous. For instance if an anchor sends transactions on behalf of its users the account id will be of the anchor and the federation server won’t be able to resolve the particular user that sent the transaction. In cases like that you may need to use txid instead. Example: https://YOUR_FEDERATION_SERVER/federation?q=GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD&type=id
  • txid: returns the federation record of the sender of the transaction if known by the server. Example: https://YOUR_FEDERATION_SERVER/federation?q=c1b368c00e9852351361e07cc58c54277e7a6366580044ab152b8db9cd8ec52a&type=txid

Federation Response

The federation server should respond with an appropriate HTTP status code, headers and a JSON response.

You must enable CORS on the federation server so clients can send requests from other sites. The following HTTP header must be set for all federation server responses.

Access-Control-Allow-Origin: *

When a record has been found the response should return 200 OK HTTP status code and the JSON body with following fields:

  • stellar_address - stellar address
  • account_id - Stellar public key / account ID
  • memo_type - [optional] type of memo to attach to transaction, one of text, id or hash
  • memo - [optional] value of memo to attach to transaction, for hash this should be base64-encoded. This field should always be of type string (even when memo_type is equal id) to support parsing value in languages that don't support big numbers.

Example:

{
  "stellar_address": "bob*stellar.org",
  "account_id": "GCIBUCGPOHWMMMFPFTDWBSVHQRT4DIBJ7AD6BZJYDITBK2LCVBYW7HUQ",
  "memo_type": "id",
  "memo": "123"
}

If a redirect is needed the federation server should return 3xx HTTP status code and immediately redirect the user to the correct URL using the Location header.

When a record has not been found 404 Not Found HTTP status code should be returned.

Every other HTTP status code will be considered an error. The body should contain error details:

{
  "error": "extra details provided by the federation server"
}

Federation responses should not be cached. Some organizations may generate random IDs to protect their users’ privacy. Those IDs may change over time.

Reference implementations

Other implementations