@ouronet/talos-registry 1.3.0 → 2.0.0

package/README.md

@@ -178,10 +178,10 @@ import { tooltipModel, signatureRows } from "@ouronet/talos-registry";
 const m = tooltipModel("TS01-C1.DPTF|C_Transfer", { id: '"OURO-8Nh-JO8JO4F5"' });
 // m.slots -> EVERY execution parameter, in order, with type, value and flags
 // m.preview -> the INFO_ call with ITS OWN parameter list
-// m.kind -> "ouronet" | "native"   (native renders gold, has no cost section)
+// m.kind -> "ouronet" | "stoa" | "kadena"   (only ouronet has a cost section)
 ```
 
-Six rules, each there because it was got wrong first — most recently a six-parameter transfer
+Seven rules, each there because it was got wrong first — most recently a six-parameter transfer
 whose tooltip showed five arguments, because it was rendering the preview's list under the
 execution's heading. Read the canon before building one.
 

package/TOOLTIP-CANON.md

@@ -21,6 +21,19 @@ This file explains **why** each rule exists. Every one is here because it was go
 
 ---
 
+## Rule 0 — this tooltip is for CHAINWEB calls only
+
+It describes a **Pact call on a Chainweb chain**: what function, what arguments, what it costs. A
+button that transacts on **Arweave**, or any other non-Chainweb chain, has none of those things in
+this shape.
+
+**Such a button gets no tooltip of this kind — not an empty one.** An empty panel reads as "the
+price failed to load"; absence reads as "this is a different kind of thing", which is the truth.
+If you want an affordance there, write a different one; do not stretch this model over it.
+
+`chainOf(key)` returns `undefined` for anything this model cannot describe, and `tooltipModels()`
+drops such keys rather than throwing. That is how a caller learns to render nothing.
+
 ## Rule 1 — show every execution parameter
 
 All of them, always, in declared order.
@@ -74,19 +87,37 @@ already the widest thing on screen when it opens. A parallel row costs one line.
 
 `signatureRows(m)` returns `{ names, types }` as equal-length arrays for exactly this.
 
-## Rule 4 — native is not Ouronet, and the difference is narrower than it looks
+## Rule 4 — three worlds, and they must be distinguishable
+
+`kind` is `"ouronet"`, `"stoa"` or `"kadena"`. Only the first is in this registry; the other two
+are transcribed by hand in `STOA_SIGNATURES` and `KADENA_SIGNATURES`.
+
+| | `ouronet` | `stoa` | `kadena` |
+|---|---|---|---|
+| what it is | the `ouronet-ns` surface | StoaChain's own `coin` | **Kadena mainnet's `coin`** |
+| INFO_ preview | yes | **no** | **no** |
+| IGNIS | collected | **none** | **none** |
+| accounts | Ouronet glyph strings | `k:` `c:` `u:` `w:` | `k:` principals |
+| gas | station pays | **station pays** | **a different chain's gas entirely** |
 
-A `coin.*` call is StoaChain's own root-namespace contract. It is **not** in this registry and
-never will be: the registry is generated from `ouronet-ns`.
+**`kadena` is not a variant of the other two.** Different chain, different gas, different balances;
+nothing about Ouronet's gas station or IGNIS applies to it. Getting this wrong is worse than the
+other confusions on this page, because a user who thinks a Kadena transfer is sponsored is wrong
+about their own money.
 
-What is actually different:
+**Both chains call their contract `coin`.** StoaChain uses Ouronet-style names (`C_Transfer`,
+`C_URV|Stake`); Kadena uses KIP-0002 kebab-case (`transfer`, `transfer-create`). Nothing collides
+today, and `chainOf` **throws** rather than guesses if anything ever does — picking wrong would
+describe a call on the wrong chain, which is the kind of wrong that looks right.
 
-| | Ouronet | native |
-|---|---|---|
-| INFO_ preview | yes | **no** — nothing prices a `coin` call |
-| IGNIS | collected | **none** |
-| accounts | Ouronet glyph strings | **Kadena-shaped** (`k:` `c:` `u:` `w:`) |
-| gas sponsorship | gas station pays | **gas station pays** — the same |
+Note `coin.transfer-crosschain` is a **`defpact`** — a multi-step continuation. Worth saying out
+loud in a renderer: its later steps are not sponsored by anybody.
+
+**The sponsorship row is the one to get right.** An earlier version of this claimed a StoaChain
+native call was not sponsored and that the signing account paid its own gas. Both false: every
+native modal carries `GAS_PAYER` on the gas-station key and says so in its own header comment. The
+claim had been *inferred* from "this is not an Ouronet operation", which says nothing about who
+pays the host chain — and it was wrong in the direction that matters.
 
 **That last row is the one to get right.** An earlier version of this claimed a native call was
 not sponsored and that the signing account paid its own STOA gas. Both false: every native modal
@@ -95,9 +126,21 @@ header comment. The claim had been *inferred* from "this is not an Ouronet opera
 nothing about who pays the host chain — and it was wrong in the direction that matters, telling a
 user they were about to spend when they were not.
 
-**Render native with a gold perimeter.** The gold is semantic, not decorative: it means *nothing
-here prices this call*. And say what is missing rather than leaving the cost panel empty — an
-empty panel reads as "the price failed to load".
+**Make the two visually distinct — the palette is yours.** The distinction is mandatory because
+the two differ in what they cost and what can be previewed; the specific colour is presentation,
+and this package does not get a vote on your design language. A rule that mandates a palette in
+someone else's application is a rule that gets ignored, and an ignored rule weakens the ones that
+matter.
+
+In practice:
+
+| | `stoa` | `ouronet` | `kadena` |
+|---|---|---|---|
+| OuronetUI | gold `#ceac5f` | blue `#3b82f6` | *(not surfaced)* |
+| Codex | *its own* | violet | **green** |
+
+Whatever you choose, make it carry meaning rather than decoration, and **say what is missing**
+rather than leaving the cost panel empty — an empty panel reads as "the price failed to load".
 
 Suggested footer, which is what OuronetUI ships:
 
