Tokens · Variants

Variants — states gallery

Two collection-level surfaces: Variants — every variant across every token in the collection, browsable the same way tokens are (card grid or list, filters, pagination) — and Actions — the optional, reusable action-template library. The transition itself — which variant a holding is reached from, and what triggers the change — is configured per token, on the variant's own edit panel; it is not a separate graph-building page. A transition can use a shared, reusable template (when more than one token follows the same path with the same asset) or a one-off definition just for that variant — templates are a convenience, not a requirement.

Frames 15–20 cover variant profiles — a named, versioned, project-level variant set that can be applied to many tokens at once. A profile carries the set and never the topology, so applying one seeds the list and the author still declares each transition per token.

Frames 21–25 are new, and 15, 16 and 19 are revised. Variant identity is now a stable variant_id that never changes and is never reused (T10), separate from display order — so re-apply can update an uncustomised variant, a profile may place a variant anywhere in the order, and reordering is harmless. Apply, re-apply and detach are Draft only; the operation is offered from Review as one atomic step that returns the token to Draft. And the State Policy is resolved into the token's contract rather than snapshotted onto the token.

Frames 01–14 unchanged · 15, 16, 19 revised · 21–25 new

Source: Phase2/Composition Template System/token-contract-system-spec.md §4A (variant profiles) · token-variant-actions-spec.md (transitions, TVA1–TVA11) · state-policy-design.md — all ratified. Extends Phase1/token-system-design.md (the variant data model, T1–T10). Rulings R114–R131. Related: Token draft · My Tokens · Collection nav.

Setup · creator, on the token itself

01What a variant isDeveloper reference — not a screen. The model in four rules; every frame below follows them.

The model

A variant = a different version of the same token

It has a different name and a different asset. Everything else about the token stays the same.

The Original Token is always the default variant

The token's name and main asset are the Original Token — the default variant. There is never a time when the default isn't set, and only the default variant can be minted.

Every other variant declares its own transition

On the token itself, each variant's own edit panel says which variant it's reached from and what triggers the change — a shared, reusable action template, or a one-off action defined just for it. There's no separate graph-building page; the resulting chain or branch is just a preview, derived from what each variant declares.

Coming later (not in the launch candidate)

A future version will let an action require a payment or the burning of another token before it runs. Recorded in the design docs; not built for launch.

02Token · Supply — stack behaviourStack behaviour (Allow stacking / Always individual) is a per-token setting, and it does not gate variants — variants are available either way. With stacking on, each variant is its own separate stack; with it off, the variant just labels each individual copy. Locks when the token goes Live.

Studio/Collection: Paper Trail/Dollar Wallet/Token supply

Draft

Token · Supply

Token supply.

Per-token supply and stack behaviour. Variants (Variants tab) are available in either mode below.

Stack behaviour

For stackable tokens, each variant stacks separately. For always-individual tokens, the variant just labels each copy. Locks when this token goes Live.

03Token · Variants tab — no variants yetA tab on the token editor, so a creator who isn't using variants never sees the options. The tab opens with a plain explanation, shows the Original Token as the default, and — if there are no other variants — a short message and one button.

04Add a variantAdding a variant needs just an asset and a name — enough to create it. Its transition (how it's reached, what triggers it) is set up straight after, from Edit (frame 06), so a variant is never left half-configured for more than a moment.

05Token · Variants tab — with variantsEach row shows its asset, name, and — once configured — a plain summary of its transition ("Reached via Gild · from Original Token"). A variant added but not yet wired up reads "Not yet reachable." Below the list, a read-only preview of the resulting chain or branch — it's derived from what each variant declares, not authored here directly.

06Edit a variant — name, asset, and its transitionThis is where a variant is actually configured: its asset and name, and its transition — the variant it's reached from, and what triggers the change into it. Triggering can reuse a shared action template (when other tokens follow the same path with the same asset) or be defined as a one-off just for this variant — templates are optional. A variant may declare more than one incoming transition, and the Original Token / default may declare them too — which is how a return path and a full cycle are expressed. (The default is edited from the token's Details & Assets tabs, like any token — it has no transition of its own to configure.)

06 ·One-off trigger — no shared templateSame modal, "One-off for this variant" chosen instead. The template dropdown is replaced by the wording fields directly — nothing is added to the reusable Actions library. A good fit when only one token ever needs this exact path.

06 ·A multi-step chain is just this same form, repeatedThere is no separate "build a chain" flow. A 4-link chain like Relic's (Unforged → Forged → Awakened → Ascended) is three of these single-transition edits, one per non-default variant — each one just points its Reached from at whichever variant comes before it. Here, editing Awakened Relic: its "Reached from" select lists every other variant on this token — Unforged Relic, Forged Relic, Ascended Relic — and Forged Relic is chosen, making this the second link in the chain. Editing Ascended Relic the same way, with "Reached from: Awakened Relic," adds the third. Branches work the same way — two variants both pointing "Reached from" at the same predecessor (frame 05's Dollar Wallet example) instead of at each other in sequence.

