@cardano-slips/flow 0.2.0 → 0.3.0

package/src/complete.ts

@@ -6,13 +6,25 @@
  * a person's name on something nobody read.
  */
 import type { Intent, Network } from "@cardano-slips/core"
-import { compare, decodeTransaction, deriveEffects, type Effects } from "@cardano-slips/verifier"
+import {
+  compare,
+  decodeBech32,
+  decodeTransaction,
+  deriveAssets,
+  deriveEffects,
+  deriveLovelace,
+  type Effects,
+  type ResolvedInput
+} from "@cardano-slips/verifier"
 import { Effect, Either } from "effect"
 
+import { readOwnAddress } from "./address.js"
 import { balanceIntent, type BalancingParameters } from "./balance.js"
 import type { BalanceError } from "./balance-error.js"
-import type { Cip30Api } from "./cip30.js"
+import { type Cip30Api, describeApiError, readApiError } from "./cip30.js"
 import { type CompletionError, refuse } from "./complete-error.js"
+import { networkIdFor } from "./connect.js"
+import type { Derived } from "./derived.js"
 import { asResolvedInputs } from "./resolve.js"
 import { signTransaction, submitTransaction } from "./sign.js"
 import type { SigningError } from "./sign-error.js"
@@ -22,26 +34,27 @@ import { transactionIdOf } from "./witness.js"
 /** Enough rebuilds to outlast an unlucky moment, few enough that nobody is asked forever. */
 const defaultAttempts = 3
 
