Permalink
Branch: master
Find file Copy path
292 lines (231 sloc) 16.8 KB

Preamble

SEP: 0001
Title: stellar.toml
Author: stellar.org
Status: Approved
Created: 2017-10-30
Updated: 2018-09-11
Version: 1.4.0

Simple Summary

The stellar.toml file is used to provide a common place where the Internet can find information about your domain’s Stellar integration. Any website can publish Stellar network information. You can announce your validation key, your federation server, peers you are running, your quorum set, if you are an anchor, etc.

If you are an anchor or issuer, the stellar.toml file serves a very important purpose. It allows you to publish information about your organization and token(s) that help to legitimize your offerings. Clients and exchanges can use this information to decide whether a token should be listed. Fully and truthfully disclosing contact and business information is an essential step in responsible token issuance.

Specification

Given the domain DOMAIN, the stellar.toml will be searched for at the following location:

https://DOMAIN/.well-known/stellar.toml

You must enable CORS on the stellar.toml so people can access this file from other sites. The following HTTP header must be set for a HTTP response for /.well-known/stellar.toml file request.

Access-Control-Allow-Origin: *

stellar.toml is in TOML file format. The stellar.toml fields and sections are described below. You should complete as much of this as you can. Many Stellar apps, including important wallets and exchanges, make decisions on which tokens to support based on the completeness of their Account Information and Documentation sections.

Account Information

These are global fields in the stellar.toml file.

Field Requirements Description
FEDERATION_SERVER uses https:// The endpoint for clients to resolve stellar addresses for users on your domain via SEP-2 federation protocol
AUTH_SERVER uses https:// The endpoint used for SEP-3 Compliance Protocol
TRANSFER_SERVER uses https:// The server used for SEP-6 Anchor/Client interoperability
KYC_SERVER uses https:// The server used for SEP-12 Anchor/Client customer info transfer
WEB_AUTH_ENDPOINT uses https:// The endpoint used for SEP-10 Web Authentication
SIGNING_KEY Stellar public key The signing key is used for the compliance protocol
NODE_NAMES list of "G... name" strings convenience mapping of common names to node IDs. You can use these common names in sections below instead of the less friendly nodeID. This is provided mainly to be compatible with the stellar-core.cfg
ACCOUNTS list of G... strings A list of Stellar accounts that are controlled by this domain. Names defined in NODE_NAMES can be used as well, prefixed with $.
OUR_VALIDATORS list of G... strings A list of validator public keys that are declared to be used by this domain for validating ledgers. They are authorized signers for the domain. Names defined in NODE_NAMES can be used as well, prefixed with $.
ASSET_VALIDATOR G... string The validator through which the issuer pledges to honor redemption transactions, and which therefore maintains the authoritative ownership records for assets issued by this organization. Specified as a public key G... or NODE_NAME prefixed with $. This field may also contain a list of validators. In this case, transactions must be processed by all listed validators. In the event that this field specifies multiple validators and they do not all agree, then the authoritative ownership records will be the last ledger number on which all validators agree.
DESIRED_BASE_FEE int Your preference for the Stellar network base fee, expressed in stroops
DESIRED_MAX_TX_PER_LEDGER int Your preference for max number of transactions per ledger close
KNOWN_PEERS list of strings List of known Stellar core servers, listed from most to least trusted if known. Can be IP:port, IPv6:port, or domain:port with the :port optional.
HISTORY list of URL strings List of history archives maintained by this domain

Issuer Documentation

These fields go in the stellar.toml [DOCUMENTATION] table.

