@cardano-slips/flow 0.2.0 → 0.3.0

package/src/exchange.ts

@@ -0,0 +1,212 @@
+/**
+ * The two HTTP exchanges a client makes: `GET` for the Slip and `POST` for the
+ * partial intent. Every way either can fail arrives as one error in the spec's
+ * vocabulary, classified by the rules in "Failure responses".
+ */
+import {
+  type BoundedAnswer,
+  boundedRequest,
+  type BoundedRequestOptions,
+  checkTemplates,
+  classifyErrorCode,
+  classifyStatus,
+  decodePartialIntent,
+  decodeSlip,
+  decodeSlipError,
+  fetchDomainMapping,
+  type InsecureSlipUrl,
+  type Network,
+  type PartialIntent,
+  PROTOCOL_VERSION,
+  resolveSlipUrl,
+  type Slip,
+  type SlipErrorClass
+} from "@cardano-slips/core"
+import { Data, Effect, Either } from "effect"
+
+export type ExchangeOptions = BoundedRequestOptions
+
+/**
+ * `code` is a spec code, or one an endpoint sent that the spec does not define.
+ * It is absent only where the body could not be read, and then `status` is all
+ * there is to go on.
+ */
+export class ExchangeError extends Data.TaggedError("ExchangeError")<{
+  readonly code?: string
+  readonly errorClass: SlipErrorClass
+  /** The endpoint's own words, present only when its failure body was readable. */
+  readonly endpointMessage?: string
+  readonly field?: string
+  readonly status?: number
+  /** Seconds, from `Retry-After`. */
+  readonly retryAfter?: number
+  /** For whoever integrates this; never put in front of a person. */
+  readonly detail: string
+}> {
+  override get message(): string {
+    return this.detail
+  }
+}
+
+const clientFailure = (code: string, detail: string, status?: number): ExchangeError =>
+  new ExchangeError({
+    code,
+    errorClass: classifyErrorCode(code),
+    detail,
+    ...(status === undefined ? {} : { status })
+  })
+
+/** Whole seconds or an HTTP date, per RFC 9110; anything else says nothing. */
+const readRetryAfter = (header: string | null, now: number): number | undefined => {
+  if (header === null) return undefined
+  const trimmed = header.trim()
+  if (/^\d+$/.test(trimmed)) return Number(trimmed)
+  const at = Date.parse(trimmed)
+  return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - now) / 1000))
+}
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return undefined
+  }
+}
+
+/** A major version is checked before the shape, so a newer protocol is not reported as a broken one. */
+const newerVersion = (body: unknown): string | undefined => {
+  if (typeof body !== "object" || body === null) return undefined
+  const version = (body as Record<string, unknown>).version
+  return typeof version === "string" && /^[1-9][0-9]*$/.test(version) && version !== PROTOCOL_VERSION
+    ? version
+    : undefined
+}
+
+const failureFrom = (response: Response, text: string): ExchangeError => {
+  const status = response.status
+  const retryAfter = readRetryAfter(response.headers.get("retry-after"), Date.now())
+  const retry = retryAfter === undefined ? {} : { retryAfter }
+  const body = parseJson(text)
+
+  const version = newerVersion(body)
+  if (version !== undefined) {
+    return clientFailure("UNSUPPORTED_VERSION", `the failure body speaks version ${version}`, status)
+  }
+
+  const read = decodeSlipError(body)
+  // Unreadable, so classified by status and never rendered: it is as likely an
+  // intermediary's error page as the publisher's words.
+  if (Either.isLeft(read)) {
+    return new ExchangeError({
+      errorClass: classifyStatus(status),
+      status,
+      detail: `answered ${status} with a body that is not a failure response`,
+      ...retry
+    })
+  }
+
+  return new ExchangeError({
+    code: read.right.code,
+    errorClass: classifyErrorCode(read.right.code),
+    endpointMessage: read.right.message,
+    status,
+    detail: `answered ${status} ${read.right.code}`,
+    ...(read.right.field === undefined ? {} : { field: read.right.field }),
+    ...retry
+  })
+}
+
+type Answer = BoundedAnswer
+
+/**
+ * One request, through core's bounded request. Anything that stops a usable
+ * answer arriving — DNS, TLS, a refused CORS read, the clock, the size — is `UNREACHABLE`.
+ */
+const exchange = (url: string, init: RequestInit, options: ExchangeOptions): Effect.Effect<Answer, ExchangeError> =>
+  boundedRequest(url, init, options).pipe(Effect.mapError((failure) => clientFailure(failure.code, failure.detail)))
+
+const successBody = ({ response, text }: Answer): Effect.Effect<unknown, ExchangeError> => {
+  if (response.status !== 200) return Effect.fail(failureFrom(response, text))
+  const body = parseJson(text)
+  if (body === undefined) {
+    return Effect.fail(clientFailure("MALFORMED_RESPONSE", `${response.url} answered 200 with something not JSON`))
+  }
+  const version = newerVersion(body)
+  if (version !== undefined) {
+    return Effect.fail(clientFailure("UNSUPPORTED_VERSION", `the response speaks version ${version}`))
+  }
+  return Effect.succeed(body)
+}
+
+export type FetchedSlip = {
+  readonly slip: Slip
+  /** The endpoint the link resolved to. Every `href` resolves against it. */
+  readonly discoveryUrl: string
+}
+
+/**
+ * The link to a Slip a person can be shown, or why not. `slips.json` is read
+ * first, because the link a person shares is not always the endpoint. A link
+ * that is not `https:` fails as `InsecureSlipUrl`, before anything is fetched.
+ */
+export const fetchSlip = (
+  link: string,
+  options: ExchangeOptions = {}
+): Effect.Effect<FetchedSlip, ExchangeError | InsecureSlipUrl> =>
+  Effect.gen(function* () {
+    const mapping = yield* fetchDomainMapping(link, options).pipe(
+      Effect.catchTag("DomainMappingFailure", (failure) => Effect.fail(clientFailure(failure.code, failure.detail)))
+    )
+    const discoveryUrl = yield* resolveSlipUrl(link, mapping)
+
+    const answer = yield* exchange(discoveryUrl, { method: "GET", headers: { accept: "application/json" } }, options)
+    const body = yield* successBody(answer)
+
+    const slip = decodeSlip(body)
+    if (Either.isLeft(slip)) {
+      return yield* Effect.fail(clientFailure("MALFORMED_RESPONSE", `${discoveryUrl} did not answer with a Slip`))
+    }
+
+    const defects = checkTemplates(slip.right, discoveryUrl)
+    if (defects.length > 0) {
+      return yield* Effect.fail(
+        clientFailure("MALFORMED_RESPONSE", `${discoveryUrl} answered a Slip with ${defects[0]?._tag ?? "a defect"}`)
+      )
+    }
+
+    return { slip: slip.right, discoveryUrl }
+  })
+
+export type IntentRequest = {
+  /** Absolute, as `SlipCard` hands it over. */
+  readonly href: string
+  readonly changeAddress: string
+  readonly network: Network
+}
+
+/**
+ * The partial intent for one action. The body is the change address and the
+ * network and nothing else: Mode A never tells an endpoint what a wallet holds.
+ */
+export const requestIntent = (
+  { changeAddress, href, network }: IntentRequest,
+  options: ExchangeOptions = {}
+): Effect.Effect<PartialIntent, ExchangeError> =>
+  Effect.gen(function* () {
+    const answer = yield* exchange(
+      href,
+      {
+        method: "POST",
+        headers: { accept: "application/json", "content-type": "application/json" },
+        body: JSON.stringify({ changeAddress, network })
+      },
+      options
+    )
+    const body = yield* successBody(answer)
+
+    const intent = decodePartialIntent(body)
+    if (Either.isLeft(intent)) {
+      return yield* Effect.fail(clientFailure("MALFORMED_RESPONSE", `${href} did not answer with a partial intent`))
+    }
+    return intent.right
+  })

