b96cb8e151
Splits ProtocolMessages exceeding NIP-44's 65,535-byte plaintext ceiling across multiple gift-wrapped events. Symmetric (both directions), fire-and-forget, backward-compatible via a new transport-level \`extensions\` field on \`dapp_ready\` and \`wallet_ready\`. Resolves the \"Failed to swap: invalid plaintext size\" error on aggregated swap requests and enables signed-tx responses up to the 1 MB BCH consensus limit (~2 MB hex).
90 lines
4.2 KiB
Markdown
90 lines
4.2 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 relays at `wss://relay.riften.net:443` and `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/extensions.md` | hdwalletv1 protocol-level extensions, `WalletAdapter` extension hooks, known protocol extensions, or custom message conventions change |
|
|
| `docs/transport.md` (transport extensions section) | Transport-level extensions (`chunk`, future: compression), base-level `extensions` field on `dapp_ready`/`wallet_ready`, reassembly semantics |
|
|
| `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/`).
|