@@ -106,8 +149,13 @@ no IGNIS — this is not an Ouronet operation
 a StoaChain `coin` call, so nothing prices it. Gas is still sponsored.
 ```
 
-Signatures for the native calls are in `NATIVE_SIGNATURES`, transcribed from the deployed
-contract with line numbers. Use them rather than typing your own.
+Signatures are in `STOA_SIGNATURES` and `KADENA_SIGNATURES`, transcribed from the deployed
+contracts with line numbers. Use them rather than typing your own.
+
+**Make the distinction run in every direction.** We coloured `stoa` gold and left `ouronet` on the
+panel's ordinary grey — so the distinction existed one way only, and a reader who never hovered a
+native button learned no rule at all. Gold then reads as "something is odd about this one" rather
+than as a category. Give every kind a colour and a label, not just the exceptional ones.
 
 ## Rule 5 — a ghost is not data
 

package/dist/index.d.ts

@@ -16,6 +16,6 @@ export type { CallPlan } from "./plan.js";
 export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js";
 export type { ParsedCapability, CapabilityRecipe } from "./caps.js";
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
-export { tooltipModel, tooltipModels, signatureRows, isNativeKey, isPlaceholder, PLACEHOLDER, NATIVE_SIGNATURES } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
 export type { TooltipModel, TooltipSlot, TooltipPreview } from "./tooltip.js";
 export type * from "./types.js";

package/dist/index.js

@@ -15,4 +15,4 @@ export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js"
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
 // THE TOOLTIP CANON. Shared implementation rather than a shared document -- see TOOLTIP-CANON.md
 // for why each rule exists, and `tooltip.ts` for the rules themselves.
-export { tooltipModel, tooltipModels, signatureRows, isNativeKey, isPlaceholder, PLACEHOLDER, NATIVE_SIGNATURES } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";

package/dist/tooltip.d.ts

@@ -25,8 +25,25 @@ export interface TooltipPreview {
     call: string;
 }
 export interface TooltipModel {
-    /** `native` renders with a gold perimeter and no cost section -- rule 4. */
-    kind: "ouronet" | "native";
+    /**
+     * Which world this call belongs to -- rule 4.
+     *
+     *   ouronet  the `ouronet-ns` surface. Priced by an INFO_ reader, collects IGNIS.
+     *   stoa     StoaChain's own root-namespace `coin`. No preview, no IGNIS, gas still sponsored.
+     *   kadena   Kadena mainnet's `coin`. A DIFFERENT CHAIN -- different gas, different accounts,
+     *            and nothing about Ouronet applies to it.
+     *
+     * A renderer MUST make these visually distinct, because they differ in what they cost and what
+     * can be previewed. It is NOT told how: OuronetUI uses gold/blue, the Codex violet for Ouronet
+     * and green for Kadena, and all are conformant. Mandating a palette in a package consumed by
+     * applications with their own design languages is a rule that gets ignored, and an ignored rule
+     * weakens the ones that matter.
+     *
+     * RENAMED from `"native"` in 2.0.0. With only two worlds "native" was unambiguous; with three
+     * it silently invited the question "native to WHAT" -- and both candidate answers are a
+     * contract called `coin`.
+     */
+    kind: "ouronet" | "stoa" | "kadena";
     /** fully qualified execution, as it would be typed in a transaction. */
     exec: string;
     /** EVERY execution parameter, in declared order -- rule 1. */
@@ -46,18 +63,42 @@ export interface TooltipModel {
 /** The registry's generic placeholder: an entity id for something that does not exist on chain. */
 export declare const PLACEHOLDER = "\"example\"";
 export declare const isPlaceholder: (rendered: string) => boolean;
-/** A `coin.*` key is StoaChain's root-namespace contract -- outside this registry by design. */
-export declare const isNativeKey: (key: string) => boolean;
 /**
- * STOA-native specs, which the generated registry does not and will not describe.
+ * Off-registry signatures, by chain.
  *
- * They live HERE rather than in each consumer so that both applications render the same
- * signatures. Transcribed from the deployed contract with its line numbers; `tooltip.test.ts`
- * asserts internal consistency and the Pact repo's own test re-reads the source.
+ * Neither chain's `coin` contract is in the generated registry -- that describes `ouronet-ns`
+ * only -- so these are transcribed by hand with their source lines. They live HERE rather than in
+ * each consumer so both applications render the same signatures instead of each keeping a copy.
  *
- *   source: 0_Stoa/coin-contract/coin-live.pact
+ * BOTH CHAINS CALL THEIR CONTRACT `coin`, which is the one real hazard in this table. StoaChain's
+ * uses Ouronet-style names (`C_Transfer`, `C_URV|Stake`); Kadena's uses KIP-0002 kebab-case
+ * (`transfer`, `transfer-create`). No key collides TODAY, and `chainOf` refuses rather than
+ * guesses if one ever does -- the same posture `resolveByName` takes for the four SWP names that
+ * resolve to two modules. Guessing wrong here would price a call on the wrong chain.
  */
-export declare const NATIVE_SIGNATURES: Readonly<Record<string, ReadonlyArray<[string, string]>>>;
+/** StoaChain's root-namespace `coin`.  source: 0_Stoa/coin-contract/coin-live.pact */
+export declare const STOA_SIGNATURES: Readonly<Record<string, ReadonlyArray<[string, string]>>>;
+/**
+ * Kadena mainnet's `coin`.  source: 00_KadenaSandbox/kda-env/kadena/coin-v6.pact
+ *
+ * A DIFFERENT CHAIN. Different gas, different accounts, and nothing about Ouronet's gas station
+ * or IGNIS applies. `transfer-crosschain` is a `defpact` -- a multi-step continuation -- which a
+ * renderer may want to say out loud, because its later steps are not sponsored by anyone.
+ */
+export declare const KADENA_SIGNATURES: Readonly<Record<string, ReadonlyArray<[string, string]>>>;
+/** Back-compat alias. `NATIVE_SIGNATURES` meant StoaChain's before Kadena joined the model. */
+export declare const NATIVE_SIGNATURES: Readonly<Record<string, readonly [string, string][]>>;
+/**
+ * Which chain a key belongs to, or `undefined` for a key this model does not describe.
+ *
+ * Refuses an AMBIGUOUS key rather than picking: both chains have a `coin`, and pricing a call on
+ * the wrong chain is the kind of wrong that looks right.
+ */
+export declare function chainOf(key: string): "ouronet" | "stoa" | "kadena" | undefined;
+/** True for any key this model can describe at all. Arweave and friends answer false -- rule 0. */
+export declare const isOffRegistryKey: (key: string) => boolean;
+/** @deprecated use `chainOf(key) === "stoa"`. Kept so 1.x callers keep compiling. */
+export declare const isNativeKey: (key: string) => boolean;
 /**
  * Everything a renderer needs for one entrypoint.
  *

package/dist/tooltip.js

@@ -22,10 +22,18 @@
  * 3. TYPES GO ON THEIR OWN ROW. `patron:string executor:string ...` doubles the width of the
  *    widest line in the panel. A parallel row under the names costs one line and reads better.
  *
- * 4. NATIVE IS NOT OURONET, and the difference is narrow. A `coin.*` call has no INFO_ preview
- *    and collects no IGNIS. Gas IS still sponsored -- claiming otherwise tells a user they are
- *    about to spend when they are not. Render native with a gold perimeter so the two are never
- *    confused, and say what is actually different rather than inventing a difference.
+ * 4. THREE WORLDS, and they must be distinguishable at a glance. `ouronet` (the ouronet-ns
+ *    surface), `stoa` (StoaChain's own `coin` contract) and `kadena` (Kadena mainnet's `coin`).
+ *    They differ in what they cost and what can be previewed. Only `ouronet` has an INFO_ reader
+ *    and collects IGNIS; gas is sponsored on the Stoa side regardless -- claiming otherwise tells
+ *    a user they are about to spend when they are not. HOW you distinguish them is yours: `kind`
+ *    is the canon, the palette is not.
+ *
+ * 0. CHAINWEB ONLY -- the rule that decides whether a tooltip exists at all. This model describes
+ *    a PACT call on a Chainweb chain: what function, what arguments, what it costs. A button that
+ *    transacts on Arweave, or any non-Chainweb chain, has none of those things in this shape and
+ *    gets NO tooltip of this kind rather than an empty one. An empty panel reads as a failure to
+ *    load; absence reads as "this is a different kind of thing", which is the truth.
  *
  * 5. A GHOST IS NOT DATA. An unresolved argument must LOOK unresolved, and a tooltip whose
  *    arguments are placeholders must not fire the preview read at all: the answer is a foregone
@@ -36,19 +44,21 @@ import { formatForType } from "./format.js";
 /** The registry's generic placeholder: an entity id for something that does not exist on chain. */
 export const PLACEHOLDER = '"example"';
 export const isPlaceholder = (rendered) => rendered === PLACEHOLDER;
-/** A `coin.*` key is StoaChain's root-namespace contract -- outside this registry by design. */
-export const isNativeKey = (key) => key.startsWith("coin.");
 /**
- * STOA-native specs, which the generated registry does not and will not describe.
+ * Off-registry signatures, by chain.
  *
- * They live HERE rather than in each consumer so that both applications render the same
- * signatures. Transcribed from the deployed contract with its line numbers; `tooltip.test.ts`
- * asserts internal consistency and the Pact repo's own test re-reads the source.
+ * Neither chain's `coin` contract is in the generated registry -- that describes `ouronet-ns`
+ * only -- so these are transcribed by hand with their source lines. They live HERE rather than in
+ * each consumer so both applications render the same signatures instead of each keeping a copy.
  *
- *   source: 0_Stoa/coin-contract/coin-live.pact
+ * BOTH CHAINS CALL THEIR CONTRACT `coin`, which is the one real hazard in this table. StoaChain's
+ * uses Ouronet-style names (`C_Transfer`, `C_URV|Stake`); Kadena's uses KIP-0002 kebab-case
+ * (`transfer`, `transfer-create`). No key collides TODAY, and `chainOf` refuses rather than
+ * guesses if one ever does -- the same posture `resolveByName` takes for the four SWP names that
+ * resolve to two modules. Guessing wrong here would price a call on the wrong chain.
  */
-export const NATIVE_SIGNATURES = {
-    // [name, type] pairs, in declared order.
+/** StoaChain's root-namespace `coin`.  source: 0_Stoa/coin-contract/coin-live.pact */
+export const STOA_SIGNATURES = {
     "coin.C_Transfer": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :583
     "coin.C_Transmit": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :593
     "coin.C_TransferAnew": [["sender", "string"], ["receiver", "string"], ["receiver-guard", "guard"], ["amount", "decimal"]], // :586
@@ -59,37 +69,82 @@ export const NATIVE_SIGNATURES = {
     "coin.C_URV|Unstake": [["account", "string"], ["urstoa-amount", "decimal"]], // :1439
     "coin.C_URV|Collect": [["account", "string"]], // :1467
 };
-/** Kadena-shaped, NOT an Ouronet glyph account -- a `coin` call takes k:/c:/u:/w:. */
-const NATIVE_GHOST = {
+/**
+ * Kadena mainnet's `coin`.  source: 00_KadenaSandbox/kda-env/kadena/coin-v6.pact
+ *
+ * A DIFFERENT CHAIN. Different gas, different accounts, and nothing about Ouronet's gas station
+ * or IGNIS applies. `transfer-crosschain` is a `defpact` -- a multi-step continuation -- which a
+ * renderer may want to say out loud, because its later steps are not sponsored by anyone.
+ */
+export const KADENA_SIGNATURES = {
+    "coin.transfer": [["sender", "string"], ["receiver", "string"], ["amount", "decimal"]], // :329
+    "coin.transfer-create": [["sender", "string"], ["receiver", "string"], ["receiver-guard", "guard"], ["amount", "decimal"]], // :356
+    "coin.transfer-crosschain": [["sender", "string"], ["receiver", "string"], ["receiver-guard", "guard"], ["target-chain", "string"], ["amount", "decimal"]], // :528 (defpact)
+    "coin.create-account": [["account", "string"], ["guard", "guard"]], // :278
+    "coin.rotate": [["account", "string"], ["new-guard", "guard"]], // :307
+};
+/** Back-compat alias. `NATIVE_SIGNATURES` meant StoaChain's before Kadena joined the model. */
+export const NATIVE_SIGNATURES = STOA_SIGNATURES;
+/**
+ * Which chain a key belongs to, or `undefined` for a key this model does not describe.
+ *
+ * Refuses an AMBIGUOUS key rather than picking: both chains have a `coin`, and pricing a call on
+ * the wrong chain is the kind of wrong that looks right.
+ */
+export function chainOf(key) {
+    const inStoa = key in STOA_SIGNATURES;
+    const inKda = key in KADENA_SIGNATURES;
+    if (inStoa && inKda)
+        throw new Error(`tooltip: "${key}" is declared for BOTH StoaChain and Kadena. Both chains have a \`coin\` ` +
+            `contract, so this cannot be resolved by name -- and choosing wrong would describe a call ` +
+            `on the wrong chain. Remove the duplicate or key it explicitly.`);
+    if (inStoa)
+        return "stoa";
+    if (inKda)
+        return "kadena";
+    return tryGetEntrypoint(key) ? "ouronet" : undefined;
+}
+/** True for any key this model can describe at all. Arweave and friends answer false -- rule 0. */
+export const isOffRegistryKey = (key) => key in STOA_SIGNATURES || key in KADENA_SIGNATURES;
+/** @deprecated use `chainOf(key) === "stoa"`. Kept so 1.x callers keep compiling. */
+export const isNativeKey = (key) => key in STOA_SIGNATURES;
+/** StoaChain `coin` accounts are k:/c:/u:/w: shaped, NOT Ouronet glyph strings. */
+const STOA_GHOST = {
+    string: '"k:1ac0d8b0a4f6e2c9d3b5a7e1f4c6089d2b3e5a7c9f1d3b5e7a9c1f3d5b7e9a1c"',
+    decimal: "1.0",
+    integer: "1",
+    bool: "false",
+    guard: '(read-keyset "ks")',
+};
+/** Kadena accounts are `k:` principals. Same shape, different chain -- and a different balance. */
+const KADENA_GHOST = {
     string: '"k:1ac0d8b0a4f6e2c9d3b5a7e1f4c6089d2b3e5a7c9f1d3b5e7a9c1f3d5b7e9a1c"',
     decimal: "1.0",
     integer: "1",
     bool: "false",
     guard: '(read-keyset "ks")',
 };
