@cardano-slips/flow 0.0.2 → 0.1.0

package/dist/tokens.css

@@ -0,0 +1,184 @@
+/*
+ * 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 sheet's contrast audit
+ * against these values.
+ *
+ * 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.
+ *
+ * Three families of surface, and the difference is the point:
+ *   page / card    the ordinary ground, and what lifts off it
+ *   vault-*        the transaction preview, which separates itself by surface
+ *                  and border rather than by being dark
+ *   dark-*         code blocks and the Open Graph card, dark in both themes
+ */
+
+.slip-root {
+  color-scheme: light;
+
+  /* Surfaces. Depth is a border, never a shadow: there is no shadow token. */
+  --page: #f6f8fe; /* never pure white */
+  --card: #ffffff;
+  --subtle: rgba(114, 142, 243, 0.08); /* hover, chips */
+  --skeleton: rgba(114, 142, 243, 0.14);
+  --border: rgba(18, 23, 33, 0.12);
+  --divider: rgba(18, 23, 33, 0.1);
+
+  /* Ink */
+  --ink: #121721;
+  --muted: #5c6a9c;
+
+  /*
+   * The split rule: --accent-fill reaches 3.05:1 on the card and is a fill —
+   * it never carries text below 24px. An accent-coloured word uses
+   * --accent-text. It stays a fill in the dark theme too, where it would
+   * otherwise clear AA, because the rule is about what the colour is for.
+   */
+  --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(114, 142, 243, 0.16);
+  --stripe-b: rgba(114, 142, 243, 0.05);
+  --stripe-off-a: rgba(92, 106, 156, 0.12);
+  --stripe-off-b: rgba(92, 106, 156, 0.04);
+
+  /*
+   * The transaction preview. Its own family because it is the surface that
+   * judges the publisher, and `10 · Chrome rules` fixes it whoever hosts the
+   * page. It follows the theme like everything else.
+   */
+  --vault: #ffffff;
+  --vault-ink: #121721;
+  --vault-muted: #5c6a9c;
+  --vault-surface: rgba(114, 142, 243, 0.08);
+  --vault-border: rgba(18, 23, 33, 0.12);
+  --vault-chip: rgba(114, 142, 243, 0.16);
+  --vault-rule: rgba(114, 142, 243, 0.8);
+  --vault-pos: #1f7a5c;
+  --vault-warn: #8c5a12;
+  --vault-bad: #b3261e;
+  --vault-bad-tint: rgba(179, 38, 30, 0.06);
+  --vault-bad-line: rgba(179, 38, 30, 0.32);
+  --vault-bad-chip: rgba(179, 38, 30, 0.1);
+  --vault-warn-tint: rgba(233, 180, 76, 0.14);
+  --vault-warn-line: rgba(233, 180, 76, 0.55);
+
+  /*
+   * Dark in both themes, and nowhere else: code blocks in the docs and the
+   * Open Graph card. Deliberately absent from the dark theme below — a value
+   * that is fixed cannot also follow.
+   */
+  --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;
+}
+
+/*
+ * The dark theme rebinds the roles rather than adding a second vocabulary. A
+ * component writes var(--ink) once and is correct on both grounds; a component
+ * choosing between a light token and a dark one is a component deciding the
+ * rule, and two of them will decide it differently.
+ *
+ * Whether dark follows the operating system is not settled by the sheet, so it
+ * is not decided here: the attribute is the only way in.
+ */
+.slip-root[data-theme="dark"] {
+  color-scheme: dark;
+
+  --page: #121721; /* the brand dark */
+  --card: #1b2231; /* lifted off the page */
+  --subtle: rgba(114, 142, 243, 0.16);
+  --skeleton: rgba(114, 142, 243, 0.18);
+  --border: rgba(255, 255, 255, 0.14);
+  --divider: rgba(255, 255, 255, 0.1);
+
+  --ink: #ffffff;
+  --muted: #ccd6ff;
+
+  --accent-text: #a8bcff;
+  --accent-hover: #5c79ee;
+  --accent-deep: #a8bcff;
+  --focus: #a8bcff;
+
+  --pos: #5fd1a6;
+  --warn: #e9b44c;
+  --bad: #ffa39b;
+  --bad-tint: rgba(255, 163, 155, 0.1);
+  --bad-line: rgba(255, 163, 155, 0.4);
+  --warn-tint: rgba(233, 180, 76, 0.14);
+  --warn-line: rgba(233, 180, 76, 0.45);
+
+  --stripe-a: rgba(114, 142, 243, 0.26);
+  --stripe-b: rgba(114, 142, 243, 0.1);
+  --stripe-off-a: rgba(204, 214, 255, 0.16);
+  --stripe-off-b: rgba(204, 214, 255, 0.05);
+
+  --vault: #080b12; /* still the gravest surface */
+  --vault-ink: #ffffff;
+  --vault-muted: #ccd6ff;
+  --vault-surface: rgba(255, 255, 255, 0.08);
+  --vault-border: rgba(255, 255, 255, 0.14);
+  --vault-chip: rgba(114, 142, 243, 0.24);
+  --vault-rule: rgba(114, 142, 243, 0.5);
+  --vault-pos: #5fd1a6;
+  --vault-warn: #e9b44c;
+  --vault-bad: #ffa39b;
+  --vault-bad-tint: rgba(255, 163, 155, 0.08);
+  --vault-bad-line: rgba(255, 163, 155, 0.45);
+  --vault-bad-chip: rgba(255, 163, 155, 0.2);
+  --vault-warn-tint: rgba(233, 180, 76, 0.08);
+  --vault-warn-line: rgba(233, 180, 76, 0.45);
+}

package/dist/wallet-error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { 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 declare const connectRefusals: Readonly<Record<ConnectRefusal, 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 declare const slipErrorCodeFor: (refusal: ConnectRefusal) => ClientErrorCode | undefined;
+declare const WalletConnectError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WalletConnectError";
+} & Readonly<A>;
+/** `cip30` is the wallet's own `{ code, info }`, kept so a `-3` stays distinguishable from a crash. */
+export declare class WalletConnectError extends WalletConnectError_base<{
+    readonly refusal: ConnectRefusal;
+    readonly key: string;
+    readonly detail: string;
+    readonly cip30?: Cip30ApiError;
+}> {
+    get message(): string;
+    get code(): ClientErrorCode | undefined;
+}
+export declare const refuse: (refusal: ConnectRefusal, key: string, detail: string, cip30?: Cip30ApiError) => WalletConnectError;
+export {};
+//# sourceMappingURL=wallet-error.d.ts.map

package/dist/wallet-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-error.d.ts","sourceRoot":"","sources":["../src/wallet-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAG1D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,MAAM,cAAc;AACxB,sFAAsF;AACpF,aAAa;AACf,wEAAwE;GACtE,UAAU;AACZ,gFAAgF;GAC9E,SAAS;AACX,yFAAyF;GACvF,cAAc;AAChB,mGAAmG;GACjG,YAAY;AACd,2EAA2E;GACzE,cAAc,CAAA;AAElB;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,IAAI,CAAC,CAOlE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,cAAc,KAAG,eAAe,GAAG,SACnB,CAAA;;;;AAE1D,uGAAuG;AACvG,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;IAED,IAAI,IAAI,IAAI,eAAe,GAAG,SAAS,CAEtC;CACF;AAED,eAAO,MAAM,MAAM,GACjB,SAAS,cAAc,EACvB,KAAK,MAAM,EACX,QAAQ,MAAM,EACd,QAAQ,aAAa,KACpB,kBAAiH,CAAA"}

package/dist/wallet-error.js

