docs(tokens): draft BRC-165 P1Sat permission scheme

[shruggr]

Summary

• Draft BRC-165: P1Sat permission scheme (BRC-99 scheme id 1sat).
• Storage remains basket 1sat (BRC-147).
• View: listOutputs basket p 1sat <scope> where scope is all | collection | app | creator | id; filter values on ordinary tags (e.g. collection:<txid_vout>, id:<key>). Scope required (bare p 1sat rejected). id lookup does not require grant-all.
• Spend: createAction labels p 1sat input id <key> (BRC-164); per-action approval, not a standing send grant. Pay/auto-pay MUST NOT cover item access.
• Module probe: getPublicKey with [0, "p 1sat"] (cites BRC-98/99/116; no new reject rules).
• Register 1sat in BRC-123; small clarifications on BRC-147 (drop tag aliases; underscore writers for origin/content/collection keys; link 165) and BRC-164 (see-also spend labels).

Authors: David Case; Brandon Cryderman (credit for HandCash item-access prior art and related drafts).

Relationship to #221

Alternative draft to Brandon’s scope-in-basket BRC-165. This version keeps BRC-100 basket charset ([a-z0-9 ]), puts values in tags, and specifies spend labels via BRC-164.

Test plan

• Spec read-through by wallet / 1sat-sdk folks
• Confirm no collision with BSV-21 drafts (BRC-161/162: BSV-21 fungible tokens (JSON + binary) #213 / docs(tokens): BRC-163 BSV-21 basket profile (BRC-46/100) #217)
• Align implementation (@1sat/permission-module scopes already track this draft)

Draft PR for feedback — not ready to merge.

[shruggr]

@GenericCPU Please review. It's pretty close to what you had, but rearranged slightly to bring compatibility with the reference wallet.

[GenericCPU]

Thanks @shruggr — reviewed. Happy to align.

Storage stays 1sat; permission axis in p 1sat <scope>; values in tags. Agreed on pay ≠ item access, per-action spend via p 1sat input id <key>, p 1sat all for full inventory, and app: / creator: as distinct (we may later map app: to a Sigma identity).

On the HandCash side, nothing else is on this contract yet. We’ll update Desktop/Mobile and the app guide to the axis+tags wire, drop value-in-basket and creator→app mapping, and use BRC-164 id spend labels. Then I’ll close or retarget #221.

[Copilot]

Pull request overview

Adds a draft specification for BRC-165 defining the P1Sat permission scheme (1sat) that separates storage (1sat basket) from permissioned view/spend routing (p 1sat <scope> and spend labels), and registers/links it across the repository’s indices and related wallet/token BRCs.

Changes:

• Introduces tokens/0165.md (BRC-165) describing scoped listOutputs view access and per-action spend approval via createAction labels.
• Registers scheme id 1sat in BRC-123 and cross-links spend-label usage from BRC-164.
• Updates BRC-147 and repository indexes (README.md, SUMMARY.md, tokens/README.md) to reference BRC-165 and align tag guidance.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
wallet/0164.md	Adds a cross-reference explaining how BRC-165 uses BRC-164 list keys in spend labels.
wallet/0123.md	Registers the 1sat permission scheme and describes its view/spend semantics at a high level.
tokens/README.md	Adds BRC-165 to the tokens index.
tokens/0165.md	New draft spec defining P1Sat permission scheme behaviors for view and spend.
tokens/0147.md	Clarifies tag/customInstructions encoding guidance and links BRC-165 as the normative permission scheme for 1sat.
SUMMARY.md	Adds BRC-165 to the book summary.
README.md	Adds BRC-165 to the root index table.

Suppressed comments (2)

tokens/0165.md:67

• The module-detection note describes the claimed protocol name as p 1sat, but BRC-98 parsing requires a token after the scheme id (e.g. p 1sat probe). Update the note to match the probe protocol so the spec remains self-consistent and implementers don’t use an identifier that wallets should reject.

* **Protocol claim:** security level **0**, protocol name **`p 1sat`**. Level 0 keeps the probe outside ordinary Level 1/2 protocol-permission UX when the wallet routes it to this scheme’s module ([BRC-43](../key-derivation/0043.md), [BRC-116](../wallet/0116.md)).

tokens/0165.md:58

• The module-detection JSON example uses protocolID: [0, "p 1sat"], but under BRC-98 a p protocol identifier must be p <scheme> <rest> (i.e., include a token after the scheme id). If the probe protocol is meant to be p 1sat probe, this line should reflect that so implementers don’t copy an identifier that conforming wallets would reject.

  "protocolID": [0, "p 1sat"],

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[GenericCPU]

HandCash implementation update: Desktop v1.2.248 and Mobile v0.1.204 now use the axis+tags wire described here. I also closed #221 as superseded.

[shruggr]

Addressed Copilot review:

1. Probe protocol — now [0, "p 1sat probe"] (p <scheme> <rest> per BRC-98).
2. BRC-147 underscore — writers MUST underscore for CI origin/content and outpoint tags; origin-tag rules and examples aligned; readers still normalize either form.

Pushed on this branch.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

tokens/0165.md:37

• BRC-98 requires protocol IDs be of the form p <scheme-id> <rest> (with a space after the scheme id). Claiming the exact protocol name p 1sat is therefore invalid/ambiguous; the concrete probe protocol you define below (p 1sat probe) is the compliant identifier to reference here.

This scheme also claims the [BRC-98](../wallet/0098.md) protocol name **`p 1sat`** (security level **0**). That protocol is used for **module presence detection** and module routing — not as the default key-derivation protocol for new inventory tips. New tip key derivation SHOULD follow [BRC-147](./0147.md) / wallet policy (e.g. plain protocol names such as `onesat`) and is not required to use `p 1sat`.

tokens/0147.md:116

• app: and creator: tags are now explicitly distinct, but customInstructions.app is still described as “Application / creator id”, which reintroduces ambiguity about what value goes where. Align the customInstructions.app description with the updated tag semantics (application id only), or introduce a separate creator field if you intend to carry both.

| `app` | string | MAY | Application / creator id (may mirror an `app:` tag for display). |

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

tokens/0165.md:51

• The PR description mentions probing getPublicKey with protocolID: [0, "p 1sat"], but this spec defines the probe protocol as p 1sat probe (which also matches BRC-98’s p <scheme> <rest> structure). Please align the PR description (and any downstream implementation notes) with the p 1sat probe identifier.

Applications MAY detect whether scheme `1sat` is available by probing a [BRC-98](../wallet/0098.md) protocol under this scheme. Per BRC-98, protocol names are `p <scheme-id> <rest>`; the rest token for this probe is **`probe`**.

tokens/0165.md:71

• “registered” here is ambiguous because this document separately states the BRC-123 registry entry is deferred. Consider using wording like “supported by the wallet / module is available” to avoid confusing BRC-123 registration with wallet-internal module registration.

* **Interpretation:** applications treat probe **success** (on a wallet that uses P-module routing) as evidence that scheme `1sat` is registered, and a **BRC-98/99 unsupported-scheme rejection** as evidence it is not. Bare wallets without a permissions manager may not give a reliable signal; applications SHOULD only enable module-mediated labels/baskets when they expect P-module routing.

tokens/0165.md:36

• The PR description states that scheme id 1sat is registered in BRC-123, but this draft explicitly defers the BRC-123 registry entry because 1sat does not satisfy BRC-123 §3.1’s letter-first scheme-id rule. Either update the PR description to reflect the deferral, or revise BRC-123 / the scheme id so a registry row can be added.

This issue also appears in the following locations of the same file:

• line 51
• line 71

[BRC-123](../wallet/0123.md) registry listing for this scheme is deferred (current §3.1 letter-first scheme ids do not admit `1sat`).

[GenericCPU]

@shruggr Totally fine — please update 147 on this PR. Dual storage is more confusing than helpful; I welcome eliminating the redundancies as long as it doesn’t hurt functionality.

The clear line I’m happy with:

• Tags = filter / query keys only (ordinal, origin:, content:, type:, app:, collection:, creator:, id:). Lowercase-safe alphabet; not display text.
• customInstructions = remittance + case-preserving display (name, provenance, plus the remittance origin / content claims). Not a second copy of the filter vocabulary.

So: deprecate mirroring name / app into both; name: tag stays legacy. Keep origin / content in both only as the intentional split (tag for list/filter when CI isn’t loaded; CI for remittance) — not as “store everything twice.” Readers already normalize.

That matches how HandCash writes today and leaves BRC-165’s axis+tags wire alone. Happy for you to own the 147 wording — not trying to rewrite your article.