<pre>
  BIP: XXX
  Title: Endpoint Capability Discovering using HTTP Address Service
  Author: Matt David <mgd@mgddev.com>
          Frank Contreras <frank@frankintosh.net>
  Status: Draft
  Type: Standards Track
  Created: 2016-06-10
</pre>

==Abstract==

The proposed TLS-protected HTTP Address Service BIP aims to define a common flow for interacting with a TLS-protected HTTP Address Service such that Address Services can be provided to the client. Address Services may provide any of the following:

# Wallet address
# BitcoinURI
# PaymentRequest
# Store & Forward Services (supporting the Payment Protocol)

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 
"OPTIONAL" in this document are to be interpreted as described in RFC 2119.

==Motivation==

As the use of bitcoin, as well as other blockchain-based currencies, digital assets, and payment networks continues to expand, the issue of address exchange becomes ever more important. With the introduction of safer, more secure, and user friendly address exchange processes such as [[bip-0075.mediawiki|BIP75]], there comes the issue of how to expose addresses. In order to negotiate for the most secure supported method of address exchange, we feel the best way is through a unique endpoint. This will serve HD wallet addresses and [[bip-0070.mediawiki|BIP70]] PaymentRequests as well as accept [[bip-0075.mediawiki|BIP75]] InvoiceRequests through a unique endpoint that can specifically expose supported methods via negotiation between the two parties. This specification proposes a standard HTTP flow for service discovery, wallet address retrieval (plaintext, BitcoinURI and PaymentRequest) as well as [[bip-0075.mediawiki|BIP75]] message passing.

==Use Cases==

===HD Wallet Address Exchange / BIP70 Endpoint===

A bitcoin wallet developer would like to dynamically retrieve a unique address for a remote wallet. The developer would prefer a PaymentRequest, but would accept a BitcoinURI ([[bip-0021.mediawiki|BIP21]]). The Address Service spec allows the developer to discover which address options are available, if any. The developer can then specify which type of data they would prefer (based on availability) and submit a request for that data.

===BIP75 InvoiceRequest Submission Endpoint===

A bitcoin wallet developer would like to use [[bip-0075.mediawiki|BIP75]] to get a fully validated address. The Address Service specification allows the developer to discover if the receiving wallet (via the address endpoint) supports [[bip-0075.mediawiki|BIP75]]. Additionally, the Address Service specification provides the URI where a [[bip-0075.mediawiki|BIP75]] InvoiceRequest may be submitted if supported.

==Details==

===DANE / TLSA===

