889dd566d1
Canonical encoding for BigInt (<bigint: Xn>) and Uint8Array (hex or <Uint8Array: 0x...>) used in the relay protocol. Provides both serialization (sourceOutputToRelay, transactionToHex) and deserialization (parseExtendedJson, toUint8Array, toBigInt) so dapps and wallets don't have to implement this independently.
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# wizardconnect
|
|
|
|
Relay-based protocol library for connecting dapps to HD wallets over WebSocket (Nostr NIP-17 gift-wrapped messages).
|
|
|
|
## Testing philosophy
|
|
|
|
Tests are more important than the code itself. A correct implementation that lacks tests is worse than a slightly imperfect implementation that is well-tested, because untested code will silently break and the breakage will only surface in production — often as subtle protocol bugs that are hard to reproduce.
|
|
|
|
This codebase communicates over a live relay with timing-sensitive handshakes and stateful reconnection logic. These bugs cannot be caught by reading the code. They only appear in integration tests that exercise the real relay.
|
|
|
|
**Always write tests before or alongside any non-trivial change.** If you add a feature, add a test. If you fix a bug, add a regression test that would have caught it.
|
|
|
|
### Test types
|
|
|
|
**Unit tests** (`npm test` in a package):
|
|
- Fast, no network, run on every change
|
|
- Test individual functions and classes in isolation
|
|
- Use vitest, mock external deps
|
|
- Should cover all edge cases in pure logic (state managers, message builders, URI encoding, etc.)
|
|
|
|
**Integration tests** (`npm run test:integration` in a package):
|
|
- Hit the real relay at `wss://relay.cauldron.quest:443`
|
|
- Test the full protocol handshake end-to-end
|
|
- Located in `src/__tests__/*.integration.test.ts`
|
|
- Run with generous timeouts (60s per test) via `vitest.integration.config.ts`
|
|
- Must pass before any release
|
|
|
|
### Running tests
|
|
|
|
```bash
|
|
# All packages, unit tests only (fast):
|
|
npm run test
|
|
|
|
# Wallet package integration tests (requires network):
|
|
cd packages/wallet && npm run test:integration
|
|
|
|
# Custom relay:
|
|
TEST_RELAY_URL=wss://your-relay:443 npm run test:integration
|
|
```
|
|
|
|
### Test CLI (manual/exploratory testing)
|
|
|
|
```bash
|
|
# Start a dapp session and watch the protocol:
|
|
npm run dapp
|
|
|
|
# Connect a test wallet to a dapp URI:
|
|
npm run wallet -- --uri wiz://...
|
|
|
|
# Test the approval flow:
|
|
npm run dapp -- --sign
|
|
```
|
|
|
|
The test CLI (`packages/test-cli/`) is not a substitute for automated tests — it is a debugging tool.
|
|
|
|
## Documentation
|
|
|
|
Protocol and architecture documentation lives in `docs/`. Keep it up to date when making changes:
|
|
|
|
| File | Update when… |
|
|
|------|-------------|
|
|
| `docs/protocol.md` | Protocol messages, handshake logic, or `PathName`/`PathXpub`/`NextIndex` types change |
|
|
| `docs/connection-uri.md` | URI format, key exchange flow, or credential structure changes |
|
|
| `docs/transport.md` | `RelayClient`, `initiateRelay`, reconnect logic, or encryption scheme changes |
|
|
| `docs/wallet.md` | `WalletAdapter`, `WalletConnectionManager`, or connection lifecycle changes |
|
|
| `docs/dapp.md` | `DappConnectionManager` API or session lifecycle changes |
|
|
| `docs/react.md` | React components, hooks, or QR dialog API changes |
|
|
| `docs/pubkey-derivation.md` | xpub delivery, `DappPubkeyStateManager`, or gap-fill logic changes |
|
|
| `docs/xpub-sharing.md` | xpub sharing rationale, security model, or comparison with other protocols changes |
|
|
| `docs/serialization.md` | Relay JSON encoding (`sourceOutputToRelay`, `toBigInt`, `toUint8Array`, etc.) changes |
|
|
| `docs/index.md` | New top-level docs files are added |
|
|
|
|
## Packages
|
|
|
|
- `@wizardconnect/core` — transport + protocol primitives (relay client, key exchange, hdwalletv1 message types)
|
|
- `@wizardconnect/dapp` — dapp-side helpers (`DappConnectionManager`, `DappPubkeyStateManager`)
|
|
- `@wizardconnect/wallet` — wallet-side helpers (`WalletConnectionManager`, `WalletAdapter`, `PubkeyStateManager`)
|
|
- `@wizardconnect/react` — React components and hooks (`WizardConnectQRDialog`, `AlphanumericQRCode`, `useWizardConnect`)
|
|
- `@wizardconnect/test-cli` — manual test CLI (`dapp` and `wallet` modes)
|
|
|
|
## Build
|
|
|
|
```bash
|
|
npm install
|
|
npm run build # builds all packages in dependency order
|
|
```
|
|
|
|
Packages must be built before integration tests run (tests import from `dist/`).
|