@cardano-slips/flow 0.0.2 → 0.1.0

package/src/discovery.ts

@@ -0,0 +1,92 @@
+/**
+ * What is injected at `window.cardano`, read on demand. Nothing here touches a
+ * browser global at module scope: this SDK is imported by server-rendered pages
+ * we do not control, and a module that reads `window` while loading breaks them
+ * before any of it runs (ADR-0004).
+ */
+import { type Cip30Provider, isCip30Provider } from "./cip30.js"
+import { knownWallet } from "./registry.js"
+
+export type DiscoveredWallet = {
+  /** The `window.cardano` key. What `connectWallet` is asked for. */
+  readonly key: string
+  readonly name: string
+  readonly icon: string | undefined
+  readonly apiVersion: string
+  /** CIP numbers the provider says it supports, before `enable()` negotiates any of them. */
+  readonly extensions: ReadonlyArray<number>
+  /** Present only for a wallet in the registry. */
+  readonly install: string | undefined
+  readonly provider: Cip30Provider
+}
+
+/** Anything with a `cardano` namespace: a `Window`, or a stand-in in a test. */
+export type WalletHost = { readonly cardano?: unknown }
+
+const namespaceOf = (host: unknown): Record<string, unknown> | undefined => {
+  if (typeof host !== "object" || host === null) return undefined
+  const cardano = (host as Record<string, unknown>).cardano
+  if (typeof cardano !== "object" || cardano === null) return undefined
+  return cardano as Record<string, unknown>
+}
+
+const extensionsOf = (provider: Cip30Provider): ReadonlyArray<number> =>
+  (provider.supportedExtensions ?? [])
+    .filter((extension) => typeof extension?.cip === "number")
+    .map((extension) => extension.cip)
+
+const describe = (key: string, provider: Cip30Provider): DiscoveredWallet => {
+  const known = knownWallet(key)
+  return {
+    key,
+    // The registry wins over the injected name so one extension reads the same
+    // way in every list; an unknown wallet still gets to name itself.
+    name: known?.name ?? (provider.name === "" ? key : provider.name),
+    icon: typeof provider.icon === "string" && provider.icon !== "" ? provider.icon : undefined,
+    apiVersion: provider.apiVersion,
+    extensions: extensionsOf(provider),
+    install: known?.install,
+    provider
+  }
+}
+
+/**
+ * Every CIP-30 provider in the namespace, by display name. Returns an empty
+ * list where there is no namespace at all — a page with no wallet and a page
+ * rendered on a server are the same case to a caller, and neither is an error.
+ */
+export const discoverWallets = (host: unknown = globalThis): ReadonlyArray<DiscoveredWallet> => {
+  const namespace = namespaceOf(host)
+  if (namespace === undefined) return []
+
+  const found = new Map<string, DiscoveredWallet>()
+  for (const key of Object.keys(namespace)) {
+    const provider = namespace[key]
+    if (isCip30Provider(provider)) found.set(key, describe(key, provider))
+  }
+
+  // An extension injecting two keys is one wallet: listing it twice asks the
+  // person to choose between a wallet and itself.
+  for (const key of [...found.keys()]) {
+    const alias = knownWallet(key)?.aliasOf
+    if (alias !== undefined && found.has(alias)) found.delete(key)
+  }
+
+  return [...found.values()].sort(
+    (left, right) => left.name.localeCompare(right.name) || left.key.localeCompare(right.key)
+  )
+}
+
+/**
+ * Whatever sits under the key, connector or not. Lets a caller separate a
+ * wallet that is not installed from one that is and does not speak CIP-30.
+ */
+export const injectedUnder = (key: string, host: unknown = globalThis): unknown => namespaceOf(host)?.[key]
+
+/** The provider under one key, or `undefined` where nothing usable is there. */
+export const findWallet = (key: string, host: unknown = globalThis): DiscoveredWallet | undefined => {
+  const namespace = namespaceOf(host)
+  if (namespace === undefined) return undefined
+  const provider = namespace[key]
+  return isCip30Provider(provider) ? describe(key, provider) : undefined
+}

package/src/index.ts

@@ -1,11 +1,16 @@
 /**
  * The public entry point of `@cardano-slips/flow`. The `exports` map exposes
  * this module and nothing else, so moving a file is never a breaking change.
- *
- * Two properties hold as the rest of the package arrives. It refuses but does
- * not decide — the comparison is `verifier`'s, and a mismatch renders as a
- * block with no override path to write. And it does not own the page it is
- * dropped into: no fixed positioning, no assumptions about the document, and
- * colours only from the custom properties in `tokens.css`.
  */
