XAS-007d: On-Ledger NFT Metadata via Remarks (xahau-nft-remark/v1)

[zgrguric]

Title: On-Ledger NFT Metadata via Remarks
Type: Standards Track — Convention
Author: XRPLWin, Cody (cbot)
Created: 2026-08-25
Category: Application
Requires: `Remarks` amendment
Amendment required: No. This is a convention over existing ledger features.
                    It changes no transactor, adds no field, and gates on nothing.

---

Status of this draft

xahau-nft-remark/v1 is already deployed on Xahau mainnet. This document
writes down what is in use and proposes a small extension mechanism on top.

The reference token throughout is an Odin's Eyes Raven, issued by
rodinGM9xiKq7rDDnLPyieREkqGJ6zKyb, URIToken
EEF55FAE…227C1351.
Everything in §1–§4 was read off that object and verified, including its image
checksum.

Observed in production	§1 the schema remark; §2 the . fragment separator and numeric ordering; §3 the meta family; §4 the img family with mime/parts/sha256; the s key by which a payload names its own type; the remarks:<family> reference scheme.
Proposed here	§3.1–§3.2 the mutable meta2 overlay and its merge rules; §5 the # separator for sets; §6 declaring families governed by other standards; §9 a companion standard using both. None of it is required to read any token minted so far.

Where this document and deployed practice disagree, practice is correct and this
document should be corrected.

---

Abstract

Xahau's Remarks amendment lets a URIToken carry key/value annotations on the
ledger object itself. This proposal defines a convention for using them to hold
an NFT's complete metadata — including its image — on-ledger, with no
off-ledger fetch required to render the token.

It specifies how a value larger than one remark is split and reassembled, how
binary content is carried and integrity-checked, how a reader identifies what it
is looking at from the remark name alone, and how a token may declare annotations
governed by other standards.

It also proposes a split between immutable identity and mutable state (§3.1), so
that a token's attributes can evolve without giving up the guarantee that the
parts an issuer promised at mint cannot be quietly rewritten afterwards.

§9 describes a companion standard, xahau-nft-signature/v1, which records
third-party endorsement of a token in a way that does not rest on the issuer's
word — the first concrete use of the extension mechanism proposed here.

---

Motivation

A URIToken's URI field is a pointer, and conventionally everything a wallet
wants to display sits behind it. That makes every rendering of the token a
request to somebody's web server, and tokens outlive web servers. IPFS moves the
problem rather than solving it: content addressing guarantees that what you fetch
is what was pinned, not that anyone is still pinning it.

Remarks allow the alternative: the metadata and the image live in the ledger
object. A Raven's thumbnail is 6,506 bytes of WebP stored across 26 remarks, and
rendering it requires nothing but a ledger read.

Three problems follow immediately, and this standard exists to answer them:

1. A remark value holds 256 bytes, so anything larger must be split — and a
   reader must know that img.0 … img.25 are fragments of one file rather than
   26 separate things.
2. A ledger object holds only 32 remarks. The Raven uses all 32. The budget
   is real and shared between metadata, image and anything else.
3. A reader meets names it has never seen. Without a structural rule, an
   explorer can only render unknown remarks as opaque blobs — or worse, mangle a
   split value by rendering its fragments as separate documents.

---

Rationale

Why a schema remark. One place declares what the object as a whole follows,
so a reader knows what it is holding before parsing anything, and knows how many
fragments to expect before reassembling.

Why raw bytes rather than base64 for binary families. A remark value is a
blob; it does not need text encoding. Base64 would cost 33% more, and at 256
bytes per remark against a 32-remark ceiling, a third of the budget is a third of
the image.

Why sha256 in the descriptor. Reassembly is the one place this convention
can go silently wrong — a missing fragment, a mis-ordered one, an off-by-one on
the last. A checksum turns "the image renders as garbage" into a check that
either passes or does not. It is verified on the Raven and matches exactly.

Why numeric rather than lexical fragment ordering. Indices are not zero
padded in production (img.2 and img.10 both exist). Sorting those as strings
puts img.10 before img.2 and corrupts the file. This is a conformance trap
worth stating loudly, because a lexical sort produces a plausible-looking result
that is wrong only in the middle.

