1Color Offline Peer-to-Peer Payments

Abstract

This BRC specifies how one wallet pays 1Color (BRC-162) tokens to another wallet when either party, or both, may be offline. The payer hands the payee one payment bundle: a signed transaction, the data the payee needs to recognize its output, and enough evidence to show that every token the payer spends traces back to outputs an overlay has already admitted. The payee checks the bundle without any network access, credits the payment, and settles it with the overlay later.

The evidence is an admission attestation: an overlay operator's signature over the outputs it admitted. The payee walks back through the transaction graph until every token input ends at an attested output. It trusts an attestation only when the signer's identity key is one of its own trust anchors.

Offline acceptance carries counterparty risk: the payer could spend the same input twice before the payee settles. This BRC states that risk and, for regulated assets, how it is contained. The overlay records the owner of every admitted output, so a double-spent outpoint identifies the identity key that spent it, even when the payment used sender blinding. Under that asset's identity registration, the key identifies a person.

The bundle has one binary encoding. Bindings are given for a nearby session (QR pairing, sealed frame, air-gap QR) and for a BRC-33 message box.

Motivation

A token payment today is accepted when its overlay admits it. That needs a network connection at the moment of payment. Many real payments happen without one: in a shop with poor signal, between two phones on a train, at a market stall. A stablecoin that only works online is a weaker substitute for cash.

The rules needed to accept a payment offline safely are subtle. The payee must know which ancestors to check, what signature stands in for the overlay, whose signature to believe, what to do when settlement later fails, and why it is reasonable to take the risk at all. Until now these rules existed only in one wallet's source code. This document states them so that other wallets, overlays and issuers can interoperate.

BRC-207 requires a current overlay answer before a wallet spends or accepts a token. This BRC defines the deferred admission policy that relaxes that requirement under the conditions below. A wallet chooses whether to offer it. It applies to any 1Color asset and needs no declaration by the issuer.

Relationship to other documents

BRC-176 proves lineage all the way back to a deploy. This BRC stops the walk at the first attested output. That keeps a bundle small enough for a QR code, at the cost of trusting the attesting overlay for everything older.

MUST, MUST NOT, SHOULD and MAY express requirements for conforming implementations.

Roles

One organization MAY hold several roles. An issuer commonly runs the overlay and the registrar.

Admission attestation

An attestation is an overlay operator's statement: "the topic tm_color_<assetId> admitted these outputs of this transaction."

Message

1color-admit:v1:<topic>:<txid>:<outputs>

• topic is tm_color_<assetId> per BRC-207, using the canonical asset ID <64 lowercase hex>_<decimal vout>.
• txid is 64 lowercase hex characters, in display order.
• outputs is the admitted output indices as decimal integers without leading zeroes, unique, ascending and joined by ,. It MUST NOT be empty.

The topic is part of the message so an attestation for one asset cannot be replayed as evidence for another.

Signature

The signer computes e = SHA-256(UTF-8(message)) and signs e with ECDSA over secp256k1 using its identity key. e is not hashed again. Signers SHOULD use RFC 6979 deterministic nonces, so re-signing the same message gives the same bytes and settlement retries are idempotent. The signature is DER encoded. Verifiers MUST accept any valid S value and MUST NOT require low-S.

An overlay MUST sign only outputs its topic has admitted. It returns the attestation for each topic in its BRC-22 submission response as admissionSignature (lowercase DER hex) and admissionIdentityKey (compressed public key, 66 hex), next to that topic's outputsToAdmit.

Meaning and limits

An attestation proves admission at signing time. It does not prove the output is still unspent. That gap is the counterparty risk discussed below.

Trust

A verifier MUST accept an attestation only when the signer key is one of its trust anchors under BRC-189, and the signature verifies against that anchor. A key named inside a bundle is a hint for lookup. It is never a reason to trust.

Wallet builds normally ship with the issuers' attesting keys already trusted. A user MAY add or remove a key at any time, for example one published on an asset's website. Removing a key affects only future checks.