-export {}
+export type { NetworkId, WalletAddress } from "./address.js"
+export { readWalletAddress } from "./address.js"
+export type { CborHex, Cip30Api, Cip30ApiError, Cip30Provider, Paginate, SignedData } from "./cip30.js"
+export { apiErrorNames, describeApiError, isCip30Api, isCip30Provider, readApiError, REFUSED } from "./cip30.js"
+export type { ConnectedWallet, ConnectOptions } from "./connect.js"
+export { connectWallet, networkIdFor } from "./connect.js"
+export type { DiscoveredWallet, WalletHost } from "./discovery.js"
+export { discoverWallets, findWallet, injectedUnder } from "./discovery.js"
+export type { KnownWallet } from "./registry.js"
+export { knownWallet, knownWallets } from "./registry.js"
+export type { ConnectRefusal } from "./wallet-error.js"
+export { connectRefusals, slipErrorCodeFor, WalletConnectError } from "./wallet-error.js"

package/src/registry.ts

@@ -0,0 +1,32 @@
+/**
+ * Display metadata for the wallets we know by name. Ours to maintain — the one
+ * cost ADR-0004 accepted — and deliberately thin: a key an entry does not cover
+ * still connects, using the name and icon the extension injects.
+ *
+ * `install` is the wallet's own home page rather than a store listing, because
+ * a store listing is per browser and goes stale on its own schedule.
+ */
+export type KnownWallet = {
+  readonly key: string
+  readonly name: string
+  readonly install: string
+  /** A second key the same extension injects. Hidden while the primary is present. */
+  readonly aliasOf?: string
+}
+
+export const knownWallets: ReadonlyArray<KnownWallet> = [
+  { key: "lace", name: "Lace", install: "https://www.lace.io" },
+  { key: "eternl", name: "Eternl", install: "https://eternl.io" },
+  { key: "ccvault", name: "Eternl", install: "https://eternl.io", aliasOf: "eternl" },
+  { key: "vespr", name: "VESPR", install: "https://vespr.xyz" },
+  { key: "typhoncip30", name: "Typhon", install: "https://typhonwallet.io" },
+  { key: "nami", name: "Nami", install: "https://www.namiwallet.io" },
+  { key: "begin", name: "Begin", install: "https://begin.is" },
+  { key: "nufi", name: "NuFi", install: "https://nu.fi" },
+  { key: "gerowallet", name: "GeroWallet", install: "https://gerowallet.io" },
+  { key: "yoroi", name: "Yoroi", install: "https://yoroi-wallet.com" }
+]
+
+const byKey = new Map(knownWallets.map((wallet) => [wallet.key, wallet]))
+
+export const knownWallet = (key: string): KnownWallet | undefined => byKey.get(key)

package/src/tokens.css