Why the separator grammar belongs to this standard rather than to each
extension. If every extension chose its own separator, a generic reader would
need to know every extension to parse any name. Reserving the grammar centrally
lets a reader that knows only this document split any name into
(family, kind, index), group fragments, count members, and correctly present
what it cannot interpret.

---

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

1. The schema remark

A token following this standard MUST carry a remark named schema whose value is
a UTF-8 JSON object. From the reference token, verbatim:

{
  "std": "xahau-nft-remark/v1",
  "meta": { "parts": 5 },
  "img": {
    "mime": "image/webp",
    "parts": 26,
    "sha256": "516BDE7EB6B9FFA4B0331EED75C341F0C1D5110B01665EE24F9AD5510F8CB348"
  }
}

Key	Required	Meaning
std	yes	Exactly xahau-nft-remark/v1.
meta	if metadata present	Descriptor for the meta family (§3).
meta2	if a mutable overlay is present	Descriptor for the meta2 family (§3.1).
img	if an image is present	Descriptor for the img family (§4).

Every other top-level key is a family descriptor (§6). A reader MUST ignore
top-level keys it does not recognise, so a later revision can add core families
without breaking existing readers.

2. Remark names and fragment ordering

A remark name is one of:

<Family>              singleton  — one remark, complete on its own
<Family>.<N>          split      — fragment N of one value
<Family>#<NN>         set        — instance NN, each complete on its own   (proposed, §5)

. and # are reserved as separators. A family name MUST NOT contain
either. A reader determines the family by splitting the name at its first
separator; a name with no separator is a singleton.

For split families:

• <N> is a decimal index starting at 0, ascending, with no gaps.
• Indices are not zero padded in existing practice. Readers MUST order
  fragments numerically, not lexically. Lexical ordering places img.10 before
  img.2 and silently corrupts the reassembled value.
• Fragments are byte sequences, not independently valid documents. A reader MUST
  NOT attempt to parse one alone. Fragments are filled to the 256-byte remark
  limit, so a boundary falls wherever 256 bytes lands — mid-character, mid-token,
  anywhere.
• The value is the concatenation of fragments in index order, with no separator
  or padding between them.
• The descriptor's parts MUST equal the number of fragments present. A reader
  finding a mismatch MUST treat the value as incomplete rather than use what it
  has.

3. The meta family

A split family whose reassembled value is a single UTF-8 JSON object.

The object SHOULD name its own type with an s key, so it is interpretable
without reference to the schema remark. Both deployed collections do this
(odinseyes.raven.license/v2, xahaucards.card/v1).

Beyond s, the content of the metadata document is out of scope here — this
standard defines the envelope, not what an application puts in it. Fields
observed in production, offered as convention rather than requirement:

Field	Notes
name	Display name.
desc	Longer description.
image	Primary artwork. May be ipfs://, https://, or remarks:<family>.
thumbnail	Smaller representation. The Raven sets this to remarks:img.
attributes	Array of {"trait_type": …, "value": …}.

The remarks:<family> reference scheme. A metadata field MAY reference a
family carried on the same ledger object by the pseudo-URI remarks:<family> —
for example "thumbnail": "remarks:img". A reader resolves it by reassembling
that family from the same object. This is what lets a token point at its own
on-ledger image without naming a host.

s versus std. The schema remark declares itself with std; the
payloads it describes use s. This asymmetry is existing practice and is
recorded here so implementations match what is deployed.

3.1 meta2 — a second metadata family (proposed)

A token MAY carry a second metadata family, meta2, with the same split rules as
meta. A reader that finds both MUST merge them (§3.2) to obtain the token's
full metadata.

The point of the split is not size — a single family can already be split
across as many fragments as the budget allows. It is mutability: two families
can be flagged differently, and that is the only thing one family cannot do.

meta and meta2 are otherwise identical. Neither is inherently the fixed one.
Which is which is declared per family and enforced by the remark flags, not by
the name — an issuer may make meta mutable and meta2 immutable if that suits
how the token is written, and readers MUST NOT assume otherwise.

