diff --git a/README.md b/README.md index 3e4482b..dfc353d 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,14 @@ A tiny, framework-agnostic SDK for **Dusk wallet discovery + dApp integration**. - Includes an **optional connect modal** (conceptually similar to a very small Reown/AppKit) - Includes an optional **connect button** (``) for drop-in UI -This SDK targets the wallet provider described in the -[Dusk Wallet provider API](https://github.com/dusk-network/wallet/blob/main/docs/provider-api.md). -The discovery protocol itself is specified in [docs/wallet-discovery.md](./docs/wallet-discovery.md). -If you're implementing a wallet, start with -[docs/wallet-implementer.md](./docs/wallet-implementer.md). +Canonical v0.1 docs: + +- Provider API: [dusk-network/wallet docs/provider-api.md](https://github.com/dusk-network/wallet/blob/main/docs/provider-api.md) +- Discovery protocol: [docs/wallet-discovery.md](./docs/wallet-discovery.md) +- Connect SDK usage: this README +- Wallet implementer guidance: [docs/wallet-implementer.md](./docs/wallet-implementer.md) +- Security/threat model: [dusk-network/wallet docs/SECURITY.md](https://github.com/dusk-network/wallet/blob/main/docs/SECURITY.md) +- v0.1 release checklist: [docs/RELEASE_CHECKLIST_v0.1.md](./docs/RELEASE_CHECKLIST_v0.1.md) Wallet discovery is **event-based**, not singleton-based: @@ -508,7 +511,11 @@ Example (served from your own site): console.log("Dusk Wallet not installed"); } else { await wallet.connect(); - await wallet.sendTransfer({ to: "", amount: parseDuskToLux("1") }); + await wallet.sendTransfer({ + privacy: "public", + to: "", + amount: parseDuskToLux("1"), + }); } ``` diff --git a/docs/RELEASE_CHECKLIST_v0.1.md b/docs/RELEASE_CHECKLIST_v0.1.md new file mode 100644 index 0000000..89c4909 --- /dev/null +++ b/docs/RELEASE_CHECKLIST_v0.1.md @@ -0,0 +1,36 @@ +# v0.1 Release Checklist + +This is the canonical Dusk Wallet + Connect v0.1 release checklist. It links to +the owner docs instead of restating their full specifications. + +## Canonical Docs + +- [ ] Wallet provider API is current in `dusk-network/wallet/docs/provider-api.md`. +- [ ] Discovery protocol is current in `dusk-network/connect/docs/wallet-discovery.md`. +- [ ] Connect SDK usage is current in `dusk-network/connect/README.md`. +- [ ] Wallet implementer guidance is current in `dusk-network/connect/docs/wallet-implementer.md`. +- [ ] Security/threat model is current in `dusk-network/wallet/docs/SECURITY.md`. +- [ ] Vulnerability reporting contact or private reporting instructions are present and non-placeholder in `dusk-network/wallet/docs/SECURITY.md`. + +## Provider Surface + +- [ ] Public docs use `dusk_requestProfiles`, `dusk_profiles`, and `profilesChanged`. +- [ ] `shieldedAddress` is documented as present only after explicit approval. +- [ ] Deprecated account-style APIs are absent from v0.1 examples or clearly marked deprecated. +- [ ] Wallet `providerSurface` constants, provider docs, Connect README, and conformance tests agree on RPC methods. +- [ ] Error codes, permissions, limits, and event names match the wallet provider API. + +## Verification + +- [ ] Wallet conformance tests pass. +- [ ] Connect conformance tests pass. +- [ ] Wallet build passes for supported extension targets. +- [ ] Connect build passes and generated types match source. +- [ ] Remaining v0.1 ambiguities are listed in the release notes or final audit report. + +## Release Hygiene + +- [ ] Version numbers and package metadata match the intended v0.1 release. +- [ ] Published package contents and extension artifacts are validated from clean builds. +- [ ] Dependency update and security advisory PRs are triaged before release tagging. +- [ ] Vulnerability reporting instructions are checked after branch/tag publication. diff --git a/docs/wallet-discovery.md b/docs/wallet-discovery.md index b5b8beb..990ffb0 100644 --- a/docs/wallet-discovery.md +++ b/docs/wallet-discovery.md @@ -1,6 +1,9 @@ # Dusk Wallet Discovery Standard -This document defines the canonical browser discovery flow for Dusk wallets. +This document is the canonical browser discovery protocol for Dusk wallets. +It deliberately does not duplicate the provider RPC specification. The +provider API is owned by +[dusk-network/wallet docs/provider-api.md](https://github.com/dusk-network/wallet/blob/main/docs/provider-api.md). If you want an implementer-oriented walkthrough with a minimal provider fixture, see [wallet-implementer.md](./wallet-implementer.md). @@ -78,9 +81,17 @@ Expected semantics: Wallets should keep `uuid` stable across page loads and product versions. dApps should de-duplicate discovered wallets by `uuid`. -## Provider Contract +## Provider Summary -The announced `provider` should expose the Dusk provider API: +Discovery only hands the dApp a provider object. The current v0.1 provider +identity model is profile-based: + +- connect with `dusk_requestProfiles` +- read current grants with `dusk_profiles` +- listen for `profilesChanged` +- request a `shieldedAddress` only through explicit user approval + +The provider should expose: - `request({ method, params })` - `on`, `once`, `off`, `removeListener`, `removeAllListeners` @@ -90,21 +101,9 @@ The announced `provider` should expose the Dusk provider API: - `isAuthorized` - `isDusk === true` -RPC methods remain Dusk-prefixed: - -- `dusk_getCapabilities` -- `dusk_requestProfiles` -- `dusk_profiles` -- `dusk_requestShieldedAddress` -- `dusk_chainId` -- `dusk_switchNetwork` -- `dusk_getPublicBalance` -- `dusk_estimateGas` -- `dusk_sendTransaction` -- `dusk_watchAsset` -- `dusk_signMessage` -- `dusk_signAuth` -- `dusk_disconnect` +See the wallet repo's +[provider API](https://github.com/dusk-network/wallet/blob/main/docs/provider-api.md) +for the canonical method, event, error, permission, and limit definitions. ## Selection Rules diff --git a/docs/wallet-implementer.md b/docs/wallet-implementer.md index ab9770e..116e1d5 100644 --- a/docs/wallet-implementer.md +++ b/docs/wallet-implementer.md @@ -1,7 +1,15 @@ # Dusk Wallet Implementer Guide This guide is for wallet teams that want to expose a Dusk provider compatible -with `@dusk-network/connect`. +with `@dusk-network/connect` and the v0.1 Dusk Wallet provider API. + +Canonical source ownership: + +- Discovery protocol: [wallet-discovery.md](./wallet-discovery.md) +- Provider API: [dusk-network/wallet docs/provider-api.md](https://github.com/dusk-network/wallet/blob/main/docs/provider-api.md) +- Security/threat model: [dusk-network/wallet docs/SECURITY.md](https://github.com/dusk-network/wallet/blob/main/docs/SECURITY.md) +- Runnable SDK fixture: `examples/reference-wallet/` +- SDK conformance coverage: `src/wallet-implementer.integration.test.ts` Discovery is event-based: @@ -56,9 +64,10 @@ type DuskProfile = { }; ``` -## RPC Methods +## RPC Method Summary -Wallets should expose the Dusk Send provider methods: +The wallet repo's provider API is the canonical source for method parameters, +permissions, errors, and limits. Wallets should expose these v0.1 methods: - `dusk_getCapabilities` - `dusk_requestProfiles` diff --git a/src/discovery.conformance.test.ts b/src/discovery.conformance.test.ts index a391c9a..0ca8d30 100644 --- a/src/discovery.conformance.test.ts +++ b/src/discovery.conformance.test.ts @@ -36,6 +36,19 @@ function extractSectionBacktickedBullets(markdown: string, sectionTitle: string) return out; } +function extractCallObjectArgs(source: string, callName: string): string[] { + const out: string[] = []; + const re = new RegExp(`${callName}\\s*\\(\\s*\\{([\\s\\S]*?)\\}\\s*\\)`, "g"); + + for (;;) { + const match = re.exec(source); + if (!match) break; + out.push(match[1] ?? ""); + } + + return out; +} + describe("Discovery Conformance", () => { it("docs/wallet-discovery.md matches exported discovery events and info fields", async () => { const docPath = path.resolve(process.cwd(), "docs", "wallet-discovery.md"); @@ -88,4 +101,27 @@ describe("Discovery Conformance", () => { } } }); + + it("README documents the canonical v0.1 doc owners", async () => { + const readmePath = path.resolve(process.cwd(), "README.md"); + const md = await readFile(readmePath, "utf8"); + + expect(md).toContain("Provider API"); + expect(md).toContain("Discovery protocol"); + expect(md).toContain("Connect SDK usage"); + expect(md).toContain("Wallet implementer guidance"); + expect(md).toContain("Security/threat model"); + expect(md).toContain("v0.1 release checklist"); + }); + + it("README sendTransfer examples include required transfer privacy", async () => { + const readmePath = path.resolve(process.cwd(), "README.md"); + const md = await readFile(readmePath, "utf8"); + const examples = extractCallObjectArgs(md, "sendTransfer"); + + expect(examples.length).toBeGreaterThan(0); + for (const example of examples) { + expect(example, example).toMatch(/\bprivacy\s*:\s*["'](?:public|shielded)["']/); + } + }); });