Small BIP-70 update for better UX on Bitcoin Cash

By | 2018-12-14

This is a follow-up post to the previous BIP-70 ideas I had a while back. I think I have come to the conclusion of what the easiest way forward should be but I do not really know how to formally standardize it. The original BIP has a section about extensibility:

[…] Implementations that need to extend messages in this specification shall use tags starting at 1000, and shall update the extensions page via pull-req to avoid conflicts with other extensions.

I could do it this way but I do not think a pull-request to the bitcoin GitHub repository would be honored in this case since one of the proposed parameters is not applicable to BTC.


The update I am proposing is to extend the PaymentDetails message with three additional optional parameters:

message PaymentDetails {
        optional string network = 1 [default = "main"]; // "main" or "test"
        repeated Output outputs = 2;        // Where payment should be sent
        required uint64 time = 3;           // Timestamp; when payment request created
        optional uint64 expires = 4;        // Timestamp; when this request should be considered invalid
        optional string memo = 5;           // Human-readable description of request for the customer
        optional string payment_url = 6;    // URL to send Payment and get PaymentACK
        optional bytes merchant_data = 7;   // Arbitrary data to include in the Payment message
        optional uint64 mining_fee = 8 [default = 1000];       // Minimum mining fee as 1/1000 satoshis/byte
        optional uint64 input_confirmations = 9 [default = 1]; // Minimum of blockchain confirmations of each input
        optional uint64 forfeit = 10 [default = 0];            // Minimum amount of satoshis in a ZeroConf Forfeit

Mining Fee

This parameter denotes the minimum fee required by the customer. Currently it is considered modus operandi on the BCH network to use 1 satoshi/byte which corresponds to the default value of 1000 in this message. The value is interpreted as 1/1000 satoshi/byte for future compatability.

Input Confirmations

This parameter denotes how many confirmations each of the UTXO used to create the payment needs to have. A value of “0” means that the merchant allows the customer to spend unconfirmed outputs.


This parameter denotes the amount (in satoshis) that the costumer needs to provide in a ZeroConf Forfeit (ZCF) transaction. If the value is 0 satoshis the payment can be done with a normal P2PKH transaction.

Errors and backwards compatibility

For backwards compatibility it is important that the wallet software displays any error message from the merchant to the user. Since the payment_details_version value is not bumped any current wallet that handles BIP-70 will skip the new parameters and might miss any requirements that is higher then the default values.

Other changes

The other major change is, as I described in my previous post, that the wallet should not broadcast the transaction before a PaymentACK is received. The wallet software might want to broadcast the transaction after the PaymentACK is received but is not obligated to do so.


This change needs to be implemented in a majority of all Bitcoin Cash wallets that currently supports BIP-70 until merchants are able to implement and use these new features. I suspect that the ZCF functionality will be the biggest challenge for wallet developers to implement.

Tip the author of this article:

Send a tip

Approximate value: 0.1 USD