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.
Draft — for design review, not yet finalized
Source: Design Documentation/Phase2/token-variant-actions-design.md (extends Phase1/token-system-design.md) — draft, pending design-team review. 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.
Per-token supply and stack behaviour. Variants (Variants tab) are available in either mode below.
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.
Edit token · Variants Draft
Variants are different versions of this token with a different name and asset. Each one you add here says which variant it's reached from and what triggers the change.
Dollar Wallet
Original Token · the default · the only one that mints
Default
This token does not have any variants. If you do not wish to add any, there is nothing more to do here.
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.
Add variant
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.
Edit token · Variants Draft
Dollar Wallet
Original Token · the default · the only one that mints
Default
Opened Wallet
Reached via Open · from Original Token
Golden Wallet
Reached via Gild · from Original Token — and Un-gild declared back to it
2-way
Original Token
OpenOpened Wallet
GildGolden Wallet
two-way — because Original Token also declares an incoming transition (Un-gild) from Golden Wallet. There is no reversible flag; a return path is a second declared transition, and cycles are legal.
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.)
Edit variant · Golden Wallet
Reusable — pick this again for any other token that reaches a variant the same way with the same asset.
A holding on Original Token will show a Gild button once this is saved. A holding on Golden Wallet shows a way back only because Original Token separately declares Un-gild from it — declare both directions and you have a two-way pair.
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.
Edit variant · Sprout
What the holder taps.
Pins an exact version. Editing the template later never changes a token already Live.
Later, if another token needs this same path and asset, this can be promoted into a reusable template from the Actions tab.
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.
Edit variant · Awakened Relic
Every other variant on this token — pick whichever one this step follows.
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.
Can't remove Forged Relic
Awakened Relic is reached from this variant. Change or clear that variant's transition first, then Forged Relic can be deleted.
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.
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.
Action template
Internal — how you'll find this template in the list.
What the holder taps.
A variant pins an exact template version. The template stays editable — each edit makes a new version future tokens may pin — and a version pinned by a Live token is frozen.
10Collection · Variants page — Variants tabEvery variant across every token in the collection, browsed the same way tokens are — card grid or list, search, filters, pagination. Read-only: this is a catalog for finding and reviewing variants, not for editing them (that's frames 04–07, on the token). The Original Token of each token is not listed here — it's the token itself, not a variant of it; this catalog only holds the additional variants layered on top.
Every variant in this collection, and the optional action templates that trigger them.
Opened Wallet
Dollar Wallet
Opened Wallet
Via Open
Golden Wallet
Dollar Wallet
Golden Wallet
Via Gild
Forged Relic
Relic
Forged Relic
Via Forge
Awakened Relic
Relic
Awakened Relic
Via Awaken
Ascended Relic
Relic
Ascended Relic
Via Ascend
Bloom
Seedling
Bloom
Not yet reachable
Showing 6 of 6
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.
Open this token?
Warning — you're about to Open this token. This change is permanent and can't be undone.
Evolve this token?
Warning — you're about to Evolve this token. This change is reversible — you can change it back to the Original Token later.
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.