package/src/explain.ts

@@ -0,0 +1,211 @@
+/**
+ * The words the effects panel puts in front of a person: exact figures, and a
+ * plain account of each mismatch. Nothing here rounds, and nothing guesses a
+ * token's decimals — the CIP requires base units where they are not known.
+ */
+import type { Reason, UnsupportedMember } from "@cardano-slips/verifier"
+
+const lovelacePerAda = 1_000_000n
+
+const grouped = (digits: string): string => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",")
+
+const magnitude = (value: bigint): bigint => (value < 0n ? -value : value)
+
+/** Lovelace as ADA, to the lovelace. The sign is dropped: "you pay" and "you receive" carry the direction. */
+export const formatAda = (lovelace: bigint): string => {
+  const amount = magnitude(lovelace)
+  const whole = grouped((amount / lovelacePerAda).toString())
+  const fraction = (amount % lovelacePerAda).toString().padStart(6, "0").replace(/0+$/, "")
+  return `${fraction === "" ? whole : `${whole}.${fraction}`} ADA`
+}
+
+/** A token quantity in base units, unsigned for the same reason as `formatAda`. */
+export const formatQuantity = (quantity: bigint): string => grouped(magnitude(quantity).toString())
+
+const bytesOf = (hex: string): Uint8Array =>
+  Uint8Array.from({ length: hex.length / 2 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16))
+
+/** The asset name as text, or null where it is not text a person could read — which is then no name at all. */
+export const assetLabel = (assetName: string): string | null => {
+  if (assetName === "") return null
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytesOf(assetName))
+    return /\p{C}/u.test(text) ? null : text
+  } catch {
+    return null
+  }
+}
+
+const tokenAmount = (quantity: bigint, policyId: string, assetName: string): string => {
+  const label = assetLabel(assetName)
+  return label === null
+    ? `${formatQuantity(quantity)} of token ${assetName || "with no name"} under policy ${policyId}`
+    : `${formatQuantity(quantity)} ${label}`
+}
+
+const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+/** Unix milliseconds as a UTC instant. UTC so that the publisher and the person read the same moment. */
+export const formatInstant = (time: bigint): string => {
+  const date = new Date(Number(time))
+  const two = (value: number): string => value.toString().padStart(2, "0")
+  return `${date.getUTCDate()} ${months[date.getUTCMonth()]} ${date.getUTCFullYear()}, ${two(date.getUTCHours())}:${two(date.getUTCMinutes())} UTC`
+}
+
+/** Whole seconds until `until`, never below zero. */
+export const secondsLeft = (until: bigint, now: bigint): number =>
+  until <= now ? 0 : Math.floor(Number(until - now) / 1000)
+
+/** The sheet's clock: `4m 12s`, and hours in front once there are any. */
+export const formatCountdown = (seconds: number): string => {
+  const hours = Math.floor(seconds / 3600)
+  const minutes = Math.floor((seconds % 3600) / 60)
+  const rest = `${(seconds % 60).toString().padStart(2, "0")}s`
+  return hours > 0 ? `${hours}h ${minutes.toString().padStart(2, "0")}m ${rest}` : `${minutes}m ${rest}`
+}
+
+/**
+ * A bech32 string cut to what a column can hold: the prefix, three characters,
+ * and the last four. Only where the full string is a click away.
+ */
+export const shortened = (text: string): string => {
+  const separator = text.lastIndexOf("1")
+  if (separator < 1 || text.length - separator <= 12) return text
+  return `${text.slice(0, separator + 4)}…${text.slice(-4)}`
+}
+
+const unsupportedWords: { readonly [member in UnsupportedMember]: string } = {
+  "reference-input": "reads another output without spending it",
+  collateral: "puts up collateral",
+  "required-signer": "asks for an extra signature",
+  vote: "casts a governance vote",
+  proposal: "submits a governance proposal",
+  donation: "donates to the treasury",
+  "treasury-value": "states the treasury's value",
+  script: "runs a script",
+  datum: "attaches data to an output"
+}
+
+const payments = (count: number): string => (count === 1 ? "1 payment" : `${count} payments`)
+
+const certificates = (count: number): string => (count === 1 ? "1 certificate" : `${count} certificates`)
+
+/**
+ * What the block shows for one reason, in the sheet's voice: the transaction
+ * is held to "the link", and a sentence never carries an address — `where` does,
+ * in full, beside it. The CIP asks for the difference, not the rule: `declared`
+ * is what the link asked for and `actual` is what the transaction does, where
+ * the reason has a figure for each.
+ */
+export type Explanation = {
+  readonly summary: string
+  readonly declared?: string
+  readonly actual?: string
+  /** The address or reward account the reason is about. */
+  readonly where?: string
+}
+
+export const explainReason = (reason: Reason): Explanation => {
+  switch (reason.code) {
+    case "output.missing":
+      return {
+        summary: "The transaction leaves out a payment the link asks for.",
+        declared: payments(reason.declared),
+        actual: payments(reason.paid),
+        where: reason.address
+      }
+    case "output.undeclared":
+      return reason.declared === 0
+        ? { summary: "The transaction pays an address the link never mentions.", where: reason.address }
+        : {
+            summary: "The transaction pays one address more times than the link asks for.",
+            declared: payments(reason.declared),
+            actual: payments(reason.paid),
+            where: reason.address
+          }
+    case "output.lovelace":
+      return {
+        summary: "The transaction pays a different amount of ADA from the one the link asks for.",
+        declared: formatAda(reason.declared),
+        actual: formatAda(reason.paid),
+        where: reason.address
+      }
+    case "output.assets":
+      return {
+        summary: "The transaction pays a different amount of a token from the one the link asks for.",
+        declared: tokenAmount(reason.declared, reason.policyId, reason.assetName),
+        actual: tokenAmount(reason.paid, reason.policyId, reason.assetName),
+        where: reason.address
+      }
+    case "certificate.missing":
+      return {
+        summary: "A certificate the link asks for is missing from the transaction.",
+        declared: certificates(reason.declared),
+        actual: certificates(reason.carried)
+      }
+    case "certificate.undeclared":
+      return {
+        summary: "The transaction carries a certificate the link never mentions.",
+        declared: certificates(reason.declared),
+        actual: certificates(reason.carried)
+      }
+    case "certificate.order":
+      return { summary: "The transaction's certificates are in a different order from the link's." }
+    case "certificate.target":
+      return {
+        summary: `Certificate ${reason.index + 1} names a different pool or DRep from the one the link asks for.`,
+        declared: reason.declared,
+        actual: reason.carried
+      }
+    case "certificate.credential":
+      return { summary: `Certificate ${reason.index + 1} acts on a stake key this wallet does not hold.` }
+    case "certificate.deposit":
+      return {
+        summary: `Certificate ${reason.index + 1} takes a deposit other than the one the network sets.`,
+        declared: formatAda(reason.parameter),
+        actual: formatAda(reason.stated)
+      }
+    case "withdrawal.missing":
+      return { summary: "The link asks to withdraw your rewards, and the transaction does not." }
+    case "withdrawal.undeclared":
+      return { summary: "The transaction withdraws rewards the link never mentions." }
+    case "withdrawal.account":
+      return {
+        summary: "The transaction withdraws from a reward account that is not this wallet's.",
+        where: reason.account
+      }
+    case "mint.undeclared":
+      return {
+        summary: "The transaction creates or destroys tokens, which no link can ask for.",
+        actual: reason.assets
+          .map(
+            (asset) =>
+              `${asset.quantity < 0n ? "Destroys" : "Creates"} ${tokenAmount(asset.quantity, asset.policyId, asset.assetName)}`
+          )
+          .join(", ")
+      }
+    case "body.unsupported":
+      return {
+        summary: `The transaction does things a link cannot describe: it ${reason.members
+          .map((member) => unsupportedWords[member])
+          .join(", ")}.`
+      }
+    case "fee.excessive":
+      return {
+        summary: "The network fee is higher than this transaction needs.",
+        declared: `At most ${formatAda(reason.ceiling)}`,
+        actual: formatAda(reason.fee)
+      }
+    case "interval.beyond-declared":
+      return {
+        summary: "The transaction stays valid for longer than the link says.",
+        declared: `Until ${formatInstant(reason.declared)}`,
+        actual: reason.validUntil === null ? "Never expires" : `Until ${formatInstant(reason.validUntil)}`
+      }
+    case "interval.not-yet-valid":
+      return {
+        summary: "The transaction cannot be submitted yet.",
+        actual: `Valid from ${formatInstant(reason.validFrom)}`
+      }
+  }
+}