Payment bundle

Encoding

All integers marked VarInt use Bitcoin CompactSize encoding in its minimal form. A non-minimal VarInt MUST fail. str is a VarInt byte length followed by strict UTF-8. bytes is a VarInt length followed by raw bytes. A txid field is 32 bytes in display order: the bytes of the hex string as written. A decoder MUST reject trailing bytes.

u8      version            = 0x01
33B     senderKey
VarInt  outputIndex
str     derivationPrefix
str     derivationSuffix
str     assetId
VarInt  nSubmissions
        nSubmissions × { 32B txid ; bytes offChainValues }
VarInt  nAttestations
        nAttestations × { 32B txid ; VarInt nOutputs ; nOutputs × VarInt output ;
                          bytes signature ; 33B signerKey }
str     note
bytes   transaction

Why each field is sent

There is deliberately no amount field: the amount is read from the payee's output script, so the bundle cannot claim a different one. There is also no overlay URL and no trusted key: the payee uses its own configuration for both, so a payer cannot steer it to a server or signer of the payer's choosing.

Structural rules

• senderKey and each signerKey MUST be valid compressed secp256k1 points.
• assetId MUST be canonical as defined in BRC-162.
• Submission txids MUST be unique. Attestation txids MUST be unique. No txid appears in both lists.
• Attestation outputs MUST be ascending and unique, and the list MUST NOT be empty.
• derivationPrefix and derivationSuffix MUST satisfy BRC-207's remittance rules: nonempty strict UTF-8 without whitespace. The resulting protocol name MUST fit BRC-43's 280-character bound.
• transaction MUST parse as a BRC-233 Subject BEEF whose subject is the tip. Like a BRC-176 packet, it MUST NOT be validated, stripped or round-tripped as BRC-95 Atomic BEEF: BRC-95 handling may drop the ancestor bodies the walk-back needs.

A bundle that breaks any rule fails as decode_failed.

Walk-back

The walk-back decides whether every token in the payment traces to attested outputs, and which transactions the payee must settle. It runs without network access.

function walk(tx):                       // tx starts as the tip
    if tx.txid is on the stack: fail "shape"         // malformed bag
    for each input i of tx:
        parentId, vout = i.sourceTxid, i.sourceOutputIndex
        parent = body of parentId in transaction, if present
        if parent is absent:
            if attested(parentId, vout): continue    // attested and reduced: fine
            fail "uncovered_ancestor"                // rule B
        if parent.outputs[vout] is not a token of assetId: continue   // rule K
        if attested(parentId, vout): continue        // bottom of this branch
        if attestation exists for parentId:          // admitted, but not this output
            fail "uncovered_ancestor"                // rule A
        walk(parent)
        mustSubmit.add(parentId)
    return

attested(txid, vout) =
    an attestation for txid exists, its signerKey is a trust anchor,
    its signature verifies for topic tm_color_<assetId>, and vout is in its outputs

The result is mustSubmit plus the tip, ordered so every parent comes before its children.

Rules A, B and K, and why they exist:

• A. Admitted but not this output. The overlay admitted a transaction but not the spent output. That output was never a valid token in the overlay's view, for example a phantom coin from an over-output transaction. The walk MUST NOT search further back to justify it.
• B. Missing body. A missing parent counts as attested only when an attestation covers that exact output. Otherwise there is nothing to check. A mined parent is not treated as admitted: mined is not admitted.
• K. Non-token inputs. Inputs that do not carry this asset, such as fee funding, are neither walked nor counted. They do not affect token lineage. Their scripts are still validated below.

Every txid in mustSubmit, and the tip, MUST have a submission entry. Otherwise the bundle fails as not_covered. A wallet MAY cap walk depth or bundle size by policy; exceeding a cap fails as limit_exceeded.

Payee acceptance

The payee MUST run these checks in order and stop at the first failure. Each failure maps to an ack code. A payee that declines MUST NOT have saved or credited anything.