07Topology integrity · deletion blocks, and reachability at go-LiveTwo rules keep the graph sound. Deletion is blocked while another variant is reached from this one — shown below. And at go-Live, every non-default variant must be reachable from the default by following declared transitions: orphans, and closed cycles the default cannot enter, fail with the unreachable variants named. Because cycles are legal, validation walks from the default with a visited set. Deleting from the Variants tab's row action. Blocked when another variant's transition is reached from this one — the exact dependency is named, with a way to jump straight to it.

Variants & Actions · collection-level, browse only

08Collection · Variants page — Actions tabOne collection-level page with two tabs (more may be added as variants grow): Variants (frame 10 — browse every variant) and Actions (here — the optional, reusable template library). Both stay reachable whatever the collection's own stage; nothing here is edited from this page — editing happens on the token (frames 04–07). A template locks the moment any variant using it belongs to a Live token: Open and Gild are locked because Dollar Wallet is Live; Forge / Awaken / Ascend stays editable because Relic (its only user) is still Draft.

Studio/Collection: Paper Trail/Variants

Live

Collection · Variants

Variants.

Every variant in this collection, and the optional action templates that trigger them.

Reusable wording you can apply to any variant's transition — optional, only useful when more than one token shares a path and asset.

Template	Button wording	Version	Used by	Actions
Open	Open	v1 · frozen	Dollar Wallet Live · locked	Locked
Forge / Awaken / Ascend	varies	v3 · editable	Relic Draft
Gild	Gild	v2 · frozen	Dollar Wallet Live · locked	Locked
Un-gild	Un-gild	v1 · editable	Unused

09Action template editorOpened from "+ New template" or a template's Edit icon. Purely reusable wording and behaviour — which variants it connects is chosen where the template is picked, on each variant's own edit panel (frame 06), not here.

Holder · wallet

11In your walletA holding shows a button only when it's owned, active, not listed, and its current variant has an incoming... rather, an outgoing trigger declared by some other variant that names it as "from". The card shows the token's current name and asset — there's no variant-state label on it. Three points along the Relic chain.

Unforged Relic

Relics

Unforged Relic

#014

Limited edition

Forged Relic

Relics

Forged Relic

#014

Limited edition

Ascended Relic

Relics

Ascended Relic

#014

Limited edition

