@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/example/scripts/match-derivation.mjs

@@ -0,0 +1,65 @@
+/**
+ * Find which derivation path produced a given address.
+ *
+ * `chainNumber` is *not* part of the derivation path — it is stamped into the
+ * address envelope alongside the account id. So two apps on the same chain
+ * still disagree whenever their coin type, record type, account, address index
+ * or passphrase differ. This walks the plausible combinations and tells you
+ * which one your app used.
+ *
+ *   MNEMONIC="word word …" TARGET=fvCvcdu… CHAIN=1000000008 \
+ *     node scripts/match-derivation.mjs
+ *
+ * TARGET is optional — leave it off to print the whole matrix. The phrase is
+ * read from the environment and never written anywhere.
+ */
+import { keypairFromMnemonic } from '@geeqdev/geeq-sdk'
+
+const mnemonic = process.env.MNEMONIC
+const target = process.env.TARGET
+const chainNumber = Number(process.env.CHAIN ?? 1)
+
+if (!mnemonic) {
+  console.error('Set MNEMONIC, e.g. MNEMONIC="legal winner thank …" node scripts/match-derivation.mjs')
+  process.exit(1)
+}
+
+const COIN_TYPES = ['testnet', 'mainnet']
+const RECORD_TYPES = ['coin-asset', 'coin-hl', 'coin-micro']
+const INDICES = [0, 1, 2]
+// '' is the SDK default. To try others as well, PASSPHRASES=",one,two".
+const PASSPHRASES = (process.env.PASSPHRASES ?? '').split(',')
+
+let found = null
+for (const passphrase of PASSPHRASES) {
+  for (const coinType of COIN_TYPES) {
+    for (const recordType of RECORD_TYPES) {
+      for (const account of INDICES) {
+        for (const addressIndex of INDICES) {
+          const options = { coinType, recordType, account, addressIndex, passphrase }
+          const keypair = await keypairFromMnemonic(mnemonic, options)
+          // The envelope record type is independent of the derivation one, but an
+          // app that derives with X almost always encodes with X too.
+          const address = keypair.getAddress({ chainNumber, recordType })
+          keypair.dispose()
+
+          const match = address === target
+          if (match) found = options
+          if (!target || match) {
+            console.log(
+              `${coinType.padEnd(8)} ${recordType.padEnd(11)} account=${account} addressIndex=${addressIndex} passphrase=${passphrase === '' ? '(none)' : passphrase}  ${address}${match ? '  <<< MATCH' : ''}`,
+            )
+          }
+        }
+      }
+    }
+  }
+}
+
+if (target) {
+  console.log(
+    found
+      ? `\nMatched with ${JSON.stringify(found)} at chain ${chainNumber}.`
+      : `\nNo match at chain ${chainNumber}. Try another BIP-39 passphrase via PASSPHRASES=..., a record type outside ${RECORD_TYPES.join('/')}, or an index above ${Math.max(...INDICES)}.`,
+  )
+}

package/example/src/App.vue

