Unsolicited Transaction Delivery to a BRC-169 Mailbox

Abstract

This specification privately delivers a transaction, its existing wallet receipt instructions and its protected lifecycle through a BRC-169 mailbox. The receiving Conforming Application owns acceptance and authorized publication/registration; the wallet independently validates receipt. Delivery, wallet acceptance, overlay admission and Bitcoin confirmation are distinct facts.

The format supports ordinary BRC-29 payments, BRC-207 1Color value and authority, BRC-209 resources, and declared alternative evidence profiles including offline attested chains. It reuses their receipt contracts rather than defining another token-remittance protocol. BRC-169's outer payment remains the visible delivery toll; the asset delivery stays inside encrypted content.

Dependencies and conformance

MUST, MUST NOT, SHOULD and MAY express conformance requirements. A Conforming Application implements the default auto-accept policy, authenticated bounded framing, whole-transaction preflight, durable recovery and the wallet adapter below. It may additionally offer receiver-choice acceptance. A Message Box or wallet alone does not thereby claim application conformance.

The normative wallet dependencies are the BRC-207 required-profile and receipt contract, BRC-162 declarations, BRC-209 resource profile, and BRC-177 protected batches, never expiry and portable lifecycle statements. The offline evidence construction is BRC-207's https://brc.dev/207/attested profile; BRC-175 is another transport for it. These are exact semantic dependencies, not claims that older wallets or relays implement them. Capability metadata is optional and never substitutes for checks on actual operations.

Responsibilities

Authenticated content framing

The sender MUST encrypt the plaintext MIME entity under BRC-169 and MUST include contentHash over its exact plaintext bytes, as specified there. The recipient MUST verify the BRC-169 signature, decrypt, and check that hash before acting on the contents. JSON and binary outer-envelope encodings retain their different BRC-169 signing preimages; relays MUST NOT transcode a signed envelope. A valid envelope without contentHash may be another BRC-169 message, but is not an actionable BRC-232 delivery.

Use this MIME content type (this specification does not claim IANA registration):

Content-Type: application/vnd.metanet.transaction+cbor
Content-Transfer-Encoding: binary

Header lines end with CRLF; exactly one CRLF CRLF ends the header block, followed by raw DAG-CBOR bytes. Header field names and media type are case-insensitive. Require one Content-Type with this type and no parameters, and one Content-Transfer-Encoding: binary. Reject duplicate fields, folded lines, malformed headers, multipart content and unsupported transfer encodings. Other well-formed headers are advisory only. Do not decode a headerless text/plain message, arbitrary JSON or an old unversioned body as this format.

Bound headers to 8 KiB and the complete decrypted MIME entity to 32 MiB before large allocation. A transport, wallet or host may impose a smaller documented limit and MUST return an explicit size/support failure. Decode exactly one canonical DAG-CBOR map: reject trailing bytes, duplicate keys, indefinite forms, nonminimal encodings, tags and unsupported scalar types. All text is strict UTF-8. There is no decompression or executable-data interpretation. Limits apply to encoded bytes, not nominal token amounts.

Body and wallet mapping

The top-level map has exactly these members; unknown members fail:

Every outputIndex is a uint32, exists in the subject, and occurs once. Require exact source bytes, independently computed subject TXID, and matching BEEF identity. No byte-order guess or conflicting duplicate transaction is allowed. Extra unrelated transactions in ordinary BEEF cannot serve as undeclared token proofs. Preserve profile evidence separately when producing BRC-95 Atomic BEEF for internalizeAction; do not strip it by treating a BRC-176 token packet or BRC-175 Subject BEEF as ordinary tx data.

Txid-only source entries are usable only when resolved from authenticated local knowledge or permitted providers. If Bitcoin evidence is incomplete, resolve and verify it under policy or fail/persist as unvalidated; inclusion in an envelope is not validation. BRC-67 / BEEF validation covers all Bitcoin inputs independently of which token ancestry a profile requires.

Ordinary satoshi receipt

{ outputIndex: uint32, protocol: "wallet payment",
  paymentRemittance: {
    derivationPrefix: tstr, derivationSuffix: tstr,
    senderIdentityKey: bstr(33)
  }
}

Copy this directly to BRC-100, converting the valid compressed public-key bytes to exactly 66 lowercase hex characters. Prefix/suffix strings retain their exact BRC-29/BRC-100 encoding; do not decode/re-encode or normalize them. The remittance counterparty may differ from the envelope deliverer, but MUST derive the actual recipient-controlled output. This map has no other members.

Module basket receipt

{ outputIndex: uint32, protocol: "basket insertion",
  insertionRemittance: {
    basket: tstr, customInstructions: tstr, tags?: [tstr, ...]
  }
}