@@ -0,0 +1,31 @@
+import { Data } from "effect";
+/**
+ * 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 = {
+    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) => 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") {
+    get message() {
+        return `${this.key}: ${this.detail}`;
+    }
+    get code() {
+        return slipErrorCodeFor(this.refusal);
+    }
+}
+export const refuse = (refusal, key, detail, cip30) => new WalletConnectError({ refusal, key, detail, ...(cip30 === undefined ? {} : { cip30 }) });
+//# sourceMappingURL=wallet-error.js.map

package/dist/wallet-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-error.js","sourceRoot":"","sources":["../src/wallet-error.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAkB7B;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2C;IACrE,WAAW,EAAE,IAAI;IACjB,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,IAAI;IACb,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,IAAI;CACnB,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAuB,EAA+B,EAAE,CACvF,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAA;AAE1D,uGAAuG;AACvG,MAAM,OAAO,kBAAmB,SAAQ,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAK3E;IACA,IAAa,OAAO;QAClB,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,MAAM,EAAE,CAAA;IACtC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACvC,CAAC;CACF;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,OAAuB,EACvB,GAAW,EACX,MAAc,EACd,KAAqB,EACD,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardano-slips/flow",
-  "version": "0.0.2",
+  "version": "0.1.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,9 @@
     "react": "^19.0.0"
   },
   "dependencies": {
-    "@cardano-slips/core": "^0.1.0",
-    "@cardano-slips/verifier": "^0.0.2"
+    "effect": "^3.22.1",
+    "@cardano-slips/core": "^0.2.0",
+    "@cardano-slips/verifier": "^0.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
@@ -53,7 +55,7 @@
     "typescript": "^6.0.3"
   },
   "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/cip30.ts

@@ -0,0 +1,94 @@
+/**
+ * The CIP-30 surface this client calls, declared here because evolution-sdk's
+ * `WalletApi` omits `getChangeAddress`, `getCollateral` and `getNetworkId`
+ * while the object a wallet actually hands back carries all three (ADR-0004).
+ * A typing we assert rather than one the SDK guarantees, so it is proved
+ * against a stubbed provider rather than trusted.
+ */
+
+/** Hex-encoded CBOR: the only form CIP-30 speaks, and the form `verifier` decodes. */
+export type CborHex = string
+
+export type Paginate = { readonly page: number; readonly limit: number }
+
+export type SignedData = { readonly signature: CborHex; readonly key: CborHex }
+
+export interface Cip30Api {
+  readonly getNetworkId: () => Promise<number>
+  readonly getChangeAddress: () => Promise<CborHex>
+  readonly getUsedAddresses: (paginate?: Paginate) => Promise<ReadonlyArray<CborHex>>
+  readonly getUnusedAddresses: () => Promise<ReadonlyArray<CborHex>>
+  readonly getRewardAddresses: () => Promise<ReadonlyArray<CborHex>>
+  readonly getBalance: () => Promise<CborHex>
+  /** `null` where the wallet has nothing to give, per CIP-30. */
+  readonly getUtxos: (amount?: CborHex, paginate?: Paginate) => Promise<ReadonlyArray<CborHex> | null>
+  readonly getCollateral: (params?: { readonly amount: CborHex }) => Promise<ReadonlyArray<CborHex> | null>
+  /** Returns a **witness set**, never a signed transaction — invariant 4 is CIP-30's own shape. */
+  readonly signTx: (tx: CborHex, partialSign?: boolean) => Promise<CborHex>
+  readonly signData: (address: CborHex, payload: CborHex) => Promise<SignedData>
+  readonly submitTx: (tx: CborHex) => Promise<string>
+}
+
+/** What an extension injects at `window.cardano[key]`, before anyone calls `enable()`. */
+export interface Cip30Provider {
+  readonly apiVersion: string
+  readonly name: string
+  readonly icon: string
+  readonly supportedExtensions?: ReadonlyArray<{ readonly cip: number }>
+  readonly enable: (extensions?: ReadonlyArray<{ readonly cip: number }>) => Promise<Cip30Api>
+  readonly isEnabled: () => Promise<boolean>
+}
+
+const isFunction = (value: unknown): boolean => typeof value === "function"
+
+/**
+ * Shape, not name: `window.cardano` is a namespace anything may write to, and a
+ * key that does not answer these four is not a connector whatever it is called.
+ */
+export const isCip30Provider = (value: unknown): value is Cip30Provider => {
+  if (typeof value !== "object" || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    isFunction(candidate.enable) &&
+    isFunction(candidate.isEnabled) &&
+    typeof candidate.name === "string" &&
+    typeof candidate.apiVersion === "string"
+  )
+}
+
+/** The methods we call. A provider may enable and still not answer them. */
+const apiMethods = ["getNetworkId", "getChangeAddress", "getUsedAddresses", "getUtxos", "signTx", "submitTx"] as const
+
+export const isCip30Api = (value: unknown): value is Cip30Api => {
+  if (typeof value !== "object" || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return apiMethods.every((method) => isFunction(candidate[method]))
+}
+
+/** CIP-30's `APIError`, kept whole: the numeric code is what says a person declined. */
+export type Cip30ApiError = { readonly code: number; readonly info: string }
+
+/** The four `APIError` codes CIP-30 defines. Anything else is passed through as its number. */
+export const apiErrorNames: Readonly<Record<number, string>> = {
+  [-1]: "InvalidRequest",
+  [-2]: "InternalError",
+  [-3]: "Refused",
+  [-4]: "AccountChange"
+}
+
+/** `-3` is the person saying no, which is not a fault and must not be shown as one. */
+export const REFUSED = -3
+
+/** 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
+  const candidate = cause as Record<string, unknown>
+  if (typeof candidate.code !== "number") return undefined
+  return { code: candidate.code, info: typeof candidate.info === "string" ? candidate.info : "" }
+}
+
+export const describeApiError = (error: Cip30ApiError): string => {
+  const name = apiErrorNames[error.code]
+  const label = name === undefined ? `code ${error.code}` : name
+  return error.info === "" ? label : `${label}: ${error.info}`
+}

package/src/connect.ts

@@ -0,0 +1,136 @@
+/**
+ * `enable()` and the three answers a connection is not usable without: the API
+ * object, the network, and the change address. Everything downstream of here —
+ * UTxOs, balancing, signing — goes through evolution-sdk with this API object
+ * (ADR-0004).
+ */
+import { type Network } from "@cardano-slips/core"
+import { Effect } from "effect"
+
+import { type NetworkId, readWalletAddress } from "./address.js"
+import { type Cip30Api, describeApiError, isCip30Api, readApiError, REFUSED } from "./cip30.js"
+import { type DiscoveredWallet, findWallet, injectedUnder } from "./discovery.js"
+import { refuse, type WalletConnectError } from "./wallet-error.js"
+
+export type ConnectOptions = {
+  /** The network the Slip declares. The wallet is held to it, not asked for it. */
+  readonly network: Network
+  /** Where `cardano` lives. Defaults to the global object, so a test never needs one. */
+  readonly host?: unknown
+  /** CIP extensions to ask for. A wallet may grant fewer, and none of ours are required. */
+  readonly extensions?: ReadonlyArray<{ readonly cip: number }>
+}
+
+export type ConnectedWallet = {
+  readonly wallet: DiscoveredWallet
+  readonly api: Cip30Api
+  /** The Slip's network, now known to be the wallet's as well. */
+  readonly network: Network
+  readonly networkId: NetworkId
+  /** Bech32, ready for a `BuildRequest`. */
+  readonly changeAddress: string
+}
+
+/**
+ * A CIP-19 address separates mainnet from testnet and no further, so this is
+ * every network id there is — preprod and preview are one value here. Telling
+ * them apart is exactly why a Slip states its network by name (`core/types.ts`).
+ */
+export const networkIdFor = (network: Network): NetworkId => (network === "mainnet" ? 1 : 0)
+
+const networkNames: Readonly<Record<NetworkId, string>> = { 0: "a test network", 1: "mainnet" }
+
+const call = <A>(key: string, method: string, run: () => Promise<A>): Effect.Effect<A, WalletConnectError> =>
+  Effect.tryPromise({
+    try: run,
+    catch: (cause) => {
+      const cip30 = readApiError(cause)
+      return refuse(
+        "Unreadable",
+        key,
+        `${method} failed: ${cip30 === undefined ? String(cause) : describeApiError(cip30)}`,
+        cip30
+      )
+    }
+  })
+
+/**
+ * Connects, or says why not. The network check happens here rather than in a
+ * component because it decides whether there is a connection at all: a wallet
+ * on another chain cannot sign this Slip's transaction, and letting the flow
+ * continue only moves the failure to where it costs a person more.
+ */
+export const connectWallet = (
+  key: string,
+  options: ConnectOptions
+): Effect.Effect<ConnectedWallet, WalletConnectError> =>
+  Effect.gen(function* () {
+    const host = options.host ?? globalThis
+    const wallet = findWallet(key, host)
+    if (wallet === undefined) {
+      return yield* Effect.fail(
+        injectedUnder(key, host) === undefined
+          ? refuse("NotInjected", key, "no wallet is installed under this name")
+          : refuse("NotCip30", key, "what is installed under this name does not implement CIP-30")
+      )
+    }
+
+    const api = yield* Effect.tryPromise({
+      try: () => wallet.provider.enable(options.extensions),
+      catch: (cause) => {
+        const cip30 = readApiError(cause)
+        if (cip30?.code === REFUSED) {
+          return refuse("Refused", key, "the connection was declined in the wallet", cip30)
+        }
+        const detail = cip30 === undefined ? String(cause) : describeApiError(cip30)
+        return refuse("EnableFailed", key, `the wallet could not be connected: ${detail}`, cip30)
+      }
+    })
+
+    // `enable()` is typed to return the API and is under no obligation to.
+    if (!isCip30Api(api)) {
+      return yield* Effect.fail(refuse("NotCip30", key, "the wallet connected without returning a CIP-30 API"))
+    }
+
+    const reported = yield* call(key, "getNetworkId", () => api.getNetworkId())
+    if (reported !== 0 && reported !== 1) {
+      return yield* Effect.fail(refuse("Unreadable", key, `getNetworkId answered ${String(reported)}`))
+    }
+    const networkId: NetworkId = reported === 1 ? 1 : 0
+
+    const hex = yield* call(key, "getChangeAddress", () => api.getChangeAddress())
+    const address = yield* readWalletAddress(hex).pipe(
+      Effect.mapError((detail) => refuse("Unreadable", key, `getChangeAddress answered ${detail}`))
+    )
+
+    // Two answers about one wallet. A wallet that gives both cannot be taken at
+    // either word, and the disagreement is not the person's to resolve.
+    if (address.networkId !== networkId) {
+      return yield* Effect.fail(
+        refuse(
+          "Unreadable",
+          key,
+          `the wallet reports ${networkNames[networkId]} and its change address is on ${networkNames[address.networkId]}`
+        )
+      )
+    }
+
+    const expected = networkIdFor(options.network)
+    if (networkId !== expected) {
+      return yield* Effect.fail(
+        refuse(
+          "WrongNetwork",
+          key,
+          `this Slip is on ${options.network} and the wallet is on ${networkNames[networkId]}`
+        )
+      )
+    }
+
+    return {
+      wallet,
+      api,
+      network: options.network,
+      networkId,
+      changeAddress: address.bech32
+    }
+  })