Stellar Asset List SEP draft
Orbit Lens
Tim Baker and I prepared a SEP for Stellar Asset Lists format convention inspired by Ethereum Token List standard to address challenges of discovering legitimate assets on Stellar network and dealing with asset spoofing and scam attempts.
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.
DependenciesMotivationWhile 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.
SpecificationSAL 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 FormatAssets 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.
List PublicationA list providers can advertise the existence of curated asset lists through their SEP-1 stellar.toml file. TOKEN_LISTS section represented as an array, containing URLs of published lists.
"https://provider.domain/tokenlist1.json",
"https://provider.domain/tokenlist2.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 revision
- feedback - URL or Github repository address where users can report bad actors or request addition of new assets
- assets - Contains an array of asset metadata entries
- name - Descriptive asset name
- contract - Asset contract address in StrKey encoding (for Soroban assets)
- code - Asset code (for Classic assets)
- issuer - Asset issuer address (for Classic assets)
- org - Issuer organization/company (max 30 chars)
- domain - FQDN of the site that hosts asset-related stellar.toml format
- icon - Icon URL (only HTTPS protocol is supported) or IPFS hash
- decimals - Number of decimals to display (optional)
- comment - Alerts, messages, or other additional information specified by the provider (max 150 chars)
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 description field and assets.comment field should not result in version changes.
Fields name and provider should be immutable to facilitate the matching logic for consumer applications.
HostingAsset 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:
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 UXUser-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.
ComposabilityWhen 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 RationaleGiven 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 ConcernsAllowing 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.
Marcin Olszowy // Whalestack LLC
Great proposal. In practice, would each participating org publish its own SAL and consumers/apps/wallets choose which org(s)'s curated SALs they want to trust/implement? The org publishes all assets it considers trustworthy, not just its own, right?
Best,
Marcin
--
You received this message because you are subscribed to the Google Groups "Stellar Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to stellar-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/stellar-dev/1cf99f63-e8d9-44da-ad81-9f2632587366n%40googlegroups.com.