When a second family is needed

meta	meta2	Result	Verdict
immutable	absent	Everything fixed at mint	Default. What is deployed today.
mutable	absent	Everything rewritable	Valid. A second family adds nothing — there is no fixed half to protect.
immutable	mutable	Fixed identity, rewritable state	The evolution case.
mutable	immutable	Rewritable bulk, fixed core	Equivalent to the row above with the halves reversed. Legal; the flags say which is which.
immutable	immutable	Two fixed halves	Legal but redundant — one meta with more fragments does the same. Justified only to stage writes across separate transactions.
mutable	mutable	Two rewritable halves	Legal but redundant — equivalent to one mutable meta.
absent	present	Metadata in meta2 alone	Discouraged. A token with one metadata family SHOULD name it meta. Readers MUST still handle it.

The rule the table encodes: a second family earns its place only when the two
halves differ in mutability. In every other case it is a more complicated way
to write one family, and complication in an immutable record is not free.

An issuer choosing which half a field goes in is choosing whether to guarantee
it. There is no way to have both, and pretending otherwise is the failure mode
§3.2 exists to prevent.

Declaring it

{
  "std": "xahau-nft-remark/v1",
  "meta":  { "parts": 2 },
  "meta2": { "parts": 1, "mutable": true }
}

mutable: true SHOULD be present on whichever descriptor describes a rewritable
family — meta, meta2, or in the redundant cases both. It tells a reader that
the merged result contains issuer-rewritable content before it has looked at a
single remark flag. Its absence means the family is fixed.

parts for a mutable family is a reserved maximum, not a count. This is a
consequence of schema being immutable: a descriptor written at mint cannot be
updated later, so a meta2 that grows from one fragment to two would leave
parts permanently wrong. Therefore, for a family declared mutable:

• parts is the largest number of fragments the issuer has reserved.
• A reader MUST count the fragments actually present and use that, and MUST NOT
  treat a count below parts as incomplete.
• Fragments MUST still be contiguous from 0. A gap is incomplete, as in §2.

An issuer SHOULD reserve more parts than it currently needs. Once minted, the
reservation cannot be raised, and remarks not yet written still count against the
32-remark ceiling only when they are written — so reserving costs nothing until
used.

3.2 Merge rules (proposed)

Under-specified merging is worse than no merging: two explorers would show
different traits for the same token and both would believe they were right. The
rules are therefore narrow and total.

Let M be the parsed meta object and O the parsed meta2 object. The rules
are symmetric: nothing below depends on which of the two is mutable.

1. Top-level keys are combined. The result contains every key from M and
   every key from O.
2. A key MUST NOT appear in both, with the sole exception of attributes.
   An issuer wanting a field to be changeable puts it in O and not in M.
3. attributes concatenates, M first, then O.
4. A trait_type MUST NOT appear in both M.attributes and O.attributes.
5. s is taken from meta, positionally — not from whichever half happens
   to be immutable. If only meta2 is present, from meta2.

There is deliberately no precedence rule, because rules 2 and 4 mean no conflict
can arise. That is the whole design: a mutable family may only add, never
override. Any precedence rule would mean a field in the fixed half could be
silently replaced by the rewritable one, which would make the fixed half's
immutability worthless — an issuer could promise "Legendary" immutably at mint
and overwrite it the next day.

A reader encountering a violation of rule 2 or 4 MUST treat the token as
malformed and SHOULD present the immutable half alone rather than guess. Displaying a
merged result from a token that broke the rules is displaying something the
standard cannot vouch for.

Distinguishing halves after merge

A reader that merges MUST retain which half each field came from, and SHOULD make
that visible wherever the distinction could matter to someone making a decision —
a marketplace listing above all. A trait the issuer can rewrite tomorrow and a
trait fixed at mint look identical after a naive merge, and a buyer paying for
the second while receiving the first has been misled by the reader, not by the
issuer.

On the name. A semantic name — state, mut — was considered and
rejected. Both presume what the second family holds and which of the two is
rewritable, and neither is true: mutability is declared per family and either
may be the fixed one. meta2 claims only that it is the second metadata
family, which is the only thing that is always so.

