Skip to content

docs(147): content + settle tags/CI (defer id: to 164) #216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sirdeggen merged 3 commits into from
Aug 13, 2026
Merged

docs(147): content + settle tags/CI (defer id: to 164) #216

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e95f259
docs(tokens/0147): define content for derivative remittance interop
GenericCPU Aug 10, 2026
98765c2
docs(tokens/0147): motivate content from indexer-scale reality
GenericCPU Aug 13, 2026
81b67be
docs(tokens/0147): settle tags/CI and defer id: to BRC-164
GenericCPU Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 59 additions & 13 deletions tokens/0147.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ It does **not** redefine 1Sat Ordinals origin theory. Offline tip→origin proof

Existing deployments (including HandCash Desktop) already use basket `1sat` with overlapping tags and JSON instructions. This BRC records that convention so independent wallets can interoperate without trusting a single vendor.

Derivative / reference tips make that contract incomplete without a named `content` field. Many children share one on-chain media outpoint (BRC-160 field 3, `text/uri-list`, `ord://`, OrdFS). Wallets that rebuild `customInstructions` from `origin` / `name` / `provenance` alone drop the shared pointer, and the receiver cannot load media peer-to-peer. Indexer fallback is not enough at collection scale: large 1Sat collections (e.g. Pixel Foxes at ~10M items) already find collection-filtered holder queries and related indexer endpoints unusable in practice, while per-origin `/content/{origin}` remains the workable path. Forwarding `content` in remittance is what lets a receiver fetch that body without waiting on an indexer to know the child tip.

## Specification

