@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/example/src/components/DigitalAssetsPanel.vue

@@ -0,0 +1,68 @@
+<script setup lang="ts">
+import { ref, shallowRef, watch } from 'vue'
+import { toBase64, toHex } from '@geeqdev/geeq-sdk'
+import type { GeeqChain, GeeqKeypair, GeeqNft } from '@geeqdev/geeq-sdk'
+import CopyButton from './CopyButton.vue'
+
+const props = defineProps<{
+  keypair: GeeqKeypair | null
+  chain: GeeqChain | null
+}>()
+
+/** 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 loading = ref(false)
+const loadError = ref('')
+
+watch([() => props.keypair, () => props.chain], () => (assets.value = null))
+
+async function load() {
+  if (props.keypair === null || props.chain === null) return
+
+  loading.value = true
+  loadError.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 })
+  } catch (error) {
+    loadError.value = (error as Error).message
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">8</span>Your digital assets</h2>
+
+    <p class="hint" style="margin-top: 0">
+      The digital assets this account holds, found in the ledger from its key alone, each with
+      the hash and labels it was created with. Send them in step 5.
+    </p>
+
+    <div class="row">
+      <button :disabled="!keypair || !chain || loading" data-testid="get-assets" @click="load">
+        {{ loading ? 'Reading ledger…' : assets ? 'Refresh' : 'Get my digital assets' }}
+      </button>
+    </div>
+    <div v-if="loadError" class="warn">{{ loadError }}</div>
+
+    <template v-if="assets">
+      <p v-if="assets.length === 0" class="hint" data-testid="no-assets">
+        None yet. A new digital asset shows here once a block has confirmed it.
+      </p>
+      <div v-for="asset in assets" :key="toBase64(asset.id)" class="field" data-testid="asset">
+        <div class="k">{{ asset.metadata.join(', ') || 'No labels' }}</div>
+        <div class="row">
+          <code class="v" style="flex: 1 1 auto">{{ toBase64(asset.id) }}</code>
+          <CopyButton :value="toBase64(asset.id)" />
+        </div>
+        <div v-if="asset.attestHash" class="hint" style="margin-top: 4px">
+          content hash {{ toHex(asset.attestHash) }}
+        </div>
+      </div>
+    </template>
+  </section>
+</template>

package/example/src/components/EvidencePanel.vue

@@ -0,0 +1,396 @@
+<script setup lang="ts">
+import { computed, markRaw, ref, shallowRef, watch } from 'vue'
+import {
+  GeeqError,
+  attestHashOf,
+  attestationSubmitBody,
+  fromHex,
+  inspectMetadata,
+  submitRoute,
+  toBase64,
+  toHex,
+} from '@geeqdev/geeq-sdk'
+import type {
+  AttestationTx,
+  GeeqChain,
+  GeeqKeypair,
+  GeeqTrackedTx,
+} from '@geeqdev/geeq-sdk'
+import type { SocketConnection } from '../composables/useSocketConnection'
+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
+}>()
+
+type Source = 'hash' | 'file'
+const source = ref<Source>('hash')
+const hashInput = ref('')
+const fileName = ref('')
+// The SDK takes a File directly — a File is a Blob — so there is nothing to read here.
+const file = ref<File | null>(null)
+const metadataInput = ref('')
+
+const tx = ref<AttestationTx | 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 transaction 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('')
+
+/** 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) }
+}
+
+/** Labels are kept in the order given; blank entries are dropped, not sent empty. */
+const metadata = computed(() =>
+  metadataInput.value
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item !== ''),
+)
+
+/** The pasted hash as bytes, or null until it is 32 bytes of hex. */
+const pastedHash = computed(() => {
+  try {
+    const bytes = fromHex(hashInput.value.trim())
+    return bytes.length === 32 ? bytes : null
+  } catch {
+    return null
+  }
+})
+
+/**
+ * The file's digest, computed as soon as it is chosen.
+ *
+ * `attestHashOf` needs no engine, so this works while the WebAssembly bundle is still
+ * downloading. It is async only because a File has to be read; the sequence guard keeps a
+ * slow large file from overwriting the answer for one chosen after it.
+ */
+const fileHash = ref<Uint8Array | null>(null)
+let hashSequence = 0
+watch(file, async (value) => {
+  const ticket = (hashSequence += 1)
+  fileHash.value = null
+  const next = value === null ? null : await attestHashOf(value)
+  if (ticket === hashSequence) fileHash.value = next
+})
+
+/** What goes into the transaction: the pasted hash, or the file's. */
+const evidenceHash = computed(() => (source.value === 'hash' ? pastedHash.value : fileHash.value))
+
+/**
+ * What the last build was pinned to.
+ *
+ * There is deliberately nothing to show before one: the ledger is only read when a
+ * transaction is actually being signed, because its values go stale within a few blocks.
+ */
+const chainState = computed(() => tx.value?.chainState ?? null)
+const limits = computed(() => chainState.value?.metadataLimits)
+/** The SDK measures metadata the same way the chain does — UTF-8 bytes, not characters. */
+const metadataReport = computed(() => inspectMetadata(metadata.value, limits.value))
+
+const canBuild = computed(
+  () => props.keypair !== null && evidenceHash.value !== null && props.chain !== null,
+)
+
+function onFile(event: Event) {
+  const chosen = (event.target as HTMLInputElement).files?.[0]
+  if (!chosen) {
+    fileName.value = ''
+    file.value = null
+    return
+  }
+  fileName.value = `${chosen.name} · ${chosen.size.toLocaleString()} bytes`
+  file.value = chosen
+}
+
+// A built transaction is pinned to a block and a nonce, so anything that changes what it
+// says invalidates it. Drop it rather than let a stale one be submitted.
+watch([evidenceHash, metadata, () => props.keypair, () => props.chain], () => {
+  tx.value = null
+  submitResult.value = ''
+  submitError.value = ''
+  expired.value = false
+})
+
+async function build() {
+  const keypair = props.keypair
+  const active = props.chain
+  const hash = evidenceHash.value
+  if (keypair === null || active === null || hash === null) return
+
+  building.value = true
+  buildError.value = null
+  tx.value = null
+  expired.value = false
+  try {
+    // A keypair and the hash. The ledger read happens in here.
+    tx.value = await active.createAttestation({
+      keypair,
+      attestHash: hash,
+      metadata: metadata.value,
+    })
+  } catch (error) {
+    buildError.value = asGeeq(error)
+  } finally {
+    building.value = false
+  }
+}
+
+/**
+ * The SDK does not POST — that stays here — but it does listen: the node socket from step
+ * 3 tracks the transaction, which is subscribed before it is sent. The transaction names
+ * the node that must process it, so it goes to `tx.nodeUrl` and nowhere else: the node
+ * compares that number to its own with strict equality.
+ */
+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: attestationSubmitBody(built.transaction, built.payload),
+    })
+    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">4</span>Submit evidence</h2>
+
+    <p class="hint" style="margin-top: 0">
+      Submitting evidence publishes a <strong>hash</strong> of something to a chain. The content
+      itself never leaves this tab — only its 32-byte BLAKE3 digest goes into the
+      transaction. Paste a digest you already have, or choose a file to hash it here.
+    </p>
+
+    <div class="row">
+      <button :class="{ primary: source === 'hash' }" @click="source = 'hash'">Paste hash</button>
+      <button :class="{ primary: source === 'file' }" @click="source = 'file'">File</button>
+    </div>
+
+    <template v-if="source === 'hash'">
+      <div class="row" style="margin-top: 12px">
+        <span class="ctl grow">
+          <label for="evidence-hash">Hash</label>
+          <input
+            id="evidence-hash"
+            v-model="hashInput"
+            type="text"
+            spellcheck="false"
+            placeholder="hex, 64 digits"
+            data-testid="evidence-hash-input"
+          />
+        </span>
+      </div>
+      <p v-if="hashInput.trim() && !pastedHash" class="warn" data-testid="evidence-hash-error">
+        An evidence hash is 32 bytes: 64 hex digits, with or without a leading <code>0x</code>.
+      </p>
+    </template>
+    <div v-else class="row" style="margin-top: 12px">
+      <input type="file" @change="onFile" />
+      <span v-if="fileName" class="hint">{{ fileName }}</span>
+    </div>
+
+    <div class="field" style="margin-top: 12px">
+      <div class="k">Evidence hash · BLAKE3 · 32 bytes · what goes into the transaction</div>
+      <div v-if="evidenceHash" class="v" data-testid="evidence-hash">{{ toHex(evidenceHash) }}</div>
+      <div v-else class="v" style="color: var(--muted)">Paste a hash or choose a file above.</div>
+    </div>
+
+    <div class="row" style="margin-top: 16px">
+      <span class="ctl grow">
+        <label for="meta">Metadata</label>
+        <input id="meta" v-model="metadataInput" type="text" placeholder="comma, separated, labels" />
+      </span>
+      <span
+        v-if="limits"
+        class="hint"
+        :class="{ over: !metadataReport.withinLimits }"
+        data-testid="meta-limits"
+      >
+        {{ metadataReport.count }}/{{ limits.maxEntries }} labels ·
+        {{ limits.maxBytesPerEntry }} bytes each
+      </span>
+    </div>
+    <p v-if="limits && !metadataReport.withinLimits" class="warn" data-testid="meta-over">
+      <strong>This chain would reject that metadata.</strong>
+      <template v-if="metadataReport.tooManyEntries">
+        It allows {{ limits.maxEntries }} labels and there are {{ metadataReport.count }}.
+      </template>
+      <template v-for="entry in metadataReport.entries" :key="entry.index">
+        <template v-if="entry.overLimit">
+          Label {{ entry.index + 1 }} is {{ entry.bytes }} bytes, over the
+          {{ limits.maxBytesPerEntry }}-byte limit — measured as UTF-8, so non-ASCII
+          characters cost more than one each.
+        </template>
+      </template>
+    </p>
+    <p v-if="metadata.length" class="warn">
+      <strong>Metadata is public.</strong> These {{ metadata.length }}
+      {{ metadata.length === 1 ? 'label is' : 'labels are' }} stored on-chain in the clear,
+      unlike the evidence itself. Put identifiers there, not secrets.
+    </p>
+
+    <div class="row" style="margin-top: 16px">
+      <button class="primary" :disabled="!canBuild || building" data-testid="build" @click="build">
+        {{ building ? 'Reading ledger & signing…' : 'Build & sign' }}
+      </button>
+    </div>
+
+    <div v-if="buildError" class="warn" data-testid="build-error">
+      <template v-if="buildError.code === 'account-not-found'">
+        <strong>This account has never received coins.</strong> A Geeq account only appears
+        in the ledger once it has been funded, so a freshly generated phrase will not be
+        there yet.
+        <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-if="buildError.code === 'nonce-collision'">
+        <strong>One transaction per account per block.</strong> Two sharing a nonce are
+        <em>both</em> rejected, not just the second — so the SDK refuses rather than
+        building one that would destroy the first. Submit the one you have and build again
+        once the block advances.
+      </template>
+      <template v-else>{{ buildError.message }}</template>
+    </div>
+
+    <template v-if="tx && chainState && chain">
+      <ChainState :chain-state="chainState" nonce-of="this account" />
+
+      <TxFee :chain="chain" :fee="tx.fee" 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</div>
+        <div class="v wrap" data-testid="tx-base64">{{ tx.transaction }}</div>
+        <div class="row" style="margin-top: 7px"><CopyButton :value="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" data-testid="payload-base64">{{ tx.payload }}</div>
+        <div class="row" style="margin-top: 7px"><CopyButton :value="tx.payload" /></div>
+      </div>
+
+      <h3 class="sub">Submit</h3>
+      <p class="hint">
+        It is sent with its payload to <code>{{ tx.nodeUrl ?? chain.endpoint }}</code> — the
+        node the chain state came from, and the only one that will take it.
+      </p>
+      <div class="row">
+        <button
+          class="primary"
+          :disabled="submitting || expired || connection.state === 'connecting'"
+          data-testid="submit"
+          @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.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;
+}
+/* Base64 blobs are long and unbroken; let them wrap rather than scroll the page. */
+.v.wrap { word-break: break-all; white-space: normal; }
+
+.over { color: #b91c1c; font-weight: 600; }
+</style>

package/example/src/components/ExplorerPanel.vue

@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { getExplorerTransaction } from '@geeqdev/geeq-sdk'
+import type { GeeqExplorerTransaction } from '@geeqdev/geeq-sdk'
+
+const explorerUrl = ref('')
+const refHash = ref('')
+
+const loading = ref(false)
+const error = ref('')
+const notFound = ref(false)
+const found = ref<GeeqExplorerTransaction | null>(null)
+
+async function lookUp() {
+  loading.value = true
+  error.value = ''
+  notFound.value = false
+  found.value = null
+  try {
+    // Given in base64; the SDK asks the explorer in hex, the form it stores.
+    found.value = await getExplorerTransaction({
+      explorerUrl: explorerUrl.value.trim(),
+      refHash: refHash.value.trim(),
+    })
+    notFound.value = found.value === null
+  } catch (e) {
+    error.value = (e as Error).message
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">9</span>Block explorer</h2>
+
+    <p class="hint" style="margin-top: 0">
+      Look a transaction up in a block explorer by its id: the base64 one shown under a
+      verdict in steps 4 to 7. The explorer only has a transaction once a block has decided
+      it.
+    </p>
+
+    <div class="row">
+      <span class="ctl grow">
+        <label for="explorer-url">Explorer URL</label>
+        <input
+          id="explorer-url"
+          v-model="explorerUrl"
+          type="text"
+          placeholder="https://blkexp.geeq-test.io"
+          data-testid="explorer-url"
+        />
+      </span>
+    </div>
+    <div class="row">
+      <span class="ctl grow">
+        <label for="explorer-refhash">Transaction id</label>
+        <input
+          id="explorer-refhash"
+          v-model="refHash"
+          type="text"
+          placeholder="base64, 44 characters"
+          spellcheck="false"
+          data-testid="explorer-refhash"
+        />
+      </span>
+      <button
+        class="primary"
+        :disabled="!explorerUrl.trim() || !refHash.trim() || loading"
+        data-testid="explorer-lookup"
+        @click="lookUp"
+      >
+        {{ loading ? 'Looking up…' : 'Look up' }}
+      </button>
+    </div>
+
+    <div v-if="error" class="warn" data-testid="explorer-error">{{ error }}</div>
+    <p v-if="notFound" class="warn" data-testid="explorer-not-found">
+      The explorer has no transaction with that id — not indexed yet, or never put in a
+      block.
+    </p>
+
+    <template v-if="found">
+      <table class="grid" data-testid="explorer-result">
+        <tbody>
+          <tr><th>Status</th><td>{{ found.status }}</td></tr>
+          <tr><th>Type</th><td>{{ found.type }}</td></tr>
+          <tr><th>Block</th><td>{{ found.block }} · chain {{ found.chainNumber }} {{ found.chainName }}</td></tr>
+          <tr><th>From</th><td class="wrap">{{ found.from }}</td></tr>
+          <tr v-if="found.to"><th>To</th><td class="wrap">{{ found.to }}</td></tr>
+          <tr v-for="(value, index) in found.values" :key="index">
+            <th>Moved</th>
+            <td>{{ value.value }} {{ value.name ?? value.type }}</td>
+          </tr>
+          <tr><th>Created</th><td>{{ found.createdAt }}</td></tr>
+        </tbody>
+      </table>
+      <details class="raw">
+        <summary>Everything the explorer returned</summary>
+        <pre>{{ JSON.stringify(found, null, 2) }}</pre>
+      </details>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.ctl { display: inline-flex; align-items: center; gap: 8px; }
+.ctl.grow { flex: 1 1 auto; }
+.ctl.grow input { width: 100%; }
+.ctl label { white-space: nowrap; }
+.grid { width: 100%; border-collapse: collapse; font-size: 14px; margin-top: 14px; }
+.grid th { text-align: left; font-weight: 600; padding: 5px 12px 5px 0; white-space: nowrap; vertical-align: top; }
+.grid td { padding: 5px 0; vertical-align: top; }
+.wrap { word-break: break-all; }
+.raw { margin-top: 12px; }
+.raw summary { cursor: pointer; color: var(--muted); font-size: 13px; }
+.raw pre { font-size: 12px; overflow-x: auto; }
+</style>