The cost is that meta2 sits one character from meta.2, and §2 gives . a
specific meaning. Readers split names at the first separator, so meta2 has
no separator and is a family name in its own right while meta.2 is fragment 2
of meta — unambiguous by the rules, but close enough on the page to be worth
stating outright.

4. The img family

A split family whose reassembled value is raw binary — the image file
itself, not base64 and not hex.

Descriptor key	Required	Meaning
mime	yes	IANA media type, e.g. image/webp.
parts	yes	Fragment count.
sha256	SHOULD	Uppercase hex SHA-256 of the reassembled bytes.

A reader that finds sha256 present MUST verify it after reassembly and MUST NOT
present the image if it does not match. A mismatch means a fragment is missing,
mis-ordered, or altered — all of which otherwise produce a corrupt image rather
than an error.

Verified against the reference token: 26 fragments (25 × 256 bytes + 106),
6,506 bytes total, beginning RIFF….WEBP, SHA-256
516BDE7E…F8CB348 — matching the descriptor exactly.

This family is a template for any binary payload. A future audio or model
family SHOULD follow the same descriptor shape.

5. Sets: the # separator (proposed)

Reserved so that repeated, independent annotations have a
form distinct from fragments.

CardSignature#00
CardSignature#07

Each member is complete on its own; the number identifies which member, not
which piece. Losing img.7 destroys an image; losing CardSignature#07 loses
one annotation and nothing else. A reader can tell these two situations apart
from the name alone, which is the entire point of a distinct separator.

Members are unordered. Zero padding to a fixed width is RECOMMENDED so names sort
correctly and so implementations parsing at fixed offsets — a hook, for instance
— need no variable-length handling.

# is chosen because it cannot appear in a family name, is never escaped in
JSON, and is never trimmed or collapsed in transit. Implementations placing these
names in URL paths should note it requires %23 there.

6. Families governed by other standards (proposed)

A family defined by this standard (meta, img) needs no std in its
descriptor — this document defines it. A family governed by another standard
declares that standard:

{
  "std": "xahau-nft-remark/v1",
  "meta": { "parts": 5 },
  "img":  { "mime": "image/webp", "parts": 26, "sha256": "…" },
  "CardSignature": { "std": "xahau-nft-signature/v1" }
}

The presence of std in a descriptor is what distinguishes an external family
from a core one. A reader MUST ignore descriptors naming standards it does not
implement, and MUST ignore keys inside a descriptor it does not recognise.

A descriptor MAY carry form (one, split, set) to declare shape without
requiring the reader to know the governing standard. It is redundant with the
separator in the names themselves and is OPTIONAL.

Declaration is advisory, never authoritative. The schema remark is written
at mint and is immutable, so every declaration is a forward statement about data
that may not exist yet — and a standard invented after a token was minted can
never be declared on it. Therefore:

• A reader MUST NOT require a declaration in order to parse a family. Values are
  self-describing via their own s key, so an undeclared family remains readable.
• Where a declaration and a value disagree about which standard applies, the
  value is authoritative. It was written later, by the party doing the work.

A descriptor MUST NOT reference a schema off-ledger. A URL would make an
immutable record depend on a host that can vanish, defeating the purpose.

7. Immutability

Remarks defined by this standard SHOULD be written with tfImmutable, with one
deliberate exception: a family declared mutable: true (§3.1) exists precisely
to be rewritable and MUST NOT be flagged immutable.

The mistake is unrecoverable in one direction only, which is worth knowing before
minting. A family flagged immutable can never be made mutable — the flag cannot
be cleared — so an issuer that intended an evolving half and flagged it by
accident has a token that can never evolve. The reverse is recoverable: a family
left mutable by accident carries no guarantee, but nothing stops the issuer
writing what it meant to write.

The declaration and the flags MUST agree. A descriptor claiming mutable: true
on remarks that are flagged immutable is malformed, and a reader SHOULD trust the
flags over the declaration — the flags are what the ledger enforces.

Practice currently differs and implementers should know it: XahauCards writes all
remarks immutable; the reference Raven writes none of them so
(Flags: 0 on all 32). An issuer retains the ability to rewrite any remark it
did not flag, on a token someone else owns, for as long as that token exists.