1. Decode. The bundle decodes under the structural rules. Else decode_failed.
2. Output. outputIndex names a tip output that is a BRC-162 value output of assetId with a P2PKH remainder. Else invalid_tx.
3. Ownership. The payee computes its key with BRC-100 getPublicKey. The arguments are protocolID [2, "p color <assetTag> <prefixTag> <suffixTag>"] and keyID "color" per BRC-207, with counterparty: senderKey and forSelf: true. The HASH160 of that key MUST equal the output's public key hash. Else session_mismatch. This proves the payee alone can spend the output.
4. Scripts. Every input of the tip and of each mustSubmit transaction MUST pass consensus script validation against its source output. Source outputs are absent only where rule B allows. Else invalid_tx. The payee SHOULD verify merkle paths when it holds the headers.
5. Token rules. The tip and each mustSubmit transaction MUST satisfy BRC-162 conservation and authority rules for assetId, with all inputs counted from walked or attested sources. Else invalid_tx.
6. Walk-back. It succeeds. Else not_covered.
7. Session or request. On the nearby rail the prefix, suffix, asset and any requested amount equal the session's. Else session_mismatch. A session already paid fails as already_paid, here or atomically at step 9.
8. Policy. The amount and depth fit the payee's deferred-admission limits. Else limit_exceeded.
9. Save. The payee durably stores the bundle and marks the session spent. This is one atomic step. Else save_failed.
10. Ack, then credit. The payee sends a positive ack, then credits the output in its per-asset basket with the color_offline tag. Saving comes before the ack, so a positive ack never refers to a payment the payee could lose.

Settlement

Settlement turns an offline credit into an admitted one. Either party MAY settle, and both MAY try. Submission is idempotent, so a duplicate does no harm.

1. Submit each mustSubmit transaction, then the tip, in order. Each goes to the settling party's configured provider for tm_color_<assetId> with its submission entry's off-chain values.
2. Accept an admission only when it carries an attestation from a trust anchor covering the expected outputs. An unsigned or unverifiable answer is a retryable failure, never an admission.
3. Store each attestation. It becomes evidence for later bundles.
4. Broadcast only after the overlay has admitted the transaction. Broadcasting the tip's BEEF also broadcasts its unmined ancestors. If a transaction were mined before admission and the overlay then refused it, its token inputs would be destroyed on-chain.
5. When the tip is admitted, remove the color_offline tag.

Outcomes:

A wallet SHOULD tell the user when settlement has not finished within its stale threshold. A threshold of three days is suggested.

The payer MUST keep its spent inputs reserved, and the exposure recorded, until it sees the tip admitted or a conflict established, as BRC-207 requires.

Deferred admission policy

This section defines the BRC-207 wallet policy that makes offline payment possible. A wallet MAY offer it. When enabled, it applies to every 1Color asset.

• Accepting. An output accepted under this BRC is held with the BRC-207 state tag color_state_available and the additional wallet-authored tag color_offline. It counts toward the asset's token balance. Applications cannot set or remove color_offline. This extends BRC-207, which otherwise reserves color_state_available for admitted outputs.
• Spending offline. A color_offline output MAY be spent in a new bundle. The payer forwards the evidence: its own bundle's submission entries and attestations for every still-unattested ancestor.
• Spending online. Before an online spend of a color_offline output releases a signature, the wallet MUST settle the transaction that created the output and its unattested ancestors. If any is refused, the spend fails before broadcast.
• Limits. The wallet sets per-asset amount caps, maximum walk depth, maximum age and accepted counterparties. The user consents to the policy when enabling it, and that consent authorizes later settlement.
• Capability. A wallet that accepts bundles MAY advertise BRC-205 attribute brc175-offline=1. A payer that cannot tell whether the payee accepts bundles SHOULD settle online first.

Bindings

Nearby session

The payee starts a payment by showing a session QR:

bsvpay1:<base64url, unpadded, of UTF-8 JSON>

The payer replies with one sealed frame:

0x01 ‖ IV (32 bytes) ‖ AES-256-GCM ciphertext of the bundle ‖ tag (16 bytes)

The key is the session PSK. A wrong key or any tampering fails authentication, which maps to decode_failed. The frame travels by whichever radio both sides support. Radio link details are implementation-specific. If no radio works, the payer shows the sealed frame as a BRC-141 animated QR; 1024-byte blocks are suggested. A sealed frame MUST NOT exceed 65,536 bytes.

The payee answers over the radio with a UTF-8 JSON ack of at most 4,096 bytes:

{ "ok": true }
{ "ok": false, "error": "not_covered" }

error is one of decode_failed, invalid_tx, session_mismatch, already_paid, not_covered, limit_exceeded and save_failed. A negative ack means the payee kept nothing, so the payer MAY release its reservation. The QR fallback has no return path. The payer then treats the payment as delivered but unconfirmed, and keeps its reservation until it observes settlement.

Message box

For payments to a remote payee, the payer sends the bundle through a BRC-33 message box named color-payments. It may first resolve a BRC-169 handle to the payee's identity key. The message body is:

{ "v": 1, "bundle": "<standard base64 of the bundle>" }

With no session, the payer chooses the derivation prefix and suffix. They MUST be fresh random values. The payee runs the acceptance checks, skipping step 7. It acknowledges the message only after step 9, or after a decline. A payee that declines MAY send the decline code back to the payer's color-payments box.

Sender blinding

A payer MAY hide its identity from the payee. It picks a fresh random scalar r and sends senderKey = A′ = A + r·G. It derives the payee's key from the shared secret S′ = S + r·B, where S is its BRC-42 shared secret with B. Because b·A′ = S′, the payee derives the same key with an unchanged getPublicKey call and counterparty: A′. The payee cannot tell a blinded payment from an unblinded one, or from a BRC-228 ephemeral key. Unblinded payment, with senderKey = A, is equally valid.

The payer keeps r privately, against the payment's outpoint. Revealing r later proves that the payer built the payment: anyone can check A′ − r·G = A. r never appears in a bundle, in an overlay submission or in BRC-100 metadata.

What each party learns:

Blinding gives privacy from counterparties and the public. It deliberately gives none from a regulated overlay.

Counterparty risk and double-spend attribution

The risk

An attestation shows that an output was admitted, not that it is still unspent. Until the payee settles, the payer can spend the same input to someone else. Whoever settles first wins; the other payee's credit is removed. Deferred admission puts that risk on the payee who accepted it. Issuer supply is never affected, because the overlay admits only one spend of each output.

The payee's limits bound the exposure. For regulated assets, attribution makes cheating traceable and therefore deterrable.

Regulated assets

A regulated asset is one whose overlay admits an output only when the submission discloses the output's owner and that owner is registered with the asset's identity registrar. Those admission controls belong to an optional issuer-controls profile declared in the asset's BRC-162 req map. This BRC does not define that profile; it states what attribution needs from it.

• Ownership disclosure. For each token output, the submission carries a BRC-69 specific linkage, encrypted to the overlay key under BRC-72. The linkage lets the overlay recompute the output key as owner + k·G and match it to the script. For a blinded output, the payer discloses the offset k it derived from S′.
• Owner record. The overlay MUST keep the owner identity key of every admitted output. It MUST keep that record after the output is spent, and record the txid of the spend it admitted.
• Conflict record. The overlay SHOULD keep the bytes of any refused submission that tried to spend an already spent output.

Only the owner can spend an output: its private key is b + k, and the payer knows k but not b. So the identity key recorded as the owner of a double-spent outpoint is the identity that signed both spends, unless that key was stolen or shared.

Reporting a double spend

