Add BRC-300: Sponsored Onboarding and Wallet Choice (supersedes #223)

[vincemedia]

Supersedes #223, which I am closing in favour of this.

Thank you

@deggen raised this in review, and it was the best objection the document has had:

A serious security attack vector in this proposal is that I can buy a prominent spot to gather a userbase to my wallet software which may be malware of some sort which waits for weeks before rugging the users all at once.

It was correct. Checking it against the text, the entire defence turned out to be one clause buried in the Security Considerations, saying choosers "MUST resolve install targets against the catalog" and "SHOULD pin vendor identity keys". Meanwhile section 4.4's offer carried the full wallet object, so a sponsor supplied its own name, icon, description and install target; section 4.3.8's eligibility list was purely economic and never looked at the wallet; and section 8.3.3 let a house exclude a site with no equivalent for a sponsor.

Two things make it worse than the objection stated, and both are now in the document.

The ranking rule selects for the attacker. An honest vendor's bounty is bounded above by what a customer is worth to it. A vendor intending to steal is bounded by what it expects to steal, which scales with everything those users will ever hold. So it outbids honest competitors at every auction, and section 4.3.1 forbade the house from considering anything else. The quantity this document ranks on correlates with intent to defraud. No sorting rule fixes that, because the problem is who gets into the set being sorted.

The retention mechanism certified the attack. Section 7.5 pays a site when the funded key is still transacting ~30 days later. A patient attacker's victims satisfy that perfectly, so the machinery built to prove quality paid sites for delivering them and stamped the settled record retained.

What changed

The governing principle, now stated outright in 4.3.8: the auction re-orders an already-vetted set and never admits to it. Money buys position among vetted wallets. It never buys entry.

1. Catalog listing is a precondition of bidding (4.3.8 condition 10). A campaign's wallet must already be in the catalog serving that site's unsponsored slots, and the catalog entry must agree with the campaign on vendor, name and platform support. The sponsored and unsponsored halves of a chooser now clear the same bar.
2. The offer names a wallet; it cannot describe one (3.2.1, 4.4.2). The wallet object is gone from the offer, replaced by vendorKey and walletName. Every card field is read from the catalog entry. There is no longer any field in which a sponsor could ship its own icon, description or install target, which is the same move as the closed schema of 4.4.9 applied to content rather than styling.
3. The sponsor key must be attested at the vendor's own domain per BRC-68 (4.3.8 condition 11). An anonymous sponsor cannot bid.
4. A house can stop serving a sponsor, and a catalog can delist the wallet (8.3.5), symmetric with the existing site rule. Delisting is the effective remedy, because condition 10 means a wallet out of the catalog cannot be bid for anywhere.
5. Retention is not a safety signal (7.5.5). No party may present a retained outcome or a paid share as evidence a wallet is safe, and a catalog may not use retention as an admission or ranking criterion.
6. Sponsorship is not endorsement (3.5.5). The disclosure expansion must now say the site is not vouching for the wallet.
7. The adverse selection is named, in the Security Considerations, in 8.5 as a third thing the design does not prevent, and in the ledger, which gains a row reading "the wallet in a sponsored slot was vetted by somebody — Asserted".

What this still does not fix

Stated plainly in the document rather than left for the next reviewer.

A wallet vetted honestly and turned malicious a year later passes every check here. The remedy is delisting, and catalog governance is not specified by this document and only sketched in BRC-137 section 3. Section 9 now lists it as unspecified and explains that it is load-bearing rather than a tidy-up: who may list a wallet, on what evidence, who may delist and how fast, and how an exclusion propagates between catalogs. The security of the sponsored half of every chooser rests on a standard nobody has written yet, and that is probably the strongest argument for writing one.

The bounty also makes the attack cheaper to run, since the attacker pays its victims to install with money it expects to recover from them. That is inherent to paying people to onboard and is not solvable inside this design.

Verification

98 checks to 100, still no third-party imports and no network.

cd apps/0300-vectors && python3 verify_vectors.py

The two new checks assert that the offer's canonical form carries no card content and does name a wallet instead. Appendix A.4 was regenerated and now reads the absence off the canonical form directly.

Re-review

@deggen would you take another look? Points 1, 2 and 4 are the ones that answer your objection directly, and I would particularly value your view on whether making catalog listing a hard precondition is the right containment or whether it just relocates the trust problem into a document that does not exist yet. I think it relocates it honestly, but you found the last thing I was wrong about.

🤖 Generated with Claude Code

[vincemedia]

@deggen re-review request, and thank you.

Your objection was right and it was the most useful thing anybody has said about this document. The defence I thought was there turned out to be one clause in the Security Considerations, while section 4.4's offer happily carried a sponsor-supplied name, icon, description and install URL, and section 4.3.8's eligibility list never looked at the wallet at all.

Three changes answer you directly:

• 4.3.8 conditions 10 and 11 make catalog listing and a BRC-68 domain-attested sponsor key preconditions of bidding. Money buys position among vetted wallets, never entry.
• 3.2.1 and 4.4.2 strip card content out of the offer entirely. It now carries vendorKey and walletName and nothing else about the wallet, and every field on the card is read from the catalog entry, so there is no field left in which a sponsor could ship its own icon or install target.
• 8.3.5 lets a house stop serving a sponsor and a catalog delist the wallet, which the previous revision allowed for sites and not for vendors.

Two things your objection implied that I have also written down. The ranking rule selects for the attacker, because a thief's willingness to bid is bounded by what it expects to steal while an honest vendor's is bounded by customer value, so the quantity the auction sorts on correlates with intent to defraud. And section 7.5's retention share would have paid sites for delivering victims, since a patient attacker's users satisfy the retention condition perfectly; 7.5.5 now forbids treating retention as a safety signal.

The question I would most value your view on: making catalog listing a hard precondition contains the attack, but it relocates the trust into catalog governance, which this document does not specify and BRC-137 only sketches. Section 9 item 3 now says so explicitly. Is that honest containment, or have I just moved the hole somewhere nobody is looking?

[sirdeggen]

It's a good question. Let's discuss at length because there's been talk in the past about hiring a company to audit wallet providers and then certifying them as the BSVA as having met BRC-100 and IT sec standards. There's also potential to limit things to ISO certified IT sec standards companies or something like that. It does move the problem elsewhere, but that was the point I think. The design of an anti manipulation / credibility system is likely a whole BRC of its own.

[sirdeggen]

merge blocked by the substantial conformance vector code in the PR. Ideally BRCs should remain documentation / idea explainers rather than code to run, that should move to its own repo and we can link to it from the BRC document please.

[vincemedia]

@sirdeggen done, and thank you: the PR is now two files, apps/0300.md and the standards-table row. Nothing executable.

The vectors have moved to their own repository at https://github.com/vincemedia/brc-conformance, under brc-300/, and the Implementations section links there. They are run against a checkout of this repository rather than shipping a copy of the document, so the two cannot drift:

python3 verify_vectors.py path/to/apps/0300.md

I have also written your reasoning into the document rather than just complying with it, because it is the better position and worth stating where an implementer will see it: a standards repository that accumulates executable code acquires a maintenance surface nobody signed up for, and a reader then has to work out whether the code or the prose is normative. The document says plainly that it is normative and the vectors are a check on it, and that where the two disagree the code has the bug.

Two notes for the record.

The conformance repository is under my account for now. If the BSVA would rather it sat in the organisation, or alongside the other reference implementations, say the word and I will move it and update the link.

And an apology: my earlier re-review request tagged @deggen, which is somebody else entirely. Sorry to whoever that is. You clearly saw it anyway, but I should have checked the handle.

On your other comment, about auditing and certifying wallet providers: I agree that is a whole BRC of its own, and section 9 item 3 now says as much in the document. Making catalog listing a precondition of bidding contains the malicious-vendor attack by relocating the trust into catalog governance, which BRC-137 only sketches, so the sponsored half of every chooser currently rests on a standard nobody has written. I would rather that gap be named in the text than discovered later. If the BSVA does pursue an audit-and-certify scheme, that is exactly the thing section 4.3.8 condition 10 would point at.