Skip to content

feat(nbcr-2023-002): adopt hex-string + UAI dot form for token-ids#19

Merged
irfan798 merged 1 commit into
mainfrom
feat/nbcr-2023-002-detailed-account-hex-string
May 4, 2026
Merged

feat(nbcr-2023-002): adopt hex-string + UAI dot form for token-ids#19
irfan798 merged 1 commit into
mainfrom
feat/nbcr-2023-002-detailed-account-hex-string

Conversation

@irfan798
Copy link
Copy Markdown
Contributor

@irfan798 irfan798 commented Apr 23, 2026

Summary

Aligns detailed-account (NBCR-2023-002, Layer 3) with:

  1. hex-string = #6.263(bstr) (IANA CBOR tag 263) as an alternative encoding for canonically hex token identifiers, primarily EVM contract addresses.
  2. UAI . separator (per NBCR-2024-001) for compound identifiers such as ERC-721 / ERC-1155.

tstr remains valid. Previously-emitted payloads decode unchanged.

On-wire impact

For an EVM ERC-20 contract address (20 bytes on-chain, 42 characters as 0x… text):

Encoding On wire Savings
tstr (previous) ~44 bytes baseline
hex-string (tag 263) ~24 bytes ~20 bytes / ~45%

A portfolio with 20 ERC-20 identifiers saves ~400 bytes total, often enough to drop one or two animated-QR frames from a sync flow (recommended fragment size is 200 characters per QR).

Parser impact

Tag 41402 (detailed-account) and the keymap (account = 1, token-ids = 2) are unchanged. The change is additive: one new alternative inside the token-ids array union.

  • Legacy tstr path decodes as before. No action needed for backward compatibility.
  • Parsers SHOULD now recognise CBOR tag 263 wrapping a bstr inside token-ids. The wrapped bytes are the hex-interpreted identifier (20 bytes for an EVM contract address; variable for future encodings). Display layers render with a 0x prefix, lowercase, preserving round-trip parity with the caller's input.
  • C parser action items (embedded, ZERO side):
    1. Add a handler for CBOR tag 263 wherever token-ids entries are consumed.
    2. Surface the wrapped bytes with a "hex-interpreted" flag so the UI renders 0x<lowercase hex>.
    3. Keep the existing tstr path for non-hex identifiers (e.g. SPL mint addresses).
  • TypeScript reference implementation in @ngraveio/ur-hex-string, consumed by DetailedAccount in feat(DetailedAccount): addhexstring to token-id definition ur-registry#49.

Backward compatibility

  • Payloads emitted under the previous [+ string] grammar decode unchanged under [+ tstr / hex-string].
  • Legacy ERC-1155 identifiers using : (e.g. 0xabc:123) remain decodable as tstr. The grammar does not constrain the separator; it is a prose convention. Producers SHOULD migrate to . to match UAI; consumers MAY continue accepting both during the transition.

Other editorial changes

  • Fix typo #6.308(output-descriptor)#6.40308(...) in the CDDL comment (tag 308 is the deprecated crypto-output; the actual rule correctly uses 40308).
  • Drop the "decimal" prescription on ERC-1155 token-id rendering. EIP-1155 defines _id as uint256; rendering is implementation choice.
  • Tighten grammar from the under-specified string to RFC 8610's canonical tstr.
  • Generalise the per-chain comments to cover ERC-721 alongside ERC-1155.
  • Add references: NBCR-2024-001, hexString tag spec, EIP-1155.

Not in this PR

  • Layer 3 examples (around lines ~978, ~1013) still use the tstr form for ERC-20 addresses. They remain valid under the new spec; a follow-up can regenerate them to showcase hex-string (also touches the accompanying CBOR hex and UR encodings below each diagnostic example).
  • A forward-looking structured array form [hex-string, biguint] for compound identifiers (separate proposal).
  • IANA tag registration for non-EVM byte-string encodings like base58 and bech32, tracked separately.

References

- Introduce 'hex-string = #6.263(bstr)' (IANA CBOR tag 263) as an
  alternative encoding for canonically hex token identifiers, halving
  the on-wire size for EVM contract addresses.
- Switch the ERC-1155 example from ':' to the '.' separator per UAI
  (NBCR-2024-001), aligning with the "tokenid[.subtype...]" convention
  used elsewhere in the paper.
- Generalise the per-chain comment block to cover ERC-721, drop the
  "decimal" prescription on ERC-1155 token ids (EIP-1155 defines
  _id as uint256; rendering is implementation choice).
- Tighten grammar from '[+ string]' to '[+ tstr / hex-string]'.
- Fix typo '#6.308(output-descriptor)' → '#6.40308(...)'.
- Add NBCR-2024-001, hexString, and EIP-1155 references.

No wire-format change for existing tstr payloads. Previously-emitted
detailed-accounts decode unchanged.

Refs LIQ-842
@irfan798 irfan798 force-pushed the feat/nbcr-2023-002-detailed-account-hex-string branch from e2e62ee to b08c569 Compare April 23, 2026 13:09
@irfan798 irfan798 self-assigned this Apr 23, 2026
@irfan798 irfan798 requested a review from Maher4Ever April 23, 2026 13:46
@Maher4Ever Maher4Ever requested a review from adbena April 23, 2026 13:58
@irfan798 irfan798 merged commit 313aff4 into main May 4, 2026
@irfan798 irfan798 deleted the feat/nbcr-2023-002-detailed-account-hex-string branch May 4, 2026 13:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants