@waaskey/sdk 0.0.1 → 0.1.0

package/README.md

@@ -16,28 +16,170 @@ pnpm add @waaskey/sdk
 ## Quickstart
 
 ```ts
-import { Waaskey } from '@waaskey/sdk';
+import { Waaskey, WasmMpcCore, EncryptedShareStore } from '@waaskey/sdk';
 
-const waaskey = new Waaskey({ apiKey: process.env.WAASKEY_PUBLISHABLE_KEY! });
+const waaskey = new Waaskey({
+  apiKey: process.env.WAASKEY_PUBLISHABLE_KEY!,
+  // Non-custodial: the device runs its half of the ceremony and seals its key share.
+  mpc: new WasmMpcCore(loadClientWasm), // device-party crypto core (WASM)
+  shareStore: EncryptedShareStore.browser(sessionSecret), // sealed in IndexedDB
+});
 
-// Create an MPC wallet
-const wallet = await waaskey.wallets.create({ userId: user.id, chain: 'ethereum' });
-// → { id: 'wlt_…', address: '0xabc…' }
+// Create an MPC wallet — runs the device keygen, seals the share, waits until active.
+const wallet = await waaskey.wallets.create({ chain: 'ethereum' });
+// → wallet.id, wallet.address, wallet.status === 'active'
 
-// Sign a message (interactive threshold-MPC, one awaited call)
-const signature = await wallet.signMessage('Hello Waaskey');
+// Sign a 32-byte digest (hex; 0x optional)
+const signature = await wallet.sign(digestHex);
+```
+
+### Send a transaction — WaaS signs, **you** broadcast
+
+WaaS is a **signing service, not a broadcaster** (non-custodial: it never owns the
+mempool, nonce, or status-tracking). `wallet.send(...)` builds and MPC-signs the
+transaction and returns the **signed raw tx** — you submit it from your own
+node/provider:
+
+```ts
+const { signedTx, txHash } = await wallet.send({ chainId: 'evm:1', to, value });
+// signedTx → the signed raw tx to broadcast; txHash → a deterministic offline id (not a confirmation)
+
+// Broadcast from YOUR node — either the optional helper…
+const { txHash: broadcastHash } = await waaskey.broadcast(signedTx, { rpcUrl: 'https://your-rpc' });
+// …or your own submitter / provider (recommended for production — you own tracking & retries).
+```
+
+The `broadcast` helper is best-effort by design — one `eth_sendRawTransaction`
+call, **no status polling and no retries**. Tracking the tx to confirmation is the
+integrator's concern.
+
+### Custody policy — choose the threshold topology (advanced)
+
+`wallets.create({ chain })` defaults to the **embedded 2-of-3** topology (the platform
+alone can meet the threshold — the honest default posture). To change the `(t, n)`
+threshold or the custody guarantee, pass a custody policy; the SDK validates it
+client-side and the backend enforces the attested invariant `platformShares < t ⟺
+non-custodial`:
+
+```ts
+const wallet = await waaskey.wallets.create({
+  chain: 'ethereum',
+  threshold: 2, // t
+  parties: ['device', 'backup', 'server'], // n = 3 party roles
+  custodyKinds: ['user_device', 'user_backup', 'platform_signer'], // parallel to parties
+  custodyType: 'shared', // requested posture — the server refuses (400) on a mismatch
+});
+
+// The returned wallet surfaces the attestation so you can display the guarantee:
+wallet.threshold; // 2
+wallet.parties; // ['device','backup','server']
+wallet.custodyKinds; // ['user_device','user_backup','platform_signer']
+wallet.platformShareCount; // 1
+wallet.custodyType; // 'shared'
+wallet.isNonCustodial; // true — platform's 1 share alone can't reach t=2
+```
+
+`CustodyKind` ∈ `user_device | user_backup | platform_signer | platform_recovery |
+external_party`; `CustodyType` ∈ `embedded | shared | self_custody`. The standalone
+`isNonCustodial(wallet)` helper is also exported.
+
+> The device runs whatever `t`-of-`n` the create ceremony describes — keygen is not
+> pinned to 2-of-3. Coordinating an **interactive** `t`-of-`n` _sign_ across more than
+> one user-held party (each running its half over the relay) is a separate follow-up;
+> today's `wallet.sign(...)` covers the device+server quorum.
+
+Read the wallet's signing activity (raw signs + send/sweep signed txs, newest first):
+
+```ts
+const { items } = await wallet.signatures({ page: 1, limit: 20 });
 ```
 
 ## API
 
