@cardano-slips/flow 0.1.0 → 0.3.0

package/src/slip-card.tsx

@@ -0,0 +1,244 @@
+"use client"
+
+/**
+ * The rendered face of a Slip link — `2 · Action card` on the design sheet.
+ * It renders what the endpoint declared and collects what the endpoint asked
+ * for; it makes no claim about the transaction, which is the effects panel's
+ * job and is checked against the bytes rather than against this card.
+ *
+ * The Slip is assumed to have been decoded and passed `checkTemplates`: a
+ * response with a placeholder naming no parameter is one a client never renders.
+ */
+import { checkValues, fillHref, type LinkedAction, type ParameterValues, type Slip } from "@cardano-slips/core"
+import { Either } from "effect"
+import { useState } from "react"
+
+import { actionLabel, actionsOf, blockedLabel, closureOf, monogramOf, originOf, valuesFor } from "./card.js"
+import { type FieldError, ParameterForm } from "./parameter-form.js"
+
+/** What the person chose, ready to `POST`. */
+export type SlipSubmission = {
+  readonly action: LinkedAction
+  /** Only what this action asked for. A caller is handed no answer it did not request. */
+  readonly values: ParameterValues
+  /** Absolute, with every placeholder percent-encoded, so no typed value can move the request. */
+  readonly href: string
+}
+
+export type SlipCardProps = {
+  readonly slip: Slip
+  /**
+   * Where the metadata came from. Every `href` resolves against it and its host
+   * is the publisher the card names, so the card cannot be rendered without it.
+   */
+  readonly discoveryUrl: string
+  readonly onSubmit?: (submission: SlipSubmission) => void
+  /**
+   * What the endpoint refused, by parameter name. The only failure that lands
+   * on a field instead of replacing the card, because there is something to fix.
+   * It is the caller's to clear, since only the caller knows which answer the
+   * endpoint was refusing.
+   */
+  readonly rejected?: Readonly<Record<string, FieldError>>
+  /** True while a request is in flight: every button stops taking presses. */
+  readonly busy?: boolean
+  /** Prefixes generated ids, so two cards on one page do not collide. */
+  readonly idPrefix?: string
+}
+
+/** The line that is the whole point of the card, and the reason it is worth pressing. */
+const promise = "You'll see the exact effects, checked against this card, before you sign."
+
+/** Nothing to choose between means the one action is already the open one. */
+const opened = (count: number): number | undefined => (count === 1 ? 0 : undefined)
+
+export const SlipCard = ({
+  slip,
+  discoveryUrl,
+  onSubmit,
+  rejected,
+  busy = false,
+  idPrefix = "slip"
+}: SlipCardProps): React.JSX.Element => {
+  const actions = actionsOf(slip, discoveryUrl)
+
+  const [values, setValues] = useState<ParameterValues>({})
+  // Errors stay quiet until a send is attempted: a card that opens red is
+  // scolding someone for not having typed yet.
+  const [attempted, setAttempted] = useState(false)
+  const [open, setOpen] = useState<number | undefined>(opened(actions.length))
+  const [failedIcon, setFailedIcon] = useState<string | undefined>(undefined)
+
+  // Resetting during render is React's own answer to a prop moving out from
+  // under the state derived from it. A second Slip must not open pre-filled
+  // with the first one's answers, and remembering to pass a `key` is not a
+  // thing to leave to whoever embeds this.
+  const [shown, setShown] = useState(discoveryUrl)
+  if (shown !== discoveryUrl) {
+    setShown(discoveryUrl)
+    setValues({})
+    setAttempted(false)
+    setOpen(opened(actions.length))
+    setFailedIcon(undefined)
+  }
+
+  const closed = slip.disabled === true
+  const parameters = (open === undefined ? undefined : actions[open]?.parameters) ?? []
+  const issues = checkValues(parameters, values)
+  const blocked = attempted && issues.length > 0
+
+  // `??=` would be wrong here: a parameter may be called `constructor`, and a
+  // plain object already answers to that with something that is not nullish.
+  const errors: Record<string, FieldError> = {}
+  const note = (name: string, error: FieldError): void => {
+    if (!Object.hasOwn(errors, name)) errors[name] = error
+  }
+  if (attempted) for (const issue of issues) note(issue.name, { message: issue.message })
+  for (const [name, error] of Object.entries(rejected ?? {})) note(name, error)
+
+  const press = (index: number): void => {
+    const action = actions[index]
+
+    // The spec: an action without parameters is submitted as soon as it is
+    // chosen. One that has them opens its form instead of sending blind.
+    if (action.parameters !== undefined && index !== open) {
+      setOpen(index)
+      setAttempted(false)
+      return
+    }
+
+    const target = fillHref(action, values, discoveryUrl)
+    if (Either.isLeft(target)) {
+      setAttempted(true)
+      return
+    }
+    onSubmit?.({ action, values: valuesFor(action, values), href: target.right })
+  }
+
+  const monogram = monogramOf(discoveryUrl)
+  const origin = originOf(discoveryUrl)
+
+  return (
+    <div className="slip-root slip-card" data-closed={closed ? "" : undefined} data-busy={busy ? "" : undefined}>
+      <div className="slip-card__head">
+        <div className="slip-card__icon">
+          {failedIcon !== slip.icon ? (
+            <img className="slip-card__image" src={slip.icon} alt="" onError={() => setFailedIcon(slip.icon)} />
+          ) : monogram === undefined ? (
+            <span className="slip-card__pattern" />
+          ) : (
+            <span className="slip-card__monogram">{monogram}</span>
+          )}
+        </div>
+        <div className="slip-card__identity">
+          <h2 className="slip-card__title">{slip.title}</h2>
+          {origin === undefined ? undefined : <span className="slip-card__origin">{origin}</span>}
+        </div>
+      </div>
+
+      {/* Plain text by the spec: a description carries no markup, so none is parsed. */}
+      <p className="slip-card__description">{slip.description}</p>
+
+      {parameters.length === 0 ? undefined : (
+        <ParameterForm
+          parameters={parameters}
+          values={values}
+          errors={errors}
+          idPrefix={idPrefix}
+          onChange={(name, value) => setValues((held) => ({ ...held, [name]: value }))}
+        />
+      )}
+
+      <div className="slip-card__actions">
+        {actions.map((action, index) => {
+          const closure = closureOf(slip, action)
+          const stopped = index === (open ?? 0) && blocked
+          return (
+            <button
+              key={index}
+              type="button"
+              className="slip-card__action"
+              data-primary={index === (open ?? 0) ? "" : undefined}
+              disabled={busy || closure !== undefined || stopped}
+              onClick={() => press(index)}
+            >
+              {stopped ? blockedLabel(issues) : actionLabel(slip, action, values)}
+            </button>
+          )
+        })}
+      </div>
+
+      {/*
+        A closed Slip states its reason once, however many actions it carries;
+        an open one states the reason of each option that is closed on its own.
+        Neither hides the action: a shared link is seen by many people at once.
+      */}
+      {closed ? (
+        <p className="slip-card__reason">{slip.reason?.message}</p>
+      ) : (
+        actions.map((action, index) =>
+          action.disabled === true && action.reason !== undefined ? (
+            <p className="slip-card__reason" key={index}>
+              {action.reason.message}
+            </p>
+          ) : undefined
+        )
+      )}
+
+      {closed ? undefined : <p className="slip-card__note">{promise}</p>}
+    </div>
+  )
+}
+
+/** The same box and the same rhythm while the metadata is in flight, so nothing shifts when it lands. */
+export const SlipCardSkeleton = (): React.JSX.Element => (
+  <div className="slip-root slip-card slip-card--loading" role="status" aria-busy="true">
+    <span className="slip-hidden">Loading this Slip</span>
+    <div className="slip-card__head">
+      <span className="slip-skeleton slip-skeleton--icon" />
+      <div className="slip-card__identity">
+        <span className="slip-skeleton slip-skeleton--title" />
+        <span className="slip-skeleton slip-skeleton--origin" />
+      </div>
+    </div>
+    <div className="slip-skeleton__lines">
+      <span className="slip-skeleton slip-skeleton--line" />
+      <span className="slip-skeleton slip-skeleton--line slip-skeleton--short" />
+    </div>
+    <span className="slip-skeleton slip-skeleton--action" />
+  </div>
+)
+
+export type SlipCardErrorProps = {
+  /** The endpoint that did not answer, in full: the person is being asked to judge it. */
+  readonly url: string
+  readonly message: string
+  readonly onRetry?: () => void
+}
+
+/**
+ * The endpoint did not answer, or answered with something that is not a Slip.
+ * This replaces the card rather than landing on a field, because there is
+ * nothing here for the person to fix.
+ */
+export const SlipCardError = ({ url, message, onRetry }: SlipCardErrorProps): React.JSX.Element => (
+  <div className="slip-root slip-card slip-card--failed" role="alert">
+    <div className="slip-card__head">
+      <span className="slip-card__alarm" aria-hidden="true">
+        !
+      </span>
+      <div className="slip-card__identity">
+        <h2 className="slip-card__title">This Slip didn't load</h2>
+        <span className="slip-card__origin">{url}</span>
+      </div>
+    </div>
+    <p className="slip-card__description">{message}</p>
+    {onRetry === undefined ? undefined : (
+      <div className="slip-card__actions">
+        <button type="button" className="slip-card__action" onClick={onRetry}>
+          Try again
+        </button>
+      </div>
+    )}
+  </div>
+)

