@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/.idea/geeq_sdk.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/geeq_sdk.iml" filepath="$PROJECT_DIR$/.idea/geeq_sdk.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.nvmrc

@@ -0,0 +1 @@
+22

package/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Working on the SDK
+
+```bash
+npm install
+npm test            # unit tests, no network needed
+npm run typecheck
+npm run build       # builds browser + Node bundles, types, and the engine
+npm run smoke       # tests the built package
+```
+
+Everything installs from the public npm registry. The two parts that come from Geeq's
+private repositories are vendored: the WASM engine in [`src/wasm`](./src/wasm/README.md)
+and the Cap'n Proto schemas in [`src/capnp`](./src/capnp/README.md).
+
+A full Vue 3 integration example lives in [`example/`](./example). It uses the SDK from
+this folder (`file:..`), so run `npm run build` here before starting it.
+
+**Update the README whenever the SDK changes.** It is the package's page on npm, and
+`tests/documented-api.test.ts` checks that its Reference section and Quick start still
+match the code.

package/example/.env.example

@@ -0,0 +1,4 @@
+# How many pennies make one Geeq. The chain counts only pennies and does not publish this,
+# so each app sets it, as the Geeq web app sets VUE_APP_BALANCE_DIVISOR. Use the same value
+# as your other apps and explorer, or the figures will not match theirs.
+VITE_PENNIES_PER_GEEQ=1000000000

package/example/README.md