-function nativeModel(key, values) {
-    // Callers reach this only through `tooltipModel`, which has already rejected an unknown key.
-    // Asserted rather than assumed: a non-null assertion here would make a future direct caller
-    // fail with a property access on undefined instead of a sentence naming the problem.
-    const sig = NATIVE_SIGNATURES[key];
+function offRegistryModel(key, kind, values) {
+    const sig = (kind === "stoa" ? STOA_SIGNATURES : KADENA_SIGNATURES)[key];
     if (!sig)
-        throw new Error(`nativeModel: no signature for "${key}"`);
+        throw new Error(`offRegistryModel: no signature for "${key}"`);
+    const ghost = kind === "stoa" ? STOA_GHOST : KADENA_GHOST;
     return {
-        kind: "native",
+        kind,
         exec: key,
         slots: sig.map(([name, type], i) => ({
             index: i + 1,
             name,
             type,
-            value: values[name] ?? NATIVE_GHOST[type] ?? PLACEHOLDER,
-            isPlaceholder: values[name] === undefined && NATIVE_GHOST[type] === undefined,
+            value: values[name] ?? ghost[type] ?? PLACEHOLDER,
+            isPlaceholder: values[name] === undefined && ghost[type] === undefined,
             isPreflightFed: false,
-            // A guard is never prefillable, native or not. Same rule, same reason.
+            // A guard is never prefillable, on any chain. Same rule, same reason.
             prefillable: type !== "guard",
         })),
-        // No preview, deliberately. Rule 4: nothing on `coin` prices a call, so there is no cost to
-        // show and a renderer must say that rather than leaving an empty panel that reads as a
-        // failed load.
+        // No preview, deliberately. Neither chain's `coin` has a reader that prices a call, so there
+        // is no cost to show -- and a renderer must SAY that rather than leaving an empty panel,
+        // which reads as "the price failed to load".
         shouldRead: false,
         warnings: [],
     };
@@ -106,12 +161,11 @@ function nativeModel(key, values) {
  * must never take down the page it annotates.
  */
 export function tooltipModel(key, values = {}) {
-    if (isNativeKey(key)) {
-        if (!NATIVE_SIGNATURES[key])
-            throw new Error(`tooltipModel: unknown native key "${key}". ` +
-                `Known: ${Object.keys(NATIVE_SIGNATURES).join(", ")}`);
-        return nativeModel(key, values);
-    }
+    const chain = chainOf(key);
+    if (chain === "stoa" || chain === "kadena")
+        return offRegistryModel(key, chain, values);
+    if (chain === undefined && isOffRegistryKey(key))
+        throw new Error(`tooltipModel: "${key}" matched no chain. This is a bug in chainOf.`);
     const ep = getEntrypoint(key); // throws, and names near matches, on a stale key
     const warnings = [];
     const use = ep.ghost.use ?? {};
@@ -212,7 +266,7 @@ export function tooltipModel(key, values = {}) {
  */
 export function tooltipModels(keys, values = {}) {
     return keys
-        .filter((k) => isNativeKey(k) ? Boolean(NATIVE_SIGNATURES[k]) : Boolean(tryGetEntrypoint(k)))
+        .filter((k) => chainOf(k) !== undefined)
         .map((k) => tooltipModel(k, values));
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouronet/talos-registry",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "The Ouronet callable surface, generated from the deployed contracts. Supply values; never type a function name.",
   "type": "module",
   "main": "./dist/index.js",