package/src/tokens.css

@@ -2,114 +2,145 @@
  * 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.
+ * one does, and `test/tokens.test.ts` re-runs the contrast audit against these
+ * values rather than trusting the numbers printed on the sheet.
  *
  * 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
+ * font-family on anything — a component reads a `--type-*` role — 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:
+ * One theme. The sheet collapsed an earlier light/dark pair into a single
+ * ground that leans light, so there is no `data-theme` and no role that means
+ * two things. What carries the weight instead is that the three surface
+ * families are genuinely different surfaces:
+ *
  *   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
+ *   vault-*        the transaction preview, on slate — the one grave surface,
+ *                  and the reason the rest can stay bright
+ *   dark-*         code blocks and the Open Graph card, fixed wherever they
+ *                  appear because neither sits on a ground we control
  */
 
 .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);
+  --page: #ebeef8; /* never pure white */
+  --card: #fcfdff;
+  --subtle: rgba(90, 110, 205, 0.09); /* hover, chips */
+  --skeleton: rgba(90, 110, 205, 0.14);
+  --border: rgba(20, 26, 40, 0.13);
+  --divider: rgba(20, 26, 40, 0.1);
 
   /* Ink */
-  --ink: #121721;
-  --muted: #5c6a9c;
+  --ink: #141a26;
+  --muted: #56628a;
 
   /*
-   * 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.
+   * The split rule: --accent-fill is a fill and never carries text below 24px.
+   * An accent-coloured word uses --accent-text. It clears AA on the vault and
+   * is still held to fills there, because the rule is about what the colour is
+   * for and not about the ratio it happens to reach.
    */
   --accent-fill: #728ef3;
