Skip to content

Latest commit

 

History

History
179 lines (137 loc) · 7.48 KB

sep-0032.md

File metadata and controls

179 lines (137 loc) · 7.48 KB
Raw

Preamble

SEP: 0032
Title: Asset Address
Author: Leigh McCulloch (@leighmcculloch)
Status: Draft
Discussion: https://groups.google.com/d/topic/stellar-dev/rWThI_BIs0Y
Created: 2020-10-29
Version 0.1.1

Summary

This proposal defines a format for specifying memorable addresses to reference assets using the assets code and a domain name that together can be used to resolve, with confidence, the assets issuing address.

Motivation

There is no consistent user-friendly approach to referencing or resolving unique assets in products that are built on Stellar.

Products built on Stellar can hardcode specific assets known by that product and display those assets using friendly hardcoded names, or they can retrieve the home domain for the asset's issuer account.

These strategies allow wallets to display user-friendly names for assets but these approaches have limitations.

Wallets that hardcode names are unable to display user-friendly names for assets that they do not have prior knowledge.

Wallets that use the home domain of an issuer addres can display user-friendly names but only if they already know the complete issuer address. Also, the home domain field of an issuer address does not provide confidence that the domain is related to the issuer of the asset because any Stellar account holder can set any domain as their home domain.

Outside of these two approaches users are left referring to assets by their fully qualified names using their code and issuer address in forms such as {asset-code}:{asset-issuer}, e.g. USD:GBAFEDJ6BNM72RXA45CRLFCAQFHRZUKPNK74SNCPFWHI2GMMGA6QAJME.

Abstract

This proposal defines a format for specifying memorable addresses that contains a domain (e.g. example.org) instead of a Stellar address for the issuing account. The domain hosts a stellar.toml containing information about the asset which is already a common practice of asset issuers. A client parses the stellar.toml of the domain in the asset address and retrieves from the file the issuer address for the asset.

Reverse verification of an asset issuer address and domain can be performed by comparing the home domain of the issuer address with the issuer address in the domains stellar.toml file to confirm that the domain and issuer both claim to issue the asset.

Specification

Asset Address Format

This proposal defines a format for memorable addresses that resolve to the asset code and asset issuer and can be used to confidently reference an asset.

The format is based on SEP-11 Txrep's definition for rendering assets as a string with the parts separated by a colon:

{asset-code}:{asset-domain}

Where:

  • {asset-code} is the 1-12 alphanumeric Stellar asset code.
  • {asset-domain} the domain name that is hosting a stellar.toml file that contains a CURRENCIES section for the asset, as defined by SEP-1.

Example:

USD:example.com

Asset Address Resolution

The process of resolving an asset address is the process of finding the asset issuing G... address given an asset-code and asset-domain in the asset address format.

The flow to resolve an asset is as follows:

  • The client is in possession of an address address in the format {asset-code}:{asset-domain}.
  • The client splits the asset address on : into two parts, the asset code and the asset domain.
  • The client retrieves the stellar.toml for the asset domain.
  • The client parses the stellar.toml and finds a CURRENCIES section with code equal to {asset-code}.
  • The client retrieves any currency.toml files as reference by the stellar.toml as required.
  • If none is found, the client finds a CURRENCIES section with code_template that matches {asset-code}.
  • If none is found, the client fails to resolve the asset address.
  • If more than one is found, the client fails to resolve the asset address.
  • If one is found, the client continues to resolve the asset's issuer address.
  • The client reads the issuer field of the found CURRENCIES section and uses it to send payments, create trustlines, etc.
  • The client verifies that the reverse resolution using the issuer resolves to the same domain as was used to resolve to the issuer address. See Reverse Asset Address Resolution. If reverse resolution results in a different domain, resolution fails.
  • If verification succeeds the client can use the asset code and asset issuer.

Reverse Asset Address Resolution

The process of reverse resolving an asset address is the process of finding the asset domain given an asset-code and asset-issuer, and constructing ane asset address.

The flow to reverse resolve an asset is as follows:

  • The client is in possession of an asset code and issuer G... address.
  • The client retrieves the home domain for the issuer address.
  • If the issuer address has no home domain reverse resolution fails.
  • The client constructs the asset address in the asset address format using the asset code and the home domain as the asset domain.
  • The client verifies that the resolution of an asset address once constructed resolves to the same issuer address as was used to perform reverse resolution. See Asset Address Resolution. If resolution results in a different issuer, resolution fails.
  • If verification succeeds the client can use the constructed asset address.

Verification of an Asset Address

The process of verifying an asset address is the process of performing Asset Address Resolution and Reverse Asset Address Resolution to verify that the domain references an issuer address that has its home domain matching the domain in the asset address.

Semantics

Asset Addresses as Aliases

Asset addresses reference an asset but provide no mechanism to ensure they stay pinned to a single asset issuer address. Asset issuers should avoid changing the asset referenced by an asset address to avoid confusion for consumers. Consumer applications should use the address address as an ephemeral identifier and persist the underlying asset details.

Asset Address Collision

An asset domain should avoid issuing assets with the same code to avoid confusion for consumers. Client's implementing the resolution process will fail resolution if multiple assets with the same code are represented in a domain's stellar.toml.

Security Concerns

The security concerns of this proposal are similar to the security concerns of SEP-1 stellar.toml, SEP-2 Federation protocol, and many systems connected to the Internet or any network. This includes but is not limited to:

  • Preventing unauthorized modification of DNS records.
  • Preventing unauthorized modification of stellar.toml and other files defined by SEP-1.

Limitations

This proposal does not provide mechanisms for changing or migrating the asset domain of an asset, although clients should follow HTTP redirects.

Implementations

None at this time, although ideally this proposal if accepted is implemented in Stellar client SDKs.