The entry and remittance have no other members. For BRC-207, customInstructions is the unchanged UTF-8 JSON string containing exactly {version:1, assetId, derivationPrefix, derivationSuffix, senderIdentityKey} and optional profileData. Parse strictly, including duplicate-member rejection, then apply the module's exact schemas. The identity key inside that JSON is already compressed lowercase hex, not a CBOR byte string. Do not introduce a protocolID/keyID/counterparty replacement, proof URL, receipt tokenProofs member or another asset-specific remittance serialization.

The wire basket is p color <assetTag> or p color <assetTag> authority. assetTag is BRC-207's lowercase TXID plus v plus canonical output index; assetId in JSON remains its underscore form. An ISSUE receipt preserves its original ISSUE derivation tuple and derives the final asset ID, role and basket from the completed deploy. Reject a wrong basket instead of silently rewriting it. No global token balance basket, caller-authored state tag or display amount can establish control, value, authority or profile support.

The top-level profileData is application context, not a new BRC-100 argument. It follows the same exact required-profile/asset leaf contracts as BRC-207. Every copy of one leaf MUST agree. Required receipt evidence MUST already be present in that receipt's instruction string; transport context cannot replace it, authorize omission, or cause the receiver to rewrite the receipt. The application can use context for a foreign/other-recipient leg that has no local basket receipt. Every required fact still has to be established independently by the wallet through its permitted evidence contract. Route foreign-leg facts through the existing receipt profileData where permitted, or an established wallet evidence integration. Top-level context alone does not reach the wallet. If no permitted route exists (including a wallet-payment-only call), retain the delivery as pending or fail; do not invent a method argument or omit a leg.

Ordinary instructions remain limited to 1000 UTF-8 bytes. Supported BRC-209 and attested-profile exceptions permit up to 16 MiB per string and in aggregate for all p color instructions in one wallet call, counting repeated JSON/hex bytes. The MIME ceiling and any lower limits also apply. Profile eligibility must be authenticated; naming a basket cannot acquire the exception. A receiver MUST NOT split a delivery into calls merely to evade the aggregate bound.

Other asset systems may use this basket map only through an explicitly supported adapter that specifies script/control validation, evidence, exact remittance, publication and receipt semantics. A generic derivation tuple or unknown basket is not such an adapter, and is not BRC-207 compliance. Unsupported content may be retained as unvalidated data; it is not a verified holding.

Sender preparation and protected graphs

A Conforming Application MUST use a wallet/integration implementing BRC-177's protected lifecycle before releasing a subject. It selects an explicitly supported finite or never policy and obtains the necessary consent. Do not substitute a hidden timeout, an unsupported label or an ordinary unprotected noSend action. Finite seconds become the wallet's persisted absolute deadline.

Apply BRC-177's single-action isolation or explicit p nosend batch rules. Only designated token/resource inputs and bounded dedicated satoshi funding/fees may be encumbered. Surplus unrelated holdings must be released by an authorized, processed and appropriately admitted preparation/split first, or construction fails. Authority, contract and BRC-209 resource objects are explicitly selected and authorized; do not split them as fungible funding. Any approved batch fee remainder is batch-designated, not ordinary available change.

Necessary preparation/funding may be published and accepted. The sending application MUST NOT publish the delivered subject or its unpublished protected ancestors, enqueue them for delayed publication, or trigger an implicit commit that publishes them. This receiver-owned delivery policy is narrower than BRC-177's general explicit sendWith permission: the receiver owns publication of this delivery. A receiver may use authorized sendWith for retained local actions, or its configured processor/overlay adapter for imported evidence; an unknown TXID is not a wallet import and BRC-100 has no new broadcast method.

All parent bytes/TXIDs must be fixed before dependent signatures are released. Maintain the complete DAG, reservations, exact signature exposure and submission intent durably before handoff. BRC-177 batch leases, process exit and message expiry never free a usable released input. A root reclaim revokes its anchored graph only when it wins; separately usable signatures and token inputs require independent exposure reconciliation.

Lifecycle evidence and expiry

Carry the BRC-177 objects unchanged: {statement, signer, signature}, with its exact network, root TXID, anchor, timestamp/blockheight/never mode and value. These are CBOR maps using BRC-177's scalar values, compressed-key hex and DER hex. Verification reconstructs BRC-177's canonical domain-separated JSON message, not a signature over the CBOR map. Verify the responsible wallet's derived key, actual root/anchor relationship, dependency coverage, and the recipient's acceptance of that wallet's promise. Duplicate identical statements add nothing; conflicting statements fail. The outer content hash binds the delivery but does not replace original root-wallet signatures. Forward them when extending a graph.