@@ -0,0 +1,184 @@
+/*
+ * Every colour, type role, step of spacing and radius the client uses, taken
+ * from `1 · Tokens` on the design sheet. This is the only file in the package
+ * that writes a colour — `test/no-hard-coded-colours.test.ts` fails if another
+ * one does, and `test/tokens.test.ts` re-runs the sheet's contrast audit
+ * against these values.
+ *
+ * Scoped to a class, never `:root`: this ships into pages we do not own, and a
+ * package that writes tokens onto the document redefines whatever the host
+ * already called `--ink`. Put `slip-root` on the element that wraps the Slip.
+ *
+ * There is no reset here and no rule that selects an element. Nothing sets a
+ * font-family on anything — a component reads `var(--font-text)` — so a host
+ * page's own stack stays where it is until something of ours asks for a token.
+ *
+ * Three families of surface, and the difference is the point:
+ *   page / card    the ordinary ground, and what lifts off it
+ *   vault-*        the transaction preview, which separates itself by surface
+ *                  and border rather than by being dark
+ *   dark-*         code blocks and the Open Graph card, dark in both themes
+ */
+
+.slip-root {
+  color-scheme: light;
+
+  /* Surfaces. Depth is a border, never a shadow: there is no shadow token. */
+  --page: #f6f8fe; /* never pure white */
+  --card: #ffffff;
+  --subtle: rgba(114, 142, 243, 0.08); /* hover, chips */
+  --skeleton: rgba(114, 142, 243, 0.14);
+  --border: rgba(18, 23, 33, 0.12);
+  --divider: rgba(18, 23, 33, 0.1);
+
+  /* Ink */
+  --ink: #121721;
+  --muted: #5c6a9c;
+
+  /*
+   * The split rule: --accent-fill reaches 3.05:1 on the card and is a fill —
+   * it never carries text below 24px. An accent-coloured word uses
+   * --accent-text. It stays a fill in the dark theme too, where it would
+   * otherwise clear AA, because the rule is about what the colour is for.
+   */
+  --accent-fill: #728ef3;
+  --accent-text: #2f4bc4; /* links */
+  --accent-action: #4361e8; /* button background */
+  --accent-hover: #2f4bc4;
+  --accent-deep: #0c288d; /* headings */
+  --on-accent: #ffffff; /* anything drawn on --accent-action */
+  --focus: #4361e8;
+
+  /* Semantic, and rare. A page that colours everything says nothing. */
+  --pos: #1f7a5c; /* positive, refundable */
+  --warn: #8c5a12;
+  --bad: #b3261e;
+  --bad-tint: rgba(179, 38, 30, 0.06);
+  --bad-line: rgba(179, 38, 30, 0.24);
+  --warn-tint: rgba(233, 180, 76, 0.16);
+  --warn-line: rgba(233, 180, 76, 0.5);
+
+  /* The alternating rows of the effects list, on and off. */
+  --stripe-a: rgba(114, 142, 243, 0.16);
+  --stripe-b: rgba(114, 142, 243, 0.05);
+  --stripe-off-a: rgba(92, 106, 156, 0.12);
+  --stripe-off-b: rgba(92, 106, 156, 0.04);
+
+  /*
+   * The transaction preview. Its own family because it is the surface that
+   * judges the publisher, and `10 · Chrome rules` fixes it whoever hosts the
+   * page. It follows the theme like everything else.
+   */
+  --vault: #ffffff;
+  --vault-ink: #121721;
+  --vault-muted: #5c6a9c;
+  --vault-surface: rgba(114, 142, 243, 0.08);
+  --vault-border: rgba(18, 23, 33, 0.12);
+  --vault-chip: rgba(114, 142, 243, 0.16);
+  --vault-rule: rgba(114, 142, 243, 0.8);
+  --vault-pos: #1f7a5c;
+  --vault-warn: #8c5a12;
+  --vault-bad: #b3261e;
+  --vault-bad-tint: rgba(179, 38, 30, 0.06);
+  --vault-bad-line: rgba(179, 38, 30, 0.32);
+  --vault-bad-chip: rgba(179, 38, 30, 0.1);
+  --vault-warn-tint: rgba(233, 180, 76, 0.14);
+  --vault-warn-line: rgba(233, 180, 76, 0.55);
+
+  /*
+   * Dark in both themes, and nowhere else: code blocks in the docs and the
+   * Open Graph card. Deliberately absent from the dark theme below — a value
+   * that is fixed cannot also follow.
+   */
+  --dark-bg: #121721;
+  --dark-surface: rgba(255, 255, 255, 0.08);
+  --dark-text: #ffffff;
+  --dark-muted: #ccd6ff;
+
+  /* Type. Each stack ends in a generic family, so a missing webfont degrades. */
+  --font-display: Poppins, system-ui, sans-serif;
+  --font-text: Figtree, system-ui, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, monospace;
+
+  /* Whole roles, so half a role cannot be applied without the other half. */
+  --type-h1: 700 44px/48px var(--font-display);
+  --type-h1-tracking: -0.01em;
+  --type-card-title: 700 18px/24px var(--font-display);
+  --type-numeral: 700 26px/32px var(--font-display); /* a figure is always Poppins 700 */
+  --type-body: 500 16px/24px var(--font-text);
+  --type-button: 500 14px/20px var(--font-text);
+  --type-button-tracking: 0.1px;
+  --type-label: 500 13px var(--font-text);
+  --type-mono: 400 12px/20px var(--font-mono); /* addresses, hashes, the tx block */
+
+  /* Spacing, on a 4px base. */
+  --space-4: 4px;
+  --space-8: 8px;
+  --space-12: 12px;
+  --space-16: 16px;
+  --space-20: 20px;
+  --space-24: 24px;
+  --space-32: 32px;
+  --space-48: 48px;
+
+  --radius-chip: 6px;
+  --radius-control: 8px;
+  --radius-card: 12px;
+}
+
+/*
+ * The dark theme rebinds the roles rather than adding a second vocabulary. A
+ * component writes var(--ink) once and is correct on both grounds; a component
+ * choosing between a light token and a dark one is a component deciding the
+ * rule, and two of them will decide it differently.
+ *
+ * Whether dark follows the operating system is not settled by the sheet, so it
+ * is not decided here: the attribute is the only way in.
+ */
+.slip-root[data-theme="dark"] {
+  color-scheme: dark;
+
+  --page: #121721; /* the brand dark */
+  --card: #1b2231; /* lifted off the page */
+  --subtle: rgba(114, 142, 243, 0.16);
+  --skeleton: rgba(114, 142, 243, 0.18);
+  --border: rgba(255, 255, 255, 0.14);
+  --divider: rgba(255, 255, 255, 0.1);
+
+  --ink: #ffffff;
+  --muted: #ccd6ff;
+
+  --accent-text: #a8bcff;
+  --accent-hover: #5c79ee;
+  --accent-deep: #a8bcff;
+  --focus: #a8bcff;
+
+  --pos: #5fd1a6;
+  --warn: #e9b44c;
+  --bad: #ffa39b;
+  --bad-tint: rgba(255, 163, 155, 0.1);
+  --bad-line: rgba(255, 163, 155, 0.4);
+  --warn-tint: rgba(233, 180, 76, 0.14);
+  --warn-line: rgba(233, 180, 76, 0.45);
+
+  --stripe-a: rgba(114, 142, 243, 0.26);
+  --stripe-b: rgba(114, 142, 243, 0.1);
+  --stripe-off-a: rgba(204, 214, 255, 0.16);
+  --stripe-off-b: rgba(204, 214, 255, 0.05);
+
+  --vault: #080b12; /* still the gravest surface */
+  --vault-ink: #ffffff;
+  --vault-muted: #ccd6ff;
+  --vault-surface: rgba(255, 255, 255, 0.08);
+  --vault-border: rgba(255, 255, 255, 0.14);
+  --vault-chip: rgba(114, 142, 243, 0.24);
+  --vault-rule: rgba(114, 142, 243, 0.5);
+  --vault-pos: #5fd1a6;
+  --vault-warn: #e9b44c;
+  --vault-bad: #ffa39b;
+  --vault-bad-tint: rgba(255, 163, 155, 0.08);
+  --vault-bad-line: rgba(255, 163, 155, 0.45);
+  --vault-bad-chip: rgba(255, 163, 155, 0.2);
+  --vault-warn-tint: rgba(233, 180, 76, 0.08);
+  --vault-warn-line: rgba(233, 180, 76, 0.45);
+}