Field Requirements Description
ORG_NAME string Legal name of your organization
ORG_DBA string (may not apply) DBA of your organization
ORG_URL uses https:// Your organization's official URL. Your stellar.toml must be hosted on the same domain.
ORG_LOGO url Your organization's logo
ORG_DESCRIPTION string Short description of your organization
ORG_PHYSICAL_ADDRESS string Physical address for your organization
ORG_PHYSICAL_ADDRESS_ATTESTATION https:// url URL on the same domain as your ORG_URL that contains an image or pdf official document attesting to your physical address. It must list your ORG_NAME or ORG_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.
ORG_PHONE_NUMBER string Your organization's phone number
ORG_PHONE_NUMBER_ATTESTATION https:// url URL on the same domain as your ORG_URL that contains an image or pdf of a phone bill showing both the phone number and your organization's name.
ORG_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.
ORG_TWITTER string Your organization's Twitter account
ORG_GITHUB string Your organization's Github account
ORG_OFFICIAL_EMAIL string An email where clients can contact your organization. Must be hosted at your ORG_URL domain.
ORG_LICENSING_AUTHORITY string Name of the authority or agency that licensed your organization, if applicable
ORG_LICENSE_TYPE string Type of financial or other license your organization holds, if applicable
ORG_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.

Point of Contact Documentation

These fields go in the stellar.toml [[PRINCIPALS]] list. It contains identifying information for the primary point of contact or principal(s) of the organization.

Field Requirements Description
name string Full legal name
email string Business email address for the principal
keybase string Personal Keybase account. Should include proof of ownership for other online accounts, as well as the organization's domain.
telegram string Personal Telegram account
twitter string Personal Twitter account
github string Personal Github account
id_photo_hash string SHA-256 hash of a photo of the principal's government-issued photo ID
verification_photo_hash string SHA-256 hash of a verification photo of principal. Should be well-lit and contain: principal holding ID card and signed, dated, hand-written message stating I, $NAME, am a principal of $ORG_NAME, a Stellar token issuer with address $ISSUER_ADDRESS.

$NAME is the principal's full legal name, $ORG_NAME is the name of the organization and must match the value in the stellar.toml file, and $ISSUER_ADDRESS is the Stellar address of the organization/issuer.

The photo hashes allow principals to provide proof of identity to businesses and important clients. The photos can be sent privately, and the recipient can verify that the hashes match. Wallets and Stellar exchanges may request this information from an issuer and add an "ID verified" badge to the issuer's tokens in their interface.

The public key in the verification photo should be the issuing public key for the issuer's assets. If there are multiple, please include the multiple keys in the statement.

Currency Documentation

These fields go in the stellar.toml [[CURRENCIES]] list, one set of fields for each currency issued. Complete all applicable fields, and exclude any that don't apply.

Field Requirements Description
code string (<= 12 char) Token code
code_template string (<= 12 char) A pattern with ? as a single character wildcard. Allows a [[CURRENCIES]] entry to apply to multiple assets that share the same info. An example is futures, where the only difference between issues is the date of the contract. E.g. CORN???????? to match codes such as CORN20180604.
issuer G... string Token issuer Stellar public key
status string Status of token. One of live, dead, test, or private. Allows issuer to mark whether token is dead/for testing/for private use or is live and should be listed in live exchanges.
display_decimals int (0 to 7) Preference for number of decimals to show when a client displays currency balance
name string (<= 20 char) A short name for the token
desc string Description of token and what it represents
conditions string Conditions on token
image url URL to image representing token
fixed_number int Fixed number of tokens, if the number of tokens issued will never change
max_number int Max number of tokens, if there will never be more than max_number tokens
is_unlimited bool The number of tokens is dilutable at the issuer's discretion
is_asset_anchored string true if token can be redeemed for underlying asset, otherwise false
anchor_asset_type string Type of asset anchored. Can be fiat, crypto, stock, bond, commodity, realestate, or other.
anchor_asset string If anchored token, asset that token is anchored to. E.g. USD, BTC, SBUX, Address of real-estate investment property.
redemption_instructions string If anchored token, these are instructions to redeem the underlying asset from tokens.
collateral_addresses list of crypto address strings If this is an anchored crypto token, list of one or more public addresses that hold the assets for which you are issuing tokens.
collateral_address_messages list of message strings Messages stating that funds in the collateral_addresses list are reserved to back the issued asset. See below for details.
collateral_address_signatures list of signature strings These prove you control the collateral_addresses. For each address you list, sign the entry in collateral_address_messages with the address's private key and add the resulting string to this list as a base64-encoded raw signature.
regulated boolean indicates whether or not this is a sep0008 regulated asset. If missing, false is assumed.
approval_server url url of a sep0008 compliant approval service that signs validated transactions.
approval_criteria string a human readable string that explains the issuer's requirements for approving transactions.

