Skip to content

Latest commit

 

History

History
85 lines (56 loc) · 6.56 KB

payment-requests.mediawiki

File metadata and controls

85 lines (56 loc) · 6.56 KB
Raw

  Title: Open Assets Extensions to Payment Requests
  Authors: Devon Gundry <devongundry@chain.com>, Oleg Andreev <oleganza@chain.com>
  Status: Draft
  Created: 2015-05-06

Table of Contents

Abstract

This document defines extensions to BIP-70, BIP-71, BIP-72 and BIP-73 to allow clients to support payments using the Open Assets Protocol.

Motivation

Merchants that receive Open Assets payments need a convenient and secure way to establish payment details with their customers. Customers need a standard mechanism to support both pure Bitcoin payments and Open Assets payments (or instead, specify only one of them as acceptable).

Standard Bitcoin payments involve only one asset: bitcoins. The Open Assets Protocol opens up the possibility for many different assets. Therefore, it becomes interesting to enable risk-free atomic swaps of one asset for another, or for pure ("non-colored") bitcoins. This specification describes how this can be accomplished in a single transaction.

Specification

Open Assets Payment Request

To enable merchants to accept payments in Open Assets units, we propose the following extension to BIP-70.

  1. A Payment Request must contain payment_details_version with value 0x4f41 to prevent incompatible (Open Assets-unaware) wallets from sending funds. (0x4f41 is the same prefix as used in the OA marker).
  2. The Output message is extended with a field optional bytes asset_id = 4001; containing a 160-bit binary Asset ID (RIPEMD-160(SHA-256(issuing script))).
  3. The Output message is extended with a field optional uint64 asset_amount = 4002; containing an amount of units.
The optional field output.amount MUST NOT be specified (it's reserved for future use). The sender should include enough satoshis to exceed the dust limit (546 per simple output as of April 2015). This is similar to the responsibility of adding adequate mining fees to the transaction.

If output.amount is specified, then output.asset_id and output.asset_amount MUST NOT be specified. This means that the output is a pure bitcoin output.

The tags 4001 and 4002 are chosen to avoid conflict with future extensions to v1 payment requests (so they can also be ported to Open Assets compatibility in the future).

Open Assets Atomic Swap

To enable atomic swaps of bitcoins and assets (in any combination) we introduce a repeated field Input. Inputs define what the merchant offers to the customer in return for payment. 

    message PaymentDetails {
        optional string network = 1 [default = "main"];
        repeated Output outputs = 2;
        (...)
        repeated Input inputs = 8;
    }
    message Input {
        required bytes txhash = 1;
        required uint32 index = 2;
    }
txhash a binary 32-byte hash of the transaction being spent by the input
index index of the output in the transaction referenced by txhash

Using input references, the client is able to determine which assets and amounts are being proposed. The merchant should use Output fields to define any necessary transaction change (assets and/or pure bitcoins). The client should take into account both inputs and outputs when computing net transferred value in terms of assets and pure bitcoins.

The client must include all specified inputs and use empty signature scripts for each of them.

The client must include specified inputs and outputs in the transaction before any of its own inputs and outputs.

If inputs are specified, the transaction should not be relayed to the network (because it is not fully signed yet), but instead should be sent directly to the merchant via PaymentDetails.payment_url wrapped in a Payment message. A Payment Request with inputs must contain a valid payment URL, otherwise it should be rejected.

MIME types for Open Assets Payment Requests

To enable merchants and customers to negotiate which Payment Request type is supported, we propose the following extension to BIP-71 and BIP-73.

Open Assets Payment Requests use media type application/oa-paymentrequest and are encoded in binary.

The Accept: HTTP header can be used by the wallet to list acceptable MIME types. If the wallet supports both regular Bitcoin payments and Open Assets payments, both MIME types (application/bitcoin-paymentrequest, application/oa-paymentrequest) are listed. If only Open Assets payments are supported, only the Open Assets MIME type is used. If the merchant cannot support any of the requested types, it must return HTTP error code 406 Not Acceptable.

Payment URI

To enable direct payments to an address, we propose an extension to the Bitcoin URI (BIP-21, BIP-72).

  1. In addition to the bitcoin: scheme, we introduce the openassets: scheme. This allows merchants to ensure that clients use Open Assets-compatible software to handle Open Assets payments (instead of launching regular Bitcoin wallets).
  2. Instead of standard bitcoin address encoding, Open Assets address encoding must be used according to the Address Format Specification.
  3. amount parameter must be formatted as integer if the address is present and formatted according to Open Assets Address Format Specification.
  4. We introduce additional query string parameter asset, which must declare an Asset ID as defined by the Open Assets Protocol Specification.
Note: merchants that support both regular bitcoin payments and Open Assets payments should use bitcoin: scheme and detect the client's intent using the Accept: HTTP header. If such URI is opened by a wallet that is unaware of Open Assets, it will detect incompatible address encoding and decline payment.

See Also