Skip to content

Latest commit

 

History

History
145 lines (112 loc) · 4.53 KB

sep-0014.md

File metadata and controls

145 lines (112 loc) · 4.53 KB
Raw

Preamble

SEP: 0014
Title: Dynamic Asset Metadata
Author: OrbitLens <orbit.lens@gmail.com>, Paul Tiplady <paul@qwil.com>
Track: Standard
Status: Draft
Created: 2018-09-30
Updated: 2019-03-12
Discussion: https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/stellar-dev/-S7FIXJAi2A
Version 0.2.1

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.