For known protected roots, missing evidence fails protected delivery. If an external ancestor's disposition cannot be established, explicitly disclose it as unknown; neither an empty array nor lack of a label proves never. Labels and activation state are not automatically conveyed by BEEF. Wallet delivery adapters obtain lifecycle statements from authoritative storage only after the root's final signed bytes and TXID are fixed.

Evaluate every still-applicable finite root deadline independently in its own units; do not compare heights numerically with timestamps, reset durations on receipt, or extend deadlines after restart. Do not initiate publication at or after an applicable deadline. Allow observation margin. Reconcile an uncertain in-flight submission before attempting recovery; a queued submission alone did not satisfy expiry. Independently established root processing acceptance ends that root's finite reclamation policy, not another root's.

A released never payment is permanently sent/committed and MUST NOT be reclaimed following refusal, lost acknowledgment, timeout, inactivity or policy changes. It is not proof of irrevocable consensus settlement. A finite reclaim and receiver publication may race; retain evidence and report the verified winner. Decline, local deletion, lockTime and a merely submitted reclaim do not revoke released signatures. Sender identity blinding does not hide the root-wallet identities exposed by lifecycle statements; disclose that before handoff.

Receiving application lifecycle

Whole-transaction preflight and receiver policy

Authenticate and durably retain the envelope, exact MIME/body bytes, receipts, Bitcoin/profile evidence and lifecycle records before deleting relay data or starting external effects. Coordinate workers for one recipient wallet/account and subject TXID. Preflight the complete transaction and every determinable asset/profile consequence, not just the first recognizable output:

1. Validate the complete mapped BRC-100 arguments and bounds before publication, including remittance encoding/lengths, tag grammar/counts and reserved-tag restrictions. Verify actual source scripts/satoshis, all required Bitcoin proofs, complete unlocking scripts, consensus finality and every requested output's control.
2. Authenticate each involved asset's original deploy under its applicable encoding. A BRC-161 JSON deploy has empty requirements; a binary deploy's immutable BRC-162 req remains binding through later JSON-encoded transfers. Enforce applicable ext and exact supported versions/parameters. Apply binary-prefix precedence and that asset's own quantity/authority or resource rules. A profile URI is not authority to install code, trust a server or bypass other profiles.
3. Apply each evidence policy below, including historical validation of consumed inputs; requiring those inputs to remain unspent would reject valid receipts. Distinguish a shared DAG ancestor from conflicting spends. Identify current conflicts, missing facts and applicable expiry before any publication.
4. Verify publication authority and all permissions for the whole effect. One recipient output cannot authorize an unsupported or unauthorized other leg. No uncommitted swap consideration may be presented as guaranteed. Processor replacement coordination, sequence/lock-time rules and signature commitments remain the wallet's obligations under BRC-207.

Fully signed but consensus-non-final transactions and incomplete offers may be retained as pending. They are not completed receipts and MUST NOT be finalized by silently changing sequences, outputs, lock time or signatures. This transport does not negotiate new revisions or transfer the originating wallet's processor obligations; an explicit supported higher-level flow is needed for that work.

Every Conforming Application MUST implement auto-accept, the default when valid supported receipts fit existing permissions and policy. No separate per-transfer click is required then. Auto-accept never grants missing permissions or waives limits. The optional receiver-choice mode is selected by the receiver in authenticated local account settings, and prompts before acceptance/publication. A sender cannot select or override it. Manual-only support is not conformance. Pending choice does not pause finite deadlines; supported never remains sent.

Three evidence paths

Publication before BRC-209 receipt is this delivery protocol's application ordering, not an additional BRC-209 validity rule. An explicitly declared and supported companion profile may replace that ordering under BRC-207's replacement contract; all remaining asset, wallet and delivery obligations still apply.

A mixed transaction uses each asset's own path, including ordinary satoshi legs. BRC-209 and the default attested profile cannot apply to the same asset; separately declared assets remain composable. The BRC-189 list is used only as specified by the selected profile; fixed-identity mode has no hidden list test. Authority signatures anchor token history, not Bitcoin inclusion or current global unspentness. Default untimed attestations supply no signed age guarantee.

BRC-176's complete packet rules remain unchanged. Its packet is not an Atomic BEEF receipt, and a shortened attested walk is not a BRC-176 proof. BRC-175 adapters map its evidence and lifecycle objects into the existing BRC-207 profileData and these lifecycle records, validating the whole graph; neither transport's outer framing can be passed directly as BRC-100 tx.

Processing, receipt and deferred settlement