@@ -0,0 +1,304 @@
+# Geeq SDK demo — Vue 3
+
+A minimal Vue 3 application showing how to use
+[`@geeqdev/geeq-sdk`](..) in a browser app. For how the SDK works and
+how to integrate it, read its
+**[README](../README.md)** — that is the single SDK document. This file
+only covers the demo.
+
+To install the demo and try it step by step, see **[USAGE.md](USAGE.md)**.
+
+What it does: generates a BIP-39 recovery phrase, derives a Geeq keypair and
+address, finds a node, then submits a document's hash as evidence, sends coin, delegates
+authority to an account that digital assets are created through, creates one, lists the
+account's digital assets and sends them on — and shows what the chain decided about each,
+as the node reports it over its socket. Step 9 looks any transaction
+up in a block explorer by its refHash.
+
+The steps build on each other, so each one waits — visible but unusable — until the
+steps before it are done, and says which to do first: the phrase (1), then the keypair
+and its chain number (2), then a node for that chain (3). Steps 4–8 need all three; step
+9 needs none. The chain number is set only in step 2; step 3 shows it, and moving step 2
+to another chain lets the node go until one is found for the new chain.
+
+Keys never leave the tab and nothing is stored — they live in memory and are gone on
+refresh. The only network traffic is to the simulator you name in step 3 and the node it
+points at: the SDK asks the simulator which nodes serve your chain, reads the chosen
+node's ledger to work out what a transaction must be pinned to, opens that node's
+WebSocket to hear verdicts, and the page posts the signed result back. Step 9 also
+calls the block explorer you name there.
+
+## Terminology
+
+The demo uses the words the Geeq apps show their users. The SDK and the protocol keep
+their own words, so the two meet wherever the demo calls the SDK:
+
+| The demo says | The SDK and the protocol say | SDK calls |
+|---|---|---|
+| **Submit evidence** (step 4): evidence, evidence hash | attestation, attest hash | `createAttestation`, `attestHashOf`, `attestationSubmitBody` |
+| **Delegate authority** (step 6): authority account, delegation | NFT mint proxy, proxy, proxy creation | `createNftMintProxy`, `findNftMintProxies` |
+| **Create a digital asset** (step 7): digital asset | mint an NFT, NFT | `mintNft`, `findNfts`, `createTransfer({ nfts })` |
+| **Send coin** (step 5): coin, transfer | coin asset, unchanged | `createTransfer({ amount })` |
+
+The demo's own names use its words too: `EvidencePanel.vue`, `AuthorityPanel.vue`,
+`CreateAssetPanel.vue` and `DigitalAssetsPanel.vue`, and the variables and test ids inside
+them. What comes from the SDK or the chain keeps the protocol's words:
+
+- SDK functions and types, such as `AttestationTx`, `NftMintTx` and `GeeqNftMintProxies`,
+  and the fields they return, such as `tx.nftId`, `tx.proxyAddress`, `found.proxies` and
+  `asset.attestHash`;
+- the record types listed in step 2, such as `coin-asset`, `proxy-nft-mint` and `app-nft`;
+- error messages from the SDK, which the panels show as they come, so one may say "NFT" or
+  "proxy";
+- the transaction type the block explorer reports in step 9, such as `attestation`.
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+The SDK is linked from the repository root (`file:..`), so build it first if you have
+not already:
+
+```bash
+cd .. && npm install && npm run build
+```
+
+### Pointing it at a local node
+
+Real nodes answer on port 2082 behind TLS, with the socket on the same port at `/ws/`, and
+that is what the demo uses by default. For a local node that isn't behind TLS, open
+**Local harness options** in step 3:
+
+- **Node port**: the node's HTTP port, used instead of 2082.
+- **Socket URL**: the full socket address, for a node that serves it elsewhere, such as
+  `ws://10.0.0.1:3100/ws/`. Leave it empty to derive it from the node.
+
+The socket URL is read when the socket opens, so set it before **Find a node**, or press
+Retry after changing it.
+
+## What it demonstrates
+
+| Step | SDK functions |
+|---|---|
+| Show engine status | `initGeeq()` |
+| Generate a 12–24 word phrase | `generateMnemonic({ words })` |
+| Validate a pasted phrase as you type | `validateMnemonic()` |
+| Derive the keypair | `keypairFromMnemonic()` |
+| Show the address | `keypair.getAddress({ chainNumber })` |
+| Show public key and account id | `keypair.publicKey`, `keypair.accountId` |
+| Release the engine handle | `keypair.dispose()` |
+| Find a node for a chain number | `GeeqChain.connect({ discovery, chainNumber, penniesPerGeeq })` |
+| Send coin to a pasted address | `chain.createTransfer({ from, to, amount })` |
+| Read and show an amount | `chain.toPennies({ geeq })`, `chain.formatGeeq(pennies)` |
+| Derive chain, block, node and nonce | `chain.getChainState({ account })` |
+| Delegate authority: create an authority account to create digital assets through | `chain.createNftMintProxy({ admin, amount })` |
+| List an account's authority accounts by index, and the next index | `chain.findNftMintProxies({ admin, maxAgeMs: 0 })` |
+| Create a digital asset through a chosen authority account | `chain.mintNft({ admin, index, content: file, metadata })` |
+| List the account's digital assets, with their hashes and labels | `chain.findNfts({ owner, maxAgeMs: 0 })` |
+| Send one digital asset or several to a pasted address | `chain.createTransfer({ from, to, nfts })` |
+| Give back the nonce of a build that was never sent | `chain.discard(tx)` |
+| Check a build that waited is not too old to send | `chain.isExpired(tx)`, `tx.validUntilBlock` |
+| Read a pasted evidence hash | `fromHex(text)` |
+| Hash a chosen file | `attestHashOf(file)` |
+| Check metadata against a chain's limits | `inspectMetadata(labels, limits)` |
+| Build and sign evidence | `chain.createAttestation({ keypair, attestHash })` |
+| Open the node's socket | `GeeqSocket.connect({ endpoint: chain.endpoint })` |
+| Show its connection state | `socket.onConnectionChange(state => …)` |
+| Show every event the node pushes | `socket.onMessage(({ event, payload }) => …)` |
+| Subscribe the account | `socket.subscribe(keypair)` |
+| Listen for a transaction's verdict before sending it | `socket.track(tx)` |
+| Settle a refused submission at once | `tracked.refused({ status, message })` |
+| Follow it to confirmed / rejected / unknown | `tracked.onChange(t => …)`, `t.status`, `t.outcome` |
+| Look a transaction up in a block explorer | `getExplorerTransaction({ explorerUrl, refHash })` |
+
+Details worth copying into a real application:
+
+**1. Mnemonic generation needs no engine.** `generateMnemonic` and
+`validateMnemonic` are pure JavaScript, so step 1 works instantly while the ~2 MB
+WebAssembly engine is still downloading. Only key derivation waits for it.
+
+**2. Mark keypairs raw in reactive state.** A keypair is a class instance holding
+an engine handle and typed arrays. `KeypairPanel.vue` uses `shallowRef` + `markRaw`,
+because deep reactivity would proxy those arrays before they reach WebAssembly and
+buys nothing — the object is replaced wholesale, never mutated.
+
+**3. Dispose before replacing.** `keypair.dispose()` releases the engine-side key.
+The demo does this whenever the phrase changes, so repeated derivation does not
+leak handles.
+
+**4. Post to `tx.nodeUrl`, not to a URL you kept.** The transaction names the node
+that must process it, and the node compares that number to its own with strict
+equality. The SDK tells you where the chain state came from; submitting anywhere else
+is a guaranteed rejection.
+
+**5. One transaction per account per block.** Two sharing a nonce are *both* rejected by
+the chain, so the SDK throws `nonce-collision` on the second rather than building
+something that would destroy the first. It applies to evidence and transfers alike, since
+they share an account's nonce — and to delegations, which spend it too. Creating a digital
+asset spends its authority account's nonce instead, so it is held to one per authority
+account per block. A build that was never sent can give its nonce back with
+`chain.discard(tx)`: step 7 does that when you change the file, labels or authority
+account, so building again is not refused.
+
+**6. Amounts name their unit.** `{ geeq: "1.5" }` or `{ pennies }` — never a bare number,
+because a unit mistake in money does not throw. The chain counts only pennies; how many make
+a Geeq is this app's setting, `VITE_PENNIES_PER_GEEQ` in `.env`, passed to `connect` as
+`penniesPerGeeq`. Set it to the divisor your other apps and explorer use. The transfer panel
+shows the penny figure as you type.
+
+**7. Track before you submit, and keep the socket for the page's life.** Every panel calls
+`socket.track(tx)` before the POST, because a verdict that arrives before anyone has
+subscribed is lost. `composables/useSocketConnection.ts` opens one socket per chain and
+closes it only when the chain changes; closing it on an account switch would strand every
+pending transaction. The tracked handle lives in the socket, so `TxStatus.vue` keeps
+showing a verdict even after the panel rebuilds its transaction.
+
+**8. No socket is not no transactions.** A socket that will not open — most often a
+node certificate the browser has not accepted — does not stop anyone submitting.
+`SocketWarning.vue` warns above Submit that no confirmation will follow, with the
+socket's error and a Retry. If subscribing fails at submit time, the transaction is sent
+anyway and the panel says no confirmation will follow.
+
+**9. A `200` is pending, not success.** The panels show a submitted transaction as
+pending until the node's verdict arrives. A refused POST is settled at once with
+`tracked.refused(...)`, since the node never sends a status for a transaction it refused.
+
+**10. Every authority account has an index, and the ledger gives the next one.** An
+authority account's id is derived from its admin's key and an index — the first is 1 — as
+the Geeq apps do it. `createNftMintProxy` finds the account's authority accounts and takes
+one past the highest index, so nothing is stored. **Find in ledger** in step 6 lists them
+by index with the balance and nonce that creating a digital asset through them will use,
+and shows the next index. An authority account is listed only once a block has confirmed
+it.
+
+**11. A digital asset is sent by its authority account, not by the account.** Step 7 lists
+the account's authority accounts to choose from. The chosen one pays the fee and the
+chain's minimum, which goes to the account with the digital asset, and spends its own
+nonce, so the account can send something else in the same block. The account signs, as
+the authority account's admin. It posts like evidence: `uat`, with a payload, using
+`attestationSubmitBody`.
+
+**12. Digital assets are sent as a transfer, with coin.** Step 8 lists the digital assets
+the account holds: which ones from its record in the ledger, and the hash and labels each
+was created with from the application layer ledger. Step 5 sends them: switch it to
+**Digital assets**, get the list, tick one or several. They go in one transfer, posted as
+`uvt`, carrying the chain's minimum transfer, since every transfer must carry at least
+that. A new digital asset is listed once a block has confirmed it, and one sent away is
+gone once a block confirms that.
+
+**13. The explorer takes the same id the socket gives you.** Paste the base64 transaction
+id shown under a verdict into step 9. The SDK asks the explorer in hex, the form it
+stores, so you never convert it yourself. `null` means the explorer does not have it yet:
+it only learns of a transaction once a block has decided it.
+
+**14. A signed transaction cannot wait long.** A node takes it only until the chain is past
+`tx.validUntilBlock`, its target block plus 8 — about nine blocks after it was built — and
+refuses it with a `400` after that. Every panel shows that block under Submit, and calls
+`chain.isExpired(tx)` before posting, which reads the ledger afresh. If the chain has moved
+past it, nothing is sent: the panel says so and turns Submit off until you build again.
+
+## Vite configuration
+
+One line, and it is the only SDK-specific configuration needed:
+
+```ts
+export default defineConfig({
+  plugins: [vue()],
+  optimizeDeps: { exclude: ['@geeqdev/geeq-sdk'] },
+})
+```
+
+Vite's dependency pre-bundling rewrites the `new URL('...wasm', import.meta.url)`
+the SDK uses to locate its engine. Excluding the SDK keeps that pattern intact, so
+the `.wasm` is emitted as a hashed asset. webpack 5 and Parcel need no equivalent.
+
+## Verifying it
+
+```bash
+npm run typecheck      # vue-tsc, strict
+npm run build          # type-checks, then builds; emits the .wasm as an asset
+npm run browser-check  # drives the production build in real Chromium
+```
+
+`browser-check` serves `dist/` and drives it with Playwright. It also stubs a Geeq
+node — serving a synthetic validation layer ledger built with the same Cap'n Proto
+schema the SDK decodes, and accepting the submitted transaction — so the whole path
+runs in a real browser with no live node. The engine loads over HTTP, a phrase is
+generated, a keypair derived and chain state read. Then evidence and a coin transfer
+are signed, posted and decoded back, to confirm that the block, node, nonce,
+amount and recipient they carry are the ones the ledger and the page supplied. It also
+drives the failure paths: a nonce collision, an unfunded account, an undecodable ledger,
+and amounts that are malformed, below the chain minimum or over the balance.
+
+The node's socket is stubbed with Playwright's `routeWebSocket`, which swaps the page's
+`WebSocket` for an in-page stand-in: the SDK's socket code runs unchanged against frames
+the check sends and records, with no network handshake. The check asserts the signer is
+subscribed *before* the POST, then pushes status events keyed by a refHash it computes
+from the posted bytes the way the node does — so an SDK that hashed a transaction
+differently from the node would never see it settle. It drives confirmed evidence, a
+refused submission that settles with no socket event, a transfer that is flagged
+`nonsane` and then found `invalid`, and an arbitrary pushed event. A delegation is posted
+and decoded back too: its authority account must take index 1 with the id the Geeq apps
+derive and name this account as admin, and once confirmed the ledger must list it as
+index 1, so that the next one built takes index 2. A digital asset is then created through
+authority account 1 and decoded back: it must be sent by the authority account on its own
+nonce, to this account, carrying the file's hash and labels. Before it is sent, a label is
+changed and the build redone in the same block on the same nonce; once it is sent, another
+build in that block must be refused. The stub then puts that digital asset and one more on
+the account's record, and serves the application layer ledger with their hashes and
+labels: step 8 must list both, and step 5 sends them — one ticked,
+built, then a second ticked and rebuilt in the same block — as a transfer carrying both, at
+their places in the account's record, with the chain's minimum. Last, a transfer is built and
+the stub's chain moved past its `validUntilBlock`: Submit must say it is too old and post
+nothing.
+
+Then the socket's failures:
+- a dropped socket that reconnects and replays its subscriptions;
+- one that cannot come back, where the transaction is sent anyway with a warning — this
+  waits out the SDK's 15 s open timeout;
+- one that never opens, where the page warns, still submits, and Retry recovers.
+
+Finally it stubs the block explorer's `byRefHash` route, which answers as the real one
+does, including its HTTP 500 for a refHash it does not have. It looks up the evidence by
+its base64 id and checks that the explorer was asked in hex. It also checks that an
+unknown refHash shows as not found, and that a hex refHash is refused before anything is
+sent.
+
+It expects Chrome at `/usr/bin/google-chrome`; override with `CHROME_PATH`.
+
+## Layout
+
+```
+src/
+├── App.vue                     engine status + page layout
+├── components/
+│   ├── PhrasePanel.vue         generate or restore a recovery phrase
+│   ├── KeypairPanel.vue        derive and display the keypair
+│   ├── ChainPanel.vue          name a simulator, find a node for step 2's chain; shows its socket
+│   ├── EvidencePanel.vue       paste a hash or hash a file, sign, track, submit
+│   ├── TransferPanel.vue       send coin or digital assets to a pasted address, track, submit
+│   ├── AuthorityPanel.vue      delegate authority, track, submit; list your authority accounts
+│   ├── CreateAssetPanel.vue    choose an authority account, create a digital asset through it, track, submit
+│   ├── DigitalAssetsPanel.vue  list the digital assets this account holds
+│   ├── ExplorerPanel.vue       look a transaction up in a block explorer by refHash
+│   ├── TxStatus.vue            one tracked transaction, followed to its verdict
+│   ├── ChainState.vue          the chain, block, node and nonce a built transaction is pinned to
+│   ├── TxFee.vue               the fee a built transaction will be charged
+│   ├── TxDeadline.vue          the last block a built transaction can still be sent at
+│   ├── SocketWarning.vue       what a panel says when no verdict can be heard
+│   ├── StepGate.vue            holds a step until the steps it builds on are done
+│   └── CopyButton.vue
+├── composables/
+│   └── useSocketConnection.ts  the chain's node socket: opened and closed with the chain
+├── style.css                   light/dark, no CSS framework
+└── main.ts
+```
+
+## Not for real funds
+
+This is an SDK demo. It has no persistence, no encryption at rest, no password, and
+it displays a private key on request — all things a real application must handle
+properly. Read it for the SDK calls, not as a security template.