Note the limit of the guarantee: a flagged remark cannot be changed or removed,
but the set of remarks on an object is not closed. An issuer can always add
new ones. That is what makes post-mint extension possible (§6), and it is a
standing capability implementations SHOULD disclose rather than leave implicit.

8. Limits and budget

Remarks per ledger object	32 — rejected at preflight, and as tecTOO_MANY_REMARKS
Remark value	256 bytes
Owner reserve added by remarks	none — a URIToken carrying 32 remarks leaves its holder's OwnerCount unchanged

The 32-remark budget is the binding constraint of this standard, and it is
shared. The reference Raven spends 1 on schema, 5 on meta and 26 on img —
all 32. It has no room for any further annotation, ever, because remarks cannot
be removed once immutable and the object cannot hold more.

Issuers SHOULD budget deliberately: an image large enough to fill the object
forecloses every future extension of that token. A smaller thumbnail on-ledger
with full-resolution art addressed elsewhere — which is what the Raven's
image/thumbnail split does — preserves room.

Implementations writing a remark to an object whose contents they do not fully
control SHOULD check the current count first. An emitted transaction that exceeds
the cap fails in a later ledger, after the originating transaction has already
reported success.

9. Companion standard: xahau-nft-signature/v1

A separate standard, proposed alongside this one and summarised here
because it is the first user of §5 and §6, and because the mechanism is easier
to judge against a concrete case than in the abstract.

The problem it solves

Everything in a remark is written by the token's issuer. That is fine for
metadata — the issuer is the natural authority on what its own token is called —
but it breaks the moment a remark makes a claim about somebody else. A remark
reading "endorsed by Alice" is the issuer asserting something about Alice, and
the issuer could write it whether Alice ever agreed or not.

Remarks alone therefore cannot record third-party endorsement. Anything built
naively on them records the issuer's word and dresses it as somebody else's.

The mechanism

Alice sends her own transaction referencing the token. The issuer then writes
a remark recording who endorsed it and, critically, the hash of that
transaction. Any reader can fetch it and read its Account field directly.

The remark is an index. The proof is the endorser's own transaction.

The issuer can still write a remark naming Alice without her involvement — but it
cannot produce a validated transaction signed by her, so the claim fails the
moment anyone checks.

Shape

A set family (§5), because a token may carry several independent
endorsements, each complete on its own. The family name is the implementation's
choice, declared per §6:

"CardSignature": { "std": "xahau-nft-signature/v1" }

Each member's value:

{"s":"xahau-nft-signature/v1","by":"rEndorserAddress","tx":"<64 hex>"}

Field	Meaning
s	Exactly xahau-nft-signature/v1.
by	The endorsing account, as an r-address.
tx	Hash of the endorser's transaction, 64 uppercase hex.

Roughly 113 bytes — one remark, no splitting. Members SHOULD be written with
tfImmutable: an endorsement the issuer can rewrite is not an endorsement.

Verification

A reader MUST NOT treat the remark as proof by itself:

1. Fetch the transaction named by tx.
2. Check it is validated.
3. Check its Account equals by.
4. Check it references this token — by whatever means the endorsement flow
   uses.

Steps 1–3 make the record trustless. Step 4 stops an unrelated transaction by the
same account being presented as an endorsement of this token. A reader skipping
these and rendering by as an endorsement is displaying the issuer's claim as
though it were the endorser's — the exact failure the standard exists to prevent.

What it does not establish

That by is any particular person. Binding an account to a human identity is
outside this standard and outside any on-chain mechanism: it rests on the account
being publicly known, or on an xrp-ledger.toml at the account's Domain.
Implementations SHOULD NOT imply more certainty than they have.

Why it belongs in this discussion

It exercises both proposed additions and shows what they are for. §5 gives it a
name form that says "each of these is whole" rather than "these are fragments",
so a reader that has never heard of endorsements still handles the remarks
correctly. §6 lets a token advertise the family without the standard having to
exist when the token was minted — which matters, because tokens outlive the
standards written for them.

---

