@cardano-slips/flow 0.0.3 → 0.2.0

package/src/registry.ts

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

package/src/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
+  })

package/src/tokens.css

@@ -0,0 +1,133 @@
+/*
+ * 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 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
+ * page's own stack stays where it is until something of ours asks for a token.
+ *
+ * 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, 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: #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: #141a26;
+  --muted: #56628a;
+
+  /*
+   * 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-deep: #0c288d; /* headings */
+  --on-accent: #ffffff; /* anything drawn on --accent-action */
+  --focus: #4361e8;
+
+  /* Semantic, and rare. A page that colours everything says nothing. */
+  --pos: #1f7a5c; /* positive, refundable */
+  --warn: #8c5a12;
+  --bad: #b3261e;
+  --bad-tint: rgba(179, 38, 30, 0.06);
+  --bad-line: rgba(179, 38, 30, 0.24);
+  --warn-tint: rgba(233, 180, 76, 0.16);
+  --warn-line: rgba(233, 180, 76, 0.5);
+
+  /* The alternating rows of the effects list, on and off. */
+  --stripe-a: rgba(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 `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: #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: #5fd1a6;
+  --vault-warn: #e9b44c;
+  --vault-bad: #ffa39b;
+  --vault-bad-tint: rgba(255, 163, 155, 0.1);
+  --vault-bad-line: rgba(255, 163, 155, 0.45);
+  --vault-bad-chip: rgba(255, 163, 155, 0.18);
+  --vault-warn-tint: rgba(233, 180, 76, 0.12);
+  --vault-warn-line: rgba(233, 180, 76, 0.5);
+
+  /*
+   * 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;
+
+  /* Whole roles, so half a role cannot be applied without the other half. */
+  --type-h1: 700 44px/48px var(--font-display);
+  --type-h1-tracking: -0.01em;
+  --type-card-title: 700 18px/24px var(--font-display);
+  --type-numeral: 700 26px/32px var(--font-display); /* a figure is always Poppins 700 */
+  --type-body: 500 16px/24px var(--font-text);
+  --type-button: 500 14px/20px var(--font-text);
+  --type-button-tracking: 0.1px;
+  --type-label: 500 13px var(--font-text);
+  --type-mono: 400 12px/20px var(--font-mono); /* addresses, hashes, the tx block */
+
+  /* Spacing, on a 4px base. */
+  --space-4: 4px;
+  --space-8: 8px;
+  --space-12: 12px;
+  --space-16: 16px;
+  --space-20: 20px;
+  --space-24: 24px;
+  --space-32: 32px;
+  --space-48: 48px;
+
+  --radius-chip: 6px;
+  --radius-control: 8px;
+  --radius-card: 12px;
+}

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)
+}

package/src/wallet-error.ts

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

package/src/witness.ts

@@ -0,0 +1,132 @@
+/**
+ * The transaction id, and the witnesses that may go into the body it names.
+ * Pure: nothing here talks to a wallet, so what assembly accepts can be stated
+ * as a rule rather than observed against an extension.
+ */
+import { extractTransactionBody } from "@cardano-slips/verifier"
+import { Transaction, TransactionWitnessSet } from "@evolution-sdk/evolution"
+import { blake2b } from "@noble/hashes/blake2.js"
+import { Effect, Either } from "effect"
+
+import type { CborHex } from "./cip30.js"
+import { refuse, type SigningError } from "./sign-error.js"
+
+const hex = /^[0-9a-fA-F]*$/
+
+const bytesOf = (value: CborHex): Uint8Array | undefined => {
+  if (value.length % 2 !== 0 || !hex.test(value)) return undefined
+  return Uint8Array.from({ length: value.length / 2 }, (_, index) =>
+    Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)
+  )
+}
+
+const toHex = (bytes: Uint8Array): string => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")
+
+/**
+ * BLAKE2b-256 over the body's original bytes, never a re-encode: this is the id
+ * the chain computes, and it is CIP-0186's commit — what binds a returned
+ * witness set to the body whose effects a person was shown.
+ */
+export const transactionIdOf = (transaction: CborHex): Effect.Effect<string, SigningError> => {
+  const bytes = bytesOf(transaction)
+  if (bytes === undefined) {
+    return Effect.fail(refuse("UnreadableTransaction", "This transaction is not readable as CBOR."))
+  }
+  const body = extractTransactionBody(bytes)
+  if (Either.isLeft(body)) {
+    return Effect.fail(
+      refuse("UnreadableTransaction", `This transaction is not readable: ${body.left.message}`, { cause: body.left })
+    )
+  }
+  return Effect.succeed(toHex(blake2b(body.right.bodyBytes, { dkLen: 32 })))
+}
+
+/**
+ * What a version 1 transaction is never signed with. We build nothing that
+ * spends from a script, so any of these in a returned set is material the body
+ * was not judged with, and merging it would let a wallet add to a transaction
+ * after the moment it was shown.
+ */
+const unexpected = (set: TransactionWitnessSet.TransactionWitnessSet): string | undefined => {
+  if ((set.nativeScripts ?? []).length > 0) return "native scripts"
+  if ((set.bootstrapWitnesses ?? []).length > 0) return "bootstrap witnesses"
+  if ((set.plutusV1Scripts ?? []).length > 0) return "Plutus v1 scripts"
+  if ((set.plutusV2Scripts ?? []).length > 0) return "Plutus v2 scripts"
+  if ((set.plutusV3Scripts ?? []).length > 0) return "Plutus v3 scripts"
+  if ((set.plutusData ?? []).length > 0) return "datums"
+  if (set.redeemers !== undefined) return "redeemers"
+  return undefined
+}
+
+const readWitnessSet = (witnesses: CborHex): Effect.Effect<TransactionWitnessSet.TransactionWitnessSet, SigningError> =>
+  Effect.try({
+    try: () => TransactionWitnessSet.fromCBORHex(witnesses),
+    catch: (cause) =>
+      refuse("UnreadableWitnesses", "The wallet answered with something that is not a witness set.", { cause })
+  })
+
+/**
+ * Refuses unless this is the body the effects were derived from. Asked twice —
+ * before the wallet is given anything, and again as assembly begins — because
+ * either moment is one where the transaction can stop being the one on screen.
+ */
+export const requireSameBody = (transaction: CborHex, transactionId: string): Effect.Effect<void, SigningError> =>
+  Effect.flatMap(transactionIdOf(transaction), (held) =>
+    held === transactionId
+      ? Effect.void
+      : Effect.fail(
+          refuse("WrongBody", "This is not the transaction the effects were derived from, so it will not be signed.")
+        )
+  )
+
+/**
+ * Appends a returned witness set to the body it was asked for, or says why not.
+ * `transactionId` is the id the effects were derived from: witnesses go into
+ * that body or into none, which is what makes what a person was shown the thing
+ * they signed.
+ */
+export const assembleWitnesses = (
+  transaction: CborHex,
+  witnesses: CborHex,
+  transactionId: string
+): Effect.Effect<CborHex, SigningError> =>
+  Effect.gen(function* () {
+    yield* requireSameBody(transaction, transactionId)
+
+    const set = yield* readWitnessSet(witnesses)
+
+    const material = unexpected(set)
+    if (material !== undefined) {
+      return yield* Effect.fail(
+        refuse(
+          "UnexpectedWitnessMaterial",
+          `The wallet answered with ${material}, which this transaction never asked for.`
+        )
+      )
+    }
+
+    // evolution-sdk returns the transaction untouched for an empty set, so
+    // without this an unsigned transaction would go to `submitTx` looking signed.
+    if ((set.vkeyWitnesses ?? []).length === 0) {
+      return yield* Effect.fail(refuse("NoWitnesses", "The wallet answered without a signature."))
+    }
+
+    // Appends to `vkeyWitnesses` and re-encodes from the format the transaction
+    // arrived in, so a co-signer's witness survives and the body keeps its bytes.
+    const assembled = yield* Effect.try({
+      try: () => Transaction.addVKeyWitnessesHex(transaction, witnesses),
+      catch: (cause) =>
+        refuse("UnreadableWitnesses", "The wallet's witnesses could not be assembled into the transaction.", { cause })
+    })
+
+    // The body is what the id is taken over, so an id that moved means the
+    // bytes moved — and the person would be signing something else.
+    const after = yield* transactionIdOf(assembled)
+    if (after !== transactionId) {
+      return yield* Effect.fail(
+        refuse("WrongBody", "Assembling the signature changed the transaction, so it will not be submitted.")
+      )
+    }
+
+    return assembled
+  })