Skip to content

Latest commit

 

History

History
259 lines (218 loc) · 8.08 KB

sep-0037.md

File metadata and controls

259 lines (218 loc) · 8.08 KB
Raw

Preamble

SEP: 0037
Title: Address Directory API
Author: OrbitLens <[email protected]>
Track: Informational
Status: Draft
Created: 2020-09-04
Discussion: https://groups.google.com/u/1/g/stellar-dev/c/vScYxlymqm0
Version 1.0.0

Simple Summary

This standard describes an open REST API interface of the service that maintains a list of well-known Stellar account addresses.

Motivation

Stellar address format works flawlessly as a unique account identifier, but from the user's perspective, such long alphanumeric sequences often look indistinguishable from one another. The address itself does not provide any additional info about the person or entity behind it. In practice, it means that users often can't identify the source/destination of a payment operation even in their own transaction history.

SEP-0001 defines a standard way for public entities' self-identification, which partially addresses the situation. However, not all exchanges and other apps follow the standard. Moreover, information for many now-defunct anchors and apps can't be retrieved since their websites don't work anymore (stellar.toml is unavailable). The same goes for obsolete exchange deposit accounts where people may send funds by mistake.

Custodian accounts that rely on transaction memos make another example of entities ignoring ecosystem guidelines. Only a few exchanges adopted quite a straightforward SEP-0029 standard, so the problem of missing memos is still relevant. A systematized list of accounts tagged as "memo-required" proved to be a convenient solution that helps to check memo prerequisites for custodial wallets regardless of their adherence to specifications.

While the latter two examples at least partially can be sorted out using existing approaches given that entities behind those accounts put some efforts into this, there is a category of addresses that will never be mapped that way. The problem of people loosing their money to various frauds is quite crucial – law enforcement agencies often can't help in such cases. Accounts spotted in scam schemes or other illicit activity can be identified and blocked only as a result of joint community effort. If the community and exchanges agree on using Directory API to prevent transfers to/from addresses marked as malicious, it will significantly complicate further transfers of stolen funds while providing crucial information for compliance checks.

StellarExpert Directory aims to address the problems described above by introducing an open REST API interface for the curated list of categorized addresses.

Abstract

The described curated Stellar addresses list provides publicly available information about well-known accounts via a set of open REST API endpoints. Address Directory API is publicly available for everyone, free of charge.

Specification

Each directory entry contains the following set of fields:

  • address - Stellar address of the account
  • name - short display name
  • domain - domain of the public entity operating the account
  • tags - array of account tags (categories)

REST API specification

GET /directory/tags - list all available categories

Example:

curl https://api.stellar.expert/explorer/directory/tags

[
  {
    "name": "exchange",
    "description": "Centralized exchange account"
  },
  {
    "name": "anchor",
    "description": "Operational account of an anchor"
  },
  {
    "name": "issuer",
    "description": "Well known asset issuer account"
  },
  {
    "name": "wallet",
    "description": "Shared account that belongs to a wallet"
  },
  {
    "name": "custodian",
    "description": "Reserved, custodian account, or cold wallet"
  },
  {
    "name": "malicious",
    "description": "Account involved in theft/scam/spam/phishing"
  },
  {
    "name": "unsafe",
    "description": "Obsolete or potentially dangerous account"
  },
  {
    "name": "personal",
    "description": "Personal signing key or account address"
  },
  {
    "name": "sdf",
    "description": "Account under the custody of SDF"
  },
  {
    "name": "memo-required",
    "description": "Destination requires transaction memo"
  },
  {
    "name": "airdrop",
    "description": "Airdrop distribution account"
  },
  {
    "name": "obsolete-inflation-pool",
    "description": "Inflation pool distribution account (obsolete)"
  }
]

GET /directory - list all entries

This API endpoint follows Stellar Horizon API response format convention. A response result contains records and navigation links.

Optional query parameters:

  • address {Array<String>} - filters results by addresses list (up to 50 per request)
  • tag {Array<String>} - applies a filter by tags
  • search {String} - applies a full-test search filter by entry address, name, or domain
  • cursor {String} - address from which to continue search (paging_token value from a results set)
  • order {String} - "asc" or "desc", controls results order
  • limit {Number} - data page size (10 entries per page by default)

Example:

curl https://api.stellar.expert/explorer/directory?limit=2

{
  "_links": {
    "self": {
      "href": "/explorer/directory?sort=address&order=asc&limit=2"
    },
    "prev": {
      "href": "/explorer/directory?sort=address&order=desc&cursor=GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF&limit=2"
    },
    "next": {
      "href": "/explorer/directory?sort=address&order=asc&cursor=GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA&limit=2"
    }
  },
  "_embedded": {
    "records": [
      {
        "address": "GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF",
        "paging_token": "GA272U6UMNKYOBDCLH5CDAPZVDG4WAGJWFY2S2RV2DN6YSSOGYECEVOF",
        "domain": "",
        "name": "SCAM ACCOUNT",
        "tags": [
          "malicious"
        ]
      },
      {
        "address": "GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA",
        "paging_token": "GA2VRL65L3ZFEDDJ357RGI3MAOKPJZ2Z3IJTPSC24I4KDTNFSVEQURRA",
        "domain": "stellar.org",
        "name": "SDF Escrow Jan 1 2023",
        "tags": [
          "sdf",
          "custodian"
        ]
      }
    ]
  }
}

More query examples:

  • Fetch information about multiple accounts in one call: 
    curl -g "https://api.stellar.expert/explorer/directory?address[]=GA6HCMBLTZS5VYYBCATRBRZ3BZJMAFUDKYYF6AH6MVCMGWMRDNSWJPIH&address[]=GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S"
  • Search for Kraken's deposit account: 
    curl "https://api.stellar.expert/explorer/directory?search=kraken"
  • Find accounts tagged as malicious or unsafe: 
    curl -g "https://api.stellar.expert/explorer/directory?tag[]=malicious&tag[]=unsafe"
  • Lookup addresses reported for "staking"-related scams: 
    curl -g "https://api.stellar.expert/explorer/directory?tag[]=malicious&search=stacking"

GET /directory/{address} - lookup specific Stellar account

Parameters:

  • address {String} - the address of the account to check

Example:

curl https://api.stellar.expert/explorer/directory/GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTM

{
  "address": "GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTM",
  "name": "Kraken",
  "domain": "kraken.com",
  "tags": [
    "exchange",
    "memo-required"
  ]
}

CORS, Rate Limiting and Caching Considerations

All described API endpoints have CORS headers enabled, so they can be used directly from any website.

The effective API request rate may be a subject to rate limiting. In such cases the server returns 429 HTTP status code error. To avoid potential problems caused by those limitations it is advised to consider response caching or group queries on the caller side in case of heavy API utilization.

Design Rationale

Ecosystem wallets and anchors have been using this API since 2018 when it was first introduced.

In order to keep the format of returned entries as lightweight and unambiguous as possible, Directory contains only the bare minimum of important information.

Security Concerns

"N/A"