Backwards Compatibility

No amendment, no gating, no transactor change. Nodes require no change.
Tokens not following this convention are unaffected.

For readers:

• A token with no schema remark is not following this standard. A reader SHOULD
  render what it can and MUST NOT fail.
• Tokens minted before §5 and §6 existed carry neither sets nor external family
  declarations. They remain fully readable under §1–§4.
• Adding # as a separator conflicts with nothing deployed: production tokens
  use . and no other separator.

---

Security Considerations

Remarks are the issuer's writing. Everything in them is an assertion by the
issuer, including assertions that appear to concern third parties. A remark
reading "endorsed by Alice" is the issuer's claim, not Alice's. Standards
recording third-party involvement MUST provide verification that does not rest on
the issuer — xahau-nft-signature/v1 does this by recording the hash of the
endorser's own transaction, which any reader can fetch and check.

Metadata is untrusted input. name, desc and trait values are arbitrary
issuer-supplied strings. Readers MUST escape them before rendering and MUST NOT
interpolate them into markup, shell commands, or SQL.

Binary families are untrusted content. img bytes are attacker-influenced to
whatever extent the issuer is untrusted. Readers SHOULD decode them in a
hardened path, SHOULD NOT trust the declared mime over content sniffing for
security decisions, and SHOULD enforce a size bound before decoding. Verifying
sha256 proves integrity — that the bytes are the ones the issuer committed to.
It proves nothing about safety.

Reassembly is a parsing surface. Enforce the declared parts and a total
size bound before concatenating or parsing.

Off-ledger references degrade the guarantee. image fields pointing at
ipfs:// or https:// reintroduce the liveness dependency this standard exists
to remove. That is a legitimate trade for full-resolution art, but a reader
SHOULD NOT present off-ledger content as though it carried the same permanence as
on-ledger content.

Immutability is a claim to verify, not assume. Check the flags rather than
trusting that the issuer set them — deployed practice varies (§7).

A merged view hides who can change what. After merging meta and meta2
(§3.2) every field looks alike, but half of them are rewritable by the issuer at
will. A reader that presents the merged result without distinguishing the halves
is showing a buyer guarantees the token does not carry. This matters most exactly
where money changes hands: a marketplace displaying a rewritable trait as though
it were fixed at mint has misled the buyer, and the issuer never had to lie to
achieve it. Readers MUST retain provenance through the merge (§3.2).

Neither half may override the other. Rules 2 and 4 of
§3.2 forbid a key or trait_type appearing in both halves, and that prohibition
is load-bearing rather than tidiness: a precedence rule allowing meta2 to win
would let an issuer promise anything immutably at mint and replace it the next
day, making meta's immutability worthless. A reader finding a collision MUST
treat the token as malformed rather than resolve it.

---

Test Plan

Names and ordering

• A singleton, a split family and a set family are classified correctly from the
  name alone.
• Fragments with unpadded indices (img.2, img.10) reassemble in numeric
  order. A lexical sort must fail this test.
• A gap in indices is treated as incomplete.
• parts disagreeing with the fragments present is treated as incomplete.

Metadata

• Multi-fragment meta reassembles and parses as JSON.
• Single-fragment meta (parts: 1) is handled.
• remarks:<family> in a metadata field resolves against the same object.

Mutable overlay

• meta and meta2 merge per §3.2; attributes concatenate in order.
• A key present in both halves is rejected as malformed, not resolved.
• A trait_type present in both halves is rejected as malformed.
• A meta2 with fewer fragments present than parts reserved is treated as
  complete, not truncated.
• A meta2 rewritten between two reads yields the new value on the second.
• The merged result reports which half each field came from.
• A token with meta mutable and meta2 immutable merges identically to the
  reverse — a reader keying off the family name rather than the flags fails this.
• A descriptor claiming mutable: true over immutable remarks is reported as
  malformed, with the flags believed over the declaration.

Binary

• img reassembles to bytes whose SHA-256 matches the descriptor.
• A deliberately mis-ordered or truncated reassembly fails the checksum and is
  not presented.

Extensions

