kaspa-wallet-standard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Pearce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# Kaspa Wallet Standard
+
+**A proposed standard for dApp↔wallet interoperability on Kaspa.** One tiny, zero-dependency handshake so
+any dApp can find any wallet — and any wallet can join every dApp — without either side hardcoding the
+other. Inspired by Ethereum's [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) and Solana's
+[Wallet Standard](https://github.com/wallet-standard/wallet-standard).
+
+> **Status: proposed / draft**, open for community adoption and headed for a [KIP](https://github.com/kaspanet/kips).
+> The full specification is in **[SPEC.md](SPEC.md)**. The wire contract is frozen — see SPEC §7.
+
+```bash
+npm install kaspa-wallet-standard
+```
+
+## Why
+
+Today every Kaspa dApp hardcodes each wallet's injected global (`window.kasware`, `window.kastle`, …) one
+at a time, and every new wallet has to lobby every dApp to be added. This package replaces that with a
+two-event handshake: wallets **announce** themselves, dApps **request** announcements. A wallet that ships
+this appears in every adopting dApp automatically; a dApp that ships this lists every present wallet —
+including ones that didn't exist when it was built.
+
+## Wallet side — announce yourself
+
+```ts
+import { announceKaspaWallet } from 'kaspa-wallet-standard';
+
+announceKaspaWallet(
+  {
+    uuid: crypto.randomUUID(),          // fresh per page load
+    name: 'YourWallet',
+    icon: 'data:image/svg+xml;base64,…', // data: URI only
+    rdns: 'com.yourwallet',             // STABLE id — enables silent session restore after reload
+  },
+  provider,                              // your provider object (see below)
+);
+```
+
+`provider` only needs `requestAccounts()`; everything else (`getAccounts`, `getNetwork`/`switchNetwork`,
+`getPublicKey`, `signMessage`, `signPskt`, events) is optional and capability-checked by the dApp. See
+[SPEC §3](SPEC.md#3-provider-interface).
+
+### If your wallet uses a `request(method, params)` bridge
+
+Some wallets (e.g. Kastle) expose a single `request()` bridge instead of discrete methods. Wrap it in a
+thin object that satisfies the interface — a few lines:
+
+```ts
+const w = window.yourwallet; // { request(method, params), on, removeListener }
+const provider = {
+  requestAccounts: () => w.request('kas:connect').then(() => w.request('kas:get_account')).then(a => [a.address]),
+  getAccounts:     () => w.request('kas:get_account').then(a => [a.address]).catch(() => []),
+  getNetwork:      () => w.request('kas:get_network'),
+  switchNetwork:   (id) => w.request('kas:switch_network', id),
+  getPublicKey:    () => w.request('kas:get_account').then(a => a.publicKey),
+  signMessage:     (m) => w.request('kas:sign_message', m),
+  signPskt: ({ txJsonString, options }) => w.request('kas:sign_tx', {
+    networkId: /* your network id */ 'kaspa_testnet_10',
+    txJson: txJsonString,
+    scripts: options.signInputs.map(s => ({ inputIndex: s.index, scriptHex: '', signType: 'All' })),
+  }),
+  on: w.on?.bind(w),
+  removeListener: w.removeListener?.bind(w),
+};
+announceKaspaWallet(info, provider);
+```
+
+### No dependency? ~10 lines of raw JS
+
+The package is a convenience, not a requirement. The handshake is small enough to inline:
+
+```js
+const detail = Object.freeze({
+  info: Object.freeze({ uuid: crypto.randomUUID(), name: 'YourWallet', icon: 'data:…', rdns: 'com.yourwallet' }),
+  provider: window.yourwallet,
+});
+const announce = () => window.dispatchEvent(new CustomEvent('kaspa:announceProvider', { detail }));
+window.addEventListener('kaspa:requestProvider', announce);
+announce();
+```
+
+## dApp side — discover wallets
+
+```ts
+import { requestKaspaWallets } from 'kaspa-wallet-standard';
+
+const wallets = new Map(); // dedupe by rdns ?? uuid
+const unsubscribe = requestKaspaWallets(({ info, provider }) => {
+  wallets.set(info.rdns ?? info.uuid, { info, provider });
+  renderWalletPicker([...wallets.values()]); // each has info.name, info.icon, and provider
+});
+// keep the subscription alive for the page lifetime to catch late-injecting wallets
+```
+
+Then on click: `const [address] = await provider.requestAccounts();`. Capability-check optional methods
+before using them, and refuse any `info.icon` that isn't a `data:` URI.
+
+## Who's using it
+
+- **[KRON](https://kron.technology)** — native-L1 Kaspa launchpad + DEX. First production adopter;
+  consumes the discovery handshake and ships built-in adapters for KasWare and Kastle behind this
+  provider interface.
+
+Using it in your wallet or dApp? Open a PR to add yourself.
+
+## Status & contributing
+
+This is a **proposed** standard. The goal is ratification as a KIP once the handshake is proven across at
+least two independently-developed wallets. If you're a wallet or dApp author — especially if you'd want a
+field changed **before** it freezes into a KIP — please [open an issue](../../issues). See
+[SPEC.md](SPEC.md) for the full contract, security model, and versioning policy.
+
+## License
+
+[MIT](LICENSE)

package/SPEC.md

@@ -0,0 +1,144 @@
+# Kaspa Wallet Standard
+
+**Status: Proposed (draft).** This is an open proposal for how Kaspa dApps and wallets discover and talk
+to each other. It is **not** (yet) a ratified [Kaspa Improvement Proposal](https://github.com/kaspanet/kips) —
+it is offered for community adoption and feedback, with the explicit goal of becoming a KIP once it has
+proven out across independent wallets. Comments, issues, and PRs are welcome.
+
+**Version:** 0.1 · **Wire contract:** frozen (see §7).
+
+---
+
+## 1. Motivation
+
+Kaspa has several good wallets (KasWare, Kastle, and more), but **no shared way for a dApp to connect to
+them**. Today each dApp hardcodes each wallet's injected global (`window.kasware`, `window.kastle`, …)
+one at a time, and each new wallet has to lobby every dApp to add it. This is the same dead end Ethereum
+hit before [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) (a common provider shape) and
+[EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) (multi-wallet discovery), and that Solana solved with
+its [Wallet Standard](https://github.com/wallet-standard/wallet-standard).
+
+This standard removes the hardcoding on **both** sides:
+
+- A **dApp** listens for one event and shows every wallet that answers — including wallets that did not
+  exist when the dApp shipped.
+- A **wallet** dispatches one event and appears in every adopting dApp — no per-dApp integration.
+
+It has two parts: a **provider interface** (§3–4) and a **discovery handshake** (§5).
+
+## 2. Terminology
+
+- **Provider** — the object a wallet injects/exposes that a dApp calls to get accounts, network, and
+  signatures (§3).
+- **Announce** — a wallet advertising its provider via the `kaspa:announceProvider` event (§5).
+- **dApp** — any web page that wants to use a Kaspa wallet.
+- Keywords **MUST**, **SHOULD**, **MAY** are used per [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
+## 3. Provider interface
+
+A provider is an object with the following shape (TypeScript; see
+[`src/index.ts`](src/index.ts) `KaspaProvider`). Only `requestAccounts` is **mandatory**; every other
+method is **optional** and MUST be capability-checked by the dApp (`typeof p.signPskt === 'function'`).
+
+| Method | Required | Purpose |
+|---|---|---|
+| `requestAccounts(): Promise<string[]>` | **yes** | Connect (prompt if needed); resolve to authorized addresses, active first. |
+| `getAccounts(): Promise<string[]>` | no | Already-authorized accounts **without** prompting → silent session restore. |
+| `getNetwork(): Promise<string>` | no | Current network id (§6). |
+| `switchNetwork(id): Promise<void>` | no | Request a network switch. |
+| `getPublicKey(): Promise<string>` | no | Active account public key hex (compressed or x-only). |
+| `signMessage(msg): Promise<string>` | no | KIP-5 message signing → Schnorr signature hex. |
+| `signPskt({ txJsonString, options }): Promise<string>` | no | Sign specific inputs of a transaction (§4). |
+| `disconnect(origin?): Promise<void>` | no | Drop the site's authorization. |
+| `on / removeListener(event, handler)` | no | `accountsChanged`, `networkChanged`. |
+
+A wallet that implements only `requestAccounts` is valid — it will connect and display balances in a
+dApp, which simply disables features that need the missing methods.
+
+## 4. Transaction signing (`signPskt`) — fund-safety rules
+
+`signPskt(txJsonString, options)` takes a Kaspa **Safe-JSON** transaction and an `options.signInputs`
+array of `{ index, sighashType }`, and returns the re-serialized signed transaction.
+
+- The wallet **MUST** sign **only** the inputs listed in `signInputs`, and **MUST** leave all other
+  inputs untouched. Kaspa covenant transactions carry inputs that are pre-authorized by on-chain rules
+  (a curve, a pool, a presence-owned token UTXO); re-signing one corrupts the transaction.
+- The wallet **MUST** honor the requested `sighashType` (1 = `SIGHASH_ALL`) and **MUST** refuse a type
+  it does not implement rather than substitute another. A signature over the wrong sighash, or over an
+  input the dApp did not list, is a **fund-safety defect**, not an API mismatch.
+- Before enabling `signPskt`, a wallet **SHOULD** verify it against a transaction that contains **both**
+  a covenant input and a user P2PK input (e.g. a bonding-curve buy) — signing a plain send never
+  exercises the "sign only these, leave the rest" requirement.
+
+## 5. Discovery handshake
+
+Two events on `window`, mirroring EIP-6963 replay semantics:
+
+- **`kaspa:announceProvider`** — a `CustomEvent` dispatched by the **wallet**. `detail` is a **frozen**
+  `{ info, provider }` (see §5.1). MUST be dispatched on load, and re-dispatched on every
+  `kaspa:requestProvider`.
+- **`kaspa:requestProvider`** — a plain `Event` dispatched by the **dApp** to ask present wallets to
+  (re-)announce.
+
+**Sequence**
+
+1. On load, the wallet registers a `kaspa:requestProvider` listener that re-announces, then announces once.
+2. The dApp registers its `kaspa:announceProvider` listener (kept alive for the page lifetime), then
+   dispatches `kaspa:requestProvider`.
+3. Late arrival is covered from both directions: a late wallet announces unprompted on load; a late dApp's
+   request triggers a replay from every wallet already present.
+
+### 5.1 Announce payload
+
+```ts
+type KaspaProviderInfo = {
+  uuid: string;   // UUIDv4, fresh per page load — instance identity / dedupe
+  name: string;   // human label, e.g. "Kastle"
+  icon: string;   // data: URI (SVG/PNG); dApps MUST refuse remote URLs
+  rdns?: string;  // reverse-DNS id, e.g. "com.kasware" — STABLE across loads; used for session restore
+};
+type KaspaProviderDetail = { info: KaspaProviderInfo; provider: KaspaProvider };
+```
+
+- The wallet **MUST** freeze `detail` (and `detail.info`) so page scripts cannot swap the provider out.
+- The wallet **SHOULD** provide a stable `rdns`; without it a dApp cannot silently restore the session
+  after a reload (there is no stable identity to match).
+- The dApp **SHOULD** dedupe announces by `info.rdns ?? info.uuid`, first-announce-wins.
+
+## 6. Network ids
+
+Canonical strings (also exported as `KASPA_NETWORKS`):
+
+`kaspa_mainnet` · `kaspa_testnet_10` · `kaspa_testnet_11` · `kaspa_devnet`
+
+## 7. Compatibility and versioning (frozen contract)
+
+The **wire contract is frozen**: the two event names, and every field defined above, never change
+meaning or type. The standard evolves **only by adding new OPTIONAL fields/methods**. A wallet or dApp
+built against this document keeps working against every future version. Breaking changes, if ever
+unavoidable, would ship under a **new event name** — never by mutating these.
+
+## 8. Security considerations
+
+- `name`/`icon` are **display hints, not trust signals**. An announce proves a provider is *present*, not
+  that it is *who it claims to be*. dApps MUST NOT grant trust based on them, and MUST refuse non-`data:`
+  icons (a remote URL is a tracking/spoofing vector).
+- Any page script can dispatch `kaspa:announceProvider`. Treat the provider as untrusted until the user
+  explicitly connects; the connect prompt is the trust boundary.
+- The fund-safety rules in §4 are the load-bearing security property. A wallet that signs sloppily can
+  lose user funds even though the handshake itself is benign.
+
+## 9. Reference implementation & adoption
+
+- **Reference implementation:** this package (`kaspa-wallet-standard`) — `announceKaspaWallet` (wallet)
+  and `requestKaspaWallets` (dApp), plus the types above. ~70 lines, zero dependencies.
+- **First adopter:** [KRON](https://kron.technology) (native-L1 Kaspa launchpad + DEX) consumes the
+  discovery handshake in production, and ships built-in adapters for KasWare and Kastle behind the same
+  provider interface.
+
+## 10. Path to standardization
+
+This document is intended to graduate into a **KIP**. The bar we're aiming for before proposing
+ratification: the handshake proven across **at least two independently-developed wallets**, and the
+provider interface exercised by covenant-grade `signPskt` on-chain. Wallet and dApp authors who adopt it
+(or who want fields changed *before* it freezes into a KIP) are invited to open an issue.

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/** Canonical network ids used by `getNetwork()` / `switchNetwork()`. String literals are the contract;
+ *  this object is a convenience so integrators don't hand-type them. */
+declare const KASPA_NETWORKS: {
+    readonly MAINNET: "kaspa_mainnet";
+    readonly TESTNET_10: "kaspa_testnet_10";
+    readonly TESTNET_11: "kaspa_testnet_11";
+    readonly DEVNET: "kaspa_devnet";
+};
+type KaspaNetworkId = (typeof KASPA_NETWORKS)[keyof typeof KASPA_NETWORKS];
+/** Identity a wallet announces about itself. `name`/`icon` are DISPLAY hints — never trust signals. */
+type KaspaProviderInfo = {
+    /** UUIDv4, freshly generated per page load — instance identity, used only for dedupe. */
+    uuid: string;
+    /** Human-readable wallet name shown in pickers, e.g. "Kastle". */
+    name: string;
+    /** Wallet icon as a `data:` URI (SVG/PNG). dApps should refuse to render remote URLs. */
+    icon: string;
+    /** Reverse-DNS identifier, e.g. "com.kasware" — STABLE across page loads and versions. Strongly
+     *  recommended: it is what lets a dApp silently restore a session with your wallet after a reload. */
+    rdns?: string;
+};
+/** One input a wallet is asked to sign, by position. `sighashType` 1 = SIGHASH_ALL (the only value
+ *  KRON uses today); a wallet MUST refuse a type it does not implement rather than guess. */
+type KaspaSignInput = {
+    index: number;
+    sighashType: number;
+};
+/**
+ * The raw provider surface a wallet exposes. Deliberately shaped like the widely-deployed injected APIs
+ * (KasWare's `window.kasware`) so an existing wallet can usually announce its injected object as-is.
+ *
+ * Only `requestAccounts` is MANDATORY. Everything else is OPTIONAL and MUST be capability-checked by the
+ * dApp (`typeof provider.signPskt === 'function'`) — a dApp degrades gracefully (e.g. disables trading)
+ * when a method is absent, rather than refusing to list the wallet.
+ *
+ * FUND-SAFETY RULE (wallet side): `signPskt` MUST sign ONLY the inputs listed in `options.signInputs`,
+ * and MUST leave every other input untouched. Kaspa covenant transactions carry pre-authorized inputs
+ * that must NOT be re-signed; a signature over an unlisted input, or over the wrong sighash, is a
+ * fund-safety bug, not a cosmetic mismatch. See SPEC.md §"Security considerations".
+ */
+interface KaspaProvider {
+    /** Connect: prompt the user if needed; resolve to the authorized address list (active address first). */
+    requestAccounts(): Promise<string[]>;
+    /** Already-authorized accounts WITHOUT prompting (empty array if none) — enables silent session restore. */
+    getAccounts?(): Promise<string[]>;
+    /** Current network id (see {@link KaspaNetworkId}). */
+    getNetwork?(): Promise<string>;
+    switchNetwork?(networkId: string): Promise<void>;
+    /** The active account's public key hex (compressed 33-byte or x-only 32-byte — both accepted). */
+    getPublicKey?(): Promise<string>;
+    /** KIP-5 message signing; resolves to the Schnorr signature hex. */
+    signMessage?(message: string): Promise<string>;
+    /** Sign ONLY the listed inputs of a Kaspa Safe-JSON transaction and return the signed Safe JSON. */
+    signPskt?(arg: {
+        txJsonString: string;
+        options: {
+            signInputs: KaspaSignInput[];
+        };
+    }): Promise<string>;
+    disconnect?(origin?: string): Promise<void>;
+    on?(event: 'accountsChanged' | 'networkChanged', handler: (...args: any[]) => void): void;
+    removeListener?(event: string, handler: (...args: any[]) => void): void;
+}
+/** Dispatched on `window` by a dApp to ask all present wallets to (re-)announce themselves. */
+declare const KASPA_REQUEST_PROVIDER_EVENT = "kaspa:requestProvider";
+/** Dispatched on `window` by a wallet; `detail` is a frozen {@link KaspaProviderDetail}. */
+declare const KASPA_ANNOUNCE_PROVIDER_EVENT = "kaspa:announceProvider";
+/** The `detail` of a `kaspa:announceProvider` CustomEvent. */
+type KaspaProviderDetail = {
+    info: KaspaProviderInfo;
+    provider: KaspaProvider;
+};
+/**
+ * WALLET SIDE — call once when your content script loads. Announces immediately AND replays on every
+ * `kaspa:requestProvider` (so a dApp that loads after you still finds you). Returns an unsubscribe
+ * (rarely needed; e.g. extension teardown). No-op outside a window context.
+ */
+declare function announceKaspaWallet(info: KaspaProviderInfo, provider: KaspaProvider): () => void;
+/**
+ * dApp SIDE — register `onAnnounce` (fires once per announce event, including replays; dedupe by
+ * `info.rdns ?? info.uuid` yourself), then request announcements from wallets already present. Keep the
+ * subscription alive for the page lifetime to catch late-injecting wallets. Returns an unsubscribe.
+ * Malformed announces (missing identity or `requestAccounts`) are dropped, never delivered. No-op
+ * outside a window context.
+ */
+declare function requestKaspaWallets(onAnnounce: (detail: KaspaProviderDetail) => void): () => void;
+
+export { KASPA_ANNOUNCE_PROVIDER_EVENT, KASPA_NETWORKS, KASPA_REQUEST_PROVIDER_EVENT, type KaspaNetworkId, type KaspaProvider, type KaspaProviderDetail, type KaspaProviderInfo, type KaspaSignInput, announceKaspaWallet, requestKaspaWallets };

package/dist/index.js

@@ -0,0 +1,39 @@
+// src/index.ts
+var KASPA_NETWORKS = {
+  MAINNET: "kaspa_mainnet",
+  TESTNET_10: "kaspa_testnet_10",
+  TESTNET_11: "kaspa_testnet_11",
+  DEVNET: "kaspa_devnet"
+};
+var KASPA_REQUEST_PROVIDER_EVENT = "kaspa:requestProvider";
+var KASPA_ANNOUNCE_PROVIDER_EVENT = "kaspa:announceProvider";
+function announceKaspaWallet(info, provider) {
+  if (typeof window === "undefined") return () => {
+  };
+  const detail = Object.freeze({ info: Object.freeze({ ...info }), provider });
+  const announce = () => window.dispatchEvent(new CustomEvent(KASPA_ANNOUNCE_PROVIDER_EVENT, { detail }));
+  window.addEventListener(KASPA_REQUEST_PROVIDER_EVENT, announce);
+  announce();
+  return () => window.removeEventListener(KASPA_REQUEST_PROVIDER_EVENT, announce);
+}
+function requestKaspaWallets(onAnnounce) {
+  if (typeof window === "undefined") return () => {
+  };
+  const listener = (e) => {
+    const detail = e.detail;
+    if (!detail?.info?.uuid || !detail?.info?.name) return;
+    if (typeof detail.provider?.requestAccounts !== "function") return;
+    onAnnounce(detail);
+  };
+  window.addEventListener(KASPA_ANNOUNCE_PROVIDER_EVENT, listener);
+  window.dispatchEvent(new Event(KASPA_REQUEST_PROVIDER_EVENT));
+  return () => window.removeEventListener(KASPA_ANNOUNCE_PROVIDER_EVENT, listener);
+}
+export {
+  KASPA_ANNOUNCE_PROVIDER_EVENT,
+  KASPA_NETWORKS,
+  KASPA_REQUEST_PROVIDER_EVENT,
+  announceKaspaWallet,
+  requestKaspaWallets
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Kaspa Wallet Standard — reference implementation.\n//\n// A PROPOSED standard (see SPEC.md) for how a Kaspa dApp and a Kaspa wallet find and talk to each other,\n// with two parts:\n//   • Part 1 — the provider interface a wallet exposes (accounts, network, signing).\n//   • Part 2 — an EIP-6963-style discovery handshake so a dApp finds every present wallet with zero\n//     per-wallet code, and any future wallet self-registers by dispatching one event.\n//\n// This package has ZERO runtime dependencies and is safe to import in Node (all browser access is guarded).\n// The wire contract — the two event names and the existing fields below — is FROZEN: it never changes.\n// Evolution happens only by adding new OPTIONAL fields. A wallet written against this file keeps working\n// against every future version.\n\n// ============================================================================================\n// Part 1 — Provider interface\n// ============================================================================================\n\n/** Canonical network ids used by `getNetwork()` / `switchNetwork()`. String literals are the contract;\n *  this object is a convenience so integrators don't hand-type them. */\nexport const KASPA_NETWORKS = {\n  MAINNET: 'kaspa_mainnet',\n  TESTNET_10: 'kaspa_testnet_10',\n  TESTNET_11: 'kaspa_testnet_11',\n  DEVNET: 'kaspa_devnet',\n} as const;\n\nexport type KaspaNetworkId = (typeof KASPA_NETWORKS)[keyof typeof KASPA_NETWORKS];\n\n/** Identity a wallet announces about itself. `name`/`icon` are DISPLAY hints — never trust signals. */\nexport type KaspaProviderInfo = {\n  /** UUIDv4, freshly generated per page load — instance identity, used only for dedupe. */\n  uuid: string;\n  /** Human-readable wallet name shown in pickers, e.g. \"Kastle\". */\n  name: string;\n  /** Wallet icon as a `data:` URI (SVG/PNG). dApps should refuse to render remote URLs. */\n  icon: string;\n  /** Reverse-DNS identifier, e.g. \"com.kasware\" — STABLE across page loads and versions. Strongly\n   *  recommended: it is what lets a dApp silently restore a session with your wallet after a reload. */\n  rdns?: string;\n};\n\n/** One input a wallet is asked to sign, by position. `sighashType` 1 = SIGHASH_ALL (the only value\n *  KRON uses today); a wallet MUST refuse a type it does not implement rather than guess. */\nexport type KaspaSignInput = { index: number; sighashType: number };\n\n/**\n * The raw provider surface a wallet exposes. Deliberately shaped like the widely-deployed injected APIs\n * (KasWare's `window.kasware`) so an existing wallet can usually announce its injected object as-is.\n *\n * Only `requestAccounts` is MANDATORY. Everything else is OPTIONAL and MUST be capability-checked by the\n * dApp (`typeof provider.signPskt === 'function'`) — a dApp degrades gracefully (e.g. disables trading)\n * when a method is absent, rather than refusing to list the wallet.\n *\n * FUND-SAFETY RULE (wallet side): `signPskt` MUST sign ONLY the inputs listed in `options.signInputs`,\n * and MUST leave every other input untouched. Kaspa covenant transactions carry pre-authorized inputs\n * that must NOT be re-signed; a signature over an unlisted input, or over the wrong sighash, is a\n * fund-safety bug, not a cosmetic mismatch. See SPEC.md §\"Security considerations\".\n */\nexport interface KaspaProvider {\n  /** Connect: prompt the user if needed; resolve to the authorized address list (active address first). */\n  requestAccounts(): Promise<string[]>;\n  /** Already-authorized accounts WITHOUT prompting (empty array if none) — enables silent session restore. */\n  getAccounts?(): Promise<string[]>;\n  /** Current network id (see {@link KaspaNetworkId}). */\n  getNetwork?(): Promise<string>;\n  switchNetwork?(networkId: string): Promise<void>;\n  /** The active account's public key hex (compressed 33-byte or x-only 32-byte — both accepted). */\n  getPublicKey?(): Promise<string>;\n  /** KIP-5 message signing; resolves to the Schnorr signature hex. */\n  signMessage?(message: string): Promise<string>;\n  /** Sign ONLY the listed inputs of a Kaspa Safe-JSON transaction and return the signed Safe JSON. */\n  signPskt?(arg: { txJsonString: string; options: { signInputs: KaspaSignInput[] } }): Promise<string>;\n  disconnect?(origin?: string): Promise<void>;\n  on?(event: 'accountsChanged' | 'networkChanged', handler: (...args: any[]) => void): void;\n  removeListener?(event: string, handler: (...args: any[]) => void): void;\n}\n\n// ============================================================================================\n// Part 2 — Discovery handshake\n// ============================================================================================\n\n/** Dispatched on `window` by a dApp to ask all present wallets to (re-)announce themselves. */\nexport const KASPA_REQUEST_PROVIDER_EVENT = 'kaspa:requestProvider';\n/** Dispatched on `window` by a wallet; `detail` is a frozen {@link KaspaProviderDetail}. */\nexport const KASPA_ANNOUNCE_PROVIDER_EVENT = 'kaspa:announceProvider';\n\n/** The `detail` of a `kaspa:announceProvider` CustomEvent. */\nexport type KaspaProviderDetail = { info: KaspaProviderInfo; provider: KaspaProvider };\n\n/**\n * WALLET SIDE — call once when your content script loads. Announces immediately AND replays on every\n * `kaspa:requestProvider` (so a dApp that loads after you still finds you). Returns an unsubscribe\n * (rarely needed; e.g. extension teardown). No-op outside a window context.\n */\nexport function announceKaspaWallet(info: KaspaProviderInfo, provider: KaspaProvider): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const detail: KaspaProviderDetail = Object.freeze({ info: Object.freeze({ ...info }), provider });\n  const announce = () =>\n    window.dispatchEvent(new CustomEvent(KASPA_ANNOUNCE_PROVIDER_EVENT, { detail }));\n  window.addEventListener(KASPA_REQUEST_PROVIDER_EVENT, announce);\n  announce();\n  return () => window.removeEventListener(KASPA_REQUEST_PROVIDER_EVENT, announce);\n}\n\n/**\n * dApp SIDE — register `onAnnounce` (fires once per announce event, including replays; dedupe by\n * `info.rdns ?? info.uuid` yourself), then request announcements from wallets already present. Keep the\n * subscription alive for the page lifetime to catch late-injecting wallets. Returns an unsubscribe.\n * Malformed announces (missing identity or `requestAccounts`) are dropped, never delivered. No-op\n * outside a window context.\n */\nexport function requestKaspaWallets(onAnnounce: (detail: KaspaProviderDetail) => void): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const listener = (e: Event) => {\n    const detail = (e as CustomEvent<KaspaProviderDetail>).detail;\n    if (!detail?.info?.uuid || !detail?.info?.name) return;\n    if (typeof detail.provider?.requestAccounts !== 'function') return;\n    onAnnounce(detail);\n  };\n  window.addEventListener(KASPA_ANNOUNCE_PROVIDER_EVENT, listener);\n  window.dispatchEvent(new Event(KASPA_REQUEST_PROVIDER_EVENT));\n  return () => window.removeEventListener(KASPA_ANNOUNCE_PROVIDER_EVENT, listener);\n}\n"],"mappings":";AAmBO,IAAM,iBAAiB;AAAA,EAC5B,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,QAAQ;AACV;AA0DO,IAAM,+BAA+B;AAErC,IAAM,gCAAgC;AAUtC,SAAS,oBAAoB,MAAyB,UAAqC;AAChG,MAAI,OAAO,WAAW,YAAa,QAAO,MAAM;AAAA,EAAC;AACjD,QAAM,SAA8B,OAAO,OAAO,EAAE,MAAM,OAAO,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,SAAS,CAAC;AAChG,QAAM,WAAW,MACf,OAAO,cAAc,IAAI,YAAY,+BAA+B,EAAE,OAAO,CAAC,CAAC;AACjF,SAAO,iBAAiB,8BAA8B,QAAQ;AAC9D,WAAS;AACT,SAAO,MAAM,OAAO,oBAAoB,8BAA8B,QAAQ;AAChF;AASO,SAAS,oBAAoB,YAA+D;AACjG,MAAI,OAAO,WAAW,YAAa,QAAO,MAAM;AAAA,EAAC;AACjD,QAAM,WAAW,CAAC,MAAa;AAC7B,UAAM,SAAU,EAAuC;AACvD,QAAI,CAAC,QAAQ,MAAM,QAAQ,CAAC,QAAQ,MAAM,KAAM;AAChD,QAAI,OAAO,OAAO,UAAU,oBAAoB,WAAY;AAC5D,eAAW,MAAM;AAAA,EACnB;AACA,SAAO,iBAAiB,+BAA+B,QAAQ;AAC/D,SAAO,cAAc,IAAI,MAAM,4BAA4B,CAAC;AAC5D,SAAO,MAAM,OAAO,oBAAoB,+BAA+B,QAAQ;AACjF;","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "kaspa-wallet-standard",
+  "version": "0.1.0",
+  "description": "A proposed standard for dApp↔wallet interoperability on Kaspa: a provider interface plus an EIP-6963-style discovery handshake so any wallet can announce itself to any dApp. Zero dependencies.",
+  "license": "MIT",
+  "author": "Shawn Pearce",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "SPEC.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "happy-dom": "^15.11.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaspa-wallet-standard/kaspa-wallet-standard"
+  },
+  "homepage": "https://github.com/kaspa-wallet-standard/kaspa-wallet-standard#readme",
+  "bugs": {
+    "url": "https://github.com/kaspa-wallet-standard/kaspa-wallet-standard/issues"
+  },
+  "keywords": [
+    "kaspa",
+    "wallet",
+    "standard",
+    "dapp",
+    "provider",
+    "discovery",
+    "eip-6963",
+    "kip"
+  ]
+}