BRC-50

Submitting Received Payments to a Wallet

An application that has received a payment on someone's behalf has no standard way to hand it over. This defines how a transaction and its proofs are submitted into a wallet, so the wallet recognises the funds as the user's own.

Brayden Langley14 Apr 2023changed 1 May 20263 min read

Why: Apps that receive payments on a user's behalf need a standard way to pass those payments, and proof of their validity, into the user's wallet instead of holding a balance themselves.
What: BRC-50 (historical) defines a message format for an application to submit a received Bitcoin transaction, its Simplified Payment Verification (SPV) proof, and sender details to a wallet, and the acknowledgment the wallet sends back.
How: An app sends a JSON Payment Submission Message containing the transaction envelope, sender's public key, derivation prefix and a note to a wallet's submitDirectTransaction route, and the wallet replies with a Payment Acknowledgment Message containing a reference number, or throws an error on failure.

What this lets you do

Submit a received transaction to a user's wallet
Include SPV proof so the wallet can verify the payment
Pass sender identity and derivation info for key recovery
Attach a human-readable note and optional expected amount
Receive a reference number acknowledging successful submission

Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.

Reference for an AI

Everything an assistant needs to answer questions about BRC-50 accurately, including what it depends on.

The specification

Read the original

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.

Status Note

BRC-50 is historical. Current incoming transaction submission is specified by BRC-100 internalizeAction. For BRC-29 payments, the current outputs[].protocol value is wallet payment; for basket insertions, it is basket insertion. The legacy submitDirectTransaction route and BRC-8 envelope payload are deprecated for new implementations.

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.

Was this helpful?

Summary