Record a processing intent before any external action. For the baseline/resource path, the receiving application arranges dependency-ordered Bitcoin processing and applicable overlay admission, then verifies the required outcomes. An overlay submission may itself publish Bitcoin; no redundant broadcast is required. Where admission must precede publication, follow that order; do not destroy token inputs by broadcasting a transition known to be rejected. Apply all assets' requirements.

Call BRC-100 internalizeAction with valid Atomic BEEF, the exact mapped output receipts, a local description and applicable permission settings. Do not invent extra method fields or rely on internalization to silently obtain missing admission. The wallet independently checks everything its contract requires. Its rejection remains a rejection even after successful application preflight.

For declared deferred receipt, every requested leg must permit that ordering, and the integration MUST establish that the call will not implicitly publish the subject, including through a wallet-payment path. If that cannot be established, use the authorized online path or remain pending; do not invent an internalizeAction.noSend flag. Durably accepted unreserved token units may contribute to available balance under BRC-207 with color_offline; reserved, restricted and pending precedence remains. The user must distinguish deferred value from settled value. Neither a source nor its prospective child may be counted twice. Onward offline spending preserves required evidence and lifecycle.

Offline wallet acceptance may precede settlement, but only under the declared policy. Later explicitly authorized processing reconciles and submits all missing ancestors in dependency order using BRC-207/175 and each companion profile's exact off-chain data. A dependency-aware package request is not proof of acceptance. Remove color_offline only after the required actual admission and dependency/asset checks succeed. Unknown, missing or contradictory requirements cannot be replaced with generic basket insertion or optimistic credit.

Useful durable facts are: delivered/pending, preflight accepted, publication attempted, processor accepted, per-asset admission verified, per-output wallet accepted, receipt complete, deferred settlement, confirmed and failed/uncertain. They are independent facts rather than one linear status: the offline path can reach wallet acceptance first. These are application records, not new BRC-100 public statuses. Confirmation requires independently verified chain evidence.

Partial outcomes, retry and acknowledgments

Preflight the entire subject before any publication. The initial receipt call SHOULD contain every requested output; there is no cross-provider transaction that can atomically roll back Bitcoin, overlays and wallet state. Record an explicit result for every requested outpoint. Receipt is complete only when all requested outputs are wallet-accepted. A successful subset cannot erase failed or pending receipts. If a wallet operation returns uncertain/partial results, reconcile its authoritative records before retrying the remaining authorized outputs; never use retry splitting to bypass bounds or preflight.

Use durable keys (network, recipient wallet/account, txid, outputIndex), with transaction-level publication and per-asset dependency records. Different relay message IDs do not create different assets. Byte-identical replays reuse state; conflicting receipts/evidence for one outpoint require reevaluation and cannot overwrite accepted custody. Persist intents before calls, coordinate concurrent workers, and reconcile exact TXIDs and wallet/processor/overlay evidence after crashes or lost responses. Do not create a new transaction or duplicate balance credit because the previous response was lost.

Transport acknowledgment deletes relay data. Send it only after the complete authenticated delivery is durably held by the receiving application, including pending/unsupported records, or after processing is complete. It is not asset receipt acknowledgment. If storage fails, keep the message queued or report failure; relay retention need not last as long as a never payment. Do not silently discard the only recoverable evidence.

An application MAY send an authenticated asset-status reply to the original deliverer through the same routing convention. Use MIME type application/vnd.metanet.transaction-receipt+cbor, binary transfer encoding, and the same framing/hash requirements. Its exact DAG-CBOR body is:

{ version: 1, txid: bstr(32), deliveryHash: bstr(32), revision: positiveSafeInteger,
  results: [{ outputIndex: uint32,
    state: "pending" | "wallet-accepted" | "rejected",
    settlement: "unknown" | "deferred" | "processing-accepted" | "confirmed" | "failed",
    reason?: tstr }] }

deliveryHash equals the original envelope's plaintext content hash. Include all requested indices once, in increasing order. reason is display-only, at most 2000 UTF-8 bytes. Persist strictly increasing revisions per subject and recipient account; retransmissions use the same revision/bytes. The sender verifies the reply identity is the intended recipient, the hash/indices and revision, and ignores stale replays. wallet-accepted requires actual wallet acceptance; a complete response requires it for every entry. Report deferred acceptance as deferred, never confirmed. Later settlement failure retains the historical acceptance record while updating current availability. A reply reports observations, not independent settlement proof or permission to reclaim. Refusal, silence or an old response cannot free released funding. No sender is entitled to an automatic reply that violates recipient messaging policy; reply delivery uses its own reachability/toll authorization.

Routing and integration