Message to put in collateral_address_messages for each entry in collateral_addresses:

The assets in the account $PUBLIC_KEY are reserved to back $CODE issued by $ISSUER_ADDRESS on Stellar. Valid from $START to $END.

Replace $PUBLIC_KEY with the account's public key, $CODE with your asset code, $ISSUER_ADDRESS with the issuing Stellar address and $START, $END with the date range in ISO 8601 for which the reserve is valid. $END cannot be more than a year in the future to ensure yearly renewals of the commitment. collateral_addresses can be used to externally validate that you hold a reserve for the crypto funds you are issuing on Stellar. Issuers that hold a provable 100% reserve are prioritized by wallets and clients. Issuers not meeting this standard may not be listed.

Note: fixed_number, max_number, and is_unlimited are mutually exclusive issuance policies. Include exactly one of those fields.

Alternately, stellar.toml can link out to a separate TOML file for each currency by specifying toml="https://DOMAIN/.well-known/CURRENCY.toml" as the currency's only field.

Validator Information

These fields go in the stellar.toml [QUORUM_SET] table.

Field Requirements Description
VALIDATORS list of G... strings List of authoritative validators for organization. This can potentially be a quorum set. Names defined in NODE_NAMES can be used as well, prefixed with $.

Testing

  1. Run a curl command in your terminal similar to the following (replace stellar.org with the hosting location of your stellar.toml file):
curl --head https://stellar.org/.well-known/stellar.toml
  1. Verify the Access-Control-Allow-Origin header is present as shown below.
curl --head https://stellar.org/.well-known/stellar.toml
HTTP/1.1 200 OK
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Content-length: 482
...
  1. Also run the command on a page that should not have it and verify the Access-Control-Allow-Origin header is missing.

Example

# Sample stellar.toml

FEDERATION_SERVER="https://api.domain.com/federation"
AUTH_SERVER="https://api.domain.com/auth"
DEPOSIT_SERVER="https://api.domain.com"
SIGNING_KEY="GBBHQ7H4V6RRORKYLHTCAWP6MOHNORRFJSDPXDFYDGJB2LPZUFPXUEW3"


NODE_NAMES=[
"GD5DJQDDBKGAYNEAXU562HYGOOSYAEOO6AS53PZXBOZGCP5M2OPGMZV3  lab1",
"GB6REF5GOGGSEHZ3L2YK6K4T4KX3YDMWHDCPMV7MZJDLHBDNZXEPRBGM  donovan",
"GBGR22MRCIVW2UZHFXMY5UIBJGPYABPQXQ5GGMNCSUM2KHE3N6CNH6G5  nelisky1",
"GDXWQCSKVYAJSUGR2HBYVFVR7NA7YWYSYK3XYKKFO553OQGOHAUP2PX2  jianing",
"GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U  anchor"
]

ACCOUNTS=[
"$lab1",
"GAENZLGHJGJRCMX5VCHOLHQXU3EMCU5XWDNU4BGGJFNLI2EL354IVBK7"
]

OUR_VALIDATORS=[
"$nelisky1",
"GCGB2S2KGYARPVIA37HYZXVRM2YZUEXA6S33ZU5BUDC6THSB62LZSTYH"
]

DESIRED_BASE_FEE=100
DESIRED_MAX_TX_PER_LEDGER=400

