@cardano-slips/flow 0.0.3 → 0.2.0

package/dist/witness.d.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { CborHex } from "./cip30.js";
+import { type SigningError } from "./sign-error.js";
+/**
+ * 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 declare const transactionIdOf: (transaction: CborHex) => Effect.Effect<string, SigningError>;
+/**
+ * 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 declare const requireSameBody: (transaction: CborHex, transactionId: string) => Effect.Effect<void, SigningError>;
+/**
+ * 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 declare const assembleWitnesses: (transaction: CborHex, witnesses: CborHex, transactionId: string) => Effect.Effect<CborHex, SigningError>;
+//# sourceMappingURL=witness.d.ts.map

package/dist/witness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness.d.ts","sourceRoot":"","sources":["../src/witness.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAA;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAa3D;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAYxF,CAAA;AA0BD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,OAAO,EAAE,eAAe,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAO3G,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,aAAa,OAAO,EACpB,WAAW,OAAO,EAClB,eAAe,MAAM,KACpB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAwClC,CAAA"}

package/dist/witness.js

@@ -0,0 +1,101 @@
+/**
+ * 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 { refuse } from "./sign-error.js";
+const hex = /^[0-9a-fA-F]*$/;
+const bytesOf = (value) => {
+    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) => 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) => {
+    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) => {
+    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) => 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, transactionId) => 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, witnesses, transactionId) => 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;
+});
+//# sourceMappingURL=witness.js.map

package/dist/witness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness.js","sourceRoot":"","sources":["../src/witness.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardano-slips/flow",
-  "version": "0.0.3",
+  "version": "0.2.0",
   "description": "The client side of Cardano Slips: CIP-30 orchestration, local balancing, and the React components that render a Slip and block a signature when its effects disagree",
   "keywords": [
     "cardano",
@@ -24,6 +24,7 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./tokens.css": "./dist/tokens.css",
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -41,8 +42,11 @@
     "react": "^19.0.0"
   },
   "dependencies": {
-    "@cardano-slips/core": "^0.2.0",
-    "@cardano-slips/verifier": "^0.1.0"
+    "@evolution-sdk/evolution": "^0.5.13",
+    "@noble/hashes": "^2.0.1",
+    "effect": "^3.22.1",
+    "@cardano-slips/verifier": "^0.3.0",
+    "@cardano-slips/core": "^0.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
@@ -50,10 +54,11 @@
     "happy-dom": "^20.11.6",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@cardano-slips/example-slips": "^0.0.0"
   },
   "scripts": {
-    "build": "tsc -b tsconfig.build.json",
+    "build": "tsc -b tsconfig.build.json && mkdir -p dist && cp src/tokens.css dist/tokens.css",
     "typecheck": "tsc -b tsconfig.src.json && tsc -p tsconfig.test.json",
     "test": "vitest run",
     "lint": "eslint .",

package/src/address.ts

@@ -0,0 +1,69 @@
+/**
+ * CIP-30 hands addresses back as hex; the endpoint is sent bech32, because that
+ * is what a `BuildRequest` carries and what a person can recognise. The
+ * conversion is also the second statement of network — the header byte says
+ * which chain the address is for, and a wallet whose `getNetworkId` disagrees
+ * with its own address has answered two ways.
+ */
+import { PaymentAddress } from "@cardano-slips/core"
+import { encodeBech32 } from "@cardano-slips/verifier"
+import { Either, Schema } from "effect"
+
+/** CIP-30's `getNetworkId`: 1 is mainnet, 0 is every test network. */
+export type NetworkId = 0 | 1
+
+export type WalletAddress = {
+  readonly bech32: string
+  readonly networkId: NetworkId
+}
+
+const decodePaymentAddress = Schema.decodeUnknownEither(PaymentAddress)
+
+const refuse = (detail: string): Either.Either<never, string> => Either.left(detail)
+
+const fromHex = (hex: string): Uint8Array | undefined => {
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) return undefined
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let index = 0; index < bytes.length; index++)
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16)
+  return bytes
+}
+
+/**
+ * CIP-30 calls the value "the CBOR of the address" and wallets ship the address
+ * bytes bare. Both are accepted, and they cannot be confused: `0x58` as a first
+ * byte is a CBOR byte string of up to 255 bytes, and as an address header it
+ * would claim network 8, which does not exist.
+ */
+const unwrapCbor = (bytes: Uint8Array): Uint8Array =>
+  bytes.length > 2 && bytes[0] === 0x58 && bytes[1] === bytes.length - 2 ? bytes.subarray(2) : bytes
+
+/** CIP-19: the header's high nibble is the address type, the low nibble the network. Types 0-7 can hold a payment. */
+const LAST_PAYMENT_TYPE = 7
+
+/**
+ * Reads what CIP-30 returned. `Either` and not a throw: this runs on whatever a
+ * browser extension chose to send, and every refusal reaches a person as words.
+ */
+export const readWalletAddress = (hex: string): Either.Either<WalletAddress, string> => {
+  const raw = fromHex(hex.trim())
+  if (raw === undefined) return refuse(`${hex.slice(0, 16)}… is not hex`)
+
+  const bytes = unwrapCbor(raw)
+  const header = bytes[0]
+
+  const networkId = header & 0x0f
+  if (networkId !== 0 && networkId !== 1) return refuse(`the address header names network ${networkId}`)
+
+  const type = header >> 4
+  if (type > LAST_PAYMENT_TYPE) {
+    // A reward address (14, 15) or a Byron address (8) cannot receive change.
+    return refuse(`address type ${type} cannot hold a payment`)
+  }
+
+  const bech32 = encodeBech32(networkId === 1 ? "addr" : "addr_test", bytes)
+  return Either.match(decodePaymentAddress(bech32), {
+    onLeft: () => refuse(`${bech32.slice(0, 16)}… is not a payment address`),
+    onRight: () => Either.right({ bech32, networkId: networkId as NetworkId })
+  })
+}

