@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/example/src/components/TransferPanel.vue

@@ -0,0 +1,416 @@
+<script setup lang="ts">
+import { computed, markRaw, ref, shallowRef, watch } from 'vue'
+import {
+  GeeqError,
+  coinTransferSubmitBody,
+  fromBase64,
+  submitRoute,
+  toBase64,
+  toHex,
+} from '@geeqdev/geeq-sdk'
+import type { CoinTransferTx, GeeqChain, GeeqKeypair, GeeqNft, GeeqTrackedTx } from '@geeqdev/geeq-sdk'
+import type { SocketConnection } from '../composables/useSocketConnection'
+import { penniesLabel } from '../pennies'
+import ChainState from './ChainState.vue'
+import CopyButton from './CopyButton.vue'
+import SocketWarning from './SocketWarning.vue'
+import TxDeadline from './TxDeadline.vue'
+import TxFee from './TxFee.vue'
+import TxStatus from './TxStatus.vue'
+
+const props = defineProps<{
+  keypair: GeeqKeypair | null
+  chain: GeeqChain | null
+  connection: SocketConnection
+}>()
+
+const recipient = ref('')
+/** The amount box, as typed: text, so no digits are lost on the way to the SDK. */
+const typedAmount = ref('')
+/** What this transfer sends: coin, or digital assets, which go with the chain's minimum. */
+const sending = ref<'geeq' | 'assets'>('geeq')
+
+/** This account's digital assets as the ledger last listed them, or null before the first look. */
+const assets = shallowRef<readonly GeeqNft[] | null>(null)
+const loadingAssets = ref(false)
+const assetsError = ref('')
+/** The base64 ids of the digital assets ticked to send. */
+const chosen = ref<string[]>([])
+
+const tx = ref<CoinTransferTx | null>(null)
+const building = ref(false)
+const buildError = ref<{ code: string; message: string } | null>(null)
+const submitting = ref(false)
+const submitError = ref('')
+const submitResult = ref('')
+/** Set when the check before submitting found the built transfer too old. */
+const expired = ref(false)
+/**
+ * The last submission, followed to its verdict. Not cleared when the inputs change: the
+ * transaction is already out, and its answer is still worth showing.
+ */
+const tracked = shallowRef<GeeqTrackedTx | null>(null)
+/** Why the last submission is not being followed, when it is not. */
+const notTracked = ref('')
+
+/** Filled after a build, which is the first moment the ledger has been read. */
+const balance = ref<bigint | null>(null)
+const minimum = ref<bigint | null>(null)
+
+/** Every SDK failure carries a stable code; branch on that, never on the message. */
+function asGeeq(error: unknown): { code: string; message: string } {
+  if (error instanceof GeeqError) return { code: error.code, message: error.message }
+  const e = error as { name?: string; code?: string; message?: string }
+  if (e?.name === 'GeeqError' && typeof e.code === 'string') {
+    return { code: e.code, message: e.message ?? '' }
+  }
+  return { code: 'unknown', message: (error as Error)?.message ?? String(error) }
+}
+
+/**
+ * What the typed figure comes to in pennies.
+ *
+ * The chain parses it at its own pennies-per-Geeq, so the demo does not get its own opinion
+ * about decimal places — and `null` here means "not a valid amount yet" rather than zero.
+ */
+const pennies = computed<bigint | null>(() => {
+  const typed = typedAmount.value.trim()
+  if (typed === '' || props.chain === null) return null
+  try {
+    return props.chain.toPennies({ geeq: typed })
+  } catch {
+    return null
+  }
+})
+
+const amountProblem = computed(() => {
+  const typed = typedAmount.value.trim()
+  if (typed === '' || props.chain === null) return null
+  try {
+    const value = props.chain.toPennies({ geeq: typed })
+    if (value === 0n) return 'An amount of zero moves nothing.'
+    return null
+  } catch (error) {
+    return asGeeq(error).message
+  }
+})
+
+const canBuild = computed(
+  () =>
+    props.keypair !== null &&
+    props.chain !== null &&
+    recipient.value.trim() !== '' &&
+    (sending.value === 'geeq' ? pennies.value !== null && pennies.value > 0n : chosen.value.length > 0),
+)
+
+/**
+ * Drop the built transfer. One that was never sent gives its nonce back, so building
+ * again in the same block is not refused.
+ */
+function dropTx() {
+  if (tx.value !== null && submitResult.value === '') props.chain?.discard(tx.value)
+  tx.value = null
+  submitResult.value = ''
+  expired.value = false
+}
+
+// A built transfer is pinned to a block and a nonce, so any change invalidates it.
+watch([recipient, typedAmount, sending, chosen, () => props.keypair, () => props.chain], () => {
+  dropTx()
+  submitError.value = ''
+})
+watch([() => props.keypair, () => props.chain], () => {
+  assets.value = null
+  chosen.value = []
+})
+
+async function loadAssets() {
+  if (props.keypair === null || props.chain === null) return
+
+  loadingAssets.value = true
+  assetsError.value = ''
+  try {
+    // A fresh read: a digital asset just created or sent shows only once a block has
+    // confirmed it.
+    assets.value = await props.chain.findNfts({ owner: props.keypair, maxAgeMs: 0 })
+    chosen.value = []
+  } catch (error) {
+    assetsError.value = (error as Error).message
+  } finally {
+    loadingAssets.value = false
+  }
+}
+
+async function build() {
+  const keypair = props.keypair
+  const chain = props.chain
+  if (keypair === null || chain === null) return
+
+  building.value = true
+  buildError.value = null
+  dropTx()
+  try {
+    // One call: reads the ledger, checks the recipient's chain, the balance and the
+    // chain's own minimum, then signs. Digital assets are named by id; the SDK checks this
+    // account holds them and sends them with the chain's minimum.
+    tx.value = await chain.createTransfer(
+      sending.value === 'geeq'
+        ? { from: keypair, to: recipient.value.trim(), amount: { geeq: typedAmount.value.trim() } }
+        : { from: keypair, to: recipient.value.trim(), nfts: chosen.value.map((id) => fromBase64(id)) },
+    )
+
+    const state = await chain.getChainState({ account: keypair })
+    balance.value = state.balance
+    minimum.value = state.minimumTransfer ?? null
+  } catch (error) {
+    buildError.value = asGeeq(error)
+  } finally {
+    building.value = false
+  }
+}
+
+/**
+ * A transfer is a validation-layer transaction: one blob, posted as `uvt`. Evidence is an
+ * application-layer one and posts two as `uat`. Same node either way, and tracked
+ * the same way.
+ */
+async function submit() {
+  const built = tx.value
+  const target = built?.nodeUrl ?? props.chain?.endpoint
+  if (built === null || target === undefined || props.chain === null) return
+
+  submitting.value = true
+  submitError.value = ''
+  submitResult.value = ''
+  tracked.value = null
+  notTracked.value = ''
+  try {
+    // It may have waited, and a node refuses one the chain has moved too far past.
+    if (await props.chain.isExpired(built)) {
+      expired.value = true
+      return
+    }
+
+    // Listen before sending: a verdict that arrives before anyone has subscribed is lost.
+    // Without a socket it is still sent, only with no one listening for the answer.
+    const socket = props.connection.socket
+    if (socket === null) {
+      notTracked.value = 'The node socket is not open.'
+    } else {
+      try {
+        tracked.value = markRaw(await socket.track(built))
+      } catch (e) {
+        notTracked.value = `Could not subscribe for its verdict: ${(e as Error).message}`
+      }
+    }
+
+    const response = await fetch(submitRoute(target), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: coinTransferSubmitBody(built.transaction),
+    })
+    const body = await response.text()
+    if (!response.ok) {
+      // A node sends no status for a submission it refused, so the tracker has to be told.
+      tracked.value?.refused({ status: response.status, message: body.slice(0, 400) })
+      submitError.value = `Node replied ${response.status} ${response.statusText}: ${body.slice(0, 400)}`
+      return
+    }
+    submitResult.value = body === '' ? `${response.status} (empty body)` : body.slice(0, 1000)
+  } catch (e) {
+    // The POST may still have arrived, so a tracked transaction stays tracked.
+    submitError.value = `Could not reach the node — ${(e as Error).message}.`
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">5</span>Send coin or digital assets</h2>
+
+    <p class="hint" style="margin-top: 0">
+      Paste an address, then send geeq or digital assets. The SDK reads the ledger, checks
+      that the address belongs to this chain and that the amount clears the chain's own
+      minimum, then signs, works out the fee from the signed bytes, and checks the account
+      holds the amount plus the fee.
+    </p>
+
+    <div class="row">
+      <label class="choice">
+        <input v-model="sending" type="radio" value="geeq" data-testid="send-geeq" /> Geeq
+      </label>
+      <label class="choice">
+        <input v-model="sending" type="radio" value="assets" data-testid="send-assets" /> Digital assets
+      </label>
+    </div>
+
+    <template v-if="sending === 'assets'">
+      <div class="row">
+        <button :disabled="!keypair || !chain || loadingAssets" data-testid="transfer-get-assets" @click="loadAssets">
+          {{ loadingAssets ? 'Reading ledger…' : assets ? 'Refresh' : 'Get my digital assets' }}
+        </button>
+      </div>
+      <div v-if="assetsError" class="warn">{{ assetsError }}</div>
+      <p v-if="assets && assets.length === 0" class="hint">None yet — create one in step 7.</p>
+      <label v-for="asset in assets" :key="toBase64(asset.id)" class="choice asset">
+        <input v-model="chosen" type="checkbox" :value="toBase64(asset.id)" data-testid="asset-choice" />
+        <span>{{ asset.metadata.join(', ') || 'No labels' }}</span>
+        <code>{{ toBase64(asset.id) }}</code>
+      </label>
+      <p class="hint">
+        Tick one or several. They go in one transaction, with the chain's minimum transfer:
+        every transfer must carry at least that much coin.
+      </p>
+    </template>
+
+    <div class="row" style="margin-top: 12px">
+      <span class="ctl grow">
+        <label for="recipient">To</label>
+        <input
+          id="recipient"
+          v-model="recipient"
+          type="text"
+          placeholder="address"
+          spellcheck="false"
+          data-testid="recipient"
+        />
+      </span>
+      <span v-if="sending === 'geeq'" class="ctl">
+        <label for="amount">Geeq</label>
+        <input
+          id="amount"
+          v-model="typedAmount"
+          type="text"
+          inputmode="decimal"
+          placeholder="1.50"
+          data-testid="amount"
+        />
+      </span>
+      <button class="primary" :disabled="!canBuild || building" data-testid="build-transfer" @click="build">
+        {{ building ? 'Reading ledger & signing…' : 'Build & sign' }}
+      </button>
+    </div>
+
+    <template v-if="sending === 'geeq'">
+      <p v-if="chain" class="hint">
+        Amounts are counted in <strong>pennies</strong>, {{ chain.penniesPerGeeq }} to a Geeq as
+        this app is set up.
+        <template v-if="pennies !== null"
+          >That is <strong data-testid="pennies">{{ pennies }}</strong> pennies.</template
+        >
+        <template v-else>The SDK refuses more decimal places than that allows, rather than rounding.</template>
+      </p>
+      <p v-if="amountProblem" class="warn" data-testid="amount-problem">{{ amountProblem }}</p>
+    </template>
+
+    <div v-if="balance !== null && chain" class="field">
+      <div class="k">Balance · as at the last ledger read</div>
+      <div class="v" data-testid="balance">
+        {{ chain.formatGeeq(balance) }} geeq {{ penniesLabel(balance) }}
+        <span v-if="minimum !== null" class="hint" style="margin-left: 8px">
+          minimum transfer {{ chain.formatGeeq(minimum) }} geeq {{ penniesLabel(minimum) }}
+        </span>
+      </div>
+    </div>
+
+    <div v-if="buildError" class="warn" data-testid="transfer-error">
+      <template v-if="buildError.code === 'insufficient-funds'">
+        <strong>Not enough coin.</strong> {{ buildError.message }}
+      </template>
+      <template v-else-if="buildError.code === 'chain-mismatch'">
+        <strong>That address belongs to another chain.</strong>
+        {{ buildError.message }}
+      </template>
+      <template v-else-if="buildError.code === 'amount-below-minimum'">
+        <strong>Below this chain's minimum.</strong> {{ buildError.message }}
+      </template>
+      <template v-else-if="buildError.code === 'account-not-found'">
+        <strong>This account has never received coins.</strong> It cannot send what it does
+        not have — fund it first.
+        <div v-if="keypair" class="row" style="margin-top: 8px">
+          <code class="v" style="flex: 1 1 auto">{{ toBase64(keypair.accountId) }}</code>
+          <CopyButton :value="toBase64(keypair.accountId)" />
+        </div>
+      </template>
+      <template v-else>{{ buildError.message }}</template>
+    </div>
+
+    <template v-if="tx && chain">
+      <div class="field">
+        <div class="k">Sending</div>
+        <div class="v" data-testid="transfer-summary">
+          <template v-if="tx.nfts.length > 0">{{ tx.nfts.length }} digital asset{{ tx.nfts.length === 1 ? '' : 's' }} + </template
+          >{{ chain.formatGeeq(tx.amount) }} geeq {{ penniesLabel(tx.amount) }} → {{ toBase64(tx.to) }}
+        </div>
+      </div>
+
+      <ChainState :chain-state="tx.chainState" nonce-of="this account" />
+      <TxFee :chain="chain" :fee="tx.fee" :amount="tx.amount" payer="this account" />
+
+      <div class="field">
+        <div class="k">Transaction hash · hex · how the chain identifies it</div>
+        <div class="v">{{ toHex(tx.transactionHash) }}</div>
+      </div>
+
+      <div class="field">
+        <div class="k">
+          Signed transaction · base64 · {{ tx.transaction.length }} chars ·
+          no separate payload
+        </div>
+        <div class="v wrap" data-testid="transfer-base64">{{ tx.transaction }}</div>
+        <div class="row" style="margin-top: 7px"><CopyButton :value="tx.transaction" /></div>
+      </div>
+
+      <h3 class="sub">Submit</h3>
+      <p class="hint">
+        A transfer is sent as the signed transaction alone, with no payload — unlike
+        evidence. It goes to the same node.
+      </p>
+      <div class="row">
+        <button
+          class="primary"
+          :disabled="submitting || expired || connection.state === 'connecting'"
+          data-testid="submit-transfer"
+          @click="submit"
+        >
+          {{ submitting ? 'Submitting…' : 'Submit to node' }}
+        </button>
+      </div>
+      <p class="hint">
+        The node's reply only means it took the transaction in. Whether it lands — the nonce
+        right, the account able to pay — is decided when the next block is built, and that
+        answer comes back over the node socket, shown below.
+      </p>
+      <TxDeadline :valid-until-block="tx.validUntilBlock" :expired="expired" />
+      <SocketWarning :connection="connection" />
+
+      <div v-if="submitError" class="warn">{{ submitError }}</div>
+      <div v-if="submitResult" class="field">
+        <div class="k">Node response</div>
+        <div class="v wrap">{{ submitResult }}</div>
+      </div>
+      <p v-if="submitResult && notTracked" class="warn" data-testid="tx-untracked">
+        <strong>Sent, but no confirmation will follow.</strong> {{ notTracked }}
+      </p>
+    </template>
+
+    <TxStatus v-if="tracked" :tracked="tracked" />
+  </section>
+</template>
+
+<style scoped>
+.ctl { display: inline-flex; align-items: center; gap: 8px; }
+.ctl input { width: 140px; }
+.ctl.grow { flex: 1 1 auto; }
+.ctl.grow input { width: 100%; }
+.choice { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; }
+.choice.asset { display: flex; gap: 8px; margin-top: 8px; min-width: 0; }
+.choice.asset code { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.sub {
+  font-size: 13px; text-transform: uppercase; letter-spacing: 0.06em;
+  color: var(--muted); font-weight: 600; margin: 22px 0 8px;
+}
+.v.wrap { word-break: break-all; white-space: normal; }
+</style>

package/example/src/components/TxDeadline.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+/**
+ * How long a built transaction can wait. A node takes it only until the chain is past
+ * `validUntilBlock`; `expired` is set when a check before submitting found it was.
+ */
+defineProps<{ validUntilBlock: number; expired: boolean }>()
+</script>
+
+<template>
+  <p class="hint" data-testid="tx-deadline">
+    A node takes it until the chain is past block
+    <strong data-testid="tx-valid-until">{{ validUntilBlock }}</strong>, about nine blocks
+    after it was built. After that it is refused, so it cannot be held and sent much later.
+  </p>
+  <p v-if="expired" class="warn" data-testid="tx-expired">
+    <strong>Too old to send.</strong> The chain is past block {{ validUntilBlock }}, so the
+    node would refuse it. Nothing was sent or charged — build and sign again.
+  </p>
+</template>

package/example/src/components/TxFee.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import type { GeeqChain, GeeqFee } from '@geeqdev/geeq-sdk'
+import { penniesLabel } from '../pennies'
+
+/**
+ * The fee the SDK worked out for a built transaction. `amount` is the coin it sends, when
+ * it sends any — evidence does not. The chain shows them in geeq, at its own unit.
+ */
+defineProps<{ chain: GeeqChain; fee: GeeqFee | undefined; payer: string; amount?: bigint }>()
+</script>
+
+<template>
+  <div class="field" data-testid="tx-fee">
+    <div class="k">Fee · paid by {{ payer }} · from the signed bytes, as the node charges it</div>
+    <div v-if="fee" class="v">
+      <strong data-testid="tx-fee-total">{{ chain.formatGeeq(fee.total) }}</strong> geeq
+      <span data-testid="tx-fee-pennies">{{ penniesLabel(fee.total) }}</span> =
+      {{ chain.formatGeeq(fee.data) }} geeq {{ penniesLabel(fee.data) }} for {{ fee.bytes }} bytes
+      <template v-if="amount !== undefined">
+        + {{ chain.formatGeeq(fee.coin) }} geeq {{ penniesLabel(fee.coin) }} on the amount (0.25%)
+      </template>
+    </div>
+    <div v-else class="v">Unknown — this chain does not publish its fee rate.</div>
+    <p v-if="fee && amount !== undefined" class="hint">
+      In all, {{ payer }} pays
+      <strong data-testid="tx-cost">{{ chain.formatGeeq(amount + fee.total) }}</strong> geeq
+      {{ penniesLabel(amount + fee.total) }}: {{ chain.formatGeeq(amount) }} geeq {{ penniesLabel(amount) }}
+      sent, plus the fee.
+    </p>
+  </div>
+</template>

package/example/src/components/TxStatus.vue

@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, shallowRef, watch } from 'vue'
+import type {
+  GeeqTrackedTx,
+  GeeqTxOutcome,
+  GeeqTxState,
+  GeeqTxStatusEvent,
+} from '@geeqdev/geeq-sdk'
+
+/**
+ * One submitted transaction, followed to its verdict.
+ *
+ * The tracked handle lives in the socket, not in this component, so the verdict is still
+ * heard if the panel above rebuilds its transaction. This only mirrors what the handle
+ * says, re-reading it on every change.
+ */
+const props = defineProps<{ tracked: GeeqTrackedTx }>()
+
+const status = ref<GeeqTxState>('pending')
+const outcome = shallowRef<GeeqTxOutcome | undefined>(undefined)
+const events = shallowRef<readonly GeeqTxStatusEvent[]>([])
+
+let stop: (() => void) | null = null
+watch(
+  () => props.tracked,
+  (tracked) => {
+    stop?.()
+    const sync = () => {
+      status.value = tracked.status
+      outcome.value = tracked.outcome
+      events.value = tracked.events
+    }
+    sync()
+    stop = tracked.onChange(sync)
+  },
+  { immediate: true },
+)
+onBeforeUnmount(() => stop?.())
+
+const dot = computed(
+  () =>
+    ({ pending: 'loading', confirmed: 'ready', rejected: 'error', unknown: '' })[status.value],
+)
+
+const headline = computed(() => {
+  const settled = outcome.value
+  if (settled === undefined) {
+    return events.value.length === 0
+      ? 'Waiting for the chain — about one block'
+      : 'The node flagged it; waiting in case a later block decides it'
+  }
+  if (settled.status === 'confirmed') return 'Confirmed — committed in a block'
+  if (settled.status === 'unknown') {
+    return settled.reason === 'timeout' ? 'No verdict heard' : 'No longer tracked'
+  }
+  return {
+    invalid: 'Rejected when the block was built — the fee is still charged',
+    nonsane: 'Refused by the node',
+    refused: 'Refused on submission',
+    'incorrectly-included': 'Rejected — carried by a node the chain distrusts',
+  }[settled.reason]
+})
+
+/** Why it was not confirmed, if it was not. */
+const reason = computed(() =>
+  outcome.value && outcome.value.status !== 'confirmed' ? outcome.value.reason : undefined,
+)
+</script>
+
+<template>
+  <div class="field" data-testid="tx-status" :data-status="status" :data-reason="reason">
+    <div class="k">Verdict · heard over the node socket</div>
+    <div class="status">
+      <span class="dot" :class="dot" />
+      <strong>{{ headline }}</strong>
+      <code v-if="reason" class="reason">{{ reason }}</code>
+    </div>
+    <p
+      v-if="outcome && outcome.status !== 'confirmed'"
+      class="hint"
+      data-testid="tx-status-message"
+    >
+      {{ outcome.message }}
+    </p>
+
+    <div class="k" style="margin-top: 10px">Transaction id · base64 · what status events name</div>
+    <div class="v" data-testid="tx-id">{{ tracked.id }}</div>
+
+    <ol v-if="events.length" class="events" data-testid="tx-events">
+      <li v-for="(event, index) in events" :key="index">
+        <code>{{ event.verdict }}</code>
+        <span v-if="event.blockNumber !== undefined" class="hint"> · block {{ event.blockNumber }}</span>
+        <span v-if="event.direction" class="hint"> · {{ event.direction }}</span>
+        <span v-if="event.createdAt" class="hint"> · {{ event.createdAt.toLocaleTimeString() }}</span>
+        <span v-if="event.error" class="hint"> · {{ event.error }}</span>
+      </li>
+    </ol>
+  </div>
+</template>
+
+<style scoped>
+.status { display: flex; align-items: center; gap: 8px; margin-top: 4px; }
+.reason { font-size: 12px; color: var(--muted); }
+.events { margin: 8px 0 0 18px; padding: 0; font-size: 13px; }
+</style>

package/example/src/composables/useSocketConnection.ts

@@ -0,0 +1,80 @@
+import { onScopeDispose, shallowReactive, watch } from 'vue'
+import type { Ref } from 'vue'
+import { GeeqSocket } from '@geeqdev/geeq-sdk'
+import type { GeeqChain } from '@geeqdev/geeq-sdk'
+
+export interface SocketConnection {
+  /** The open socket, or null while there is none. */
+  socket: GeeqSocket | null
+  state: 'none' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'failed'
+  /** Why it failed to open, when it did. */
+  error: string
+  /** The last few events the node pushed, newest first. */
+  lastEvents: string[]
+  retry: () => void
+}
+
+/**
+ * The node socket for the current chain: opened when a chain is connected, closed when it
+ * goes away. One per chain, because every tracked transaction lives in it.
+ *
+ * `socketUrl` overrides where the socket is, for a local harness. Leave it empty.
+ */
+export function useSocketConnection(
+  chain: Ref<GeeqChain | null>,
+  socketUrl: Ref<string>,
+): SocketConnection {
+  // Shallow, so the socket is stored as it is and never wrapped in a proxy.
+  const connection = shallowReactive<SocketConnection>({
+    socket: null,
+    state: 'none',
+    error: '',
+    lastEvents: [],
+    retry: () => {
+      if (chain.value !== null) open(chain.value)
+    },
+  })
+
+  function close() {
+    // Disposing also removes our listeners, and ends any pending transaction as unknown.
+    connection.socket?.dispose()
+    connection.socket = null
+    connection.state = 'none'
+    connection.error = ''
+    connection.lastEvents = []
+  }
+
+  async function open(forChain: GeeqChain) {
+    close()
+    connection.state = 'connecting'
+    const url = socketUrl.value.trim()
+    try {
+      const socket = await GeeqSocket.connect(url ? { url } : { endpoint: forChain.endpoint })
+      // The chain changed while we were connecting; this socket is not wanted any more.
+      if (chain.value !== forChain) return socket.dispose()
+
+      socket.onConnectionChange((state) => (connection.state = state))
+      socket.onMessage(({ event, payload }) => {
+        connection.lastEvents = [describe(event, payload), ...connection.lastEvents].slice(0, 6)
+      })
+      connection.socket = socket
+      connection.state = socket.state
+    } catch (error) {
+      if (chain.value !== forChain) return
+      connection.state = 'failed'
+      connection.error = error instanceof Error ? error.message : String(error)
+    }
+  }
+
+  watch(chain, (next) => (next ? open(next) : close()), { immediate: true })
+  onScopeDispose(close)
+
+  return connection
+}
+
+function describe(event: string, payload: unknown): string {
+  const data = (payload ?? {}) as Record<string, unknown>
+  if (event === 'uut_status') return `${event} ${data.status} ${String(data.refHash).slice(0, 12)}…`
+  if (typeof data.block === 'number') return `${event} block ${data.block}`
+  return event
+}

package/example/src/env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /** How many pennies make one Geeq, set in .env. */
+  readonly VITE_PENNIES_PER_GEEQ: string
+}
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, never>, Record<string, never>, unknown>
+  export default component
+}

package/example/src/main.ts

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+import './style.css'
+
+createApp(App).mount('#app')

package/example/src/pennies.ts

@@ -0,0 +1,7 @@
+/**
+ * The chain counts pennies, so every geeq figure the demo shows has its penny count
+ * beside it: `1.5 geeq (150 pennies)`.
+ */
+export function penniesLabel(value: bigint): string {
+  return `(${value} ${value === 1n ? 'penny' : 'pennies'})`
+}