@@ -0,0 +1,138 @@
+<script setup lang="ts">
+import { markRaw, onMounted, ref, shallowRef, watch } from 'vue'
+import { GeeqError, initGeeq } from '@geeqdev/geeq-sdk'
+import type { GeeqChain, GeeqKeypair } from '@geeqdev/geeq-sdk'
+import { useSocketConnection } from './composables/useSocketConnection'
+import EvidencePanel from './components/EvidencePanel.vue'
+import ChainPanel from './components/ChainPanel.vue'
+import ExplorerPanel from './components/ExplorerPanel.vue'
+import CreateAssetPanel from './components/CreateAssetPanel.vue'
+import DigitalAssetsPanel from './components/DigitalAssetsPanel.vue'
+import TransferPanel from './components/TransferPanel.vue'
+import AuthorityPanel from './components/AuthorityPanel.vue'
+import PhrasePanel from './components/PhrasePanel.vue'
+import StepGate from './components/StepGate.vue'
+import KeypairPanel from './components/KeypairPanel.vue'
+
+type EngineState = 'loading' | 'ready' | 'error'
+
+const engine = ref<EngineState>('loading')
+const engineError = ref('')
+const mnemonic = ref('')
+// Owned here because two panels need to agree on it: the address encodes the
+// chain, and the node found for it in step 3 serves that same chain. Step 2 sets it;
+// step 3 only reads it.
+const chainNumber = ref(1)
+// Published by KeypairPanel, which still owns the engine handle and disposes it —
+// this is a borrowed reference, set back to null the moment that happens.
+const keypair = shallowRef<GeeqKeypair | null>(null)
+// The chain is connected once, in step 3, and shared by everything that builds a
+// transaction. Same shallowRef + markRaw reasoning as the keypair.
+const chain = shallowRef<GeeqChain | null>(null)
+// The node's socket, opened with the chain and closed with it. Every transaction panel
+// tracks its transactions through it.
+const socketUrl = ref('')
+const connection = useSocketConnection(chain, socketUrl)
+
+// The steps everything else builds on, in the order they are done. Each later step waits
+// for the first of these before it that is not done yet.
+const foundations = [
+  { step: 1, done: () => mnemonic.value !== '', todo: 'create or restore a recovery phrase' },
+  { step: 2, done: () => keypair.value !== null, todo: 'derive a keypair' },
+  { step: 3, done: () => chain.value !== null, todo: 'find a node' },
+]
+
+/** What `step` is waiting for, as a sentence, or null when it can be used. */
+function waitingFor(step: number): string | null {
+  const missing = foundations.find((f) => f.step < step && !f.done())
+  return missing === undefined ? null : `Waiting for step ${missing.step}: ${missing.todo}.`
+}
+
+function onKeypair(next: GeeqKeypair | null) {
+  keypair.value = next === null ? null : markRaw(next)
+}
+
+// Subscribe the account whenever there is an account and a socket, so the node
+// also pushes its updates — not only the statuses of what this page sends.
+watch([keypair, () => connection.socket], ([account, socket]) => {
+  if (account === null || socket === null) return
+  // If this fails, track() subscribes again before a submission and reports it then.
+  socket.subscribe(account).catch(() => {})
+})
+
+onMounted(async () => {
+  // Loads the ~2 MB WebAssembly engine once. Every async SDK call awaits this
+  // internally, so this is only here to drive the status indicator.
+  try {
+    await initGeeq()
+    engine.value = 'ready'
+  } catch (e) {
+    engine.value = 'error'
+    engineError.value = e instanceof GeeqError ? `${e.code}: ${e.message}` : String(e)
+  }
+})
+</script>
+
+<template>
+  <div class="wrap">
+    <header>
+      <h1>Geeq sdk usage demo</h1>
+      <p>
+        Generate a recovery phrase and derive a Geeq keypair, entirely in the browser
+        with <code>@geeqdev/geeq-sdk</code>.
+      </p>
+      <div class="engine">
+        <span class="dot" :class="engine" />
+        <span v-if="engine === 'loading'">Loading engine…</span>
+        <span v-else-if="engine === 'ready'">Engine ready</span>
+        <span v-else>Engine failed to load</span>
+      </div>
+      <div v-if="engine === 'error'" class="warn">{{ engineError }}</div>
+    </header>
+
+    <StepGate :done="mnemonic !== ''">
+      <PhrasePanel @change="(value: string) => (mnemonic = value)" />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(2)" :done="keypair !== null">
+      <KeypairPanel
+        v-model:chain-number="chainNumber"
+        :mnemonic="mnemonic"
+        :engine-ready="engine === 'ready'"
+        @keypair="onKeypair"
+      />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(3)" :done="chain !== null">
+      <ChainPanel
+        v-model:socket-url="socketUrl"
+        :chain-number="chainNumber"
+        :connection="connection"
+        @chain="(next: GeeqChain | null) => (chain = next === null ? null : markRaw(next))"
+      />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(4)">
+      <EvidencePanel :keypair="keypair" :chain="chain" :connection="connection" />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(5)">
+      <TransferPanel :keypair="keypair" :chain="chain" :connection="connection" />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(6)">
+      <AuthorityPanel :keypair="keypair" :chain="chain" :connection="connection" />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(7)">
+      <CreateAssetPanel :keypair="keypair" :chain="chain" :connection="connection" />
+    </StepGate>
+    <StepGate :waiting-for="waitingFor(8)">
+      <DigitalAssetsPanel :keypair="keypair" :chain="chain" />
+    </StepGate>
+    <!-- Needs nothing from the steps above: any refHash can be looked up. -->
+    <ExplorerPanel />
+
+    <footer>
+      Keys and phrases exist only in this tab's memory and are gone on refresh — nothing
+      is stored. The only network traffic is to the simulator and the node it picks in
+      step 3: reading its ledger, submitting what you build, and its socket, which reports
+      back what the chain decided. If the socket cannot open, submitting still works —
+      nothing will report back. Step 9 also asks the block explorer you name.
+    </footer>
+  </div>
+</template>

