DEPOSIT_SERVER proposal

#Simple Summary

It will be more convenient, if we have a protocol that standardizes how a wallet communicates with an anchor to fetch the deposit info, guiding the user through the steps in the wallet, instead of opening the anchor's website to find out. In many cases the sender needs to get additional info from the receiver after the payment is sent. To either tell their customer or for their own records.

#Abstract

Proposal for a standard protocol that allows wallets to pull deposit info from anchors. The model is very similar to how the federation server works.

#Specification

#The Anchor would add DEPOSIT_SERVER to stellar.toml file

Add a DEPOSIT_SERVER section to your stellar.toml file that tells the wallet the URL of your deposit server endpoint.

For example: DEPOSIT_SERVER="https://api.yourdomain.com/deposit"

Please note that your deposit server must use https protocol.

#Step2: Implement deposit url HTTP endpoint

The deposit URL specified in your stellar.toml file should accept an HTTP GET request and issue responses of the form detailed below.

#Requests

Wallet can use this endpoint to query deposit info when user want to deposit

requests are http GET requests with the following form:

?address=<stellar address>&asset=asset_name

eg. https://api.yourdomain.com/deposit?address=GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD&asset=BTC

#Response

The deposit server should respond with an appropriate HTTP status code, headers and a JSON response.

You must enable CORS on the deposit server so clients can send requests from other sites. The following HTTP header must be set for all deposit server responses.

Access-Control-Allow-Origin: *

When a record has been found the response should return 200 OK http status code and the following JSON body:

{
  "stellar_address": <wallet provided>,
  "asset": <asset_name>
  "deposit_info": <deposit info for this address>,
  "extra_info": <extra info for deposit or notice.> *optional*
}

eg.

{
  "stellar_address": "GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD",
  "asset": "BTC",
  "deposit_info": "1NMaF4xm4pTHQJbU85PNCGqRVhz8Yp8ibE",
  "extra_info": "3 confirmations needed. This is a long term available address."
}

{
  "stellar_address": "GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD",
  "asset": "CNY",
  "deposit_info": "go to https://ripplefox.taobao.com and buy any items you like and leave your address in "leave message to seller' textarea',
  "extra_info": ""
}

{
  "stellar_address": "GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4ABLAH",
  "asset": "EURT",
  "deposit_info": "PAY OUT TO EUROZONE COUNTRIES FREE via SEPA ACCOUNT, CIS COUNTRIES @1.2%  CASH, FR & DE CASH @1%",
  "extra_info": ""
}

Every other http status code will be considered an error. The body should contain error details:

{
   "message": "extra details provided by the deposit server"
}