KNOWN_PEERS=[
"192.168.0.1",
"core-testnet1.stellar.org",
"core-testnet2.stellar.org:11290",
"2001:0db8:0100:f101:0210:a4ff:fee3:9566"
]

HISTORY=[
"http://history.stellar.org/prd/core-live/core_live_001/",
"http://history.stellar.org/prd/core-live/core_live_002/",
"http://history.stellar.org/prd/core-live/core_live_003/"
]

[DOCUMENTATION]
ORG_NAME="Organization Name"
ORG_DBA="Organization DBA"
ORG_URL="https://www.domain.com"
ORG_LOGO="https://www.domain.com/awesomelogo.jpg"
ORG_DESCRIPTION="Description of issuer"
ORG_PHYSICAL_ADDRESS="123 Sesame St., New York, NY, 12345" 
ORG_PHYSICAL_ADDRESS_ATTESTATION="https://www.domain.com/address_attestation.jpg"
ORG_PHONE_NUMBER="1 (123)-456-7890"
ORG_PHONE_NUMBER_ATTESTATION="https://www.domain.com/phone_attestation.jpg"
ORG_KEYBASE="accountname"
ORG_TWITTER="orgtweet"
ORG_GITHUB="orgcode"
ORG_OFFICIAL_EMAIL="support@domain.com"

[[PRINCIPALS]]
name="Jane Jedidiah Johnson"
email="jane@domain.com"
keybase="crypto_jane"
twitter="crypto_jane"
github="crypto_jane"
id_photo_hash="be688838ca8686e5c90689bf2ab585cef1137c999b48c70b92f67a5c34dc15697b5d11c982ed6d71be1e1e7f7b4e0733884aa97c3f7a339a8ed03577cf74be09"
verification_photo_hash="016ba8c4cfde65af99cb5fa8b8a37e2eb73f481b3ae34991666df2e04feb6c038666ebd1ec2b6f623967756033c702dde5f423f7d47ab6ed1827ff53783731f7"

[[CURRENCIES]]
code="USD"
issuer="GCZJM35NKGVK47BB4SPBDV25477PZYIYPVVG453LPYFNXLS3FGHDXOCM"
display_decimals=2

[[CURRENCIES]]
code="BTC"
issuer="GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWA6L7U"
display_decimals=7
anchor_asset_type="crypto"
anchor_asset="BTC"
redemption_instructions="Use SEP6 with our federation server"
collateral_addresses=["2C1mCx3ukix1KfegAY5zgQJV7sanAciZpv"]
collateral_address_signatures=["304502206e21798a42fae0e854281abd38bacd1aeed3ee3738d9e1446618c4571d10"]

# asset with meta info
[[CURRENCIES]]
code="GOAT"
issuer="GD5T6IPRNCKFOHQWT264YPKOZAWUMMZOLZBJ6BNQMUGPWGRLBK3U7ZNP"
display_decimals=2
name="goat share"
desc="1 GOAT token entitles you to a share of revenue from Elkins Goat Farm."
conditions="There will only ever be 10,000 GOAT tokens in existence. We will distribute the revenue share annually on Jan. 15th"
image="https://pbs.twimg.com/profile_images/666921221410439168/iriHah4f.jpg"
fixed_number=10000

#   Potential quorum set of this domain's validators.
[QUORUM_SET]
VALIDATORS=[
"$self", "$lab1", "$nelisky1","$jianing",
"$eno","$donovan"
]

# optional extra information for humans
# Useful place for anchors to detail various policies and required info

###################################
# Required compliance fields:
#      name=<recipient name>
#      addr=<recipient address>
# Federation Format:
#        <phone number>*anchor.com
#        Forwarding supported by sending to: forward*anchor.com
#           forward_type=bank_account
#           swift=<swift code of receiving bank>
#           acct=<recipient account number at receiving bank>
# Minimum Amount Forward: $2 USD
# Maximum Amount Forward: $10000 USD