The interoperable BRC-33 box name is transaction-delivery, scoped to the recipient's verified identity at its resolved Message Box. A conforming receiver MUST collect that box. Additional identity-authenticated routing agreements may select other boxes, but absent such an agreement the sender uses this default. There is no new global inbox or unauthenticated endpoint discovery. Preserve the BRC-169 handle/domain/tag in the signed envelope; a tag is organizational input, not an asset basket, authority grant or unverified box override.

For the BRC-33 JSON API, message.recipient is the verified recipient identity, message.messageBox is this box, and message.body is the exact UTF-8 JSON serialization of the BRC-169 JSON envelope. A receiver strictly parses that string, verifies the envelope and checks the route/recipient binding before processing. A binary BRC-169 envelope needs a separately negotiated binary transport such as BRC-231; do not silently convert its signature to JSON. A legacy Message Box body is not automatically a BRC-169 envelope.

Recipient sender-blocks, scope, box permissions, binding quotes, recipient tolls, server pricing, sender spend ceilings, quotas and retention remain effective. An integration with a named-box permission system MUST map BRC-169's verified identity, handle/tag and independent general/per-sender toll semantics explicitly; a server's different precedence rules cannot silently stand in for them. If it cannot enforce the requested policy, fail rather than weaken it. Existing PeerTokenClient / TokenSettlementAdapter implementations are integration points, not evidence of conformance; their adapter must implement these receipts and lifecycle rules.

The outer BRC-169 payment is unchanged. It pays for message delivery, not asset validity or settlement. Its transaction MUST be distinct from the delivered subject and MUST neither conflict with the protected graph nor depend on an unpublished protected member. Settling that payment or its BEEF ancestry must not publish the protected subject, consume its reserved inputs, or defeat receiver choice. Already accepted independent preparation may be shared. BRC-169's outer-toll rules are not authority to reclaim an encrypted inner never payment or to clear released asset exposure.

Security considerations

• Privacy: encryption hides inner receipts from the operator, not outer routing, payment metadata, traffic size, or later public transactions. Lifecycle signer identities and supplied profile evidence are disclosed to the recipient.
• Whole-transaction effect: publishing one output publishes all outputs and dependencies. Auto-accept is bounded by complete preflight and existing consent.
• Evidence boundaries: Bitcoin validity, token admission, ownership, identity, permissions and sender lifecycle promises are separate checks. Trust is not imported from a bundled key, endpoint, symbol, URI or display label.
• Deferred risk: accepted offline value can later fail settlement or lose trust. Correct balances and retain evidence; accounting correction does not undo a published transaction or recover delivered goods.
• Expiry and recovery: neither local deletion nor an acknowledgment retracts signatures. Finite races require reconciliation; released never is permanent sender disposition. Evidence persistence must survive clients and relay queues.

Conformance examples

The executable fixture at media/0169/transaction-delivery.mjs uses public test keys and a synthetic accepted chain root. It generates exact CBOR/MIME bytes, signed content-hash bindings, Atomic BEEF wallet requests and expected responses. It validates serialization, Bitcoin scripts, derivation, subject binding, attestations and selected rejection cases offline. Its fixture chain and configured overlay facts are not live network evidence, and it is not a full wallet implementation or test of arbitrary providers.

The committed delivery vectors contain complete JSON-substrate BRC-100 internalizeAction requests and expected responses for ordinary payments, token value, authority, ISSUE, resources, offline attested value, and a mixed token/resource/satoshi delivery. Each includes the exact subject, MIME/CBOR bytes, encrypted content, authenticated metadata, root lifecycle statements and required profile evidence. The receiver verifies and maps those bytes, performs the stated policy steps, and only then makes the shown wallet call. Expected wallet/overlay outcomes are fixture conditions, not claims of observed processing by a live wallet or overlay.

Run alongside the unchanged BRC-169 regression vectors:

cd peer-to-peer/media/0169
npm ci --ignore-scripts
node vectors.mjs --legacy
node vectors.mjs
node transaction-delivery.mjs

The cases below are independent required behaviors. Unstated Bitcoin, permission and profile checks pass. A success always retains the actual processing facts.

References

• BRC-29, BRC-33, BRC-169: payment and message delivery.
• BRC-42, BRC-43, BRC-78: derivation and encryption.
• BRC-62, BRC-67, BRC-95: Bitcoin evidence.
• BRC-100, BRC-112, BRC-177, BRC-189, BRC-205: wallet interfaces, lifecycle, trust and discovery.
• BRC-161, BRC-162, BRC-176, BRC-207, BRC-209: token and resource contracts.
• RFC 2045, RFC 8949, DAG-CBOR: MIME and encoding.