• An undeclared external family is readable from its value's own s.
• An unrecognised descriptor, and an unrecognised key within one, are ignored
  rather than fatal.
• Where declaration and value disagree, the value wins.

Limits and flags

• Writing a 33rd remark is refused.
• Remark flags are read back and reported accurately.

§1–§4 can be tested against any Raven on mainnet. §5, §6 and §9 have no production
deployment yet; an implementer adding them should expect to write the live cases
themselves, asserting on what the ledger holds after the fact rather than only on
transaction results — a remark that never landed and a remark that landed wrong
both leave a successful transaction behind.

---

Appendix A: the reference token, walked

URIToken EEF55FAE…227C1351, issuer rodinGM9xiKq7rDDnLPyieREkqGJ6zKyb,
URI = odinseyes:raven:v2:0007011f. 32 remarks: schema, meta.0–meta.4,
img.0–img.25.

schema   {"std":"xahau-nft-remark/v1","meta":{"parts":5},
          "img":{"mime":"image/webp","parts":26,
                 "sha256":"516BDE7EB6B9FFA4B0331EED75C341F0C1D5110B01665EE24F9AD5510F8CB348"}}

1. Read schema. Declares xahau-nft-remark/v1, metadata in 5 fragments, a
   WebP image in 26.
2. Reassemble meta. Sort meta.0…meta.4 numerically, concatenate →
   1,158 bytes of UTF-8 JSON. It declares "s":"odinseyes.raven.license/v2" and
   carries name, desc, attributes, and a render block describing how the
   full-resolution art is deterministically reproduced from the traits.
3. Reassemble img. Sort img.0…img.25 numerically — lexical ordering
   corrupts this file — and concatenate → 6,506 raw bytes beginning
   RIFF….WEBP. SHA-256 matches the descriptor.
4. Resolve references. "thumbnail":"remarks:img" points at the family just
   reassembled. "image" points at IPFS for the full-resolution render.

The token renders completely from a single ledger read. The IPFS reference is an
enhancement, not a dependency.

Appendix B: a token using §5, §6 and §9

XahauCards, Xahau testnet — the same envelope carrying an external family:

schema            {"std":"xahau-nft-remark/v1","meta":{"parts":2},
                   "CardSignature":{"std":"xahau-nft-signature/v1"}}

meta.0 + meta.1   {"s":"xahaucards.card/v1","name":"Callback #1", …}

CardSignature#07  {"s":"xahau-nft-signature/v1",
                   "by":"rGvmjaa4Ai8s4LwKkF2Qh2gZYvRUg3wYQ4",
                   "tx":"12878C12B4CFF6E17B54E665985367DF74755128BC3A10C89EA40017F2B9DB68"}

A reader knowing only §1–§4 correctly identifies CardSignature#07 as one
complete member of a set, presents it as an unrecognised annotation, and does not
mistake it for a fragment of something larger. A reader implementing
xahau-nft-signature/v1 additionally fetches the transaction named in tx and
confirms its Account is the by address — the step that makes the annotation
worth anything, because the remark itself is only the issuer's word.

---

Appendix C: an evolving token

A token whose rank changes with use. meta is flagged immutable; meta2 is not.

schema   {"std":"xahau-nft-remark/v1",
          "meta":{"parts":1},
          "meta2":{"parts":2,"mutable":true}}

meta.0   {"s":"example.card/v1","name":"Ember Drake","image":"remarks:img",
          "attributes":[{"trait_type":"Species","value":"Drake"},
                        {"trait_type":"Rarity","value":"Legendary"}]}

meta2.0  {"attributes":[{"trait_type":"Rank","value":3},
                        {"trait_type":"Battles","value":47}]}

Merged, per §3.2:

{
  "s": "example.card/v1",
  "name": "Ember Drake",
  "image": "remarks:img",
  "attributes": [
    { "trait_type": "Species", "value": "Drake"     },   // from meta,  fixed
    { "trait_type": "Rarity",  "value": "Legendary" },   // from meta,  fixed
    { "trait_type": "Rank",    "value": 3           },   // from meta2, changeable
    { "trait_type": "Battles", "value": 47          }    // from meta2, changeable
  ]
}