1. The victim's wallet reports the double-spent outpoint, the bundle it holds and the competing txid from settlement. The bundle contains the second spend, signed by the offender's key.
2. The overlay operator looks up the outpoint's owner record. That gives the owner identity key and the transaction the overlay admitted.
3. The registrar maps the identity key to the person who registered it.

The outpoint is enough to start the lookup. The victim's bundle is the proof. Blinding does not hinder either step, because the overlay saw the real keys. Access to owner records, and the legal process for disclosure, are governed by the operator's and registrar's terms. Those terms are outside this BRC.

For assets without ownership disclosure, attribution stops at the overlay's view of the transactions. There is no person behind a key.

Security considerations

• PSK exposure. Anyone who photographs the session QR can open the sealed frame. They learn the payment but cannot redirect it, because the output pays the payee's key. Payees SHOULD show session codes only briefly.
• Replay. A session is burned when its payment is saved. A message-box bundle is unique by tip txid, and saving it twice MUST be idempotent.
• Attester compromise. A stolen attester key can attest outputs that were never admitted, and wallets trusting it would accept them. Settlement would then fail, and those payees lose the credited value. Wallets SHOULD let users remove a trust anchor quickly, and overlays SHOULD rotate keys under BRC-189's rules for trust changes.
• Eviction. If an admitted transaction is later evicted, for example because it never confirmed, its outputs are no longer admitted. A settled payment can then be reversed. Wallets SHOULD show an evicted credit as reversed, not silently hide it.
• Stale trust. Removing a trust anchor does not revoke attestations already relied on. Wallets SHOULD re-check pending color_offline outputs against current anchors.
• Size. Decoders MUST bound allocation by the received length before reading counts. Walk depth and BEEF size MUST be bounded.

Test vectors

All keys below are test values. Never use them for real funds.

Blinded derivation

The payee's unchanged getPublicKey({protocolID, keyID: "color", counterparty: A′, forSelf: true}) returns P.

Attestation

a1a1…a1 and c3c3…c3 stand for the byte repeated 32 times (64 hex characters).

Bundle encoding

This vector covers framing only. Its transaction is four placeholder bytes, not valid BEEF.

• senderKey: A′ above.
• outputIndex: 1.
• prefix and suffix: as above.
• assetId: as above.
• One submission: txid b2 × 32, off-chain values {}.
• One attestation: the one above.
• Empty note.
• transaction: 01010101.

01024d4dd4c2ad973e10065a593d0203dda4174292bb36e4e99fb2fbb1373a17874b01
0441513d3d0441673d3d4261316131613161316131613161316131613161316131613161
316131613161316131613161316131613161316131613161316131613161316131613161
3161315f3001b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2
b2b2027b7d01c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3
c3c302000247304502210084f2172ef0fdd4a01038af38f00b339133580eca3393e5989d
f9688bf9462e58022042a1b88ca1750fef4b7aa0466bcfebd2d9c6bb1f4333fadce2ef25
04471ace6702798b81951a6a8c7ef8beda09b06a23031d7efaf37b663265e0188ab37812
4046000401010101

Length: 295 bytes. The line breaks are for display only.

Implementations

A prior version of this protocol is implemented in the BSV wallet (bsv-wallet, packages/expo-wallet-toolbox/core/localpay and core/mandala) with the @bsv/mandala library and its Go overlay. That implementation predates the 1Color names and this bundle encoding, and is being migrated to this specification.

References

• BRC-22: Overlay Network Data Synchronization
• BRC-33: PeerServ Message Relay Interface
• BRC-42, BRC-43: key derivation and invoice numbers
• BRC-62, BRC-95, BRC-233: BEEF, Atomic BEEF and Subject BEEF
• BRC-69, BRC-72: key linkage revelation
• BRC-141: Fountain-Coded Air-Gap Transport
• BRC-162: 1Color tokens
• BRC-169: handle addressing
• BRC-176: BSV-21 validity proofs
• BRC-189: identity and personal trust
• BRC-205: wallet version attributes
• BRC-207: 1Color wallet module
• BRC-228: unlinkable payments