Display node feedback from real-world clear-signing adoption

[lorisleiva]

We've started rolling out display nodes (#26, #27) across the hand-written IDLs of the solana-program org — e.g. token#171 and token-2022#1383 — and real-world usage is starting to surface small gaps in the spec.

Rather than patching the spec one gap at a time, I'd like to use this issue as an umbrella to collect that feedback and batch the changes in a future wave once we have a fuller picture. If you hit a display limitation whilst adding clear-signing metadata to an IDL, please add it below.

Feedback so far

No way to customise the branches of an option type

Option types currently have no display customisation, which makes them awkward to use in interpolated intents. For instance, unwrapLamports on token-2022 takes an Option<u64> amount where None means "the entire balance". If we included the amount in the interpolated intent today, we would end up with:

// Some(1.5 SOL)
Unwrap 1.5 SOL from ...

// None
Unwrap none from ...

The Some branch is fine (the inner number type already carries its own display node) but the None branch renders a lowercase "none" mid-sentence. A custom display value for None — e.g. "all SOL" here — would fix this use-case, but it means extending the spec again so it's probably best batched with whatever else this issue gathers. See the original discussion on token-2022#1383.

---

More items to be added as comments below as feedback comes in. 🙏

[lorisleiva]

Design direction settled during the #129 implementation discussion (cc #133), recorded here since this umbrella owns the display layer's evolution:

1. Symbol space vs prose space. identifier is a node's name in the world of code — the sole basis for generated symbols, links and paths, compared verbatim. Prose never influences codegen; consumer-side symbol renaming stays in codama's rename visitors, outside the IDL. This keeps display edits (including translations) from ever being breaking changes to generated clients.
2. TextNode is a carrier, not a layer. Placement of any human text is decided by audience: docs = prose for developers (node attribute, near the identity); label/intent = prose for end users (display nodes, trailing). errorNode.message stays on the node as canonical dual-audience text, translatable in place once TextNode lands.
3. Labels are derive-by-default overrides. Absent display metadata, the human representation derives from identifier; labels are only present when they differ. Validators may lint labels that equal the trivial rendering of their identifier.
4. name never returns as a node attribute. v1's name became identifier in v2 ([v2] Rename name to identifier and drop the casing mandate #129); reusing the word with different semantics would be hostile to anyone reading IDLs across majors. The term for human text is label.
5. The display gap (accounts, errors, events, programs, defined types, PDAs have no display attribute today) is filled by dedicated per-host display nodes starting with just label, grown additively with optional attributes — shipped as v2.x minors, sequenced after the [v2] Introduce textNode for all human-facing text #133 go/no-go so labels are TextNode-typed from birth. A generic shared labelDisplayNode was considered and rejected: swapping it for a richer per-host node later would be a breaking type change, whereas per-host nodes grow additively forever. Instructions gain no label — intent already is the instruction's human label, in verb form.

[lorisleiva]

A third framework piece settled during the #132 (numeric system) design, joining the symbol/prose split above — the type/display line:

Type layer = what the value is; display layer = how to show it. The test: would two honest consumers disagree about the value — not its rendering — without this information? If yes (width, endianness, scale/base, unit of measure, datetime/duration semantics), it belongs on the type. If they would only render it differently (labels, locale, relative vs absolute time, symbol placement), it belongs on display.

Consequences applied in #132's implementation: ticksPerSecond moved from the two time display nodes (deleted) into dateTimeTypeNode and the new durationTypeNode; unit and scale live on the numeric types (fixedPointTypeNode, unit-ed integerTypeNode/floatTypeNode). amountNumberDisplayNode survives as the one deliberate exception: its injectable decimals/unit handle quantities whose semantics are contextual (per-mint decimals and symbols resolved at presentation time) — something static types cannot express today. If context-dependent type parameters ever land (see the v3 exploration issue), that role migrates into the type layer too.

Corollary for this umbrella's future work: display nodes should assume type-level truth and only override or enrich presentation; a renderer needing display data to type something is the signal a fact was mis-filed.