package/src/index.ts

@@ -2,12 +2,13 @@
  * 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.
  */
-export type { NetworkId, WalletAddress } from "./address.js"
-export { readWalletAddress } from "./address.js"
+export type { NetworkId, OwnAddress, WalletAddress } from "./address.js"
+export { readOwnAddress, readWalletAddress } from "./address.js"
 export type { BalancedTransaction, BalanceInputs, BalancingParameters } from "./balance.js"
 export { balanceIntent } from "./balance.js"
 export type { BalanceRefusal } from "./balance-error.js"
 export { BalanceError, balanceRefusals, slipErrorCodeFor as balanceErrorCodeFor } from "./balance-error.js"
+export { actionLabel, actionsOf, blockedLabel, closureOf, monogramOf, originOf } from "./card.js"
 export type { CborHex, Cip30Api, Cip30ApiError, Cip30Provider, Paginate, SignedData } from "./cip30.js"
 export {
   apiErrorNames,
@@ -20,14 +21,47 @@ export {
   txSignErrorNames,
   USER_DECLINED
 } from "./cip30.js"
-export type { Attempt, CompletionRequest, Receipt } from "./complete.js"
+export type { Attempt, CompletionRequest, Progress, Receipt } from "./complete.js"
 export { completeIntent } from "./complete.js"
 export type { CompletionRefusal } from "./complete-error.js"
 export { CompletionError, completionRefusals, slipErrorCodeFor as completionErrorCodeFor } from "./complete-error.js"
 export type { ConnectedWallet, ConnectOptions } from "./connect.js"
 export { connectWallet, networkIdFor } from "./connect.js"
+export type { Derived } from "./derived.js"
 export type { DiscoveredWallet, WalletHost } from "./discovery.js"
 export { discoverWallets, findWallet, injectedUnder } from "./discovery.js"
+export type { EffectsPanelProps } from "./effects-panel.js"
+export { EffectsPanel } from "./effects-panel.js"
+export type { ExchangeOptions, FetchedSlip, IntentRequest } from "./exchange.js"
+export { ExchangeError, fetchSlip, requestIntent } from "./exchange.js"
+export type { Explanation } from "./explain.js"
+export {
+  assetLabel,
+  explainReason,
+  formatAda,
+  formatCountdown,
+  formatInstant,
+  formatQuantity,
+  secondsLeft,
+  shortened
+} from "./explain.js"
+export type { Amount, Evidence, Group, Headline, Mark, Row, Tone } from "./ledger.js"
+export {
+  blockedLine,
+  describeCertificate,
+  evidenceOf,
+  groupsOf,
+  headlineOf,
+  isCollapsed,
+  isGrouped,
+  ledgerOf,
+  matchLine,
+  rawLines
+} from "./ledger.js"
+export type { Outcome, OutcomePanelProps, SlipReceiptProps } from "./outcome-panel.js"
+export { networkNames, OutcomePanel, SlipReceipt } from "./outcome-panel.js"
+export type { FieldError, ParameterFormProps } from "./parameter-form.js"
+export { boundsOf, ParameterForm } from "./parameter-form.js"
 export type { KnownWallet } from "./registry.js"
 export { knownWallet, knownWallets } from "./registry.js"
 export { asResolvedInput, asResolvedInputs } from "./resolve.js"
@@ -35,6 +69,8 @@ export type { SignedTransaction, SignRequest } from "./sign.js"
 export { signTransaction, submitTransaction } from "./sign.js"
 export type { SignRefusal } from "./sign-error.js"
 export { signRefusals, SigningError, slipErrorCodeFor as signErrorCodeFor } from "./sign-error.js"
+export type { SlipCardErrorProps, SlipCardProps, SlipSubmission } from "./slip-card.js"
+export { SlipCard, SlipCardError, SlipCardSkeleton } from "./slip-card.js"
 export { readWalletUtxos } from "./utxo.js"
 export type { ConnectRefusal } from "./wallet-error.js"
 export { connectRefusals, slipErrorCodeFor, WalletConnectError } from "./wallet-error.js"