### Basket identifier
Expand Down Expand Up @@ -53,13 +55,44 @@ Tags are optional BRC-46 / BRC-100 output tags used for filtering and display hi
| Tag | Requirement | Meaning |
|-----|-------------|---------|
| `ordinal` | SHOULD on conforming transfers and imports | Marks the output as an ordinal/inscription tip under this profile. |
| `origin:<outpoint>` | SHOULD when origin is known | Claimed inscription origin (`dot` or `underscore` form). |
| `name:<string>` | MAY | Short display name (implementations SHOULD truncate to ≤ 80 UTF-8 code units when writing). |
| `app:<string>` | MAY | Creator / application id for filtering (SHOULD truncate to ≤ 40). |
| `origin` or `origin:<outpoint>` | SHOULD when origin is known | Claimed inscription origin. Two forms — see rules below. |
| `content:<outpoint>` | SHOULD when the tip is a derivative / reference inscription | Shared media outpoint for display (see `content` below). |
| `type:<type>/<subtype>` | SHOULD when the content type is known | IANA media type of the **origin** inscription (envelope content-type), with parameters removed — the substring before the first `;` (e.g. `type:image/png` from `image/png; charset=binary`). |
| `name:<string>` | MAY (legacy) | Short display name in a tag. New writers SHOULD put display name in `customInstructions` instead (see [Tags vs customInstructions](#tags-vs-custominstructions)). If written, implementations SHOULD truncate to ≤ 80 UTF-8 code units. |
| `app:<string>` | MAY | Application / creator id for filtering (SHOULD truncate to ≤ 40). |
| `collection:<id>` / `collectionId:<id>` | MAY | Collection filter keys (synonyms). |
| `creator:<id>` / `author:<id>` | MAY | Creator filter keys (synonyms of / complements to `app:`). |

Unknown tags MUST be preserved when transporting the output ([BRC-37](../outpoints/0037.md) / BRC-46 spirit). Tag query via `listOutputs` uses existing `tags` / `tagQueryMode` fields.
Rules:

* **Origin tag** — One tag, two forms:
* bare `origin` — this output **is** the origin (mint / chain start).
* `origin:<outpoint>` — this output is a later tip; `<outpoint>` is the chain origin (`dot` or `underscore` form; readers MUST treat both as the same outpoint per [Outpoint encoding](#outpoint-encoding)).
* On self-keep transfer or re-file: if the source has `origin:<outpoint>`, copy that tag unchanged; if the source has bare `origin`, the spent outpoint **is** the origin — write `origin:<spent outpoint>` on the new output.
* The origin tag is a wallet **claim**, not proof of chain membership ([BRC-150](./0150.md)).
* **`type:`** — Describes the origin inscription’s content type, not whatever the current tip’s locking script contains. Self-keep transfers SHOULD copy `type:…` forward with the origin claim rather than re-deriving it from a bare transfer output. Tag matching is exact; there is no prefix or wildcard form.
* **Wallet-local list keys** — Ordinary `id:<key>` tags (stable per-row handles for `listOutputs`) are defined by **BRC-164**, not by this profile. Conforming `1sat` writers MAY stamp `id:` when they adopt that convention. This profile MUST NOT treat `id:` as origin, media, collection, or global asset identity. Receivers MUST ignore a counterparty-supplied `id:` and stamp their own if they adopt BRC-164.
* Unknown tags MUST be preserved when transporting the output ([BRC-37](../outpoints/0037.md) / BRC-46 spirit). Tag query via `listOutputs` uses existing `tags` / `tagQueryMode` fields.

### Tags vs customInstructions

Both tags and `customInstructions` travel with the output under [BRC-46](../wallet/0046.md) / [BRC-37](../outpoints/0037.md). They serve different jobs:

| | **Tags** | **`customInstructions`** |
|--|----------|---------------------------|
| Role | Query and filter keys (`listOutputs` + `tags` / `tagQueryMode`) | Single remittance object: display, optional spend metadata, provenance |
| Case | Wallet storage commonly lowercases tags | JSON string values can preserve case |
| Authority | Non-authoritative claims / local metadata | Same for display fields; spend fields only describe how *this* wallet unlocks the lock; provenance is verified per [BRC-150](./0150.md) |

**Writers SHOULD:**

* Put **filterable** facts in tags: `ordinal`, `origin` / `origin:…`, `type:…`, `content:…` when useful, and when useful `app:`, `collection:…`, `creator:…` (plus `id:…` only per BRC-164).
* Put the human **display name** in `customInstructions.name` when known (case-preserving).
* Put shared media outpoints in `customInstructions.content` (and MAY mirror with tag `content:…`) for derivative / reference tips.

**Writers SHOULD NOT** rely on a `name:` tag as the primary display name. A `name:` tag remains **MAY** so existing deployments stay conforming; new implementations SHOULD prefer CI `name` and MAY omit the tag.

Readers resolving a display name SHOULD prefer `customInstructions.name` when present, and MAY fall back to a `name:` tag.

### Custom instructions ([BRC-37](../outpoints/0037.md))

Expand All @@ -68,24 +101,34 @@ When present for basket `1sat`, `customInstructions` MUST be a **UTF-8 JSON obje
```json
{
"origin": "<txid_vout>",
"content": "<optional shared media txid_vout>",
"name": "<display name>",
"app": "<optional creator/app id>",
"app": "<optional application id>",
"provenance": { }
}
```

| Field | Type | Requirement | Meaning |
|-------|------|-------------|---------|
| `origin` | string | SHOULD | Claimed origin outpoint (underscore form preferred). |
| `name` | string | MAY | Display name. |
| `app` | string | MAY | Creator / application id. |
| `content` | string | SHOULD when known for derivatives | Shared **media** outpoint (underscore form preferred). Used when this tip’s own origin envelope is a reference (e.g. [BRC-160](./0160.md) field 3 parent, or a `text/uri-list` / `ord://` / OrdFS `/content/<outpoint>` body) so receivers can load the one on-chain body without an indexer. |
| `name` | string | SHOULD when known | Display name (case-preserving). Preferred over a `name:` tag. |
| `app` | string | MAY | Application / creator id (may mirror an `app:` tag for display). |
| `provenance` | object | SHOULD on transfer when available | Provenance remittance; v2 in [BRC-150](./0150.md). |

Additional JSON keys are permitted and MUST be ignored by readers that do not understand them. Readers that do not understand `provenance` MUST still store and forward the entire string unchanged ([BRC-37](../outpoints/0037.md)).
Additional JSON keys are permitted and MUST be ignored by readers that do not understand them. Readers that do not understand `provenance` or `content` MUST still store and forward the entire string unchanged ([BRC-37](../outpoints/0037.md)). Spend-derivation fields a wallet uses only for its own unlock (`protocolID`, `keyID`, `counterparty`, …) MAY appear in the same object; they are not part of this profile’s display / provenance contract and MUST NOT be required of receivers.

#### Derivative / reference content

Some tips share one inscription body (many children point at one parent media outpoint). For interop:

1. Senders SHOULD set `content` (and MAY set tag `content:<outpoint>`) when they can resolve the shared media outpoint from the tip’s origin envelope ([BRC-160](./0160.md) field 3, or a reference body as above), or when a prior remittance already carried `content`.
2. On transfer, senders that rebuild `customInstructions` MUST preserve an existing `content` value when they do not replace it with a freshly resolved one.
3. `content` is a **display claim**. It does not change tip→origin authenticity ([BRC-150](./0150.md) still proves the child origin). Receivers SHOULD prefer `/content/<content>` (or OrdFS equivalent) for media when `content` is present and well-formed; otherwise fall back to `/content/<origin>`.

#### Claims vs proof

* `origin`, `name`, `app`, and all tags are **claims**.
* `origin`, `content`, `name`, `app`, `type:`, and all tags are **claims**.
* A wallet MUST NOT treat a claimed `origin` as proven solely because it appears in tags or `customInstructions`.
* Proven tip→origin binding is defined by [BRC-150](./0150.md) (v2). When remittance is absent or fails verification, the wallet MUST treat identity as **unproven** and SHOULD avoid presenting sender-supplied `name` / `app` as authoritative for that tip.

Expand Down Expand Up @@ -124,7 +167,7 @@ Example (non-normative shape):
"satoshis": 1,
"outputDescription": "Collectable transfer",
"basket": "1sat",
"tags": ["ordinal", "origin:<txid.vout>", "name:Example"],
"tags": ["ordinal", "origin:<txid.vout>", "type:image/png"],
"customInstructions": "{\"origin\":\"<txid_vout>\",\"name\":\"Example\",\"provenance\":{}}"
}]
}
Expand All @@ -146,7 +189,7 @@ To place an existing tip into basket `1sat`, use BRC-100 `internalizeAction` wit
"protocol": "basket insertion",
"insertionRemittance": {
"basket": "1sat",
"tags": ["ordinal", "origin:<txid.vout>"],
"tags": ["ordinal", "origin:<txid.vout>", "type:image/png"],
"customInstructions": "{\"origin\":\"<txid_vout>\",\"name\":\"Example\"}"
}
}]
Expand All @@ -173,10 +216,10 @@ Normative fine-grained asset permission schemes remain [BRC-99](../wallet/0099.m

## Security considerations

* **Tag / metadata spoofing** — Without provenance verification, a sender can attach another inscription’s `origin` and `name`. See [BRC-150](./0150.md).
* **Tag / metadata spoofing** — Without provenance verification, a sender can attach another inscription’s `origin` and `name`. See [BRC-150](./0150.md). A forged `content` only mis-points display media; it does not prove tip→origin.
* **Basket pollution** — Placing non-1-sat or non-ordinal outputs in `1sat` confuses list UIs; receivers should re-check `satoshis` and inscription rules.
* **Burn** — Per 1Sat Ordinals, packing a sat into a multi-sat output ends that origin trail. Do not continue `origin:` claims across a burn.
* **Indexer trust** — Display media URLs and collection metadata often come from indexers; this profile does not make indexers authoritative for tip→origin binding.
* **Indexer trust** — Display media URLs and collection metadata often come from indexers; this profile does not make indexers authoritative for tip→origin binding. Forwarding `content` reduces indexer dependence for derivative media.

## Implementations

Expand All @@ -194,3 +237,6 @@ Normative fine-grained asset permission schemes remain [BRC-99](../wallet/0099.m
7. [BRC-99](../wallet/0099.md) — P Baskets (reserved permission schemes)
8. [BRC-100](../wallet/0100.md) — Unified Open BSV Wallet-to-Application Interface
9. [BRC-150](./0150.md) — 1Sat Provenance Remittance for Basket `1sat`
10. [BRC-160](./0160.md) — 1Sat Ordinals — Inscription Envelopes
11. BRC-164 — Output Identity Tags for BRC-100 Wallets (`id:` list keys; not defined by this profile)
12. 1Sat reference inscriptions — <https://docs.1satordinals.com/reference-inscriptions>