-| Method                                       | Description                               |
-| -------------------------------------------- | ----------------------------------------- |
-| `new Waaskey({ apiKey, baseUrl?, fetch? })`  | Create a client.                          |
-| `waaskey.wallets.create({ chain, userId? })` | Create a new wallet. Returns a `Wallet`.  |
-| `waaskey.wallets.get(id)`                    | Load an existing wallet.                  |
-| `wallet.signMessage(message)`                | Sign a message with the wallet's MPC key. |
+| Method                                                                                                   | Description                                                                                            |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `new Waaskey({ apiKey, mpc, shareStore, baseUrl?, fetch? })`                                             | Create a client. `mpc` + `shareStore` are required to create wallets.                                  |
+| `waaskey.wallets.create({ chain, label?, threshold?, parties?, custodyKinds?, custodyType? }, options?)` | Create (keygen + sealed share). Optional custody policy (default embedded 2-of-3). Returns a `Wallet`. |
+| `waaskey.wallets.get(id, options?)`                                                                      | Load an existing wallet.                                                                               |
+| `wallet.sign(digestHex, options?)`                                                                       | Sign a 32-byte digest with the wallet's MPC key.                                                       |
+| `wallet.send(params, options?)`                                                                          | Build + MPC-sign a tx. Returns the **signed raw tx** (you broadcast).                                  |
+| `wallet.signatures(query?, options?)`                                                                    | The wallet's signing activity (paginated).                                                             |
+| `waaskey.broadcast(signedTx, { rpcUrl })`                                                                | **Optional** best-effort submit of a signed tx from your own node.                                     |
+
+`create` / `sign` accept `{ signal }` for cancellation; `create` also takes
+`{ waitForActive?, activationTimeoutMs?, pollIntervalMs? }`.
+
+Errors are thrown as `WaaskeyError` with a typed `code` (e.g. `unauthorized`,
+`forbidden`, `validation`, `device_core_required`, `keygen_failed`, `aborted`) plus
+`status?` and `details?` — branch on `error.code`, never on the message text.
+
+### Secure share storage
+
+The device key share is the user's half of the key. `EncryptedShareStore` seals it
+with AES-256-GCM (key derived from a secret **you** supply — the user's session,
+a passkey, or a device secret — never embedded) and persists the ciphertext in
+IndexedDB (`MemoryKeyValueStore` for tests/SSR). Wipe everything on logout:
+
+```ts
+await shareStore.clear();
+```
+
+### Multi-factor recovery
+
+Back up the device share so a user can recover after losing their device. The share
+is encrypted **client-side** with a recovery code (the server only ever stores the
+opaque ciphertext), and its release is gated behind 3 factors: recovery code, TOTP,
+and email OTP.
+
+```ts
+// Enrol — show the returned recoveryCode to the user once (it's the only key).
+const { recoveryCode } = await waaskey.recovery.register(wallet.id, {
+  share: (await shareStore.get(wallet.id))!,
+  totpSecret, // base32 authenticator secret
+  email,
+});
+
+// Later, on a new device — verify factors, re-key, and restore the share locally.
+const { challengeId, requiredFactors } = await waaskey.recovery.challenge(wallet.id);
+await waaskey.recovery.recover(wallet.id, {
+  challengeId,
+  recoveryCode,
+  verifications: [
+    { type: 'recovery_code', token: recoveryCode },
+    { type: 'totp', token: otpFromAuthenticator },
+    { type: 'email_otp', token: otpFromEmail },
+  ],
+});
+```
+
+| Method                                     | Description                                                    |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| `recovery.register(walletId, params)`      | Encrypt the share + enrol factors. Returns the `recoveryCode`. |
+| `recovery.getInfo(walletId)`               | The wallet's registered factors.                               |
+| `recovery.challenge(walletId)`             | Start a recovery session (`challengeId` + required factors).   |
+| `recovery.recover(walletId, params)`       | Verify, re-key, decrypt, and restore the share to the store.   |
+| `recovery.retrieveShare(walletId, params)` | Verify + decrypt the share without re-keying (read-only).      |
+
+### Balances (client-side, no backend)
+
+WaaS is non-custodial and the backend does not index chain state — balances are read
+**directly from a chain provider**, dApp-style. EVM chains work out of the box via a
+default public RPC; override per chain (or plug a custom provider for non-EVM):
+
+```ts
+const waaskey = new Waaskey({
+  apiKey,
+  chains: { ethereum: { rpcUrl: 'https://your-rpc' } }, // optional; EVM has defaults
+});
+
+const eth = await waaskey.balances.getBalance('ethereum', wallet.address!);
+// → { raw: 1000000000000000000n, decimals: 18, symbol: 'ETH', formatted: '1' }
+
+const usdc = await waaskey.balances.getTokenBalance('ethereum', usdcAddress, wallet.address!, { symbol: 'USDC' });
+```
 
-Errors are thrown as `WaaskeyError` (`{ message, status, code }`).
+Balances are exact `bigint` base units plus a `formatted` decimal string (no float).
+`formatUnits(raw, decimals)` is exported for rendering.
 
 ## Development
 
@@ -51,4 +193,4 @@ pnpm build       # tsup → dist (esm + cjs + d.ts)
 
 ## License
 
-[MIT](./LICENSE) © Waaskey
+[MIT](./LICENSE) © WAASKey