@cardano-slips/flow 0.1.0 → 0.2.0

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

package/src/cip30.ts

@@ -79,6 +79,25 @@ export const apiErrorNames: Readonly<Record<number, string>> = {
 /** `-3` is the person saying no, which is not a fault and must not be shown as one. */
 export const REFUSED = -3
 
+/**
+ * `TxSignError` and `TxSendError` are `APIError`'s shape on their own
+ * numbering, and the numbering is the footgun: a declined signature is `2`
+ * here, where `2` in `APIError` is an internal error. They never share a call,
+ * so which table applies is decided by the method that rejected.
+ */
+export const txSignErrorNames: Readonly<Record<number, string>> = {
+  1: "ProofGeneration",
+  2: "UserDeclined"
+}
+
+/** `2` from `signTx`: the person declined in the wallet. */
+export const USER_DECLINED = 2
+
+export const txSendErrorNames: Readonly<Record<number, string>> = {
+  1: "Refused",
+  2: "Failure"
+}
+
 /** A wallet rejects with a plain `{ code, info }` object, not an `Error`. */
 export const readApiError = (cause: unknown): Cip30ApiError | undefined => {
   if (typeof cause !== "object" || cause === null) return undefined

package/src/complete-error.ts

@@ -0,0 +1,83 @@
+/**
+ * Why a Slip did not reach the chain, for the failures that belong to the whole
+ * path rather than to building, signing or submitting alone. `Blocked` is the
+ * one that matters: it is invariant 3 in the error channel, and there is no
+ * field on it that lets anyone past.
+ */
+import { type ClientErrorCode } from "@cardano-slips/core"
+import type { Reason } from "@cardano-slips/verifier"
+import { Data } from "effect"
+
+export type CompletionRefusal =
+  /** The wallet reported no unspent outputs, so there is nothing to build from. */
+  | "NoUtxos"
+  /** What `getUtxos` answered is not something these bytes can be read as. */
+  | "UnreadableUtxos"
+  /** The effects could not be derived from the transaction, or compared with the declaration. */
+  | "CannotJudge"
+  /** The derived effects disagree with what the endpoint declared. Nothing signs after this. */
+  | "Blocked"
+  /** The caller could not put the effects in front of a person, so nothing may be signed. */
+  | "NotShown"
+  /** The funds kept moving, and the transaction has been rebuilt as often as it will be. */
+  | "OutOfAttempts"
+
+/**
+ * Exhaustive by type: adding a refusal above without listing it here fails to
+ * compile, and `test/complete.test.ts` fails if any of them stops being reachable.
+ */
+export const completionRefusals: Readonly<Record<CompletionRefusal, true>> = {
+  NoUtxos: true,
+  UnreadableUtxos: true,
+  CannotJudge: true,
+  Blocked: true,
+  NotShown: true,
+  OutOfAttempts: true
+}
+
+export const slipErrorCodeFor = (refusal: CompletionRefusal): ClientErrorCode | undefined => {
+  switch (refusal) {
+    case "Blocked":
+      return "EFFECTS_MISMATCH"
+    case "NoUtxos":
+      return "INSUFFICIENT_FUNDS"
+    case "CannotJudge":
+      return "CANNOT_BALANCE"
+    case "UnreadableUtxos":
+    case "NotShown":
+    case "OutOfAttempts":
+      return undefined
+  }
+}
+
+/**
+ * `reasons` is what the transaction actually does against what was declared,
+ * for the block to render. There is no way to carry on from one — a mismatch
+ * hard-blocks, with no override, no allowlist and no confirmation.
+ */
+export class CompletionError extends Data.TaggedError("CompletionError")<{
+  readonly refusal: CompletionRefusal
+  readonly detail: string
+  readonly reasons?: ReadonlyArray<Reason>
+  readonly cause?: unknown
+}> {
+  override get message(): string {
+    return this.detail
+  }
+
+  get code(): ClientErrorCode | undefined {
+    return slipErrorCodeFor(this.refusal)
+  }
+}
+
+export const refuse = (
+  refusal: CompletionRefusal,
+  detail: string,
+  extra: { readonly reasons?: ReadonlyArray<Reason>; readonly cause?: unknown } = {}
+): CompletionError =>
+  new CompletionError({
+    refusal,
+    detail,
+    ...(extra.reasons === undefined ? {} : { reasons: extra.reasons }),
+    ...(extra.cause === undefined ? {} : { cause: extra.cause })
+  })

package/src/complete.ts

@@ -0,0 +1,198 @@
+/**
+ * The whole path: build against what the wallet holds, judge it with the
+ * verifier's own engine, sign, submit. When the funds move underneath, every
+ * one of those happens again — a rebuilt transaction is a different transaction,
+ * and asking for a signature on it without deriving its effects first would put
+ * a person's name on something nobody read.
+ */
+import type { Intent, Network } from "@cardano-slips/core"
+import { compare, decodeTransaction, deriveEffects, type Effects } from "@cardano-slips/verifier"
+import { Effect, Either } from "effect"
+
+import { balanceIntent, type BalancingParameters } from "./balance.js"
+import type { BalanceError } from "./balance-error.js"
+import type { Cip30Api } from "./cip30.js"
+import { type CompletionError, refuse } from "./complete-error.js"
+import { asResolvedInputs } from "./resolve.js"
+import { signTransaction, submitTransaction } from "./sign.js"
+import type { SigningError } from "./sign-error.js"
+import { readWalletUtxos } from "./utxo.js"
+import { transactionIdOf } from "./witness.js"
+
+/** Enough rebuilds to outlast an unlucky moment, few enough that nobody is asked forever. */
+const defaultAttempts = 3
+
+export type Attempt = {
+  /** Counting from one, so a rendered "attempt 2 of 3" reads as a person would say it. */
+  readonly number: number
+  readonly transactionId: string
+  /** What this transaction does, derived from its own bytes. */
+  readonly effects: Effects
+}
+
+export type CompletionRequest = {
+  readonly api: Cip30Api
+  /** What the endpoint declared, and what the transaction is judged against. */
+  readonly intent: Intent
+  readonly network: Network
+  readonly changeAddress: string
+  /**
+   * Every address the wallet calls its own, its reward account included. An
+   * address missing from here is read as a stranger's, which turns the wallet's
+   * own change into an undeclared payment and blocks the Slip.
+   */
+  readonly userAddresses: ReadonlyArray<Uint8Array>
+  readonly parameters: BalancingParameters
+  readonly rewardBalance?: bigint
+  /** Read once per attempt: a rebuilt transaction gets its own validity window. */
+  readonly now?: () => number
+  /** How many times the transaction may be built. Beyond this the funds are moving faster than we can follow. */
+  readonly attempts?: number
+  /** Called once per attempt, after the effects are derived and before the wallet is asked to sign. */
+  readonly onAttempt?: (attempt: Attempt) => void
+}
+
+export type Receipt = {
+  readonly transactionId: string
+  readonly effects: Effects
+  /** How many transactions it took, which is how many times the funds moved plus one. */
+  readonly attempts: number
+}
+
+type Failure = BalanceError | CompletionError | SigningError
+
+const fromHex = (hex: string): Uint8Array =>
+  Uint8Array.from({ length: hex.length / 2 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16))
+
+const walletUtxos = (api: Cip30Api) =>
+  Effect.gen(function* () {
+    const answered = yield* Effect.tryPromise({
+      try: () => api.getUtxos(),
+      catch: (cause) => refuse("UnreadableUtxos", "The wallet could not say what it holds.", { cause })
+    })
+
+    // `null` is CIP-30's own answer for a wallet with nothing to give.
+    const hexes = answered ?? []
+    const read = readWalletUtxos(hexes)
+    if (Either.isLeft(read)) {
+      return yield* Effect.fail(
+        refuse("UnreadableUtxos", `The wallet's unspent outputs could not be read: ${read.left}`)
+      )
+    }
+    if (read.right.length === 0) {
+      return yield* Effect.fail(refuse("NoUtxos", "This wallet holds nothing to pay with."))
+    }
+    return read.right
+  })
+
+/**
+ * One transaction, from the wallet's outputs to a verdict. The judging happens
+ * here rather than at the caller so that no path reaches `signTransaction`
+ * without having passed it.
+ */
+const buildAndJudge = (request: CompletionRequest, number: number) =>
+  Effect.gen(function* () {
+    const utxos = yield* walletUtxos(request.api)
+    const now = (request.now ?? Date.now)()
+
+    const built = yield* balanceIntent({
+      intent: request.intent,
+      network: request.network,
+      changeAddress: request.changeAddress,
+      utxos,
+      parameters: request.parameters,
+      ...(request.rewardBalance === undefined ? {} : { rewardBalance: request.rewardBalance }),
+      now
+    })
+
+    const transaction = decodeTransaction(fromHex(built.cbor))
+    if (Either.isLeft(transaction)) {
+      return yield* Effect.fail(
+        refuse("CannotJudge", `This transaction could not be read back: ${transaction.left.message}`)
+      )
+    }
+
+    const effects = deriveEffects({
+      transaction: transaction.right,
+      userAddresses: request.userAddresses,
+      resolvedInputs: asResolvedInputs(utxos),
+      protocolParameters: request.parameters
+    })
+    if (Either.isLeft(effects)) {
+      return yield* Effect.fail(
+        refuse("CannotJudge", `What this transaction does could not be worked out: ${effects.left.message}`)
+      )
+    }
+
+    const verdict = compare({
+      effects: effects.right,
+      declared: request.intent,
+      changeAddress: request.changeAddress,
+      now: BigInt(now),
+      protocolParameters: request.parameters
+    })
+    if (Either.isLeft(verdict)) {
+      return yield* Effect.fail(
+        refuse(
+          "CannotJudge",
+          `This transaction could not be checked against what was declared: ${verdict.left.message}`
+        )
+      )
+    }
+
+    if (verdict.right._tag === "mismatch") {
+      return yield* Effect.fail(
+        refuse("Blocked", "This transaction does not do what the Slip said it would, so it will not be signed.", {
+          reasons: verdict.right.reasons
+        })
+      )
+    }
+
+    const transactionId = yield* transactionIdOf(built.cbor)
+    const attempt: Attempt = { number, transactionId, effects: effects.right }
+
+    // The caller is what puts these effects in front of a person. If that
+    // throws, the person has not seen them, so this fails closed rather than
+    // carrying on to a signature — and as a refusal rather than a stack trace.
+    yield* Effect.try({
+      try: () => request.onAttempt?.(attempt),
+      catch: (cause) => refuse("NotShown", "This transaction could not be shown, so it will not be signed.", { cause })
+    })
+
+    return { cbor: built.cbor, attempt }
+  })
+
+/**
+ * Completes the Slip, or says why not. A submission that failed because an
+ * input was spent is the one failure worth repeating: everything else either
+ * cannot be helped by a rebuild or is a person having said no.
+ */
+export const completeIntent = (request: CompletionRequest): Effect.Effect<Receipt, Failure> =>
+  Effect.gen(function* () {
+    const allowed = Math.max(1, request.attempts ?? defaultAttempts)
+
+    for (let number = 1; number <= allowed; number += 1) {
+      const { attempt, cbor } = yield* buildAndJudge(request, number)
+
+      const signed = yield* signTransaction({
+        api: request.api,
+        transaction: cbor,
+        transactionId: attempt.transactionId
+      })
+
+      const submitted = yield* Effect.either(submitTransaction(request.api, signed))
+      if (Either.isRight(submitted)) {
+        return { transactionId: submitted.right, effects: attempt.effects, attempts: number }
+      }
+      if (submitted.left.refusal !== "InputsSpent") {
+        return yield* Effect.fail(submitted.left)
+      }
+    }
+
+    return yield* Effect.fail(
+      refuse(
+        "OutOfAttempts",
+        `The wallet's funds moved every time this was built, ${allowed} times over. Try again in a moment.`
+      )
+    )
+  })

package/src/index.ts

@@ -4,13 +4,38 @@
  */
 export type { NetworkId, WalletAddress } from "./address.js"
 export { 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 type { CborHex, Cip30Api, Cip30ApiError, Cip30Provider, Paginate, SignedData } from "./cip30.js"
-export { apiErrorNames, describeApiError, isCip30Api, isCip30Provider, readApiError, REFUSED } from "./cip30.js"
+export {
+  apiErrorNames,
+  describeApiError,
+  isCip30Api,
+  isCip30Provider,
+  readApiError,
+  REFUSED,
+  txSendErrorNames,
+  txSignErrorNames,
+  USER_DECLINED
+} from "./cip30.js"
+export type { Attempt, CompletionRequest, 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 { DiscoveredWallet, WalletHost } from "./discovery.js"
 export { discoverWallets, findWallet, injectedUnder } from "./discovery.js"
 export type { KnownWallet } from "./registry.js"
 export { knownWallet, knownWallets } from "./registry.js"
+export { asResolvedInput, asResolvedInputs } from "./resolve.js"
+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 { readWalletUtxos } from "./utxo.js"
 export type { ConnectRefusal } from "./wallet-error.js"
 export { connectRefusals, slipErrorCodeFor, WalletConnectError } from "./wallet-error.js"
+export { assembleWitnesses, requireSameBody, transactionIdOf } from "./witness.js"

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)