-  --accent-text: #2f4bc4; /* links */
-  --accent-action: #4361e8; /* button background */
-  --accent-hover: #2f4bc4;
+  --accent-text: #123cd3; /* links */
+  --accent-action: #123cd3; /* the outline and the label of a button */
+  --accent-hover: #0e2fa6;
   --accent-deep: #0c288d; /* headings */
-  --on-accent: #ffffff; /* anything drawn on --accent-action */
-  --focus: #4361e8;
+  --on-accent: #ffffff; /* anything drawn on a filled accent */
+  --focus: #123cd3;
+
+  /* The accent lightened for slate, where #123cd3 disappears into the ground. */
+  --accent-on-slate: #8fa9ff;
 
   /* 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);
+  --pos: #065708; /* value arriving */
+  --warn: #7a5200; /* held, taken, caution */
+  --bad: #d20a19; /* problem, blocked */
+  --bad-tint: rgba(210, 10, 25, 0.06);
+  --bad-line: rgba(210, 10, 25, 0.24);
+  --warn-tint: rgba(254, 206, 82, 0.22);
+  --warn-line: rgba(254, 206, 82, 0.85);
+  --warn-fill: #fece52; /* the warning as a fill, never as a word on a light ground */
+  --on-warn: #3a2600; /* words on the warning fill: the testnet bar */
 
   /* 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);
+  --stripe-a: rgba(90, 110, 205, 0.16);
+  --stripe-b: rgba(90, 110, 205, 0.05);
+  --stripe-off-a: rgba(86, 98, 138, 0.12);
+  --stripe-off-b: rgba(86, 98, 138, 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.
+   * judges the publisher, and `13 · Chrome rules` fixes it whoever hosts the
+   * page. Slate rather than black: it has to read as a distinct surface, not
+   * as a hole in the page.
    */