-export type Attempt = {
+export type Attempt = Derived & {
   /** Counting from one, so a rendered "attempt 2 of 3" reads as a person would say it. */
   readonly number: number
   readonly transactionId: string
-  /** What this transaction does, derived from its own bytes. */
-  readonly effects: Effects
 }
 
+/** Where the path has got to after the person agreed, for a screen that says so. */
+export type Progress =
+  /** The wallet has been asked for a signature on this transaction. */
+  | { readonly _tag: "Signing"; readonly transactionId: string }
+  /** The witnesses are in the body and the wallet has been asked to submit it. */
+  | { readonly _tag: "Submitting"; readonly transactionId: string }
+  /** The funds moved under the last transaction; attempt `number` of `of` is being built. */
+  | { readonly _tag: "Rebuilding"; readonly number: number; readonly of: number }
+
 export type CompletionRequest = {
   readonly api: Cip30Api
   /** What the endpoint declared, and what the transaction is judged against. */
   readonly intent: Intent
   readonly network: Network
   readonly changeAddress: string
-  /**
-   * Every address the wallet calls its own, its reward account included. An
-   * address missing from here is read as a stranger's, which turns the wallet's
-   * own change into an undeclared payment and blocks the Slip.
-   */
-  readonly userAddresses: ReadonlyArray<Uint8Array>
   readonly parameters: BalancingParameters
   readonly rewardBalance?: bigint
   /** Read once per attempt: a rebuilt transaction gets its own validity window. */
@@ -50,6 +63,14 @@ export type CompletionRequest = {
   readonly attempts?: number
   /** Called once per attempt, after the effects are derived and before the wallet is asked to sign. */
   readonly onAttempt?: (attempt: Attempt) => void
+  /**
+   * Resolves `true` once the person has pressed sign on this attempt, `false`
+   * if they turned it down. Asked again for every rebuilt transaction, because
+   * agreeing to one body is not agreeing to the next. Without it, showing the
+   * effects is taken as agreement.
+   */
+  readonly confirm?: (attempt: Attempt) => Promise<boolean>
+  readonly onProgress?: (progress: Progress) => void
 }
 
 export type Receipt = {
@@ -85,6 +106,62 @@ const walletUtxos = (api: Cip30Api) =>
     return read.right
   })
 
+const addressesFrom = (api: Cip30Api, method: "getUsedAddresses" | "getUnusedAddresses" | "getRewardAddresses") =>
+  Effect.tryPromise({
+    try: () => api[method](),
+    catch: (cause) => {
+      const cip30 = readApiError(cause)
+      const said = cip30 === undefined ? String(cause) : describeApiError(cip30)
+      return refuse("UnreadableAddresses", `The wallet could not say which addresses are its own: ${said}`, { cause })
+    }
+  }).pipe(
+    Effect.filterOrFail(
+      (answered): answered is ReadonlyArray<string> => Array.isArray(answered),
+      () => refuse("UnreadableAddresses", `The wallet answered ${method} with something that is not a list.`)
+    )
+  )
+
+/**
+ * Every address the wallet vouches for: those CIP-30 lists, the change address,
+ * and the address of every output it said it holds. Read with the outputs on
+ * each attempt, since both can change when the funds move. One missing is read
+ * as a stranger's, and its value would be shown as someone else's. The outputs'
+ * addresses are ahead of the spec's list, until
+ * https://github.com/emmanuel-musau/cardano-slips/issues/186 brings it into line.
+ */
+const ownAddresses = (request: CompletionRequest, inputs: ReadonlyArray<ResolvedInput>) =>
+  Effect.gen(function* () {
+    const listed = [
+      ...(yield* addressesFrom(request.api, "getUsedAddresses")),
+      ...(yield* addressesFrom(request.api, "getUnusedAddresses")),
+      ...(yield* addressesFrom(request.api, "getRewardAddresses"))
+    ]
+
+    const network = networkIdFor(request.network)
+    const read: Array<Uint8Array> = []
+    for (const hex of listed) {
+      const address = readOwnAddress(hex)
+      if (Either.isLeft(address)) {
+        return yield* Effect.fail(
+          refuse("UnreadableAddresses", `The wallet named an address of its own that cannot be read: ${address.left}`)
+        )
+      }
+      if (address.right.networkId !== undefined && address.right.networkId !== network) {
+        return yield* Effect.fail(
+          refuse("UnreadableAddresses", "The wallet named an address on another network as its own.")
+        )
+      }
+      read.push(address.right.bytes)
+    }
+
+    const change = decodeBech32(request.changeAddress)
+    if (Either.isLeft(change)) {
+      return yield* Effect.fail(refuse("UnreadableAddresses", "The change address is not an address."))
+    }
+
+    return [...read, change.right.bytes, ...inputs.map((input) => input.address)]
+  })
+
 /**
  * One transaction, from the wallet's outputs to a verdict. The judging happens
  * here rather than at the caller so that no path reaches `signTransaction`
@@ -112,20 +189,27 @@ const buildAndJudge = (request: CompletionRequest, number: number) =>
       )
     }
 
-    const effects = deriveEffects({
+    const resolvedInputs = asResolvedInputs(utxos)
+    const derivation = {
       transaction: transaction.right,
-      userAddresses: request.userAddresses,
-      resolvedInputs: asResolvedInputs(utxos),
+      userAddresses: yield* ownAddresses(request, resolvedInputs),
+      resolvedInputs,
       protocolParameters: request.parameters
+    }
+    const read = Either.all({
+      effects: deriveEffects(derivation),
+      lovelace: deriveLovelace(derivation),
+      assets: deriveAssets(derivation)
     })
-    if (Either.isLeft(effects)) {
+    if (Either.isLeft(read)) {
       return yield* Effect.fail(
-        refuse("CannotJudge", `What this transaction does could not be worked out: ${effects.left.message}`)
+        refuse("CannotJudge", `What this transaction does could not be worked out: ${read.left.message}`)
       )
     }
+    const derived: Derived = read.right
 
     const verdict = compare({
-      effects: effects.right,
+      effects: derived.effects,
       declared: request.intent,
       changeAddress: request.changeAddress,
       now: BigInt(now),
@@ -143,13 +227,14 @@ const buildAndJudge = (request: CompletionRequest, number: number) =>
     if (verdict.right._tag === "mismatch") {
       return yield* Effect.fail(
         refuse("Blocked", "This transaction does not do what the Slip said it would, so it will not be signed.", {
-          reasons: verdict.right.reasons
+          reasons: verdict.right.reasons,
+          derived
         })
       )
     }
 
     const transactionId = yield* transactionIdOf(built.cbor)
-    const attempt: Attempt = { number, transactionId, effects: effects.right }
+    const attempt: Attempt = { ...derived, number, transactionId }
 
     // The caller is what puts these effects in front of a person. If that
     // throws, the person has not seen them, so this fails closed rather than
@@ -162,6 +247,15 @@ const buildAndJudge = (request: CompletionRequest, number: number) =>
     return { cbor: built.cbor, attempt }
   })
 
+/** A progress report is a courtesy to the screen; one that throws must not stop a submission already under way. */
+const report = (request: CompletionRequest, progress: Progress): void => {
+  try {
+    request.onProgress?.(progress)
+  } catch {
+    // Nothing to do: the flow carries on, and the next state the screen is given corrects it.
+  }
+}
+
 /**
  * Completes the Slip, or says why not. A submission that failed because an
  * input was spent is the one failure worth repeating: everything else either
@@ -174,12 +268,26 @@ export const completeIntent = (request: CompletionRequest): Effect.Effect<Receip
     for (let number = 1; number <= allowed; number += 1) {
       const { attempt, cbor } = yield* buildAndJudge(request, number)
 
+      const { confirm } = request
+      if (confirm !== undefined) {
+        const agreed = yield* Effect.tryPromise({
+          try: () => confirm(attempt),
+          catch: (cause) =>
+            refuse("NotShown", "This transaction could not be put to you, so it will not be signed.", { cause })
+        })
+        if (!agreed) {
+          return yield* Effect.fail(refuse("Cancelled", "The transaction was closed without signing."))
+        }
+      }
+
+      report(request, { _tag: "Signing", transactionId: attempt.transactionId })
       const signed = yield* signTransaction({
         api: request.api,
         transaction: cbor,
         transactionId: attempt.transactionId
       })
 
+      report(request, { _tag: "Submitting", transactionId: attempt.transactionId })
       const submitted = yield* Effect.either(submitTransaction(request.api, signed))
       if (Either.isRight(submitted)) {
         return { transactionId: submitted.right, effects: attempt.effects, attempts: number }
@@ -187,6 +295,7 @@ export const completeIntent = (request: CompletionRequest): Effect.Effect<Receip
       if (submitted.left.refusal !== "InputsSpent") {
         return yield* Effect.fail(submitted.left)
       }
+      if (number < allowed) report(request, { _tag: "Rebuilding", number: number + 1, of: allowed })
     }
 
     return yield* Effect.fail(

package/src/derived.ts

@@ -0,0 +1,8 @@
+/** What a transaction does, read from its own bytes: the part the comparison judges, and the figures a person is shown. */
+import type { AssetEffects, Effects, LovelaceEffects } from "@cardano-slips/verifier"
+
+export type Derived = {
+  readonly effects: Effects
+  readonly lovelace: LovelaceEffects
+  readonly assets: AssetEffects
+}

package/src/effects-panel.tsx

@@ -0,0 +1,386 @@
+"use client"
+
+/**
+ * The transaction preview, drawn from `4 · Anatomy` and `6 · Preview states` on
+ * the design sheet. Every figure is derived from the transaction; the claim is
+ * only the title it is held against. A mismatch removes the sign button rather
+ * than disabling it, and no prop brings it back.
+ */
+import type { Verdict } from "@cardano-slips/verifier"
+import { useEffect, useId, useState } from "react"
+
+import type { Derived } from "./derived.js"
+import { formatCountdown, secondsLeft } from "./explain.js"
+import {
+  blockedLine,
+  evidenceOf,
+  groupsOf,
+  headlineOf,
+  isCollapsed,
+  isGrouped,
+  ledgerOf,
+  matchLine,
+  rawLines,
+  type Group,
+  type Row
+} from "./ledger.js"
+
+export type EffectsPanelProps = {
+  /** What the card promised, restated so it can be compared with what follows. */
+  readonly claim: string
+  /** The card's description, set beside the transaction when the two disagree. */
+  readonly description?: string
+  /** The host that served the link, as a host only. Whether it is verified is the identity chip's to say. */
+  readonly origin?: string
+  readonly derived: Derived
+  /** The verifier's own verdict. Required, so no caller renders a match by leaving the reasons out. */
+  readonly verdict: Verdict
+  /** Read once a second for the countdown. */
+  readonly clock?: () => number
+  readonly onSign?: () => void
+  readonly onCancel?: () => void
+  readonly onRebuild?: () => void
+  /** "Report this link" is offered only where there is somewhere to send the report. */
+  readonly onReport?: () => void
+}
+
+/** Under this, the countdown leaves the meta row and takes the headline's place (state f). */
+const expiringUnder = 60
+
+const groupNames: { readonly [group in Group]: string } = {
+  arriving: "Arriving",
+  leaving: "Leaving",
+  unmoved: "No value moved"
+}
+
+const markWords = { "not-in-the-link": "Not in the link", "not-as-the-link-says": "Not as the link says" } as const
+
+const chipWords = { refundable: "Refundable", "as-stated": "As stated" } as const
+
+const useNow = (clock: () => number): number => {
+  const [now, setNow] = useState(clock)
+  useEffect(() => {
+    const timer = setInterval(() => setNow(clock()), 1000)
+    return () => clearInterval(timer)
+  }, [clock])
+  return now
+}
+
+const LedgerRow = ({ row }: { readonly row: Row }): React.JSX.Element => (
+  <div className="slip-panel__row" data-mark={row.mark}>
+    <div className="slip-panel__row-name">
+      <div className="slip-panel__row-label">
+        <span className="slip-panel__label">{row.label}</span>
+        {row.chip === undefined ? undefined : (
+          <span className="slip-panel__chip" data-chip={row.chip}>
+            {chipWords[row.chip]}
+          </span>
+        )}
+        {row.mark === undefined ? undefined : (
+          <span className="slip-panel__chip" data-chip="mark">
+            {markWords[row.mark]}
+          </span>
+        )}
+      </div>
+      {row.detail === undefined ? undefined : <span className="slip-panel__detail">{row.detail}</span>}
+    </div>
+    <div className="slip-panel__amounts">
+      {row.identifier === undefined ? undefined : <span className="slip-panel__identifier">{row.identifier}</span>}
+      {row.amounts.map((amount, index) => (
+        <span key={index} className="slip-panel__amount" data-tone={amount.tone}>
+          {amount.text}
+        </span>
+      ))}
+    </div>
+    {row.note === undefined ? undefined : <p className="slip-panel__note">{row.note}</p>}
+  </div>
+)
+
+const Rows = ({ rows }: { readonly rows: ReadonlyArray<Row> }): React.JSX.Element => (
+  <div className="slip-panel__ledger">
+    {rows.map((row) => (
+      <LedgerRow key={row.key} row={row} />
+    ))}
+  </div>
+)
+
+/**
+ * Past eight rows each group folds to its header and a count. A group holding
+ * a marked row never starts folded: the one thing the block points at is not
+ * something a person should have to open.
+ */
+export const Ledger = ({ rows }: { readonly rows: ReadonlyArray<Row> }): React.JSX.Element => {
+  if (!isGrouped(rows)) return <Rows rows={rows} />
+  const collapsed = isCollapsed(rows)
+  return (
+    <div className="slip-panel__groups">
+      {groupsOf(rows).map(({ group, rows: inGroup }) =>
+        collapsed ? (
+          <details
+            key={group}
+            className="slip-panel__group"
+            open={inGroup.some((row) => row.mark !== undefined) || undefined}
+          >
+            <summary className="slip-panel__group-name">
+              {groupNames[group]} · {inGroup.length}
+            </summary>
+            <Rows rows={inGroup} />
+          </details>
+        ) : (
+          <div key={group} className="slip-panel__group">
+            <p className="slip-panel__group-name">{groupNames[group]}</p>
+            <Rows rows={inGroup} />
+          </div>
+        )
+      )}
+    </div>
+  )
+}
+
+const Raw = ({ derived }: { readonly derived: Derived }): React.JSX.Element => (
+  <pre className="slip-panel__raw-lines">{rawLines(derived).join("\n")}</pre>
+)
+
+const Countdown = ({ seconds }: { readonly seconds: number }): React.JSX.Element => (
+  // The server and the browser read the clock a moment apart.
+  <span suppressHydrationWarning>{formatCountdown(seconds)}</span>
+)
+
+const Blocked = ({
+  claim,
+  description,
+  derived,
+  reasons,
+  onCancel,
+  onReport
+}: Pick<EffectsPanelProps, "claim" | "description" | "derived" | "onCancel" | "onReport"> & {
+  readonly reasons: Extract<Verdict, { _tag: "mismatch" }>["reasons"]
+}): React.JSX.Element => {
+  const [rawOpen, setRawOpen] = useState(false)
+  const title = useId()
+  const rows = ledgerOf(derived, reasons)
+  return (
+    <section className="slip-root slip-panel" data-blocked="" aria-labelledby={title}>
+      <div className="slip-panel__claim" role="alert">
+        <p className="slip-panel__kicker" data-tone="bad">
+          Signing blocked
+        </p>
+        <h2 className="slip-panel__title" id={title}>
+          This transaction doesn't do what the link says
+        </h2>
+        <p className="slip-panel__lead">{blockedLine(reasons)}</p>
+      </div>
+
+      <div className="slip-panel__compare">
+        <div className="slip-panel__side">
+          <p className="slip-panel__kicker">The link claims</p>
+          <p className="slip-panel__claimed">{claim}</p>
+          {description === undefined ? undefined : <p className="slip-panel__note">{description}</p>}
+        </div>
+        <div className="slip-panel__side" data-tone="bad">
+          <p className="slip-panel__kicker" data-tone="bad">
+            The transaction does
+          </p>
+          {reasons.map((reason, index) => {
+            const { figure, lines } = evidenceOf(reason, derived)
+            return (
+              <div key={index} className="slip-panel__evidence">
+                {figure === undefined ? undefined : <p className="slip-panel__evidence-figure">{figure}</p>}
+                {lines.map((line) => (
+                  <p key={line} className="slip-panel__detail">
+                    {line}
+                  </p>
+                ))}
+              </div>
+            )
+          })}
+        </div>
+      </div>
+
+      <Ledger rows={rows} />
+
+      {rawOpen ? <Raw derived={derived} /> : undefined}
+
+      <div className="slip-panel__exits">
+        <button type="button" className="slip-panel__button" data-kind="close" onClick={onCancel}>
+          Close without signing
+        </button>
+        <div className="slip-panel__quiet">
+          <button
+            type="button"
+            className="slip-panel__button"
+            data-kind="quiet"
+            aria-expanded={rawOpen}
+            onClick={() => setRawOpen((open) => !open)}
+          >
+            {rawOpen ? "Hide raw transaction" : "Show raw transaction"}
+          </button>
+          {onReport === undefined ? undefined : (
+            <button type="button" className="slip-panel__button" data-kind="quiet" onClick={onReport}>
+              Report this link
+            </button>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+export const EffectsPanel = ({
+  claim,
+  description,
+  origin,
+  derived,
+  verdict,
+  clock = Date.now,
+  onSign,
+  onCancel,
+  onRebuild,
+  onReport
+}: EffectsPanelProps): React.JSX.Element => {
+  const now = useNow(clock)
+  const [rawOpen, setRawOpen] = useState(false)
+  const title = useId()
+
+  if (verdict._tag === "mismatch") {
+    return (
+      <Blocked
+        claim={claim}
+        derived={derived}
+        reasons={verdict.reasons}
+        {...(description === undefined ? {} : { description })}
+        {...(onCancel === undefined ? {} : { onCancel })}
+        {...(onReport === undefined ? {} : { onReport })}
+      />
+    )
+  }
+
+  const rows = ledgerOf(derived)
+  const until = derived.effects.validity.validUntil
+  const seconds = until === null ? undefined : secondsLeft(until.time, BigInt(now))
+
+  if (seconds === 0) {
+    return (
+      <section className="slip-root slip-panel" data-expired="" aria-labelledby={title}>
+        <div className="slip-panel__claim">
+          <p className="slip-panel__kicker" data-tone="warn">
+            Expired
+          </p>
+          <h2 className="slip-panel__title" id={title}>
+            This transaction ran out of time
+          </h2>
+          <p className="slip-panel__lead">
+            Nothing was signed and nothing left your wallet. Building a new one takes a second, and the amounts will be
+            checked again.
+          </p>
+        </div>
+        <div className="slip-panel__stale">
+          <Ledger rows={rows} />
+        </div>
+        <div className="slip-panel__buttons">
+          <button type="button" className="slip-panel__button" data-kind="cancel" onClick={onCancel}>
+            Cancel
+          </button>
+          <button type="button" className="slip-panel__button" data-kind="primary" onClick={onRebuild}>
+            Build a new transaction
+          </button>
+        </div>
+      </section>
+    )
+  }
+
+  const headline = headlineOf(derived)
+  const expiring = seconds !== undefined && seconds < expiringUnder
+
+  return (
+    <section className="slip-root slip-panel" aria-labelledby={title}>
+      <div className="slip-panel__claim">
+        <p className="slip-panel__kicker">What you're signing</p>
+        <h2 className="slip-panel__title" id={title}>
+          {claim}
+        </h2>
+        {origin === undefined ? undefined : <span className="slip-panel__origin">{origin}</span>}
+      </div>
+
+      {expiring ? (
+        <div className="slip-panel__expiring" role="timer">
+          <div className="slip-panel__expiring-head">
+            <span>This transaction expires in</span>
+            <span className="slip-panel__expiring-clock">
+              <Countdown seconds={seconds} />
+            </span>
+          </div>
+          <div className="slip-panel__bar" aria-hidden="true">
+            <span
+              className="slip-panel__bar-fill"
+              suppressHydrationWarning
+              style={{ width: `${(seconds / expiringUnder) * 100}%` }}
+            />
+          </div>
+          <p className="slip-panel__note">After that the amounts could be stale, so we'll build a fresh one.</p>
+        </div>
+      ) : (
+        <div className="slip-panel__headline">
+          <div className="slip-panel__figure">
+            <span className="slip-panel__note">{headline.label}</span>
+            <span className="slip-panel__figure-amount" data-tone={headline.tone}>
+              {headline.amount}
+            </span>
+            {headline.fee === undefined ? undefined : <span className="slip-panel__note">{headline.fee}</span>}
+          </div>
+          {headline.held === undefined ? undefined : (
+            <>
+              <span className="slip-panel__rule" aria-hidden="true" />
+              <div className="slip-panel__figure">
+                <span className="slip-panel__note">{headline.held.label}</span>
+                <span className="slip-panel__figure-amount" data-tone={headline.held.tone}>
+                  {headline.held.amount}
+                </span>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <Ledger rows={rows} />
+
+      {expiring || seconds === undefined ? undefined : (
+        <div className="slip-panel__expiry">
+          <span className="slip-panel__note">Expires in</span>
+          <span className="slip-panel__clock">
+            <Countdown seconds={seconds} />
+          </span>
+        </div>
+      )}
+
+      <p className="slip-panel__verdict">
+        <span className="slip-panel__tick" aria-hidden="true">
+          ✓
+        </span>
+        <span>{matchLine(derived, rows)}</span>
+      </p>
+
+      <div className="slip-panel__buttons">
+        <button type="button" className="slip-panel__button" data-kind="cancel" onClick={onCancel}>
+          Cancel
+        </button>
+        <button type="button" className="slip-panel__button" data-kind="primary" onClick={onSign}>
+          Sign transaction
+        </button>
+      </div>
+
+      <div className="slip-panel__raw">
+        <button
+          type="button"
+          className="slip-panel__raw-toggle"
+          aria-expanded={rawOpen}
+          onClick={() => setRawOpen((open) => !open)}
+        >
+          <span aria-hidden="true">{rawOpen ? "▾" : "▸"}</span>
+          <span>Raw transaction</span>
+        </button>
+        {rawOpen ? <Raw derived={derived} /> : undefined}
+      </div>
+    </section>
+  )
+}