package/src/balance-error.ts

@@ -0,0 +1,77 @@
+/**
+ * Why an intent did not become a transaction. Every refusal carries a spec
+ * error code, because each one is a failure of the exchange the spec describes
+ * rather than a state of a browser extension (`wallet-error.ts` is the other
+ * half, and deliberately has refusals that carry no code).
+ */
+import { type ClientErrorCode } from "@cardano-slips/core"
+import { Data } from "effect"
+
+export type BalanceRefusal =
+  /** `validUntil` has already passed. A fresh POST returns a fresh intent. */
+  | "IntentExpired"
+  /** An address in the intent encodes a different network from the Slip's. */
+  | "ForeignAddress"
+  /** A certificate or withdrawal needs the wallet's stake credential and the address carries none. */
+  | "NoStakeCredential"
+  /** The change address the wallet gave is not an address these bytes can be read as. */
+  | "UnreadableChangeAddress"
+  /** The intent withdraws rewards and nobody said what the reward balance is. */
+  | "RewardBalanceUnknown"
+  /** The wallet cannot cover the intent, the minimum ADA its outputs require, and the fee. */
+  | "InsufficientFunds"
+  /** The intent cannot be built into a valid transaction for any other reason. */
+  | "CannotBalance"
+
+/**
+ * Exhaustive by type: adding a refusal above without listing it here fails to
+ * compile, and `test/balance.test.ts` fails if any of them stops being reachable.
+ */
+export const balanceRefusals: Readonly<Record<BalanceRefusal, true>> = {
+  IntentExpired: true,
+  ForeignAddress: true,
+  NoStakeCredential: true,
+  UnreadableChangeAddress: true,
+  RewardBalanceUnknown: true,
+  InsufficientFunds: true,
+  CannotBalance: true
+}
+
+/**
+ * A wrong-network address is `MALFORMED_RESPONSE` and not `WRONG_NETWORK`:
+ * the latter is a disagreement the person can act on by switching wallets, and
+ * an endpoint that sent an address on another chain is not one of those.
+ */
+export const slipErrorCodeFor = (refusal: BalanceRefusal): ClientErrorCode => {
+  switch (refusal) {
+    case "IntentExpired":
+      return "INTENT_EXPIRED"
+    case "ForeignAddress":
+      return "MALFORMED_RESPONSE"
+    case "InsufficientFunds":
+      return "INSUFFICIENT_FUNDS"
+    case "NoStakeCredential":
+    case "UnreadableChangeAddress":
+    case "RewardBalanceUnknown":
+    case "CannotBalance":
+      return "CANNOT_BALANCE"
+  }
+}
+
+/** `cause` keeps what evolution-sdk said, so a build failure stays diagnosable. */
+export class BalanceError extends Data.TaggedError("BalanceError")<{
+  readonly refusal: BalanceRefusal
+  readonly detail: string
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    return this.detail
+  }
+
+  get code(): ClientErrorCode {
+    return slipErrorCodeFor(this.refusal)
+  }
+}
+
+export const refuse = (refusal: BalanceRefusal, detail: string, cause?: unknown): BalanceError =>
+  new BalanceError({ refusal, detail, ...(cause === undefined ? {} : { cause }) })

