@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/example/src/components/KeypairPanel.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import { markRaw, ref, shallowRef, watch } from 'vue'
+import { GEEQ_RECORD_TYPES, GeeqError, keypairFromMnemonic, toBase64 } from '@geeqdev/geeq-sdk'
+import type { GeeqCoinType, GeeqKeypair, GeeqRecordType } from '@geeqdev/geeq-sdk'
+import CopyButton from './CopyButton.vue'
+
+const props = defineProps<{ mnemonic: string; engineReady: boolean }>()
+
+// Evidence must name the chain it targets, and it has to be the chain this
+// account lives on — so the number is owned by App and shared, not duplicated here.
+const chainNumber = defineModel<number>('chainNumber', { required: true })
+// The signing key is shared the same way. Emitted as null whenever it is disposed,
+// so no other panel can reach a freed engine handle.
+const emit = defineEmits<{ (e: 'keypair', keypair: GeeqKeypair | null): void }>()
+// Fixed, deliberately not exposed. It is part of the SLIP-0010 derivation path
+// (BIP-44 coin type: testnet 1, mainnet 1019), so it changes the key itself rather
+// than just labelling the address the way chainNumber does. Note this overrides the
+// SDK's own 'testnet' default — passing it explicitly on every call is what keeps
+// this demo lined up with the Geeq apps.
+// GeeqCoinType is a string union ('mainnet' | 'testnet'), not an enum — the SDK
+// keeps the readable name in its public API and maps it to the engine's numeric
+// CoinType internally, so there is no GeeqCoinType.Mainnet to reference.
+const COIN_TYPE: GeeqCoinType = 'mainnet'
+// BIP-39 passphrase ("25th word"). Folded into the seed, so it changes the key.
+const passphrase = ref('')
+// Record type sits in the derivation path *and* in the address envelope, so it is
+// passed to both calls below — deriving under one record type and encoding under
+// another would yield an address the owner of the key could not reproduce.
+const recordType = ref<GeeqRecordType>('coin-asset')
+// shallowRef + markRaw: a keypair is a class instance holding an engine handle and
+// typed arrays. Deep reactivity would proxy those arrays before they reach
+// WebAssembly, and buys nothing — the object is replaced wholesale, never mutated.
+const keypair = shallowRef<GeeqKeypair | null>(null)
+const address = ref('')
+const error = ref('')
+const busy = ref(false)
+const revealPrivateKey = ref(false)
+
+
+// A keypair holds an engine-side handle; release it before replacing or dropping it.
+function clear() {
+  keypair.value?.dispose()
+  keypair.value = null
+  address.value = ''
+  error.value = ''
+  revealPrivateKey.value = false
+  emit('keypair', null)
+}
+
+// The phrase or the derivation path changing invalidates any keypair derived from
+// the previous one.
+watch([() => props.mnemonic, passphrase, recordType], clear)
+
+async function derive() {
+  clear()
+  busy.value = true
+  try {
+    const kp = await keypairFromMnemonic(props.mnemonic, {
+      coinType: COIN_TYPE,
+      passphrase: passphrase.value,
+      recordType: recordType.value,
+    })
+    keypair.value = markRaw(kp)
+    address.value = kp.getAddress({
+      chainNumber: chainNumber.value,
+      recordType: recordType.value,
+    })
+    emit('keypair', kp)
+  } catch (e) {
+    error.value =
+      e instanceof GeeqError ? `${e.code}: ${e.message}` : (e as Error).message
+  } finally {
+    busy.value = false
+  }
+}
+
+// The address encodes the chain, so changing it re-derives the address only —
+// the keypair itself is unaffected.
+watch(chainNumber, (next) => {
+  if (keypair.value) {
+    address.value = keypair.value.getAddress({
+      chainNumber: next,
+      recordType: recordType.value,
+    })
+  }
+})
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">2</span>Keypair &amp; address</h2>
+
+    <div class="row">
+      <span class="ctl">
+        <label for="chain">Chain number</label>
+        <input id="chain" v-model.number="chainNumber" type="number" min="0" />
+      </span>
+      <span class="ctl">
+        <label for="record">Record type</label>
+        <select id="record" v-model="recordType">
+          <option v-for="type in GEEQ_RECORD_TYPES" :key="type" :value="type">{{ type }}</option>
+        </select>
+      </span>
+      <span class="ctl">
+        <label for="passphrase">Passphrase</label>
+        <input
+          id="passphrase"
+          v-model="passphrase"
+          type="text"
+          placeholder="empty — type here"
+          :class="{ unset: passphrase === '' }"
+        />
+      </span>
+      <button
+        class="primary"
+        :disabled="!mnemonic || !engineReady || busy"
+        @click="derive"
+      >
+        {{ busy ? 'Deriving…' : 'Derive keypair' }}
+      </button>
+    </div>
+
+    <p v-if="!engineReady" class="empty">Waiting for the engine to finish loading…</p>
+
+    <div v-if="error" class="warn">{{ error }}</div>
+
+    <template v-if="keypair">
+      <div class="field">
+        <div class="k">
+          Address · base58 · chain {{ chainNumber }} · {{ COIN_TYPE }} · {{ recordType }} ·
+          <template v-if="passphrase">passphrase “{{ passphrase }}”</template>
+          <template v-else>no passphrase</template>
+        </div>
+        <div class="v">{{ address }}</div>
+        <div class="row" style="margin-top: 7px"><CopyButton :value="address" /></div>
+      </div>
+
+      <div class="field">
+        <div class="k">Public key · base64 · 32 bytes</div>
+        <div class="v">{{ toBase64(keypair.publicKey) }}</div>
+      </div>
+
+      <div class="field">
+        <div class="k">Account id · base64 · 32 bytes · BLAKE3 of the public key</div>
+        <div class="v">{{ toBase64(keypair.accountId) }}</div>
+      </div>
+
+      <div class="field">
+        <div class="k">Private key · 32 bytes</div>
+        <div v-if="revealPrivateKey" class="v">{{ toBase64(keypair.privateKey) }}</div>
+        <div v-else class="v" style="color: var(--muted)">••••••••••••••••••••••••••••••••</div>
+        <div class="row" style="margin-top: 7px">
+          <button class="small" @click="revealPrivateKey = !revealPrivateKey">
+            {{ revealPrivateKey ? 'Hide' : 'Reveal' }}
+          </button>
+        </div>
+      </div>
+
+      <div class="warn">
+        Shown here only to demonstrate the SDK. A real application should never display
+        or log a private key. The SDK keeps it out of harm's way by default —
+        <code>JSON.stringify(keypair)</code> emits only the public key.
+      </div>
+
+      <p class="hint">
+        Changing the chain number only re-encodes the address, since the chain is stamped
+        alongside the account id. Record type and passphrase feed the derivation path
+        instead, so changing either re-derives the key and the account id with it — which
+        is how one phrase yields different addresses in two apps. Coin type is fixed
+        at <code>mainnet</code> here.
+      </p>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.ctl { display: inline-flex; align-items: center; gap: 8px; }
+.ctl input, .ctl select { width: 140px; }
+/* An empty passphrase is a real setting, not a missing one — say so rather than
+   letting a grey placeholder read as a chosen value. */
+.ctl input.unset { border-style: dashed; }
+</style>