Same holding (#014), three points on its journey. Left: at the start, so Forge shows. Middle: mid-chain — the same holding after Forge ran, now showing the next step's button, Awaken. Right: at Ascended Relic, the end of the chain — no variant names it as "from," so no action button, same as any token with no variants.

12A branch, from the holder's sideTwo variants (Opened Wallet, Golden Wallet) both declare the Original Token as their "from" — so a holding on the Original Token shows both buttons. Both buttons show — the holder picks which action to run, same confirm-then-run flow either way (frame 13).

Dollar Wallet

Paper Trail

Dollar Wallet

#042

Limited edition

Running either one moves this holding off the Original Token — a holding only ever sits on one variant at a time, so taking one branch removes the other's button along with it.

13The prompt · in the creator's wordsBefore the action runs, the holder sees the creator's warning and confirms. Amber caution — this changes the token, it doesn't delete it. Two examples: a one-way step, and one whose target also declares a transition back. The holder is told which, in plain words — the mechanism (a second declared transition) is not their concern. A one-way step, and one whose target declares a transition back.

14After the actionThe token now shows the variant's name and asset, plus whatever button that variant's own "from" declarations provide next. Left: a one-way step — the token simply is the new variant now. Right: where the source variant declares its own transition back, the holder simply sees a way back.

Opened Wallet

Paper Trail

Opened Wallet

#042

Limited edition

Evolved

Paper Trail

Evolved Seedling

#088

Limited edition

Variant profiles · applying a shared set

15Applying a profile — the rulesRevisedDeveloper reference — not a screen. A variant profile is a named, versioned, project-level variant set. Applying one to a token snapshot-copies the set; editing the profile afterwards never reaches a token that already applied it. Apply is additive: it adds variants and updates uncustomised ones, and it never removes, never re-keys, and never overwrites a local edit. See frame 21 for why it is no longer append-only.

Apply and re-apply — every case

Case	What happens
In the profile, not on the token	Added, with a fresh variant_id, at the profile's own place in the order — or at the end once the creator has reordered by hand
From the profile, not customised	Name and asset updated to the new version. Its key and variant_id never change
From the profile, customised locally	Preserved, and reported as customised — the profile never reaches its content again
On the token, absent from a newer profile version	Blocker. Reported with what references it; never removed for you (frame 18)
Profile key collides with a locally authored variant	Whole apply rejected, naming the key and both sources (frame 17)
Merged length would exceed 255	Whole apply rejected (frame 17)
The default variant	Never touched. A profile carries no default field and cannot set one

Re-apply matches on the key each variant was copied from — never on position, never on the name. So renaming Admitted to Scanned in the profile updates the same variant rather than looking like a new one, and reordering either side matches nothing differently (frame 21).

Where it came from · and two independent things that can be true of it

Shown as	Meaning, and what it changes
Festival ticket v2	From the profile, untouched. A re-apply updates its name and asset; a detach removes it
customised	Its name or asset was edited here. Re-apply never overwrites it, and detach leaves it behind
has transitions	A transition or action binding names it. This blocks detach only — its name and asset still update from the profile, because a profile carries the set and never the topology
Authored locally	Never came from a profile. Unaffected by anything a profile does

The middle two are independent, and a variant can carry both. Treating "has transitions" as a customisation would freeze a variant out of its profile the first time anyone wired it up — and wiring unused → admitted is the entire point of a ticket profile, so the profile would break on first use.

16Token · Variants tab — a profile appliedRevisedThe same tab as frame 05, after Seasonal reskin v3 was applied. Each row carries its stable variant_id and its source. Winter Wallet came from the profile untouched; Summer Wallet came from it and has since been renamed, so its content has gone local; Autumn Wallet is untouched but has a transition declared against it, which blocks detach without blocking updates; Golden Wallet was authored by hand. Topology is still declared per variant — a profile carries the set, never the transitions — so every row still needs its own "reached from" (frame 06). Apply, re-apply and detach are Draft only; from Review the same action is offered as one atomic step that returns the token to Draft (frame 22). Everything freezes at Live.

17Apply rejected — nothing partially appliedNewTwo rejections, and in both cases no variant is added at all — a partial apply is never performed. Left: a key already in use. The message names the key and both sources, because "duplicate key" alone leaves the creator guessing which of their variants collided. Right: the merged set would exceed the 255-variant ceiling. Both are the same rule the attribute templates already follow.

18Re-apply — a variant the new version dropsNewThe dry-run always runs before anything is written, and it reports all four outcomes at once. Here v4 of the profile no longer contains Autumn Wallet — so re-apply stops and says what depends on it. It does not offer to remove it: deleting a variant is a deliberate act the creator performs themselves, never a side effect of accepting a template update.

Re-apply Seasonal reskin · v3 → v4

Variant	Source	Outcome
Spring Wallet	New in v4	Will be added
Winter Wallet	From profile, untouched	Unchanged
Summer Wallet	Customised	Skipped — customised
Autumn Wallet	Not in v4	Blocked

Autumn Wallet isn't in v4, and something still points at it.

Winter Wallet is reached from it, and it uses the Fall action template. Change or clear those first if you want it gone — nothing here will remove it for you.

19Detach a profile — what goes, what staysRevisedDetach removes only the variants that came from this profile and carry neither marker. Anything customised stays; anything authored by hand was never the profile's and stays; anything a transition or action binding names is a blocker; and the default variant is never touched. This is the reason the markers in frame 15 have to exist — without them, a creator cannot predict this screen before opening it.

Detach Seasonal reskin?

Variant	Source	On detach
Winter Wallet	From profile, untouched	Removed
Summer Wallet	From profile · name edited here	Kept
Golden Wallet	Authored locally	Kept
Autumn Wallet	From profile · has transitions	Blocked

Autumn Wallet can't be removed. Winter Wallet is reached from it. Clear that transition first, or keep the profile attached.

Detach is Draft only — from Review it is offered as a return-to-Draft step first (frame 22). Once the token is Live the variant set is frozen and nothing here can change.

20Nothing to apply yet — two different empty statesNewThese say different things and must not be merged. Left: the project has no variant profiles at all, so the creator is pointed at the Templates library to make one. Right: a profile exists but its working copy has never been published — a Draft template is never appliable, so "nothing here" would be actively misleading to someone who has just authored one and is looking for it.

Variant identity · Draft-only apply · contract authority

21Variant identity — the id, not the positionNewDeveloper reference — not a screen. Every variant gets a variant_id when it is created, and keeps it for good. Holdings, the default variant, transition endpoints and policy endpoints all name that id. Where a variant sits in the list carries no meaning, which is what makes reordering safe and lets a profile place a variant anywhere rather than only at the end.

The four rules

Assigned once, never changed

A variant's id is set at creation and is immutable. Renaming it, moving it, or changing its asset never touches the id.

Never reused

Deleting a Draft variant retires its id permanently. Nothing later inherits it, so a stale reference can never quietly point at something else.

Ids are gappy, and that is normal

Because they are never reused, a token's ids are usually not consecutive. Never show an id as a position, a count, or an ordinal — it is a name that happens to be a number.

Order is presentation only

display_order is what the creator arranges. It can change at any stage, including after Live, because nothing reads meaning from it.

A festival ticket, after the creator inserted VIP and deleted two drafts along the way

Shown at	Stable id	Key	What references it
1st	id 0	unused	The default variant · 10,000 holdings · the source of unused → admitted
2nd	id 9	vip	Added last, placed second. Its position says nothing about when it arrived
3rd	id 7	admitted	3,000 holdings · the target of unused → admitted
4th	id 8	souvenir	The target of admitted → souvenir

Ids 1–6 were allocated to drafts that were deleted, so they are retired and will never be issued again. If identity were the position instead, inserting VIP second would have silently turned 3,000 scanned-in ticket holders into VIPs — no error, nothing to notice.

Before reordering is switched on

Every positional lookup over the variants list has to be found and removed first — including anything that treats the first variant as the Original Token. The Original Token is whichever variant default_variant names, never whichever one sorts first.

22Applying from Review — one step, and it costs reservationsNewApply, re-apply and detach are Draft only: a token in Review is locked, and its only moves are going Live or returning to Draft. The action is still offered here, as a single atomic operation that returns the token to Draft and applies — never two separate steps, because returning to Draft releases the issue-number reservation and that cannot be undone. The tokens stay in Draft afterwards for re-submission: the definition that was approved has to be the definition that was reviewed.

23Batch preview — atomic per token, mixed outcomes expectedNewThe preview runs before anything is written and shows every outcome at once. A token either applies completely or not at all — but one blocked token never fails the others. This is the same discipline the state-policy batch tool already uses, so there is one rule rather than two.

Apply Festival ticket · v1 → v2

Token	Stage	Outcome
Day pass	Draft	Adds 1 · updates 2
Weekend pass	Draft	Updates 2 · keeps 1 customised
VIP pass	Review · holds #0007	Returns to Draft first
Camping add-on	Draft	Blocked · key collision
Season ticket	Live	Skipped · frozen

Camping add-on will be skipped. Its locally authored variant already uses the key souvenir. The other four are unaffected — rename it and run this again to include it.

Nothing has been written yet. 3 tokens will change, 1 is blocked, 1 is frozen.

24Re-apply — what a new profile version actually changesNewDeveloper reference — not a screen. A newer version does update the variants that came from it and have not been customised here; that is the point of versioning a profile. It matches each one on the key it was copied from, so the id, the holdings and the transitions all survive a rename in the profile.

Festival ticket v1 → v2 · the profile renamed Admitted to Scanned and added VIP

Variant	On the token now	After re-apply	Why
id 0 unused	Unused · from v1	Name and asset updated	From the profile and never edited here, so v2's content lands on it
id 7 admitted	Admitted · from v1	Renamed to Scanned, id and holdings untouched	Matched on the key admitted, not on the old name — a rename in the profile is not a new variant
id 8 souvenir	Keepsake · renamed here	Left exactly as it is	Customised locally. The profile never overwrites a creator's own wording
id 3 earlybird	Early bird · from v1	Blocked — nothing is written	v2 dropped it, and removing a variant is never something an update does on your behalf (frame 18)
—	Not present	Added as id 9	VIP is new in v2. It takes the next free id, and can sit second in the order without disturbing anything

A transition declared against a variant does not stop it updating. unused → admitted being wired up is the normal state of a working ticket, not a customisation — it only blocks detach.

25Token · State tab — the rules come from the contractNewThe State Policy is resolved into the token's contract version when that contract is published. The token stores which contract it pins and nothing else, so there is no second copy to drift, edit or reconcile. That makes this tab read-only by construction rather than by restraint — there is no attach, re-apply or detach control here because there is no separate object to act on. Changing the rules means a new contract version and an explicit migration, which is a Draft-only batch operation.

Edit token · State Draft

Festival admission

State policy · v4 — resolved into Ticket contract v6

From the contract

Field	Who may write	Rule
variant	Owner	Transitionable · one-way
scanned_at	Approved app	One-time write
gate	Approved app	One-time write

To change these rules, publish a contract version carrying the newer policy and migrate this token to it. Migration is a Draft-only batch operation, and it is validated before it runs. Once the token is Live it does not migrate at all.

Runtime values still move after Live — a ticket can still be scanned. What freezes is the rulebook, not the memory.