package/example/USAGE.md

@@ -0,0 +1,74 @@
+# Using the demo
+
+How to install the demo and try each step. For how the code works, see the
+[README](README.md).
+
+## Install
+
+You need Node.js 20 or newer. The demo lives in the SDK repository's `example/` folder
+and uses the SDK from the repository root, so build that first:
+
+```bash
+cd .. && npm install && npm run build
+cd example && npm install
+cp .env.example .env
+```
+
+In `.env`, check `VITE_PENNIES_PER_GEEQ` (how many pennies make one Geeq). Use the same
+value as your other Geeq apps and your explorer.
+
+## Run
+
+```bash
+npm run dev
+```
+
+Open the printed URL and wait for **Engine ready**.
+
+## Steps
+
+Steps unlock in order. Steps 1–3 set up the account and the node, steps 4–8 need them,
+and step 9 works on its own. Nothing is saved, so a refresh clears your keys.
+
+1. **Recovery phrase**: click **Create new**, then **Generate phrase**. Or click
+   **Restore existing** and paste your own.
+2. **Keypair & address**: set the **Chain number** and click **Derive keypair**.
+3. **Chain**: paste a **Simulator URL** and click **Find a node**.
+4. **Submit evidence**: paste a hash or choose a file.
+5. **Send coin or digital assets**: choose **Geeq** or **Digital assets** and paste the
+   recipient's address.
+6. **Delegate authority**: create and fund an authority account. You need one before you
+   can create a digital asset.
+7. **Create a digital asset**: click **Find my authority accounts**, pick one, and choose
+   a file.
+8. **Your digital assets**: click **Get my digital assets**.
+9. **Block explorer**: paste an explorer URL and a transaction id from steps 4–7.
+
+In steps 4–7, click **Build & sign**, then **Submit to node**, and wait for the
+**Verdict**. A new account is empty, so send it some coin before step 4.
+
+## Terminology
+
+The demo uses the words the Geeq apps show their users. The SDK and the protocol use
+their own:
+
+| In the demo                           | In the SDK and the protocol      |
+| ------------------------------------- | -------------------------------- |
+| Submit evidence, evidence             | attestation                      |
+| Delegate authority, authority account | create an NFT mint proxy, proxy  |
+| Create a digital asset, digital asset | mint an NFT, NFT                 |
+| Send coin                             | coin asset, unchanged            |
+
+So an error message from the SDK may say "NFT" or "proxy", the record types in step 2
+keep their protocol names, and the block explorer in step 9 reports its own transaction
+types, such as `attestation`. The [README](README.md#terminology) lists which names in the
+code changed.
+
+## If something goes wrong
+
+| You see                                                | Fix                                                                                   |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **Engine failed to load**                              | Rebuild the SDK and restart `npm run dev`.                                            |
+| `Cannot convert undefined to a BigInt`                 | Set `VITE_PENNIES_PER_GEEQ` in `.env` (VITE_PENNIES_PER_GEEQ=1000000000) and restart. |
+| **Could not reach that simulator**, or socket `failed` | Open the URL in a tab, accept its certificate, then try again.                        |
+| **This account has never received coins**              | Send coin to the account's address first.                                             |

package/example/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Geeq SDK Demo</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>