#Abstract
This standard aims to enhance user experiences and trust by standardizing a mechanism for defining, validating, and sharing curated lists of Stellar assets, while ensuring ease of integration for wallets and applications across the Stellar network.
#Dependencies
#Motivation
While some Stellar-based platforms offer curated asset lists, there is a need for a universal approach for creating and sharing comprehensive, community-driven asset lists. This proposal presents a methodology to facilitate the creation, endorsement, and consumption of such curated lists, augmenting consumer trust while simplifying asset integrations across ecosystem applications and services. This generalized approach not only increases interface decentralization, eliminating the requirement of vendor-locked asset lists, but also provide means for feedback and collaboration with the entire Stellar community.
#Specification
SAL is a specification for lists of asset metadata that can be used by any Stellar applications and services which rely on externally curated asset catalogs published by trusted providers. Any organization can create, maintain, and publish an asset list following the guidelines outlined in this standard. Inclusion of any particular asset in a list should not be considered as endorsement or recommendation of any kind.
#List Format
Assets metadata is published in a JSON format with the following structure:
{
"name": "Fantasy Token Universe",
"provider": "MagicalFinance",
"description": "Assets traded on the MagicalFinance DEX platform",
"version": "2.3",
"feedback": "https://magical.finance/asset-list/contact",
"assets": [
{
"contract": "CGAMER1Y4U6AZEDPMQNRUT7ZH6UUSK6C3TWVLMJ64M3DIMQGYXF4GYQJO",
"code": "DRGN",
"issuer": "GDRAKET5NDQ4MTZXFA7ATZZA5LQIU7GQNZWKF5TKO5AFJLAAI77XDRGN",
"name": "Dragon Coin",
"org": "DragonKeepers Federation",
"domain": "fantasytokens.com",
"icon": "https://fantasytokens.com/drgn.png",
"decimals": 14
},
{
"code": "EGLD",
"issuer": "GDRAKET5NDQ4MTZXFA7ATZZA5LQIU7GQNZWKF5TKO5AFJLAAI77XDRGN",
"name": "Elven Gold",
"org": "Elven Treasury",
"domain": "fantasytokens.com",
"icon": "bafkreicjdptvjcidbwsnbeddt2uhl3tej4crgmgsvlxarlg3fsc4a2i454",
"decimals": 7,
"comment": "Official currency of Elven lands, endorsed by Elven Treasury."
},
{
"contract": "CORCMINT7R52SZMIQBOVNQZJ5QGN5XC2JFB3MYUBL4LEZ5I5YDQY3ORC",
"name": "Orc Steel",
"org": "Orcish Smith Guild",
"domain": "orcforged.dapp",
"icon": "https://fantasytokens.com/orcst.png",
"decimals": 3
}
]
}
In order to be considered valid, an asset list must validate against this JSON schema.
A list should not contain the native (Stellar XLM) asset to prevent possible
naming conflicts.
#List Publication
A list providers can advertise the existence of curated asset lists through
their
SEP-1
stellar.toml file. ASSET_LISTS section represented as an array, containing
URLs of published lists.
...
ASSET_LISTS = [
"https://provider.domain/assetlist1.json",
"https://provider.domain/assetlist2.json"
]
Here:
name- Short descriptive title of the list (max 30 chars)provider- Organization or entity that put together the list (max 50 chars)description- Text description of the list to display alongside with the name (optional, max 150 chars)version- Current list revisionnetwork- Stellar network identifier ("public" or "testnet")feedback- URL or GitHub repository address where users can report bad actors or request addition of new assetsassets- Contains an array of asset metadata entriesname- Descriptive asset namecontract- Asset contract address in StrKey encodingcode- Asset code (for Classic assets) or value returned bysymbol()function (for Soroban assets)issuer- Asset issuer address (for Classic assets, ignored for pure Soroban tokens)org- Issuer organization/company (max 30 chars)domain- FQDN of the site that hosts asset-relatedstellar.tomlformaticon- Icon URL (only HTTPS protocol is supported) or IPFS hashdecimals- Number of decimals to display (optional)comment- Alerts, messages, or other additional information specified by the provider (max 150 chars)
#Changes and Versioning
The version field should be updated every time the list changes, following a
short semantic versioning format:
- Major version is incremented when assets were added/removed, or if an asset contract address has been changed.
- Minor version is incremented when other asset details were updated.
- Modifications of the top-level
descriptionfield andassets.commentfield should not result inversionchanges.
Fields name and provider should be immutable to facilitate the matching
logic for consumer applications.
#Hosting
Asset lists should be published over HTTPS protocol in JSON format following
the structure described above. In case of HTTPS, the list can be a static file
or a dynamically generated server response with CORS HTTP header, with
application/json content type, and served from the domain (or a subdomain)
which hosts the stellar.toml file itself.
CORS response header example:
Access-Control-Allow-Origin: *
Content-Type: application/json
The size of any individual list should not exceed 200KB. If providers want to advertise more assets, they can maintain several separate asset lists for this purpose.
#Consumer UX
User-focused consumer applications should provide an option of selecting one or
more asset lists in the interface, preferably using checkboxes, multiselect, or
another similar UX controls. To provide relevant context for a user, an
application must display information from at least name and provider fields
in such a checklist, with an option to show more details about selected assets.
#Composability
When several asset lists selected in a consumer application, the interface
should display assets from all of them. Potentially, this may result in
collisions if similar assets are present in different lists (e.g. with the same
name). To resolve possible contradictions, the contract field or the
combination of code+issuer fields should be treated as a unique ID of an
asset. Consumer applications must utilize this approach to avoid displaying
duplicate assets in the assets list. It's up to the developers how to resolve
collision of other properties for assets found in multiple asset lists.
#Design Rationale
Given the extensive nature of asset lists and limitations of TOML format, JSON
was utilized for its capacity and ubiquity, ensuring detailed asset
specifications without breaching size constraints. To decouple list references
from data, asset lists are advertised in the stellar.toml file to facilitate
accessible integration and compatibility with existing Stellar standards. This
decoupling also provides additional flexibility for the provider: asset lists
can be either stored as static JSON files or dynamically generated on the
server.
Due to unique asset structures and the Soroban/Classic duality, the SAL is tailored to Stellar technical aspects, diverging from standards existing for other blockchain, like Ethereum’s TokenLists.
This standard aims to find the balance between providing relevant asset
information and minimizing transferred data size, which is especially important
in case of mobile browsers. The decision to allow publication of more than one
SAL in stellar.toml aims to provide means for lists segmentation by
categories, as well as dealing with size limitations.
Additional asset information can be fetched from the stellar.toml file hosted
on the domain specified in the asset description. The comment field
facilitates the transparent sharing of supplementary information regarding
assets communicated by the list provider, enhancing user awareness and
engagement.
The decision to allow hosting icons on both HTTPS and IPFS protocols contributes to higher hosting versatility and fault tolerance for asset logos.
List versioning allows downstream applications to refresh asset information obtained from the list only when it changes.
Users can submit their feedback, report bad actors or request addition of new
assets by contacting the provider via the communication channel specified in
the feedback field.
General interface recommendations laid out in "Composability" and "Consumer UX" sections intended to at least partially unify user experience of asset lists across ecosystem wallets following best practices gathered from prior experience.
#Security Concerns
Allowing users to unrestrictedly connect arbitrary asset lists in the application interface is potentially dangerous because bad actors can carry on attacks to spoof legitimate assets by mimicking asset name and logo. Therefore, application developer should either depend only on several trustworthy providers or utilize the community-maintained repository of curated asset lists.
Displaying the assets.comment contents in the interface might confuse
end-users and, depending on the context, can be regarded as endorsements. So
it's up to the application developers whether to show these comments to end
users.
#Implementation
- Community-managed GitHub repository for the
Asset Lists Catalog.
It contains references to asset lists created by ecosystem providers. Client applications can use it to discover, fetch available lists, and allow their users to select trusted providers in the interface. Web UI for this catalog is available here. - Basic JS library that simplifies integration of asset lists into web applications.
- Lobstr Curated List by UltraStellar.
- Soroswap List by SoroswapFinance.
- StellarExpert Top50 asset list for Stellar Pubnet.
- StellarExpert Testnet Top50 asset list for Stellar Testnet.