Skip to content

Latest commit

 

History

History
174 lines (127 loc) · 7.31 KB

sep-0027.md

File metadata and controls

174 lines (127 loc) · 7.31 KB

Preamble

SEP: 0027
Title: Asset Information
Author: Fritz Ekwoge(@efritze), Ernest Mbenkum (@cameroon)
Status: Draft
Created: 2019-11-22
Updated: 2019-11-22
Version: 0.1.0
Discussion: https://github.com/stellar/stellar-protocol/issues/483

Simple Summary

If you are an anchor or issuer, the info_server endpoint is used to provide a common place where the Internet, wallet integrators, and other stellar clients can find out more information about your asset. Asset information obtained via the info_server API endpoint supplements asset information found in stellar.toml, while also providing a more standard way to localize asset information. Anchors are encouraged to provide an info_server endpoint for each of their assets.

Specification

The url for the asset information server will be located inside the field: info_server, which itself will be placed under the relevant [[CURRENCIES]] table in stellar.toml.

[[CURRENCIES]]
code = "BTC"
issuer = "GCKLZLMYTLRBKM6BDZJYAKHDBSNCGBSN7EDF32FMIAYFAITLCB45ZJW4"
is_asset_anchored = true
anchor_asset_type="crypto"
anchor_asset="BTC"
status="live"

info_server="https://acme.inc/api/v1/asset_info/"

You must enable CORS on the info_server endpoint so people can access this api endpoint from other sites. The following HTTP header must be set from an info_server GET response.

Access-Control-Allow-Origin: *

It is also recommended to set an application/json content type so that browsers render the contents, rather than prompting for a download.

content-type: application/json

The response from an info_server GET request can have a maximum file size of 100KB.

All info_server endpoints should be served over a secure channel like https.

Request

GET info_server

Request Parameters:

Name Type Description
asset_code (required) string The code of the asset, e.g. BTC, ETH, USD, INR, etc. This should not be different from the asset code that the anchor issues.
asset_issuer (required) string The issuer of the asset.
lang (optional) string Defaults to en. Language code specified using ISO 639-1. Fields in the response should be in this language.

Example:

GET https://btc.anchor.io/asset_info?asset_code=ETH&asset_issuer=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI&lang=fr

Error Response

Every HTTP status code other than 200 OK will be considered an error. For example:

{
   "error": "This anchor doesn't support the given currency code: ETH"
}

OK Response

The HTTP status code for a succesful response should be 200 OK.

The response should be a JSON object like:

{
    "name": "Bitcoin",
    "description": "ACME Inc promises to purchase each BTC token from any holder for the value of 1 Bitcoin",
    "conditions": "Withdrawal fees apply.",
    "logo": "https://acme.inc/btc_logo.png",
    "redemption_instructions": "Use any Stellar SEP26 compatible wallet.",

    "org": {
        "name": "Acme BTC Inc",
        "dba": "Acme BTC",
        "url": "https://acme.inc/btc/",
        "logo": "https://acme.inc/logo.png",
        "desc": "BTC Stellar anchor service",
        "physical_address": "Cybertron",
        "phone_number": "+123456789",
        "phone_number_attestation": "",
        "keybase": "@acme",
        "twitter": "@acme",
        "email": "hello_btc@acme.inc"
    },

    "transfer_protocols" : {
        "sep24": {
            "...": "..."
        },
        "sep26": {
            "..." : "..."
        }
    }
    
}

Root level response fields.

Values set here override equivalent values defined in stellar.toml.

Field Requirements Description
name string (<= 20 char) A short name for the token
description string Description of token and what it represents
conditions string Conditions on token
logo url URL to a PNG image on a transparent background representing token
redemption_instructions string If anchored token, these are instructions to redeem the underlying asset from tokens.

Organization response fields.

Optional, but anchors are recommended to provide more information regarding the organization anchoring an asset.

Organization information is placed inside the root-level org field.

Field Requirements Description
name string Legal name of your organization
dba string (may not apply) DBA of your organization
url uses https:// Your organization's official URL. Your stellar.toml must be hosted on the same domain.
logo url A PNG image of your organization's logo on a transparent background
description string Short description of your organization
physical_address string Physical address for your organization
physical_address_attestation https:// url URL on the same domain as your url that contains an image or pdf official document attesting to your physical address. It must list your name or dba as the party at the address. Only documents from an official third party are acceptable. E.g. a utility bill, mail from a financial institution, or business license.
phone_number string Your organization's phone number in E.164 format, e.g. +14155552671. See also this guide.
phone_number_attestation https:// url URL on the same domain as your url that contains an image or pdf of a phone bill showing both the phone number and your organization's name.
keybase string A Keybase account name for your organization. Should contain proof of ownership of any public online accounts you list here, including your organization's domain.
twitter string Your organization's Twitter account
github string Your organization's Github account
email string An email where clients can contact your organization. Must be hosted at your url domain.
licensing_authority string Name of the authority or agency that licensed your organization, if applicable
license_type string Type of financial or other license your organization holds, if applicable
license_number string Official license number of your organization, if applicable

Issuers that list verified information including phone/address attestations and Keybase verifications will be prioritized by Stellar clients.

Transfer protocols response fields.

(Optional)

Certain anchors may provide users with the option to deposit or withdraw assets in and out of the Stellar network, directly from their wallets. For such assets, the transaction_protocols field is an object containing all transfer protocols the anchor supports for that asset.

Pure stellar assets that only exist within the Stellar network need not define this field.

Asset-backed tokens on the other hand are encouraged to either implement SEP24 for interactive anchor/wallet asset transfer, or SEP26 for non-interactive anchor/wallet asset transfer.

The "..." placeholders will be replaced with fields defined by each transfer protocol. See SEP24 and SEP26 for more details.