-  --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);
+  --vault: #222b3d;
+  --vault-ink: #f5f7ff;
+  --vault-muted: #c3cdec;
+  --vault-surface: rgba(255, 255, 255, 0.09);
+  --vault-border: rgba(255, 255, 255, 0.16);
+  --vault-chip: rgba(168, 188, 255, 0.22);
+  --vault-rule: rgba(168, 188, 255, 0.7);
+  --vault-pos: #6fcb72;
+  --vault-warn: #fece52;
+  /*
+   * #ff5247 on the sheet, lightened here: that value measures 4.42:1 on the
+   * vault and the sheet's own row calls it a pass. This is the colour the
+   * mismatch block is written in, so it clears AA or it does not ship.
+   */
+  --vault-bad: #ff5a50;
+  --vault-bad-tint: rgba(210, 10, 25, 0.16);
+  --vault-bad-line: rgba(255, 82, 71, 0.55);
+  --vault-bad-chip: rgba(210, 10, 25, 0.28);
+  --vault-warn-tint: rgba(254, 206, 82, 0.14);
+  --vault-warn-line: rgba(254, 206, 82, 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.
+   * Code blocks in the docs and the Open Graph card. Both land on a ground we
+   * do not control — a reader's docs theme, someone else's timeline — so they
+   * carry their own and do not follow anything.
    */
   --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;
+  /*
+   * One family, for everything. The sheet's earlier display/text/mono trio is
+   * gone: weight and size separate a heading from a label perfectly well, and
+   * three names for one face is three chances to drift apart. The stack ends in
+   * a generic family, so a missing webfont degrades rather than disappears.
+   */
+  --font: Poppins, system-ui, sans-serif;
 
   /* Whole roles, so half a role cannot be applied without the other half. */
-  --type-h1: 700 44px/48px var(--font-display);
+  --type-h1: 700 44px/48px var(--font);
   --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-card-title: 700 18px/24px var(--font);
+  --type-numeral: 700 26px/32px var(--font); /* a figure is always 700 */
+  --type-body: 400 16px/24px var(--font);
+  --type-button: 500 14px/20px var(--font);
   --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 */
+  --type-label: 500 13px var(--font);
+  /* Addresses, hashes, error codes, the tx block — text meant for a machine. */
+  --type-technical: 400 12px/20px var(--font);
+
+  /* The transaction preview's own scale, from `4 · Anatomy` and `6 · Preview states`. */
+  --type-headline: 700 32px/38px var(--font); /* the one figure the person is deciding on */
+  --type-preview-title: 700 20px/26px var(--font);
+  --type-amount: 700 20px/26px var(--font); /* a row's figure, one size so the column scans */
+  --type-countdown: 700 16px/20px var(--font);
+  --type-row: 400 14px/20px var(--font);
+  --type-note: 400 13px/19px var(--font);
+  --type-kicker: 400 11px/16px var(--font);
+  --type-kicker-tracking: 0.12em;
+  --type-chip: 600 11px/20px var(--font);
 
   /* Spacing, on a 4px base. */
   --space-4: 4px;
@@ -125,60 +156,3 @@
   --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/utxo.ts

@@ -0,0 +1,70 @@
+/**
+ * CIP-30 hands unspent outputs back as CBOR hex; evolution-sdk's builder takes
+ * them typed. The SDK has this conversion — `cip30UtxoFromCBORHex` — but only
+ * behind an export path its manifest blocks, so it is the sixth gap of ADR-0004
+ * and belongs upstream rather than here.
+ */
+import {
+  Address,
+  AddressEras,
+  Assets,
+  CBOR,
+  Schema,
+  Script,
+  TransactionInput,
+  TransactionOutput,
+  UTxO
+} from "@evolution-sdk/evolution"
+import { Either } from "effect"
+
+import type { CborHex } from "./cip30.js"
+
+/** The output's address is era-tagged and a UTxO's is not; the bytes are the same. */
+const toAddressStructure = (tagged: AddressEras.AddressEras): Address.Address =>
+  Schema.decodeSync(Address.FromBytes)(Schema.encodeSync(AddressEras.FromBytes)(tagged))
+
+const readOne = (hex: CborHex): UTxO.UTxO => {
+  const decoded = CBOR.fromCBORHex(hex)
+  if (!Array.isArray(decoded) || decoded.length !== 2) {
+    throw new Error("a CIP-30 unspent output is an input and an output, and this is neither")
+  }
+  const input = TransactionInput.fromCBORBytes(CBOR.toCBORBytes(decoded[0]))
+  const output = TransactionOutput.fromCBORBytes(CBOR.toCBORBytes(decoded[1]))
+  const amount = output.amount
+
+  return new UTxO.UTxO({
+    transactionId: input.transactionId,
+    index: input.index,
+    address: toAddressStructure(output.address),
+    assets:
+      amount._tag === "WithAssets"
+        ? Assets.withMultiAsset(amount.coin, amount.assets)
+        : Assets.fromLovelace(amount.coin),
+    // A Babbage output carries a datum option and a script; a Shelley one carries
+    // a datum hash, which is itself a valid datum option.
+    datumOption: output._tag === "BabbageTransactionOutput" ? output.datumOption : output.datumHash,
+    scriptRef:
+      output._tag === "BabbageTransactionOutput" && output.scriptRef
+        ? Script.fromCBOR(output.scriptRef.bytes)
+        : undefined
+  })
+}
+
+/**
+ * Reads what `getUtxos` returned. `Either` and not a throw: this runs on
+ * whatever a browser extension chose to send, and one unreadable entry must
+ * not take the page down.
+ */
+export const readWalletUtxos = (hexes: ReadonlyArray<CborHex>): Either.Either<ReadonlyArray<UTxO.UTxO>, string> => {
+  const utxos: Array<UTxO.UTxO> = []
+  for (const [index, hex] of hexes.entries()) {
+    try {
+      utxos.push(readOne(hex))
+    } catch (cause) {
+      return Either.left(
+        `unspent output ${index} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`
+      )
+    }
+  }
+  return Either.right(utxos)
+}