package/src/wallet-error.ts

@@ -0,0 +1,68 @@
+/**
+ * Why a wallet did not reach a usable connection. One error, a closed set of
+ * refusals, because the client renders a state per refusal and a state nothing
+ * can produce is a screen nobody sees.
+ */
+import { type ClientErrorCode } from "@cardano-slips/core"
+import { Data } from "effect"
+
+import { type Cip30ApiError } from "./cip30.js"
+
+export type ConnectRefusal =
+  /** Nothing is injected under this key. The wallet was uninstalled, or never there. */
+  | "NotInjected"
+  /** Something is under the key that does not implement the connector. */
+  | "NotCip30"
+  /** The person declined the connection — CIP-30 `APIError` `-3`. Not a fault. */
+  | "Refused"
+  /** `enable()` rejected for another reason, or returned something that is not the API. */
+  | "EnableFailed"
+  /** A question the wallet did not answer, or answered with something that is not what it claims. */
+  | "Unreadable"
+  /** The wallet is on a different network from the one the Slip declares. */
+  | "WrongNetwork"
+
+/**
+ * Exhaustive by type: adding a refusal above without listing it here fails to
+ * compile, and `test/connect.test.ts` fails if any of them stops being reachable.
+ */
+export const connectRefusals: Readonly<Record<ConnectRefusal, true>> = {
+  NotInjected: true,
+  NotCip30: true,
+  Refused: true,
+  EnableFailed: true,
+  Unreadable: true,
+  WrongNetwork: true
+}
+
+/**
+ * Only the network disagreement has a spec code, because only it is a failure
+ * of the exchange the spec describes. The rest are states of a browser
+ * extension, and dressing them in a protocol code would say the endpoint
+ * answered when nothing was ever sent.
+ */
+export const slipErrorCodeFor = (refusal: ConnectRefusal): ClientErrorCode | undefined =>
+  refusal === "WrongNetwork" ? "WRONG_NETWORK" : undefined
+
+/** `cip30` is the wallet's own `{ code, info }`, kept so a `-3` stays distinguishable from a crash. */
+export class WalletConnectError extends Data.TaggedError("WalletConnectError")<{
+  readonly refusal: ConnectRefusal
+  readonly key: string
+  readonly detail: string
+  readonly cip30?: Cip30ApiError
+}> {
+  override get message(): string {
+    return `${this.key}: ${this.detail}`
+  }
+
+  get code(): ClientErrorCode | undefined {
+    return slipErrorCodeFor(this.refusal)
+  }
+}
+
+export const refuse = (
+  refusal: ConnectRefusal,
+  key: string,
+  detail: string,
+  cip30?: Cip30ApiError
+): WalletConnectError => new WalletConnectError({ refusal, key, detail, ...(cip30 === undefined ? {} : { cip30 }) })