package/src/balance.ts

@@ -0,0 +1,285 @@
+/**
+ * The privacy-preserving heart of Mode A: the endpoint's half-transaction
+ * becomes a whole one here, against unspent outputs it never sees (ADR-0002).
+ *
+ * Every term arrives as an argument — unspent outputs, protocol parameters, the
+ * reward balance, the clock — for the same reason the verifier takes its five:
+ * a balancer that fetched them could be made slow, made to fail, or made to
+ * answer wrongly by whoever answered.
+ */
+import { addressIsOnNetwork, type Certificate, type Intent, type Network, type Output } from "@cardano-slips/core"
+import type { ProtocolParameters } from "@cardano-slips/verifier"
+import {
+  Address,
+  Assets,
+  DRep,
+  mainnet,
+  PoolKeyHash,
+  preprod,
+  preview,
+  Schema,
+  type SlotConfig,
+  Transaction,
+  type UTxO
+} from "@evolution-sdk/evolution"
+import {
+  makeTxBuilder,
+  type ProtocolParameters as BuilderParameters,
+  type ReadOnlyTransactionBuilder
+} from "@evolution-sdk/evolution/sdk/builders/TransactionBuilder"
+import { Effect } from "effect"
+
+import { type BalanceError, refuse } from "./balance-error.js"
+import type { CborHex } from "./cip30.js"
+
+/**
+ * The verifier's parameters plus the one bound the builder needs and the gate
+ * does not. One vocabulary across both halves: the figures that balance a
+ * transaction are the figures it will be judged against.
+ */
+export type BalancingParameters = ProtocolParameters & {
+  /** `maxTxSize`: the byte ceiling a built transaction must fit under. */
+  readonly maxTxSize: number
+}
+
+export type BalanceInputs = {
+  readonly intent: Intent
+  /** The Slip's network. Every address in the intent is held to it. */
+  readonly network: Network
+  /** Bech32, from the connected wallet. Change returns here. */
+  readonly changeAddress: string
+  readonly utxos: ReadonlyArray<UTxO.UTxO>
+  readonly parameters: BalancingParameters
+  /**
+   * The whole balance of the wallet's own reward account, required when the
+   * intent withdraws rewards. The ledger accepts one figure and only one, and
+   * no CIP-30 method answers it.
+   */
+  readonly rewardBalance?: bigint
+  /** Unix milliseconds. Handed in, so an expiry is decided by one clock and not two. */
+  readonly now: number
+}
+
+export type BalancedTransaction = {
+  /** The complete unsigned transaction: what `verifier` decodes and the wallet signs. */
+  readonly cbor: CborHex
+  readonly fee: bigint
+  /** The slot the body expires at, for the rebuild path to watch. */
+  readonly ttl: bigint
+}
+
+const chains = { mainnet, preprod, preview }
+
+/**
+ * The slot mapping comes from the parameters rather than from the chain preset:
+ * the client converts `validUntil` to a slot and the gate converts that slot
+ * back to a time, and two mappings would put an honest transaction outside its
+ * own declared window.
+ */
+const slotConfigOf = ({ slots }: BalancingParameters): SlotConfig.SlotConfig => ({
+  zeroTime: slots.time,
+  zeroSlot: slots.slot,
+  slotLength: Number(slots.slotLength)
+})
+
+const builderParameters = (parameters: BalancingParameters): BuilderParameters => ({
+  minFeeCoefficient: parameters.minFeeCoefficient,
+  minFeeConstant: parameters.minFeeConstant,
+  coinsPerUtxoByte: parameters.coinsPerUtxoByte,
+  maxTxSize: parameters.maxTxSize
+})
+
+/**
+ * What the builder reads for a certificate's deposit. The script fields are
+ * zeroed rather than guessed: version 1 builds no transaction that spends from
+ * a script, so a cost model here would be a figure nothing computes from.
+ */
+const depositParameters = (parameters: BalancingParameters) => ({
+  minFeeA: Number(parameters.minFeeCoefficient),
+  minFeeB: Number(parameters.minFeeConstant),
+  maxTxSize: parameters.maxTxSize,
+  maxValSize: 0,
+  keyDeposit: parameters.stakeDeposit,
+  poolDeposit: parameters.poolDeposit,
+  drepDeposit: parameters.drepDeposit,
+  govActionDeposit: parameters.governanceActionDeposit,
+  priceMem: 0,
+  priceStep: 0,
+  maxTxExMem: 0n,
+  maxTxExSteps: 0n,
+  coinsPerUtxoByte: parameters.coinsPerUtxoByte,
+  collateralPercentage: 0,
+  maxCollateralInputs: 0,
+  minFeeRefScriptCostPerByte: 0,
+  costModels: { PlutusV1: {}, PlutusV2: {}, PlutusV3: {} }
+})
+
+const assetsOf = (output: Output): Assets.Assets =>
+  (output.assets ?? []).reduce(
+    (assets, asset) => Assets.addByHex(assets, asset.policyId, asset.assetName, BigInt(asset.quantity)),
+    Assets.fromLovelace(BigInt(output.lovelace))
+  )
+
+/**
+ * `Schema.decodeSync(FromBech32)` and not `DRep.fromBech32`: the SDK's
+ * declarations carry that function and the shipped module does not export it,
+ * so calling it compiles and throws. The seventh gap of ADR-0004.
+ */
+const drepFromBech32 = Schema.decodeSync(DRep.FromBech32)
+
+const drepOf = (declared: Certificate & { readonly type: "voteDelegation" }): DRep.DRep => {
+  if (declared.drep === "abstain") return DRep.alwaysAbstain()
+  if (declared.drep === "noConfidence") return DRep.alwaysNoConfidence()
+  return drepFromBech32(declared.drep)
+}
+
+/**
+ * The Conway forms throughout. The legacy pair encodes no deposit and no
+ * refund, and evolution-sdk's builder therefore leaves both out of the balance —
+ * a transaction the ledger rejects, because consumed and produced no longer
+ * agree. The stated deposit is the protocol parameter exactly, which is what
+ * the ledger charges and what the gate holds it to (ADR-0013).
+ */
+const applyCertificate = (
+  builder: ReadOnlyTransactionBuilder,
+  declared: Certificate,
+  stakeCredential: StakeCredential
+): ReadOnlyTransactionBuilder => {
+  switch (declared.type) {
+    case "stakeRegistration":
+      return builder.registerStake({ stakeCredential })
+    case "stakeDeregistration":
+      return builder.deregisterStake({ stakeCredential })
+    case "stakeDelegation":
+      return builder.delegateToPool({ stakeCredential, poolKeyHash: PoolKeyHash.fromBech32(declared.poolId) })
+    case "voteDelegation":
+      return builder.delegateToDRep({ stakeCredential, drep: drepOf(declared) })
+  }
+}
+
+/** The staking half of a base address — what every certificate and withdrawal here acts on. */
+type StakeCredential = NonNullable<Address.Address["stakingCredential"]>
+
+/**
+ * What the transaction does to the wallet's own stake credential, gathered
+ * once so the credential is proved present before the builder runs rather than
+ * asserted inside it.
+ */
+type StakeActions = {
+  readonly credential: StakeCredential
+  readonly certificates: ReadonlyArray<Certificate>
+  /** The whole reward balance, or `null` where the intent withdraws nothing. */
+  readonly withdrawal: bigint | null
+}
+
+const actsOnStake = (intent: Intent): boolean =>
+  (intent.certificates ?? []).length > 0 || intent.withdrawRewards === true
+
+/** The two sites evolution-sdk reports a shortfall from, neither of which carries a structured cause. */
+const isShortfall = (message: string): boolean =>
+  message.startsWith("Coin selection failed") || message.includes("Insufficient funds to cover")
+
+const readFailure = (cause: unknown): BalanceError => {
+  const message = cause instanceof Error ? cause.message : String(cause)
+  return isShortfall(message)
+    ? refuse("InsufficientFunds", "This wallet does not hold enough to cover the transaction and its fee.", cause)
+    : refuse("CannotBalance", `This intent could not be built into a transaction: ${message}`, cause)
+}
+
+/**
+ * Builds the transaction, or says why not. Nothing here asks the network
+ * anything, and nothing describing what the wallet holds leaves this function.
+ */
+export const balanceIntent = (inputs: BalanceInputs): Effect.Effect<BalancedTransaction, BalanceError> =>
+  Effect.gen(function* () {
+    const { changeAddress, intent, network, parameters, utxos } = inputs
+
+    const validUntil = Date.parse(intent.validUntil)
+    if (validUntil <= inputs.now) {
+      return yield* Effect.fail(refuse("IntentExpired", "This request expired while it was open. Ask for a fresh one."))
+    }
+
+    for (const output of intent.outputs ?? []) {
+      if (!addressIsOnNetwork(output.address, network)) {
+        return yield* Effect.fail(
+          refuse("ForeignAddress", `This Slip is on ${network} and it asks to pay an address on another network.`)
+        )
+      }
+    }
+
+    // Inside the error channel, not thrown past it: the signature promises a
+    // `BalanceError` and a defect here would reach a person as a stack trace.
+    const change = yield* Effect.try({
+      try: () => Address.fromBech32(changeAddress),
+      catch: (cause) =>
+        refuse("UnreadableChangeAddress", "This wallet's change address could not be read as an address.", cause)
+    })
+    const credential = change.stakingCredential
+    if (actsOnStake(intent) && credential === undefined) {
+      return yield* Effect.fail(
+        refuse("NoStakeCredential", "This action acts on a stake credential and this wallet's address carries none.")
+      )
+    }
+
+    if (intent.withdrawRewards === true && inputs.rewardBalance === undefined) {
+      return yield* Effect.fail(
+        refuse("RewardBalanceUnknown", "The reward balance to withdraw is not known, so this cannot be built.")
+      )
+    }
+
+    const stake: StakeActions | null =
+      credential === undefined
+        ? null
+        : {
+            credential,
+            certificates: intent.certificates ?? [],
+            withdrawal: intent.withdrawRewards === true ? (inputs.rewardBalance ?? 0n) : null
+          }
+
+    const built = yield* Effect.tryPromise({
+      try: async () => {
+        let builder: ReadOnlyTransactionBuilder = makeTxBuilder({ chain: chains[network] })
+
+        for (const output of intent.outputs ?? []) {
+          // Declared lovelace is a floor: `autoMinUtxo` raises an output that
+          // cannot pay for its own bytes, and the difference is shown to the
+          // person as the client's own adjustment rather than folded in.
+          builder = builder.payToAddress({ address: Address.fromBech32(output.address), assets: assetsOf(output) })
+        }
+
+        if (stake !== null) {
+          for (const declared of stake.certificates) builder = applyCertificate(builder, declared, stake.credential)
+          if (stake.withdrawal !== null) {
+            builder = builder.withdraw({ stakeCredential: stake.credential, amount: stake.withdrawal })
+          }
+        }
+
+        // Never after `validUntil`, which is the whole of what the spec fixes here.
+        builder = builder.setValidity({ to: BigInt(validUntil) })
+
+        return await builder.build({
+          changeAddress: change,
+          availableUtxos: utxos,
+          protocolParameters: builderParameters(parameters),
+          fullProtocolParameters: depositParameters(parameters),
+          slotConfig: slotConfigOf(parameters),
+          autoMinUtxo: true,
+          // Leftover too small to become change would otherwise be paid as fee —
+          // lovelace leaving the wallet that nothing on screen accounted for.
+          onInsufficientChange: "error"
+        })
+      },
+      catch: readFailure
+    })
+
+    const transaction = yield* Effect.tryPromise({ try: () => built.toTransaction(), catch: readFailure })
+
+    const ttl = transaction.body.ttl
+    if (ttl === undefined) {
+      // We asked for an interval; a body without one could be submitted after
+      // `validUntil`, which is the one thing the spec forbids outright here.
+      return yield* Effect.fail(refuse("CannotBalance", "The built transaction carries no expiry, and it must."))
+    }
+
+    return { cbor: Transaction.toCBORHex(transaction), fee: transaction.body.fee, ttl }
+  })