Three things to notice:

Rarity is in meta and nowhere else. The issuer promised it at mint and
cannot take it back. Had it also appeared in meta2, the token would be
malformed under rule 4 — precisely so that no issuer can promise Legendary
immutably and quietly demote it later.

Rank is in meta2 and nowhere else. It is expected to change, so it is not
promised. meta2.1 is reserved but unwritten: parts is 2, one fragment is
present, and §3.1 says that is complete rather than truncated. Rewriting Rank
to 4 means rewriting meta2.0, which is not immutable and so may be rewritten.

A reader must not flatten the distinction. The comments above are the
provenance §3.2 requires be retained. A marketplace showing all four traits
identically tells a buyer that Rank 3 is as fixed as Legendary. It is not.

Nothing here depends on meta being the immutable one. The same token written
with meta mutable and meta2 immutable behaves identically: the flags decide,
the descriptors declare, and a reader that keyed off the family name rather
than the flags would get it exactly backwards.

---

Reference implementations

Sections	Status
§1–§4 (schema, meta, img)	In production on mainnet. Odin's Eyes Ravens, issuer rodinGM9xiKq7rDDnLPyieREkqGJ6zKyb. Every claim in those sections was read off that collection and verified.
§5–§6 (sets, external families)	Proposed. Implemented and exercised on Xahau testnet by XahauCards (xahaucards.com); not yet on mainnet.
§9 (xahau-nft-signature/v1)	Proposed, as a separate standard. Same testnet implementation.

Anyone can verify §1–§4 independently: read any Raven's remarks, reassemble them
by the rules above, and check the image SHA-256 against the descriptor.

[Cbot-XRPL]

Adding some production data from the reference-implementation side (Odin's Eyes Ravens) - we've been running sections 1-4 live on mainnet since early July, so a few of the answers this proposal asks for we can now give from real usage rather than theory.

Scale so far: every license NFT minted since #7 carries the full xahau-nft-remark/v1 package - schema + meta.* + img.* (~300px WebP) - authored by the mint hook itself in one emitted SetRemarks at mint time. No keeper, no off-ledger writer. On-chain art is pre-staged well ahead of the mint counter. Tokens render in explorers with zero IPFS dependency, and the image survives resale because the remarks travel with the URIToken.

Fragment ordering (numeric vs lexical): numeric is the right call and should stay normative. Our images routinely split into 25+ img.N parts, so lexical ordering breaks immediately (img.10 sorts before img.2). Integer-compare on the suffix reassembles correctly every time; zero-padding conventions are unnecessary if the spec mandates numeric compare - ours never padded.

The 32-remark ceiling in practice: tighter than it looks, but workable. Our budget function solves 1 (schema) + meta.parts + img.parts <= 32 and sizes the WebP to fit - a ~300px WebP lands at ~6-7 KB (~26-27 img parts) with a compact metadata doc in 3-4 parts. The lesson: treat ~8 KB as the on-ledger image budget and carry full resolution elsewhere (we pin a deterministic re-render recipe in metadata.render, plus an optional ipfs:// for legacy viewers - neither is needed to display the token). Base64 would have cost ~33% of that budget, so the raw-binary choice in this spec genuinely matters.

Mutable overlay (section 5): strong +1 from live experience. We shipped with the schema remark immutable and the rest mutable specifically because we needed to backfill/correct metadata post-mint, and that tension - immutable identity vs correctable presentation - is exactly what the meta2 overlay formalizes.

Two implementer notes for anyone emitting the package from a hook (each took real debugging to learn):

1. An emitted SetRemarks must carry a FirstLedgerSequence of the same ledger as the mint transaction it accompanies (fls, not fls+1) - a future-dated emit is silently dropped with no surfaced error.
2. On a hooked issuer account the SetRemarks fee must be hook-inclusive; a bare base fee gets the emit rejected under load.

Happy to contribute the encode/decode reference (xahau-nft-remark-composer) and our budget/verification code to whatever test-vector suite this standard ends up with. Verifying the sha256 of the reassembled image against the schema manifest has caught every partial-load we've ever had - a normative test-vector set around exactly that would be my main ask.