@cardano-slips/flow 0.1.0 → 0.3.0

package/src/outcome-panel.tsx

@@ -0,0 +1,263 @@
+"use client"
+
+/**
+ * What happens after the person presses sign — `10 · Signing and outcomes`.
+ * Every state but the receipt keeps the effects on screen, because waiting is
+ * not a modal: a spinner over a hidden ledger asks for trust the panel exists
+ * to avoid needing.
+ */
+import type { Network } from "@cardano-slips/core"
+import { useId } from "react"
+
+import type { Derived } from "./derived.js"
+import { Ledger } from "./effects-panel.js"
+import { ledgerOf } from "./ledger.js"
+
+export type Outcome =
+  /** The wallet is open over the page, asked for a signature. */
+  | { readonly _tag: "Waiting"; readonly wallet: string }
+  /** The person said no in the wallet. Not a failure: the offer stands. */
+  | { readonly _tag: "Declined" }
+  /** Signed, and on its way to the network. */
+  | { readonly _tag: "Submitting"; readonly transactionId: string }
+  /** The funds moved; a fresh transaction is being built and will be shown before it is signed. */
+  | { readonly _tag: "Rebuilding"; readonly number: number; readonly of: number }
+  /** The network refused it. `reason` is the node's own words, shown as they came. */
+  | { readonly _tag: "Refused"; readonly reason: string }
+
+export type OutcomePanelProps = {
+  readonly claim: string
+  readonly derived: Derived
+  readonly outcome: Outcome
+  /** Cancel while waiting or rebuilding; Close once declined or refused. */
+  readonly onClose?: () => void
+  /** Review and sign again after a decline; start again after a refusal. */
+  readonly onAgain?: () => void
+}
+
+const Spinner = (): React.JSX.Element => <span className="slip-panel__spin" aria-hidden="true" />
+
+const Head = ({
+  kicker,
+  lead,
+  title,
+  titleId,
+  tone
+}: {
+  readonly kicker: string
+  readonly title: string
+  readonly titleId: string
+  readonly lead?: string
+  readonly tone?: "bad" | "warn"
+}): React.JSX.Element => (
+  <div className="slip-panel__claim">
+    <p className="slip-panel__kicker" data-tone={tone}>
+      {kicker}
+    </p>
+    <h2 className="slip-panel__title" id={titleId}>
+      {title}
+    </h2>
+    {lead === undefined ? undefined : <p className="slip-panel__lead">{lead}</p>}
+  </div>
+)
+
+export const OutcomePanel = ({ claim, derived, onAgain, onClose, outcome }: OutcomePanelProps): React.JSX.Element => {
+  const title = useId()
+  const rows = ledgerOf(derived)
+
+  switch (outcome._tag) {
+    case "Waiting":
+      return (
+        <section className="slip-root slip-panel" data-outcome="waiting" aria-labelledby={title} aria-busy="true">
+          <Head kicker="What you're signing" title={claim} titleId={title} />
+          <Ledger rows={rows} />
+          <div className="slip-panel__wallet" role="status">
+            <Spinner />
+            <div className="slip-panel__wallet-words">
+              <span>Approve in your wallet</span>
+              <span className="slip-panel__note">{outcome.wallet} is open. Nothing is sent until you do.</span>
+            </div>
+          </div>
+          <button type="button" className="slip-panel__button" data-kind="cancel" onClick={onClose}>
+            Cancel
+          </button>
+        </section>
+      )
+
+    case "Declined":
+      return (
+        <section className="slip-root slip-panel" data-outcome="declined" aria-labelledby={title}>
+          <Head
+            kicker="Not signed"
+            title="You declined in your wallet"
+            titleId={title}
+            lead="Nothing was sent and nothing left your wallet. The link still works if you want to look again."
+          />
+          <div className="slip-panel__stale">
+            <Ledger rows={rows} />
+          </div>
+          <div className="slip-panel__buttons">
+            <button type="button" className="slip-panel__button" data-kind="close" onClick={onClose}>
+              Close
+            </button>
+            <button type="button" className="slip-panel__button" data-kind="primary" onClick={onAgain}>
+              Review and sign again
+            </button>
+          </div>
+        </section>
+      )
+
+    case "Submitting":
+      return (
+        <section className="slip-root slip-panel" data-outcome="submitting" aria-labelledby={title} aria-busy="true">
+          <Head kicker="Submitting" title="Sending your signed transaction" titleId={title} />
+          <ol className="slip-panel__steps">
+            <li className="slip-panel__step">
+              <span className="slip-panel__tick" aria-hidden="true">
+                ✓
+              </span>
+              <span>Signature checked against the transaction you read</span>
+            </li>
+            <li className="slip-panel__step" role="status">
+              <Spinner />
+              <span>Handing it to the network</span>
+            </li>
+          </ol>
+          {/* The id is what a person can carry away if the page dies mid-submit, so it is here in full. */}
+          <div className="slip-panel__transaction">
+            <span className="slip-panel__note">Transaction</span>
+            <span className="slip-panel__transaction-id">{outcome.transactionId}</span>
+          </div>
+        </section>
+      )
+
+    case "Rebuilding":
+      return (
+        <section className="slip-root slip-panel" data-outcome="rebuilding" aria-labelledby={title} aria-busy="true">
+          <Head
+            kicker="Rebuilding"
+            tone="warn"
+            title="Your funds moved while you were signing"
+            titleId={title}
+            lead="Something else spent the outputs this transaction used. Nothing was signed twice and nothing left your wallet."
+          />
+          <div className="slip-panel__wallet" role="status">
+            <Spinner />
+            <div className="slip-panel__wallet-words">
+              <span>Building a fresh transaction</span>
+              <span className="slip-panel__note">
+                Attempt {outcome.number} of {outcome.of}
+              </span>
+            </div>
+          </div>
+          <p className="slip-panel__note">
+            It will have different amounts and a different id, so you'll see its effects checked before your wallet is
+            asked again.
+          </p>
+          <div className="slip-panel__stale">
+            <Ledger rows={rows} />
+          </div>
+          <button type="button" className="slip-panel__button" data-kind="cancel" onClick={onClose}>
+            Cancel
+          </button>
+        </section>
+      )
+
+    case "Refused":
+      return (
+        <section className="slip-root slip-panel" data-outcome="refused" aria-labelledby={title}>
+          <Head
+            kicker="Not submitted"
+            tone="bad"
+            title="The network wouldn't accept this transaction"
+            titleId={title}
+            lead="You signed it, but it never took effect and nothing left your wallet. Your signature cannot be reused."
+          />
+          <pre className="slip-panel__reason">{outcome.reason}</pre>
+          <div className="slip-panel__buttons">
+            <button type="button" className="slip-panel__button" data-kind="close" onClick={onClose}>
+              Close
+            </button>
+            <button type="button" className="slip-panel__button" data-kind="primary" onClick={onAgain}>
+              Start again
+            </button>
+          </div>
+        </section>
+      )
+  }
+}
+
+export type SlipReceiptProps = {
+  readonly claim: string
+  readonly derived: Derived
+  readonly transactionId: string
+  readonly network: Network
+  /** Where this transaction can be looked up: the only durable copy anyone keeps. */
+  readonly explorer: { readonly name: string; readonly url: string }
+}
+
+/** A transaction id is hex with no separator, so it is shortened from both ends. */
+const shortId = (id: string): string => (id.length <= 12 ? id : `${id.slice(0, 4)}…${id.slice(-4)}`)
+
+/** One spelling for every surface that names a network, so the receipt and the top bar never disagree. */
+export const networkNames: Readonly<Record<Network, string>> = {
+  mainnet: "Mainnet",
+  preprod: "Preprod",
+  preview: "Preview"
+}
+
+/**
+ * `10 · d`, back on the card surface. It says sent rather than confirmed: the
+ * node accepted the transaction, and nothing here watches the chain for it.
+ */
+export const SlipReceipt = ({
+  claim,
+  derived,
+  explorer,
+  network,
+  transactionId
+}: SlipReceiptProps): React.JSX.Element => {
+  const title = useId()
+  return (
+    <section className="slip-root slip-receipt" aria-labelledby={title}>
+      <div className="slip-receipt__head">
+        <span className="slip-receipt__tick" aria-hidden="true">
+          ✓
+        </span>
+        <div className="slip-receipt__identity">
+          <h2 className="slip-receipt__title" id={title}>
+            {claim}
+          </h2>
+          <span className="slip-receipt__note">Sent to {networkNames[network]}</span>
+        </div>
+      </div>
+      <div className="slip-receipt__ledger">
+        {ledgerOf(derived).map((row) => (
+          <div key={row.key} className="slip-receipt__row">
+            <span className="slip-receipt__label">{row.label}</span>
+            <span className="slip-receipt__amounts">
+              {row.identifier ?? undefined}
+              {row.amounts.map((amount, index) => (
+                <span key={index} className="slip-receipt__amount" data-tone={amount.tone}>
+                  {amount.text}
+                </span>
+              ))}
+            </span>
+          </div>
+        ))}
+      </div>
+      <div className="slip-receipt__transaction">
+        <span className="slip-receipt__kicker">Transaction</span>
+        <span className="slip-receipt__id" title={transactionId}>
+          {shortId(transactionId)}
+        </span>
+        <a className="slip-receipt__link" href={explorer.url} target="_blank" rel="noreferrer">
+          View on {explorer.name}
+        </a>
+      </div>
+      <p className="slip-receipt__note slip-receipt__foot">
+        No account was created and nothing was stored. This page keeps none of it.
+      </p>
+    </section>
+  )
+}