package/example/src/components/PhrasePanel.vue

@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { generateMnemonic, validateMnemonic } from '@geeqdev/geeq-sdk'
+import type { MnemonicWordCount } from '@geeqdev/geeq-sdk'
+import CopyButton from './CopyButton.vue'
+
+const emit = defineEmits<{ (e: 'change', mnemonic: string): void }>()
+
+const mode = ref<'create' | 'restore'>('create')
+// Fixed, deliberately not exposed. The SDK supports 12/15/18/21/24, but the Geeq
+// apps this demo mirrors issue 12-word phrases, so offering a choice here would let
+// someone generate a phrase those apps cannot produce.
+const WORD_COUNT: MnemonicWordCount = 12
+const phrase = ref('')
+const restoreInput = ref('')
+
+const words = computed(() => (phrase.value ? phrase.value.split(' ') : []))
+
+// Pure JavaScript in the SDK — no engine needed, so this is instant and works
+// even while the WebAssembly engine is still downloading.
+function create() {
+  phrase.value = generateMnemonic({ words: WORD_COUNT })
+  emit('change', phrase.value)
+}
+
+const restoreState = computed(() => {
+  if (restoreInput.value.trim() === '') return 'empty'
+  return validateMnemonic(restoreInput.value) ? 'valid' : 'invalid'
+})
+
+function useRestored() {
+  phrase.value = restoreInput.value.trim().replace(/\s+/gu, ' ').toLowerCase()
+  emit('change', phrase.value)
+}
+
+function switchMode(next: 'create' | 'restore') {
+  mode.value = next
+  phrase.value = ''
+  emit('change', '')
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">1</span>Recovery phrase</h2>
+
+    <div class="row">
+      <button :class="{ primary: mode === 'create' }" @click="switchMode('create')">
+        Create new
+      </button>
+      <button :class="{ primary: mode === 'restore' }" @click="switchMode('restore')">
+        Restore existing
+      </button>
+    </div>
+
+    <template v-if="mode === 'create'">
+      <div class="row" style="margin-top: 16px">
+        <button class="primary" @click="create">Generate phrase</button>
+        <CopyButton v-if="phrase" :value="phrase" />
+      </div>
+
+      <div v-if="words.length" class="phrase" style="margin-top: 16px">
+        <div v-for="(word, i) in words" :key="i" class="word">
+          <span class="n">{{ i + 1 }}</span><span>{{ word }}</span>
+        </div>
+      </div>
+      <p v-else class="hint">
+        Twelve words, generated with <code>generateMnemonic()</code> using the platform's
+        secure random source. No engine required, so this works instantly.
+      </p>
+
+      <div v-if="phrase" class="warn">
+        <strong>Write these words down in order.</strong>
+        They are the only way to recover your account. Anyone who reads them controls it.
+        This demo keeps them in memory only — nothing is saved or sent anywhere.
+      </div>
+    </template>
+
+    <template v-else>
+      <div style="margin-top: 16px">
+        <textarea
+          v-model="restoreInput"
+          spellcheck="false"
+          autocapitalize="none"
+          placeholder="Enter your 12-word recovery phrase, separated by spaces"
+        />
+        <div class="row" style="margin-top: 10px">
+          <span
+            class="hint grow"
+            :class="{ valid: restoreState === 'valid', invalid: restoreState === 'invalid' }"
+          >
+            <template v-if="restoreState === 'empty'">
+              Checked with <code>validateMnemonic()</code> as you type.
+            </template>
+            <template v-else-if="restoreState === 'valid'">Valid phrase.</template>
+            <template v-else>Not a valid phrase — check the words and their order.</template>
+          </span>
+          <button class="primary" :disabled="restoreState !== 'valid'" @click="useRestored">
+            Use this phrase
+          </button>
+        </div>
+      </div>
+    </template>
+  </section>
+</template>

package/example/src/components/SocketWarning.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import type { SocketConnection } from '../composables/useSocketConnection'
+
+defineProps<{ connection: SocketConnection }>()
+</script>
+
+<template>
+  <div v-if="connection.state === 'failed'" class="warn" data-testid="socket-warning">
+    <strong>No confirmation will follow.</strong> The node socket did not open, so you can
+    still submit, but nothing will tell you what the chain decided. {{ connection.error }}
+    <div class="row" style="margin-top: 8px">
+      <button class="small" data-testid="socket-retry" @click="connection.retry()">Retry</button>
+    </div>
+  </div>
+  <p v-else-if="connection.state === 'reconnecting'" class="hint">
+    The node socket is reconnecting. Anything the node reports meanwhile is lost.
+  </p>
+</template>

package/example/src/components/StepGate.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+/**
+ * Holds a step until the steps it builds on are done.
+ *
+ * A held step stays on the page, so what it does can be read ahead, but nothing in it can
+ * be used: `inert` takes every control out of reach, keyboard included. The note above it
+ * names the step to do first.
+ */
+defineProps<{
+  /** What has to happen first, or null once nothing does. */
+  waitingFor?: string | null
+  /** Whether this step's own work is done, which marks its number. */
+  done?: boolean
+}>()
+</script>
+
+<template>
+  <div class="gate" :class="{ locked: !!waitingFor, done }">
+    <p v-if="waitingFor" class="gate-note" data-testid="step-locked">{{ waitingFor }}</p>
+    <div :inert="!!waitingFor">
+      <slot />
+    </div>
+  </div>
+</template>