> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/peer-to-peer/0246.md).

# Session Upgrade: BRC-33 Messages over WebRTPay

Brandon Cryderman / HandCash (<brandongcryderman@gmail.com>)

**Status:** Draft (proposed number, not a BSVA assignment)

## Abstract

This BRC lets two online wallets, or two installs of one account, send [BRC-33](https://bsv.brc.dev/peer-to-peer/0033.md) messagebox traffic over a direct WebRTC data channel. It uses the connection that `webrtpay/1` ([WebRTPay protocol reference](https://github.com/bsv-blockchain/ts-stack/blob/83c748ab474615c5404cd7eb0f6e1464603613b5/packages/messaging/webrtpay/docs/protocol.md)) defines for direct payments, unchanged: the same signalling envelopes, presence check, channel framing and identity handshake. It adds only what messages need: a `messages` purpose, device addressing for installs that share an identity key, and two session messages, `msg` and `ack`.

The messagebox stays the meeting point and the offline inbox. The channel carries the same message bodies the box would. It never carries custody.

## Motivation

A messagebox exists because the other wallet is often offline, firewalled, or unable to keep a listener. When both wallets are online, sending every chat line, remittance card and coordination message through a store-and-forward host only adds delay.

`webrtpay/1`, shipped as `@bsv/webrtpay` in the BSV TypeScript stack, already handles the hard parts for payments: NAT traversal, a presence check that answers in about two seconds, end-to-end encrypted signalling, a channel bound to both identity keys through BRC-100 signatures, an optional relay and TURN. A second protocol for the same connection would split wallets into two groups that cannot reach each other. This BRC reuses that connection and defines only the messaging layer.

## Relationship to other documents

| Concern                                                                                                                | Document                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connection: signalling envelopes and their encryption, knock and ring, ICE, channel framing, identity handshake, relay | `webrtpay/1` ([reference](https://github.com/bsv-blockchain/ts-stack/blob/83c748ab474615c5404cd7eb0f6e1464603613b5/packages/messaging/webrtpay/docs/protocol.md)) §3 to §5, §7 to §9 |
| Messages carried                                                                                                       | [BRC-33](https://bsv.brc.dev/peer-to-peer/0033.md), each body sealed per [BRC-78](https://bsv.brc.dev/peer-to-peer/0078.md)                                                          |
| Keys and signatures                                                                                                    | [BRC-100](https://bsv.brc.dev/wallet/0100.md)                                                                                                                                        |
| Coordination between installs of one account                                                                           | Draft BRC-249 ([#311](https://github.com/bsv-blockchain/BRCs/pull/311))                                                                                                              |

Section numbers such as `webrtpay/1` §7.4 refer to the reference at the commit linked below.

## Specification

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119.

### 1. Scope

This BRC covers messages that already travel over BRC-33: chat, remittance cards, token deliveries and similar notices, and coordination between installs of one account such as BRC-249 release requests. It does not cover coin selection, signing or broadcast. An on-chain output remains the only proof of payment or item custody. A payment by itself uses `webrtpay/1`'s `payment` purpose, not this one.

### 2. Endpoints

An **endpoint** is one install: an identity key and a **device**, a random identifier of 1 to 128 characters from `[A-Za-z0-9._-]` that the install keeps for its lifetime. Two endpoints may share an identity key, as installs of one account do; they MUST then differ in device. The device SHOULD NOT be derived from any key or hardware identifier.

### 3. Signalling

Signals are `webrtpay/1` signalling envelopes (§7.1 to §7.3), encrypted with BRC-100 `encrypt` under protocol `[2, "webrtpay signaling"]` exactly as there, with these differences:

* **Purpose.** The plaintext's `purpose` is `"messages"`.
* **Devices.** The plaintext carries `fromDevice`, the sender's device, and `toDevice`, the recipient's device. In a `knock` or `offer` to another identity, `toDevice` MAY be empty, meaning whichever install answers. It MUST be set when `to` equals `from`, and in every `ring`, `answer` and `reject`, where it is the dial's `fromDevice`.
* **Box.** On a messagebox carrier, signals go in box **`webrtpay_messages`**, never in `webrtpay_signals`. A wallet that implements only payments never lists that box, so it never decrypts a signal it would refuse. A relay carrier (`webrtpay/1` §8) carries them unchanged.

A receiver opens a signal as `webrtpay/1` §7.4 does, accepting `purpose` `"messages"` in step 2 and checking the device fields before anything else:

1. It ignores a signal whose `from` is its own identity and whose `fromDevice` is its own device.
2. It ignores a signal whose `toDevice` names another device, and MUST NOT acknowledge it on the messagebox, so the addressed install still finds it.
3. It acknowledges every other signal once it has processed it.

Installs that share an identity share its box. An install applies these rules even when it cannot open a data channel, so it never consumes a signal meant for another install.

### 4. Dialing and admission

Dialing follows `webrtpay/1` §7.5: knock, ring, offer, answer, with its presence and dial timeouts and its network binding. A dial that ends `peer_unreachable`, `timeout` or `rejected` sends its messages through the messagebox.

When the messagebox is polled rather than pushed (BRC-33 `listMessages`), a reply comes only after the peer's next read. A dialer on such a carrier adds the peer's poll interval to both the presence and the dial timeout. A polling wallet reads its signalling box at least every 2.5 s while it receives and every second while it dials.

A wallet SHOULD ring and answer only identities the user has exchanged messages with, and its own installs, and otherwise answer a knock with `reject` `not_receiving` or not at all. Intake limits follow `webrtpay/1` §7.6.

An endpoint has at most one `messages` session with another endpoint. If installs of one account dial each other at the same time, the one whose `identityKey + "\n" + device` sorts lower keeps its dial and the other answers it.

### 5. Session messages

After the identity handshake (`webrtpay/1` §5), the session carries `webrtpay/1` frames (§4) whose objects are:

```json
{ "t": "msg", "id": "<1–64 characters>", "body": "<the body the messagebox would have carried>" }
{ "t": "ack", "id": "<the msg id>" }
```

and `webrtpay/1`'s `error` and `bye` (§6.4). Any other `t` is a protocol error, as in `webrtpay/1` §6.

* The receiver MUST pass `body` to the same ingest path as a messagebox message from the identity the handshake proved, and send `ack` after ingest accepts it.
* A `msg` MUST NOT exceed 256 KiB; a larger body goes through the messagebox.
* If the sender receives no `ack` within one second, it MUST close the session and send that message through the messagebox. A body can therefore arrive twice, once per path, so ingest MUST treat a repeat as it treats a repeated messagebox delivery.
* An `ack` acknowledges delivery of a message, never a payment.

### 6. Lifetime

A session ends when its channel closes, ICE fails, or either side sends `bye`. Messages then go through the messagebox until a new dial completes. A wallet SHOULD close a session that has been idle for ten minutes, and MUST close its sessions when it locks or switches account.

### 7. What this is not

* Not a replacement for BRC-33. First contact, offline peers and failed dials use the messagebox.
* Not a custody channel.
* Not history sync. Installs of one account may hold a session to carry coordination messages, not to merge state continuously.
* Not a listener requirement. Neither side opens a port.

## Security considerations

* **Authentication and encryption** are `webrtpay/1`'s: each side signs a transcript of both DTLS fingerprints, both nonces and both identity keys with a BRC-100 key, so a messagebox host, STUN server or TURN relay cannot read or redirect the channel. Each `body` also keeps its own BRC-78 envelope, as on the box.
* **Address exposure.** An offer or answer reveals the sender's public address, and possibly local ones, to its recipient only, since signals are encrypted to it. `webrtpay/1` gathers no ICE before a ring, so a knock discloses nothing. STUN servers learn a wallet's public address; a TURN relay learns both endpoints' addresses and sees only encrypted traffic. For this reason §4 limits who is answered.
* **Abuse.** Anyone can post signals to a wallet's `webrtpay_messages` box. Answering only known identities, and `webrtpay/1`'s intake limits, bound the work.

## Rationale

* **Why build on `webrtpay/1`.** It is the WebRTC connection the BSV stack ships, with a byte-level reference and test vectors. Reusing it gives one connection for payments and messages, one handshake to audit, and wallets that work together.
* **Why a separate purpose and box.** `webrtpay/1` receivers refuse any purpose but `payment` and close on unknown session messages. A separate purpose and box leave payment-only wallets untouched. A wallet that implements both can route each signal without trial decryption.
* **Why devices.** Two installs of one account have the same identity key. The device tells them apart in addressing, in simultaneous dials and in acknowledgement. That is what lets BRC-249 coordinate a move over a direct session.

## Implementation

`@bsv/webrtpay` ([bsv-blockchain/ts-stack](https://github.com/bsv-blockchain/ts-stack/tree/master/packages/messaging/webrtpay)) implements the connection. HandCash Desktop and Mobile implement an earlier revision of this BRC, which signed session descriptions directly, and are moving to this one.

## References

* `webrtpay/1`: [WebRTPay protocol reference](https://github.com/bsv-blockchain/ts-stack/blob/83c748ab474615c5404cd7eb0f6e1464603613b5/packages/messaging/webrtpay/docs/protocol.md), `@bsv/webrtpay`
* [BRC-33](https://bsv.brc.dev/peer-to-peer/0033.md): PeerServ Message Relay Interface
* [BRC-78](https://bsv.brc.dev/peer-to-peer/0078.md): Serialization Format for Portable Encrypted Messages
* [BRC-100](https://bsv.brc.dev/wallet/0100.md): Wallet-to-Application Interface
* Draft BRC-249 ([#311](https://github.com/bsv-blockchain/BRCs/pull/311)): Vault Account Holding Across Devices
* [RFC 8445](https://www.rfc-editor.org/rfc/rfc8445): Interactive Connectivity Establishment (ICE)
* [RFC 8831](https://www.rfc-editor.org/rfc/rfc8831): WebRTC Data Channels


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://bsv.brc.dev/peer-to-peer/0246.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