package/src/parameter-form.tsx

@@ -0,0 +1,138 @@
+"use client"
+
+/**
+ * The form a linked action's `parameters` describe. It holds no state: what a
+ * person typed, and which errors are ripe to show, belong to the card.
+ */
+import type { Parameter, ParameterValues } from "@cardano-slips/core"
+
+import { valueOf } from "./card.js"
+
+/** A sentence about one field. `code` is the endpoint's, and is for us rather than for the person. */
+export type FieldError = {
+  readonly message: string
+  readonly code?: string
+}
+
+export type ParameterFormProps = {
+  readonly parameters: ReadonlyArray<Parameter>
+  readonly values: ParameterValues
+  /** By parameter name. What is here is shown; deciding when is the card's job. */
+  readonly errors?: Readonly<Record<string, FieldError>>
+  readonly onChange: (name: string, value: string) => void
+  /** Prefixes every generated id, so two cards on one page do not collide. */
+  readonly idPrefix?: string
+}
+
+/**
+ * The bounds line. The spec requires it beside the field rather than only on
+ * failure, so a person can tell what will be accepted before they type.
+ */
+export const boundsOf = (parameter: Parameter): string | undefined => {
+  if (parameter.type === "select") {
+    const labels = parameter.options.map((option) => option.label)
+    if (labels.length > 3) return `${labels.length} options`
+    if (labels.length === 1) return labels[0]
+    return `${labels.slice(0, -1).join(", ")} or ${labels.at(-1)}`
+  }
+
+  // On `text` the bounds count characters; on `number` they bound the value.
+  const unit = parameter.type === "text" ? " characters" : ""
+  if (parameter.min !== undefined && parameter.max !== undefined) {
+    return `Between ${parameter.min} and ${parameter.max}${unit}`
+  }
+  // The same words `checkValues` uses, so the bounds and the sentence a broken
+  // value produces read as one voice rather than two.
+  if (parameter.min !== undefined) return `At least ${parameter.min}${unit}`
+  if (parameter.max !== undefined) return `At most ${parameter.max}${unit}`
+  return undefined
+}
+
+const errorOf = (errors: Readonly<Record<string, FieldError>> | undefined, name: string): FieldError | undefined =>
+  errors !== undefined && Object.hasOwn(errors, name) ? errors[name] : undefined
+
+type FieldProps = {
+  readonly parameter: Parameter
+  readonly value: string
+  readonly error: FieldError | undefined
+  readonly id: string
+  readonly onChange: (name: string, value: string) => void
+}
+
+const Field = ({ parameter, value, error, id, onChange }: FieldProps): React.JSX.Element => {
+  const helpId = `${id}-help`
+  const invalid = error === undefined ? undefined : ""
+  const change = (next: string): void => onChange(parameter.name, next)
+
+  return (
+    <div className="slip-field" data-invalid={invalid}>
+      <label className="slip-field__label" htmlFor={id}>
+        {parameter.label}
+      </label>
+      <div className="slip-field__control">
+        {parameter.type === "select" ? (
+          <select
+            id={id}
+            className="slip-field__input"
+            value={value}
+            aria-describedby={helpId}
+            aria-invalid={error === undefined ? undefined : true}
+            onChange={(event) => change(event.target.value)}
+          >
+            {parameter.required === true && value !== "" ? undefined : <option value="" />}
+            {parameter.options.map((option) => (
+              <option key={option.value} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        ) : (
+          <input
+            id={id}
+            className={
+              parameter.type === "number" ? "slip-field__input slip-field__input--numeral" : "slip-field__input"
+            }
+            type="text"
+            // Never `type="number"`: it hands back an empty string for anything
+            // the browser dislikes, which hides the very value `checkValues` is
+            // there to judge — and the person never learns what was wrong.
+            inputMode={parameter.type === "number" ? "decimal" : undefined}
+            value={value}
+            aria-describedby={helpId}
+            aria-invalid={error === undefined ? undefined : true}
+            onChange={(event) => change(event.target.value)}
+          />
+        )}
+      </div>
+      <div className="slip-field__help" id={helpId}>
+        <span className="slip-field__bounds">{error?.message ?? boundsOf(parameter)}</span>
+        {error?.code === undefined ? (
+          <span className="slip-field__note">{parameter.required === true ? "Required" : "Optional"}</span>
+        ) : (
+          <span className="slip-field__code">{error.code}</span>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export const ParameterForm = ({
+  parameters,
+  values,
+  errors,
+  onChange,
+  idPrefix = "slip"
+}: ParameterFormProps): React.JSX.Element => (
+  <div className="slip-fields">
+    {parameters.map((parameter) => (
+      <Field
+        key={parameter.name}
+        parameter={parameter}
+        value={valueOf(values, parameter.name)}
+        error={errorOf(errors, parameter.name)}
+        id={`${idPrefix}-${parameter.name}`}
+        onChange={onChange}
+      />
+    ))}
+  </div>
+)

package/src/resolve.ts

@@ -0,0 +1,40 @@
+/**
+ * The wallet's own unspent outputs, in the form the verifier's derivation takes
+ * them. The engine is handed the value of every input the body spends because
+ * it never looks one up (invariant 1) — this is where the client, which does
+ * know, says so.
+ */
+import type { MultiAsset, ResolvedInput } from "@cardano-slips/verifier"
+import {
+  Address,
+  AssetName,
+  Assets,
+  MultiAsset as Multi,
+  PolicyId,
+  Schema,
+  TransactionHash
+} from "@evolution-sdk/evolution"
+import type { UTxO } from "@evolution-sdk/evolution"
+
+const addressBytes = Schema.encodeSync(Address.FromBytes)
+
+const multiAssetOf = (assets: Assets.Assets): MultiAsset => {
+  const held = Assets.getMultiAsset(assets)
+  if (held === undefined) return []
+  return Multi.getPolicyIds(held).map((policyId) => ({
+    policyId: PolicyId.toBytes(policyId),
+    assets: Multi.getAssetsByPolicy(held, policyId).map(([name, quantity]) => ({
+      name: AssetName.toBytes(name),
+      quantity
+    }))
+  }))
+}
+
+export const asResolvedInput = (utxo: UTxO.UTxO): ResolvedInput => ({
+  input: { transactionId: TransactionHash.toBytes(utxo.transactionId), index: utxo.index },
+  address: addressBytes(utxo.address),
+  value: { coin: Assets.lovelaceOf(utxo.assets), assets: multiAssetOf(utxo.assets) }
+})
+
+export const asResolvedInputs = (utxos: ReadonlyArray<UTxO.UTxO>): ReadonlyArray<ResolvedInput> =>
+  utxos.map(asResolvedInput)

package/src/sign-error.ts

@@ -0,0 +1,89 @@
+/**
+ * Why a transaction was not signed, or not submitted. 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 SignRefusal =
+  /** The bytes we hold are not a transaction these bytes can be read as. */
+  | "UnreadableTransaction"
+  /** This is not the body the effects were derived from, so nothing may be signed into it. */
+  | "WrongBody"
+  /** The person said no in the wallet. Not a fault. */
+  | "Declined"
+  /** The wallet tried to sign and could not, or rejected for a reason of its own. */
+  | "SignFailed"
+  /** What came back is not a witness set — a whole transaction included. */
+  | "UnreadableWitnesses"
+  /** The set carries script or datum material the body was never judged with. */
+  | "UnexpectedWitnessMaterial"
+  /** The set carries no signature, so assembling it would leave the transaction unsigned. */
+  | "NoWitnesses"
+  /** Submission failed because an input was spent between building and signing. */
+  | "InputsSpent"
+  /** The validity interval passed before the transaction reached the chain. */
+  | "IntervalPassed"
+  /** Submission failed for any other reason. */
+  | "SubmitFailed"
+  /** The wallet submitted, and named a transaction other than the one we assembled. */
+  | "WrongTransactionId"
+
+/**
+ * Exhaustive by type: adding a refusal above without listing it here fails to
+ * compile, and `test/sign.test.ts` fails if any of them stops being reachable.
+ */
+export const signRefusals: Readonly<Record<SignRefusal, true>> = {
+  UnreadableTransaction: true,
+  WrongBody: true,
+  Declined: true,
+  SignFailed: true,
+  UnreadableWitnesses: true,
+  UnexpectedWitnessMaterial: true,
+  NoWitnesses: true,
+  InputsSpent: true,
+  IntervalPassed: true,
+  SubmitFailed: true,
+  WrongTransactionId: true
+}
+
+/**
+ * Only the passed interval has a spec code, because only it is a failure of the
+ * exchange the spec describes — the intent outlived its own `validUntil`. The
+ * rest are states of a wallet or of the chain, and a protocol code on one of
+ * those would say the endpoint answered when nothing was ever asked of it
+ * (`wallet-error.ts` draws the same line).
+ */
+export const slipErrorCodeFor = (refusal: SignRefusal): ClientErrorCode | undefined =>
+  refusal === "IntervalPassed" ? "INTENT_EXPIRED" : undefined
+
+/** `cip30` is the wallet's own `{ code, info }`, kept so a decline stays distinguishable from a crash. */
+export class SigningError extends Data.TaggedError("SigningError")<{
+  readonly refusal: SignRefusal
+  readonly detail: string
+  readonly cip30?: Cip30ApiError
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    return this.detail
+  }
+
+  get code(): ClientErrorCode | undefined {
+    return slipErrorCodeFor(this.refusal)
+  }
+}
+
+export const refuse = (
+  refusal: SignRefusal,
+  detail: string,
+  extra: { readonly cip30?: Cip30ApiError; readonly cause?: unknown } = {}
+): SigningError =>
+  new SigningError({
+    refusal,
+    detail,
+    ...(extra.cip30 === undefined ? {} : { cip30: extra.cip30 }),
+    ...(extra.cause === undefined ? {} : { cause: extra.cause })
+  })

package/src/sign.ts

@@ -0,0 +1,118 @@
+/**
+ * `signTx` → witness assembly → `submitTx`. CIP-30 returns a **witness set**,
+ * never a signed transaction (invariant 4), so the body a person was shown and
+ * the body that reaches the chain are joined here or nowhere.
+ */
+import { Effect } from "effect"
+
+import { type CborHex, type Cip30Api, readApiError, REFUSED, USER_DECLINED } from "./cip30.js"
+import { refuse, type SigningError } from "./sign-error.js"
+import { assembleWitnesses, requireSameBody } from "./witness.js"
+
+export type SignRequest = {
+  readonly api: Cip30Api
+  /** The complete unsigned transaction. */
+  readonly transaction: CborHex
+  /**
+   * The id of the body the effects were derived from, from `transactionIdOf`.
+   * Required, not derived here: a signature is bound to the body a person was
+   * shown, and a function that recomputed the id from the bytes in front of it
+   * would bind it to whatever it was handed.
+   */
+  readonly transactionId: string
+}
+
+export type SignedTransaction = {
+  /** The body with the witnesses in it: what `submitTx` takes. */
+  readonly cbor: CborHex
+  /** Unchanged by signing, because witnesses live outside the body. */
+  readonly transactionId: string
+}
+
+/** What the wallet said, kept whole so a message names its own cause. */
+const said = (cause: unknown): string => {
+  const error = readApiError(cause)
+  if (error === undefined) return String(cause)
+  return error.info === "" ? `code ${error.code}` : error.info
+}
+
+/**
+ * Signs, or says why not. Nothing is asked of the wallet until the transaction
+ * is known to be the one the effects were derived from.
+ */
+export const signTransaction = ({
+  api,
+  transaction,
+  transactionId
+}: SignRequest): Effect.Effect<SignedTransaction, SigningError> =>
+  Effect.gen(function* () {
+    yield* requireSameBody(transaction, transactionId)
+
+    const witnesses = yield* Effect.tryPromise({
+      // `partialSign: true`: the wallet signs what it holds keys for and leaves
+      // the rest, rather than refusing a transaction a co-signer completes.
+      try: () => api.signTx(transaction, true),
+      catch: (cause) => {
+        const error = readApiError(cause)
+        // `-3` is `APIError`'s refusal, which wallets send from `signTx` in
+        // practice even though CIP-30 numbers a decline `2` here.
+        if (error?.code === USER_DECLINED || error?.code === REFUSED) {
+          return refuse("Declined", "The signature was declined in the wallet.", { cip30: error, cause })
+        }
+        return refuse("SignFailed", `The wallet could not sign this transaction: ${said(cause)}`, {
+          ...(error === undefined ? {} : { cip30: error }),
+          cause
+        })
+      }
+    })
+
+    const cbor = yield* assembleWitnesses(transaction, witnesses, transactionId)
+    return { cbor, transactionId }
+  })
+
+/** The ledger's own name for an input that is no longer there — what the rebuild path watches for. */
+const spentInputs = /BadInputsUTxO/i
+
+/** The ledger's name for a transaction that arrived outside its validity interval. */
+const outsideInterval = /OutsideValidityInterval/i
+
+const submissionFailure = (cause: unknown): SigningError => {
+  const error = readApiError(cause)
+  const detail = said(cause)
+  const extra = { ...(error === undefined ? {} : { cip30: error }), cause }
+
+  if (spentInputs.test(detail)) {
+    return refuse("InputsSpent", "The wallet's funds moved before this transaction reached the chain.", extra)
+  }
+  if (outsideInterval.test(detail)) {
+    return refuse("IntervalPassed", "This transaction expired before it reached the chain.", extra)
+  }
+  return refuse("SubmitFailed", `This transaction was not accepted: ${detail}`, extra)
+}
+
+/**
+ * Submits, and holds the wallet to the transaction it was given: an id other
+ * than the one we assembled is a receipt for something else, and showing it
+ * would tell a person their transaction is on the chain when another one is.
+ */
+export const submitTransaction = (api: Cip30Api, signed: SignedTransaction): Effect.Effect<string, SigningError> =>
+  Effect.gen(function* () {
+    const returned = yield* Effect.tryPromise({
+      try: () => api.submitTx(signed.cbor),
+      catch: submissionFailure
+    })
+
+    // Typed to answer with the id and under no obligation to: reading a method
+    // off whatever it did answer would reach a person as a stack trace.
+    if (typeof returned !== "string") {
+      return yield* Effect.fail(refuse("WrongTransactionId", "The wallet did not name the transaction it submitted."))
+    }
+
+    if (returned.toLowerCase() !== signed.transactionId.toLowerCase()) {
+      return yield* Effect.fail(
+        refuse("WrongTransactionId", "The wallet submitted a different transaction from the one it was given.")
+      )
+    }
+
+    return signed.transactionId
+  })