@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/example/src/components/ChainPanel.vue

@@ -0,0 +1,267 @@
+<script setup lang="ts">
+import { computed, markRaw, onBeforeUnmount, ref, shallowRef, watch } from 'vue'
+import { GeeqChain, GeeqError } from '@geeqdev/geeq-sdk'
+import type { SocketConnection } from '../composables/useSocketConnection'
+
+// The socket itself is opened by App whenever the chain changes; this panel only shows it.
+const props = defineProps<{
+  connection: SocketConnection
+  /** Set in step 2, where the address is derived for it. Read here, never changed. */
+  chainNumber: number
+}>()
+/** Only for a harness that serves the socket somewhere other than the node's own /ws/. */
+const socketUrl = defineModel<string>('socketUrl', { default: '' })
+const emit = defineEmits<{
+  (e: 'chain', chain: GeeqChain | null): void
+}>()
+
+const simulatorUrl = ref('')
+/**
+ * Deployment configuration, not node selection.
+ *
+ * Nodes answer on 2082 behind TLS; this exists so the demo can be pointed at a local
+ * harness that is not behind one.
+ */
+const nodePort = ref<number | null>(null)
+
+const chain = shallowRef<GeeqChain | null>(null)
+const connecting = ref(false)
+const error = ref<{ code: string; message: string } | null>(null)
+/** The chain the last node was found for, once step 2 has moved off it. */
+const leftChain = ref<number | null>(null)
+
+onBeforeUnmount(() => {
+  chain.value?.dispose()
+})
+
+/** Every SDK failure carries a stable code; branch on that, never on the message. */
+function asGeeq(e: unknown): { code: string; message: string } {
+  if (e instanceof GeeqError) return { code: e.code, message: e.message }
+  const shaped = e as { name?: string; code?: string; message?: string }
+  if (shaped?.name === 'GeeqError' && typeof shaped.code === 'string') {
+    return { code: shaped.code, message: shaped.message ?? '' }
+  }
+  return { code: 'unknown', message: (e as Error)?.message ?? String(e) }
+}
+
+const candidates = computed(() => chain.value?.candidates ?? [])
+
+// A node serves one chain. When step 2 moves to another, this node is no use to the
+// steps after it, so let it go rather than leave them building for the wrong chain.
+watch(
+  () => props.chainNumber,
+  (next) => {
+    if (chain.value === null || chain.value.chainNumber === next) return
+    leftChain.value = chain.value.chainNumber ?? null
+    chain.value.dispose()
+    chain.value = null
+    emit('chain', null)
+  },
+)
+
+const socketDot = computed(
+  () =>
+    ({
+      connecting: 'loading',
+      reconnecting: 'loading',
+      open: 'ready',
+      failed: 'error',
+      closed: 'error',
+      none: '',
+    })[props.connection.state],
+)
+
+/**
+ * Ask the simulator which nodes exist and take an active one.
+ *
+ * No ledger is read here — only the node's address is settled. Its number, the block, the
+ * nonce and the chain's limits all live in the ledger, and that is read when a
+ * transaction is built.
+ */
+async function connect() {
+  if (simulatorUrl.value.trim() === '') return
+
+  connecting.value = true
+  error.value = null
+  leftChain.value = null
+  try {
+    chain.value?.dispose()
+    emit('chain', null)
+    const requested = props.chainNumber
+    const found = await GeeqChain.connect({
+      discovery: simulatorUrl.value.trim(),
+      // A simulator can carry several chains, so it has to be told which: the one
+      // step 2 derives the address for.
+      chainNumber: requested,
+      // A cleared `v-model.number` field holds '', not null, and means the default port.
+      ...(typeof nodePort.value === 'number' ? { nodePort: nodePort.value } : {}),
+      // The chain counts only pennies; how many make a Geeq is this app's setting.
+      penniesPerGeeq: BigInt(import.meta.env.VITE_PENNIES_PER_GEEQ),
+    })
+    // Step 2 moved to another chain while the simulator was answering.
+    if (props.chainNumber !== requested) {
+      found.dispose()
+      leftChain.value = requested
+      return
+    }
+    chain.value = markRaw(found)
+    // App opens this chain's socket on the strength of it.
+    emit('chain', chain.value)
+  } catch (e) {
+    chain.value = null
+    emit('chain', null)
+    error.value = asGeeq(e)
+  } finally {
+    connecting.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">3</span>Chain</h2>
+
+    <p class="hint" style="margin-top: 0">
+      You name the <strong>simulator</strong>, not a node; the chain number is the one step 2
+      derived your address for. The SDK asks the simulator which nodes serve that chain, and
+      takes an active one. Nothing is read from the chain itself yet: the block, the node's number
+      and your nonce all live in its ledger, and that goes stale within a few blocks — so
+      it is read when a transaction is actually signed, not now. The node's socket is
+      opened straight away, though: that is where the verdicts on what you send arrive.
+    </p>
+
+    <div class="row">
+      <span class="ctl grow">
+        <label for="simulator">Simulator URL</label>
+        <input
+          id="simulator"
+          v-model="simulatorUrl"
+          type="text"
+          placeholder="https://simulator.geeq-test.io"
+          data-testid="simulator-url"
+        />
+      </span>
+      <span class="ctl">
+        <span class="label">Chain number</span>
+        <span class="fixed" data-testid="chain-number">{{ chainNumber }}</span>
+      </span>
+      <button
+        class="primary"
+        :disabled="!simulatorUrl.trim() || connecting"
+        data-testid="connect"
+        @click="connect"
+      >
+        {{ connecting ? 'Asking…' : 'Find a node' }}
+      </button>
+    </div>
+    <p class="hint">
+      Set in step 2: your address encodes it. To use another chain, change it there and
+      find a node again.
+    </p>
+
+    <details class="advanced">
+      <summary data-testid="dev-options">Local harness options</summary>
+      <p class="hint">
+        Nodes answer on <strong>2082</strong> behind TLS, and that is what the SDK uses.
+        Override it only when pointing the demo at a local stub that is not behind one.
+      </p>
+      <span class="ctl">
+        <label for="node-port">Node port</label>
+        <input
+          id="node-port"
+          v-model.number="nodePort"
+          type="number"
+          min="1"
+          placeholder="2082"
+          data-testid="node-port"
+        />
+      </span>
+      <span class="ctl grow" style="margin-top: 10px">
+        <label for="socket-url">Socket URL</label>
+        <input
+          id="socket-url"
+          v-model="socketUrl"
+          type="text"
+          placeholder="derived: the node URL, ws scheme, /ws/"
+          data-testid="socket-url"
+        />
+      </span>
+    </details>
+
+    <div v-if="error" class="warn" data-testid="connect-error">
+      <template v-if="error.code === 'network-unreachable'">
+        <strong>Could not reach that simulator.</strong> A browser cannot tell these apart:
+        <ul style="margin: 6px 0 0 18px">
+          <li>it sends no CORS header for this origin;</li>
+          <li>its TLS certificate is not trusted;</li>
+          <li>this page is https and the URL is http, which browsers block;</li>
+          <li>it is down, or the URL is wrong.</li>
+        </ul>
+      </template>
+      <template v-else>{{ error.message }}</template>
+    </div>
+
+    <p v-if="leftChain !== null" class="warn" data-testid="chain-changed">
+      Step 2 moved from chain <strong>{{ leftChain }}</strong> to chain
+      <strong>{{ chainNumber }}</strong>, so the node found for chain {{ leftChain }} was let
+      go. Find a node again.
+    </p>
+
+    <template v-if="chain">
+      <div class="field" data-testid="selected-node">
+        <div class="k">Selected node · chosen by the SDK from the active ones</div>
+        <div class="v">
+          {{ chain.endpoint }}
+          <span class="hint" style="margin-left: 8px">
+            chain {{ chain.chainNumber ?? '—' }}
+            <template v-if="chain.chainName">({{ chain.chainName }})</template> ·
+            {{ candidates.length }} listed,
+            {{ candidates.filter((n) => n.kind === 'active').length }} active
+          </span>
+        </div>
+      </div>
+
+      <div class="field" data-testid="socket" :data-state="connection.state">
+        <div class="k">Node socket · where transaction verdicts arrive</div>
+        <div class="v">
+          <span class="dot" :class="socketDot" style="display: inline-block; margin-right: 7px" />
+          <span data-testid="socket-state">{{ connection.state }}</span>
+          <span v-if="connection.socket" class="hint" style="margin-left: 8px">
+            {{ connection.socket.url }}
+          </span>
+          <button
+            v-if="connection.state === 'failed'"
+            class="small"
+            style="margin-left: 8px"
+            data-testid="socket-retry"
+            @click="connection.retry()"
+          >
+            Retry
+          </button>
+        </div>
+        <p v-if="connection.error" class="warn" data-testid="socket-error">
+          {{ connection.error }} Transactions can still be built and submitted, but their
+          verdicts will not be shown.
+        </p>
+        <ul v-if="connection.lastEvents.length" class="recent" data-testid="socket-events">
+          <li v-for="(event, index) in connection.lastEvents" :key="index">
+            <code>{{ event }}</code>
+          </li>
+        </ul>
+      </div>
+    </template>
+  </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%; }
+.label { font-size: 13px; color: var(--muted); }
+/* A value shown, not asked for: no field border, so it does not read as editable. */
+.fixed { font-family: var(--mono); font-size: 14px; font-weight: 600; padding: 0 4px; }
+.advanced { margin-top: 14px; }
+.advanced summary { cursor: pointer; color: var(--muted); font-size: 13px; }
+.recent { margin: 8px 0 0 18px; padding: 0; font-size: 13px; }
+</style>

package/example/src/components/ChainState.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import type { ChainStateInput } from '@geeqdev/geeq-sdk'
+
+/**
+ * What a built transaction is pinned to. `nonceOf` says whose nonce it spends: creating a
+ * digital asset spends its authority account's, everything else the signing account's.
+ */
+defineProps<{ chainState: ChainStateInput; nonceOf: string }>()
+</script>
+
+<template>
+  <h3 class="sub">Chain state · read from the ledger while signing</h3>
+  <table class="grid" data-testid="chain-state">
+    <tbody>
+      <tr>
+        <th>Chain</th>
+        <td>{{ chainState.chainNumber }}</td>
+        <td class="src">the chain the node serves</td>
+      </tr>
+      <tr>
+        <th>Ledger block</th>
+        <td>{{ chainState.ledgerBlockNumber }}</td>
+        <td class="src">the chain's latest block when it was signed</td>
+      </tr>
+      <tr>
+        <th>Target block</th>
+        <td>{{ chainState.blockNumber }}</td>
+        <td class="src">the next block — the one it asks to go into</td>
+      </tr>
+      <tr>
+        <th>Node number</th>
+        <td>{{ chainState.nodeNumber }}</td>
+        <td class="src">
+          the node it was built for, <code>{{ chainState.nodeUrl }}</code> — no other takes it
+        </td>
+      </tr>
+      <tr>
+        <th>Nonce</th>
+        <td>{{ chainState.nonce }}</td>
+        <td class="src">the number {{ nonceOf }}'s next transaction must carry</td>
+      </tr>
+    </tbody>
+  </table>
+</template>
+
+<style scoped>
+.sub {
+  font-size: 13px; text-transform: uppercase; letter-spacing: 0.06em;
+  color: var(--muted); font-weight: 600; margin: 22px 0 8px;
+}
+.grid { width: 100%; border-collapse: collapse; font-size: 14px; }
+.grid th {
+  text-align: left; font-weight: 600; padding: 5px 12px 5px 0;
+  white-space: nowrap; vertical-align: top;
+}
+.grid td { padding: 5px 12px 5px 0; vertical-align: top; }
+.grid td:nth-child(2) { font-variant-numeric: tabular-nums; font-weight: 600; }
+.grid .src { color: var(--muted); font-size: 13px; width: 100%; }
+</style>

package/example/src/components/CopyButton.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps<{ value: string; label?: string }>()
+const copied = ref(false)
+let timer: ReturnType<typeof setTimeout> | undefined
+
+async function copy() {
+  try {
+    await navigator.clipboard.writeText(props.value)
+  } catch {
+    // Clipboard is unavailable outside a secure context; the value stays selectable.
+    return
+  }
+  copied.value = true
+  clearTimeout(timer)
+  timer = setTimeout(() => (copied.value = false), 1400)
+}
+</script>
+
+<template>
+  <button class="small" type="button" @click="copy">
+    {{ copied ? 'Copied' : (label ?? 'Copy') }}
+  </button>
+</template>

package/example/src/components/CreateAssetPanel.vue

@@ -0,0 +1,313 @@
+<script setup lang="ts">
+import { markRaw, ref, shallowRef, watch } from 'vue'
+import { attestationSubmitBody, submitRoute, toBase64 } from '@geeqdev/geeq-sdk'
+import type {
+  GeeqChain,
+  GeeqKeypair,
+  GeeqNftMintProxies,
+  GeeqTrackedTx,
+  NftMintTx,
+} 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
+}>()
+
+/** This account's authority accounts as the ledger last listed them, or null before the first look. */
+const found = shallowRef<GeeqNftMintProxies | null>(null)
+const finding = ref(false)
+const findError = ref('')
+/** The index of the authority account to create the digital asset through. */
+const index = ref<number | null>(null)
+
+// The SDK takes a File directly and hashes it; only the hash goes on chain.
+const file = ref<File | null>(null)
+const metadataInput = ref('')
+
+const tx = ref<NftMintTx | null>(null)
+const building = ref(false)
+const buildError = ref('')
+const submitting = ref(false)
+const submitError = ref('')
+const submitted = ref(false)
+/** Set when the check before submitting found the built transaction too old. */
+const expired = ref(false)
+/** The last submission, followed to its verdict. */
+const tracked = shallowRef<GeeqTrackedTx | null>(null)
+/** Why the last submission is not being followed, when it is not. */
+const notTracked = ref('')
+
+/**
+ * Drop the built transaction. 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 && !submitted.value) props.chain?.discard(tx.value)
+  tx.value = null
+  submitted.value = false
+  expired.value = false
+}
+
+// A built transaction is pinned to a block and a nonce, so any change invalidates it.
+watch([index, file, metadataInput, () => props.keypair, () => props.chain], () => {
+  dropTx()
+  submitError.value = ''
+})
+watch([() => props.keypair, () => props.chain], () => {
+  found.value = null
+  index.value = null
+})
+
+async function findAuthorities() {
+  if (props.keypair === null || props.chain === null) return
+
+  finding.value = true
+  findError.value = ''
+  try {
+    // A fresh read: a new authority account, and a nonce that creating a digital asset
+    // moved, show only once a block has confirmed them.
+    found.value = await props.chain.findNftMintProxies({ admin: props.keypair, maxAgeMs: 0 })
+    // Keep the chosen authority account across a refresh; otherwise take the first.
+    if (!found.value.proxies.some((authority) => authority.index === index.value)) {
+      index.value = found.value.proxies[0]?.index ?? null
+    }
+  } catch (error) {
+    findError.value = (error as Error).message
+  } finally {
+    finding.value = false
+  }
+}
+
+function onFile(event: Event) {
+  file.value = (event.target as HTMLInputElement).files?.[0] ?? null
+}
+
+async function build() {
+  if (props.keypair === null || props.chain === null || index.value === null || file.value === null) return
+
+  building.value = true
+  buildError.value = ''
+  dropTx()
+  try {
+    // Hashes the file, finds the authority account in the ledger by this account's key and
+    // the index, checks it can pay, then signs.
+    tx.value = await props.chain.mintNft({
+      admin: props.keypair,
+      index: index.value,
+      content: file.value,
+      metadata: metadataInput.value
+        .split(',')
+        .map((label) => label.trim())
+        .filter((label) => label !== ''),
+    })
+  } catch (error) {
+    buildError.value = (error as Error).message
+  } finally {
+    building.value = false
+  }
+}
+
+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 = ''
+  submitted.value = false
+  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, as for evidence.
+    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}`
+      }
+    }
+
+    // Creating a digital asset is an application-layer transaction, so it posts exactly
+    // like evidence: the transaction and its payload, as `uat`.
+    const response = await fetch(submitRoute(target), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: attestationSubmitBody(built.transaction, built.payload),
+    })
+    if (!response.ok) {
+      const body = (await response.text()).slice(0, 400)
+      tracked.value?.refused({ status: response.status, message: body })
+      submitError.value = `Node replied ${response.status} ${response.statusText}: ${body}`
+      return
+    }
+    submitted.value = true
+  } catch (e) {
+    submitError.value = `Could not reach the node — ${(e as Error).message}.`
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">7</span>Create a digital asset</h2>
+
+    <p class="hint" style="margin-top: 0">
+      A digital asset is created through one of this account's <strong>authority
+      accounts</strong> from step 6. The authority account pays: the fee, and the chain's
+      minimum transfer, which goes to this account with the digital asset. This account
+      signs, as its admin.
+    </p>
+
+    <div class="row">
+      <span class="ctl">
+        <label for="asset-authority">Authority account</label>
+        <select
+          id="asset-authority"
+          v-model="index"
+          :disabled="!found || found.proxies.length === 0"
+          data-testid="asset-authority"
+        >
+          <option v-if="!found" :value="null">Find your authority accounts first</option>
+          <option v-else-if="found.proxies.length === 0" :value="null">
+            None yet — delegate authority in step 6
+          </option>
+          <option
+            v-for="authority in found?.proxies"
+            :key="authority.address"
+            :value="authority.index"
+            :disabled="authority.index === undefined"
+          >
+            Authority account {{ authority.index ?? '(no index)' }} ·
+            {{ chain?.formatGeeq(authority.balance) }} geeq {{ penniesLabel(authority.balance) }}
+          </option>
+        </select>
+      </span>
+      <button
+        :disabled="!keypair || !chain || finding"
+        data-testid="find-asset-authorities"
+        @click="findAuthorities"
+      >
+        {{ finding ? 'Reading ledger…' : found ? 'Refresh' : 'Find my authority accounts' }}
+      </button>
+    </div>
+    <div v-if="findError" class="warn">{{ findError }}</div>
+
+    <div class="row" style="margin-top: 12px">
+      <input type="file" data-testid="asset-file" @change="onFile" />
+    </div>
+    <p class="hint">Only the file's hash goes on chain. The file never leaves this tab.</p>
+
+    <div class="row">
+      <span class="ctl grow">
+        <label for="asset-meta">Metadata</label>
+        <input
+          id="asset-meta"
+          v-model="metadataInput"
+          type="text"
+          placeholder="comma, separated, labels"
+          data-testid="asset-metadata"
+        />
+      </span>
+    </div>
+    <p class="hint">
+      Labels are public, as they are on evidence. The digital asset's id is derived from the
+      file's hash and the labels, so the same file with the same labels makes one digital
+      asset per authority account, and no more.
+    </p>
+
+    <div class="row" style="margin-top: 16px">
+      <button
+        class="primary"
+        :disabled="!keypair || !chain || index === null || !file || building"
+        data-testid="build-asset"
+        @click="build"
+      >
+        {{ building ? 'Reading ledger & signing…' : 'Build & sign' }}
+      </button>
+    </div>
+    <div v-if="buildError" class="warn" data-testid="asset-error">{{ buildError }}</div>
+
+    <template v-if="tx && chain">
+      <div class="field">
+        <div class="k">Digital asset id · base64</div>
+        <div class="row">
+          <code class="v" style="flex: 1 1 auto" data-testid="asset-id">{{ toBase64(tx.nftId) }}</code>
+          <CopyButton :value="toBase64(tx.nftId)" />
+        </div>
+      </div>
+
+      <ChainState :chain-state="tx.chainState" :nonce-of="`authority account ${index}`" />
+      <TxFee :chain="chain" :fee="tx.fee" :amount="tx.amount" :payer="`authority account ${index}`" />
+
+      <div class="field">
+        <div class="k">Signed transaction · base64 · {{ tx.transaction.length }} chars</div>
+        <div class="v wrap" data-testid="asset-base64">{{ tx.transaction }}</div>
+      </div>
+
+      <div class="field">
+        <div class="k">Payload · base64 · {{ tx.payload.length }} chars · sent with the transaction</div>
+        <div class="v wrap">{{ tx.payload }}</div>
+      </div>
+
+      <h3 class="sub">Submit</h3>
+      <div class="row">
+        <button
+          class="primary"
+          :disabled="submitting || submitted || expired || connection.state === 'connecting'"
+          data-testid="submit-asset"
+          @click="submit"
+        >
+          {{ submitting ? 'Submitting…' : submitted ? 'Submitted' : 'Submit to node' }}
+        </button>
+      </div>
+      <p class="hint">
+        Sent like evidence, with a payload. It sends
+        {{ chain.formatGeeq(tx.amount) }} geeq {{ penniesLabel(tx.amount) }} to this account with
+        the digital asset, and spends authority account
+        {{ index }}'s own nonce <strong data-testid="authority-nonce">{{ tx.chainState.nonce }}</strong>,
+        not this account's.
+      </p>
+      <TxDeadline :valid-until-block="tx.validUntilBlock" :expired="expired" />
+      <SocketWarning :connection="connection" />
+
+      <div v-if="submitError" class="warn">{{ submitError }}</div>
+      <p v-if="submitted && 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.grow { flex: 1 1 auto; }
+.ctl.grow input { width: 100%; }
+.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>