Address Servers SHOULD be DANE / TLSA ([https://tools.ietf.org/html/rfc7671 RFC 7671]) enabled. 

===Available Services===

This flow will use a HTTP OPTIONS request to the address endpoint URL in order to determine service availability. The response will use the '''Allow''' (existing) and '''Accept''' (existing) HTTP headers to inform the client which services the address endpoint supports.
 
====Allow Header Usage====

The '''Allow''' header is used, as defined in [https://tools.ietf.org/html/rfc2616 RFC 2616] (14.7), to supply the client with supported HTTP methods for use with the address endpoint URL. The '''Allow''' header must return supported HTTP methods for the available return MIME types. See the table below for HTTP methods that relate to supported return MIME types.

====Accept Header Usage====

The '''Accept''' header is defined in [https://tools.ietf.org/html/rfc2616 RFC 2616] (14.1) and is used in the OPTIONS response. This header is generally used in the client request, but this specification uses it in the Address Service OPTIONS response.

The '''Accept''' header MUST contain all acceptable MIME types for the endpoint. The following table defines MIME types for the appropriate return values:

{| class="wikitable"
! MIME Type !! HTTP Method !! HTTP Response Content
|- 
| text/plain                                                || GET  || Raw Wallet Address
|-
| application/bitcoin-uri                                   || GET  || Bitcoin URL ([[bip-0021.mediawiki|BIP21]] / [[bip-0072.mediawiki|BIP72]])
|-
| application/bitcoin-paymentrequest                        || GET  || [[bip-0070.mediawiki|BIP70]] PaymentRequest
|-
| application/bitcoin-paymentprotocol-message               || POST || [[bip-0075.mediawiki|BIP75]] ProtocolMessage 
|-
| application/bitcoin-encrypted-paymentprotocol-message     || POST || [[bip-0075.mediawiki|BIP75]] EncryptedProtocolMessage
|-
|}

Based on the '''Allow''' and '''Accept''' headers in the OPTIONS response, the client MAY make another TLS-protected HTTP call to the URL using the HTTP method for the data type and the '''Accept''' value that the client requests.

====Optional Public Key Sharing====

In order to fully support [[bip-0075.mediawiki|BIP75]] Payment Protocol using EncryptedProtocolMessages, the Address Service MAY provide a '''receiver_public_key''' for the address endpoint by including the '''X-Identity''' HTTP header in the response. The contents of the '''X-Identity''' header MUST be a hex-encoded, DER-formatted EC Public Key.

===Raw Wallet Addresses, BitcoinURIs and PaymentRequests===

====Request====

A HTTP GET request on a TLS-protected HTTP address endpoint MUST set the '''Accept''' header to the requested content type. This requested content type MUST have been listed in the '''Accept''' header of the previous OPTIONS response. 

====Response====

The Address Service MUST respond with the appropriate requested data type and a HTTP Status Code of '''200 (OK)'''. 

If the data type is temporarily unavailable and should be retried later, the Address Service MUST respond with a HTTP Status Code of 503 (Service Unavailable). The Address Service MAY include a '''Retry-After''' HTTP Header if it can determine when an appropriate response will be available.

If the data type is permanently unavailable, for example if the address endpoint has been disabled, the Address Service MUST respond with a HTTP Status Code of 410 (Gone).

===Handling BIP75 Messages===

====Request====

A HTTP POST request on a TLS-protected HTTP address endpoint MUST set the '''Accept''' header to the requested response MIME Type. The available response MIME Types for this request are:

application/bitcoin-paymentprotocol-message
application/bitcoin-encrypted-paymentprotocol-message

The HTTP POST request MUST set the '''Content-Transfer-Encoding''' header to "binary" and the '''Content-Type header''' to either of the aforementioned MIME Types. The content of the POST message MUST be the binary representation of a serialized ProtocolMessage or EncryptedProtocolMessage.

====Immediate Response====

The Address Service MUST respond with a HTTP Status Code of '''200 (OK)''' if the response type is a ProtocolMessage or EncryptedProtocolMessage. The Address Service MUST respond with a ProtocolMessage or EncryptedProtocolMessage based on the '''Accept''' header in the client request.
 
====Delayed Response====

The Address Service MUST respond with a HTTP Status Code of '''202 (Accepted)''' and the '''Location''' header set to a location to later retrieve the resulting ProtocolMessage or EncryptedProtocolMessage

'''NOTE''': [[bip-0075.mediawiki|BIP75]] messages SHOULD be transmitted using EncryptedProtocolMessage message types in order to provide additional application-layer security.


==Implementation==

TBD

==References==
* [[bip-0021.mediawiki|BIP21 - URI Scheme]]
* [[bip-0070.mediawiki|BIP70 - Payment Protocol]]
* [[bip-0072.mediawiki|BIP72 - bitcoin: URI Extensions for Payment Protocol]]
* [[bip-0075.mediawiki|BIP75 - Out of Band Address Exchange using Payment Protocol Encryption]]
* [https://tools.ietf.org/html/rfc2616 RFC2616 - Hypertext Transfer Protocol -- HTTP/1.1]
* [https://tools.ietf.org/html/rfc6698 RFC6698 - The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA]
* [https://tools.ietf.org/html/rfc7671 RFC7671 - The DNS-Based Authentication of Named Entities (DANE) Protocol: Updates and Operational Guidance]