Submitting Received Payments to a Wallet

Brayden Langley ([e-mail])

Abstract

To ensure a seamless process for submitting payments to a wallet, there must be a standardized method by which this process takes place. Wallets that implement this standard will be able to support the direct submission of transactions from applications to a user's wallet along with the associated SPV information as defined by BRC-9. The required message structure and fields are defined below in the Payment Submission Message section, and the expected response to provide is defined in the Payment Acknowledgment Message section. Wallets that choose to implement this specification will allow applications that facilitate the exchange of payments to be built in a way that is interoperable, extensible, and SPV compliant.

Motivation

BRC-50 standardizes payment submission to a wallet, improving the user experience for incoming Bitcoin payments. This enables higher-layer applications to add funds to a user's wallet without needing to maintain their own external balance. By standardizing payment submission, developers can create interoperable, extensible, and SPV compliant applications. This ensures a seamless and secure payment process, benefiting both wallet providers and end-users.

Specification

For this specification, we assume that there exists a wallet that facilitates a channel by which communication can occur with an application, such as over HTTP as defined in BRC-5. Based on this premise, we specify a standard by which payments can be submitted from an application to a wallet which then receives and processes the payment.

Payment Submission Message

We define an extension to the abstract BRC-1 messaging layer as the Payment Submission Message which comprises a JSON object with the following fields:

Several of the same fields as defined in BRC-29 are present in this message. This standard essentially facilitates an implementation of BRC-29 over an abstract, wallet-to-application interface.

Field	Type / Required	Description
protocol	(string, required)	This field denotes that the JSON object comprises a payment message according to the given protocol (such as 3241645161d8 for BRC-29).
transaction	(object, required)	The BRC-8 transaction envelope to submit, including key derivation information (the "Outputs Extension" as defined in BRC-29)
senderIdentityKey	(string, required)	The recipient will need to know the public identity key of the sender in order to validate the incoming payment. This field's value should be the 33-byte, compressed, hex-encoded secp256k1 public key of the sender
derivationPrefix	(string, required)	This field denotes the payment-wide derivation prefix used by the sender when the keys for the payment UTXOs were derived
note	(string, required)	Human-readable description for the transaction.
amount	(number, optional)	Amount of satoshis associated with the transaction. If provided, it is used to verify that the amount returned from processing the transaction matches the payment amount.

The transaction field is a JSON object that conforms to the BRC-8, with the BRC-29 Outputs Extension. Only one transaction can be submitted per request.

This provides the wallet with enough information to verify and receive payments from an application.

Here is an example of a simple Payment Submission Message:

{
  "protocol": "3241645161d8", // Simple Authenticated BSV P2PKH Payment Protocol
  "transaction": {
    "rawTx": "01000000017...",
    "inputs": {
        "b7d1297158f01bfc3fdace31f62a0d4634e9471d11b2a99f0784621cedb9367c": {
        "proof": {...},
        "rawTx": "01000000011..."
        }
    },
    "mapiResponses": [...],
    "txid": "737a1e90af9745da3f22ef74bc71a089c5e2a76e9662a0c9fa5b7cf94fe32e75"
  },
  "senderIdentityKey": "031d903f5b32a6121f29c59c547d2ea41ee8157ab0f0c2b5190be24a032816f827",
  "note": "Payment for spelling fix pull request.",
  "amount": 1033,
  "derivationPrefix:": "8217bb4e7fa0541e0f5e04fea764ab91"
}

Payment Acknowledgment Message

The Payment Acknowledgment Message is the response that should be returned from the wallet to the calling application with the status of the request, and a reference number for the transaction submitted.

Here is an example response from a successful payment submission:

{
  "reference": "cd5b1e4947e304476c788cd474fb579a"
}

Payment Error Message

If an error occurs during submission, an internal error should be thrown which can be caught and handled by the application code.

Implementation

Wallets can implement this specification by providing access to a submitDirectTransaction route over a given BRC-1 communications substrate, such as BRC-5, BRC-6 or BRC-7.

A specific implementation of this BRC can be seen in the Babbage Dojo/Ninja architecture.