Dynamic Asset Metadata

#Simple Summary

This SEP extends SEP-0001 and adds the support of the dynamic asset metadata resolution. It describes a standard way to query asset metadata, thereby allowing the issuer to deal with an unlimited number of assets without defining each of them in stellar.toml file.

#Motivation

Current SEP-0001 specification works excellent for issuers that manage only a few assets. However, stellar.toml has a size limit of 100 KB, effectively reducing the maximum possible number of assets to ~300 per file. At present time there is no standard way for the anchor to provide metadata for a large number of assets issued by the same anchor. There are plenty of use-cases that require issuing thousands of assets: bonds, securities, futures, non-fungible tokens.

#Specification

To allow dynamic asset properties resolution, the issuer implements the described REST API endpoint and advertises the existence of a Dynamic Asset Metadata Service through the stellar.toml file. Top-level parameter ASSET_METADATA_SERVER should contain a fully-qualified URL of a metadata resolution service.

Example of stellar.toml:

ASSET_METADATA_SERVER="https://anchor.com/assets"
...

#Asset Metadata Resolution Flow

• The client discovers the home_domain for the asset issuing account and downloads stellar.toml.
• Once the file is downloaded and parsed, the client searches for the asset by its code in [[CURRENCIES]] section.
• If the metadata for the asset was not found in [[CURRENCIES]] section, the client checks for the top-level ASSET_METADATA_SERVER parameter.
• If present, the client pulls a metadata from the remote server using the URL defined in ASSET_METADATA_SERVER parameter.

#API Endpoints

Dynamic Asset Metadata Service exposes a single REST API endpoint.

GET <ASSET_METADATA_SERVER>

This API endpoint returns the metadata for all assets issued by the anchor. It follows Horizon REST API format convention.

Request

Request query parameters:

• code - Filters assets by the asset code.
• issuer - Filters assets by the issuer account.
• cursor - Asset code from which to continue the search (referred also as paging_token in a result set).
• order - Results ordering - "asc"(default) or "desc".
• limit - Data page size. Default 10, maximum 200.

Example:

curl https://example.com/?issuer=GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U&order=asc&limit=2

Response

On success, the endpoint should return 200 OK HTTP status code and JSON-encoded object containing the list of the issued assets' metadata. A response result should contain records and navigation links following Horizon response convention.

Example:

{
  "_links": {
    "self": {
      "href": "https://example.com/?order=asc&limit=2"
    },
    "prev": {
      "href": "https://example.com/?cursor=BRL-GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U&order=desc&limit=2"
    },
    "next": {
      "href": "https://example.com/?cursor=BSD-GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U&order=asc&limit=2"
    }
  },
  "_embedded": {
    "records": [
      {
        "code": "BRL",
        "issuer": "GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U"
        "name": "Brazil Real",
        "paging_token": "BRL-GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U"
      },
      {
        "code": "BSD",
        "issuer": "GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U"
        "name": "Bahamas Dollar",
        "paging_token": "BSD-GAOO3LWBC4XF6VWRP5ESJ6IBHAISVJMSBTALHOQM2EZG7Q477UWC6L7U"
      }
    ]
  }
}

#CORS headers

In order to comply with browser cross-origin access policies, the service should provide wildcard CORS response HTTP header. The following HTTP header must be set for both API endpoints:

Access-Control-Allow-Origin: *

#Design Rationale

Such minimalistic design provides simple and convenient interface for exchanges, wallets, infrastructure apps, and external services.

#Security Concerns

N/A

#Implementation

Reference implementation of the Dynamic Asset Metadata Service for NodeJS can be found here.