package/example/src/components/AuthorityPanel.vue

@@ -0,0 +1,277 @@
+<script setup lang="ts">
+import { markRaw, ref, shallowRef, watch } from 'vue'
+import { coinTransferSubmitBody, submitRoute, toBase64 } from '@geeqdev/geeq-sdk'
+import type {
+  GeeqChain,
+  GeeqKeypair,
+  GeeqNftMintProxies,
+  GeeqTrackedTx,
+  NftMintProxyTx,
+} 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 amount = ref('5')
+
+const tx = ref<NftMintProxyTx | 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('')
+
+/** 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('')
+
+// A built transaction is pinned to a block and a nonce, so any change invalidates it.
+watch([amount, () => props.keypair, () => props.chain], () => {
+  tx.value = null
+  submitted.value = false
+  submitError.value = ''
+  expired.value = false
+})
+watch([() => props.keypair, () => props.chain], () => (found.value = null))
+
+async function build() {
+  if (props.keypair === null || props.chain === null) return
+
+  building.value = true
+  buildError.value = ''
+  tx.value = null
+  submitted.value = false
+  expired.value = false
+  try {
+    // Reads the ledger, checks the funding against the balance and the chain's minimum,
+    // finds this account's authority accounts to take the next index, then signs.
+    tx.value = await props.chain.createNftMintProxy({
+      admin: props.keypair,
+      amount: { geeq: amount.value.trim() },
+    })
+  } 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 a transfer.
+    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}`
+      }
+    }
+
+    // Delegating authority is a validation-layer transaction, so it posts exactly like a
+    // transfer: one blob, as `uvt`.
+    const response = await fetch(submitRoute(target), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: coinTransferSubmitBody(built.transaction),
+    })
+    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
+  }
+}
+
+async function findAuthorities() {
+  if (props.keypair === null || props.chain === null) return
+
+  finding.value = true
+  findError.value = ''
+  try {
+    // A fresh read: an authority account is in the ledger only once a block has confirmed it.
+    found.value = await props.chain.findNftMintProxies({ admin: props.keypair, maxAgeMs: 0 })
+  } catch (error) {
+    findError.value = (error as Error).message
+  } finally {
+    finding.value = false
+  }
+}
+</script>
+
+<template>
+  <section class="card">
+    <h2><span class="step">6</span>Delegate authority</h2>
+
+    <p class="hint" style="margin-top: 0">
+      A digital asset is created through an <strong>authority account</strong>: a record of
+      its own on the chain that holds coin to pay for creating digital assets, and that only
+      its admin — this account — can sign for. Delegate authority here to create one, then
+      create digital assets through it in step 7.
+    </p>
+    <p class="hint">
+      Each authority account has an <strong>index</strong> — an account's first is 1 — and its
+      id is derived from the admin's key and that index. The SDK finds this account's
+      authority accounts in the ledger and takes the next index, so nothing has to be
+      remembered.
+    </p>
+
+    <div class="row">
+      <span class="ctl">
+        <label for="authority-amount">Fund with</label>
+        <input
+          id="authority-amount"
+          v-model="amount"
+          type="text"
+          inputmode="decimal"
+          placeholder="5"
+          data-testid="authority-amount"
+        />
+        geeq
+      </span>
+      <button
+        class="primary"
+        :disabled="!keypair || !chain || amount.trim() === '' || building"
+        data-testid="build-authority"
+        @click="build"
+      >
+        {{ building ? 'Reading ledger & signing…' : 'Build & sign' }}
+      </button>
+    </div>
+    <p class="hint">
+      The funding moves onto the authority account and pays for the digital assets created
+      through it. It must clear the chain's minimum transfer, and the fee is charged on top.
+    </p>
+    <div v-if="buildError" class="warn" data-testid="authority-error">{{ buildError }}</div>
+
+    <template v-if="tx && chain">
+      <div class="field">
+        <div class="k">
+          Authority account <span data-testid="authority-index">{{ tx.index }}</span> of this account · address
+        </div>
+        <div class="row">
+          <code class="v" style="flex: 1 1 auto" data-testid="authority-address">{{ tx.proxyAddress }}</code>
+          <CopyButton :value="tx.proxyAddress" />
+        </div>
+      </div>
+
+      <div class="field">
+        <div class="k">Authority account id · base64 · derived from your key and the index</div>
+        <div class="v" data-testid="authority-id">{{ toBase64(tx.proxyAccountId) }}</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">Signed transaction · base64 · {{ tx.transaction.length }} chars</div>
+        <div class="v wrap" data-testid="authority-base64">{{ tx.transaction }}</div>
+      </div>
+
+      <h3 class="sub">Submit</h3>
+      <div class="row">
+        <button
+          class="primary"
+          :disabled="submitting || submitted || expired || connection.state === 'connecting'"
+          data-testid="submit-authority"
+          @click="submit"
+        >
+          {{ submitting ? 'Submitting…' : submitted ? 'Submitted' : 'Submit to node' }}
+        </button>
+      </div>
+      <p class="hint">
+        Sent like a transfer. It uses this account's nonce
+        <strong data-testid="admin-nonce">{{ tx.chainState.nonce }}</strong>, not an
+        authority account's, so send it once: a second copy is refused once the first has
+        landed. The authority account exists once a block confirms it.
+      </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" />
+
+    <h3 class="sub">Your authority accounts</h3>
+    <div class="row">
+      <button :disabled="!keypair || !chain || finding" data-testid="find-authorities" @click="findAuthorities">
+        {{ finding ? 'Reading ledger…' : 'Find in ledger' }}
+      </button>
+    </div>
+    <div v-if="findError" class="warn">{{ findError }}</div>
+    <template v-if="found && chain">
+      <p v-if="found.proxies.length === 0" class="hint" data-testid="no-authorities">
+        None yet. An authority account shows here once a block has confirmed it.
+      </p>
+      <div v-for="authority in found.proxies" :key="authority.address" class="field" data-testid="authority">
+        <div class="k">Authority account {{ authority.index ?? '(no index)' }}</div>
+        <div class="v">{{ authority.address }}</div>
+        <div class="hint">
+          {{ chain.formatGeeq(authority.balance) }} geeq {{ penniesLabel(authority.balance) }} · own
+          nonce {{ authority.nonce }}
+        </div>
+      </div>
+      <p class="hint">
+        The next authority account takes index
+        <strong data-testid="next-index">{{ found.nextIndex }}</strong>. Each authority account
+        has its own nonce, which starts at 1 and moves only when a digital asset is created
+        through it. Delegating authority spends this account's nonce instead.
+      </p>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.ctl { display: inline-flex; align-items: center; gap: 8px; }
+.ctl input { width: 100px; }
+.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>