cruzo-web3 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# cruzo-web3
+
+Web3 addon for [cruzo](https://github.com/MaratBektemirov/cruzo): wallet connect, sign, verify, and ready-made UI components.
+
+## Install
+
+```bash
+npm install cruzo cruzo-web3
+```
+
+For mobile wallets, also install optional peer dependencies:
+
+```bash
+npm install @tonconnect/sdk @tonconnect/ui @walletconnect/ethereum-provider
+```
+
+## Public API
+
+Main entry (`cruzo-web3`):
+
+- `web3Service` — wallet connect, sign, verify, wallet picker config
+- `Web3SigningComponent`, `Web3SignerComponent` — ready-made UI
+- `ALL_BUILTIN_WALLET_SLOTS`, `isBuiltinWallet`, `isCustomWallet`
+- types: `Web3Config`, `Web3CustomProviderConfig`, `Web3WalletSlot`, `Web3WalletTarget`, …
+
+Subpath entries (side-effect imports that register components):
+
+- `cruzo-web3/components/web3-signing`
+- `cruzo-web3/components/web3-signer`
+
+```ts
+import { web3Service } from "cruzo-web3";
+import { Web3SigningComponent } from "cruzo-web3/components/web3-signing";
+import { Web3SignerComponent } from "cruzo-web3/components/web3-signer";
+```
+
+Package exports point to TypeScript sources in `lib/`. The app bundler (e.g. Vite) compiles them in dev and production — no separate build step in `cruzo-web3` is required.
+
+### App setup
+
+Import cruzo UI **styles** and register **toast** in your app entry (`main.ts`). `modal` registers automatically when you import web3 components (`Web3SignerComponent` imports `cruzo/ui-components/modal`).
+
+Use a single `cruzo` instance in the bundle — in Vite: `resolve.dedupe: ['cruzo']`.
+
+## Setup
+
+Configure `web3Service` once at app startup, before components mount.
+
+`web3Service.setup$` updates when WalletConnect Project ID, TON manifest URL, or wallet config changes — the wallet picker reacts automatically.
+
+### WalletConnect (Ethereum mobile)
+
+WalletConnect is required for **Ethereum → Mobile wallet** in the connect modal.
+
+1. Create a project at [cloud.walletconnect.com](https://cloud.walletconnect.com).
+2. Pass the Project ID to `web3Service`:
+
+```ts
+import { web3Service } from "cruzo-web3";
+
+web3Service.setWalletConnectProjectId("your_project_id");
+```
+
+With Vite:
+
+```env
+# .env
+VITE_WALLETCONNECT_PROJECT_ID=your_project_id
+```
+
+```ts
+const projectId = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID;
+
+if (projectId) {
+  web3Service.setWalletConnectProjectId(projectId);
+}
+```
+
+Without a Project ID, the **Mobile wallet (WalletConnect)** option stays disabled in the picker.
+
+### TON Connect manifest
+
+TON wallets (extension and mobile app) require a public `tonconnect-manifest.json`.
+
+1. Add the manifest file to your site root (must be reachable over HTTPS in production).
+2. Point `web3Service` to it:
+
+```ts
+web3Service.setTonManifestUrl(
+  new URL("/tonconnect-manifest.json", window.location.href).href
+);
+```
+
+Example manifest:
+
+```json
+{
+  "url": "https://cruzo.org",
+  "name": "cruzo",
+  "iconUrl": "https://cruzo.org/favicon.ico"
+}
+```
+
+- `url` — canonical app URL (production domain)
+- `name` — app name shown in the wallet
+- `iconUrl` — square icon, HTTPS
+
+Spec: [Ton Connect manifest](https://github.com/ton-blockchain/ton-connect/blob/main/spec/manifest.md)
+
+Without a manifest URL, TON wallet options stay disabled.
+
+### Custom providers (optional)
+
+```ts
+import { web3Service } from "cruzo-web3";
+
+web3Service.configure({
+  // hide built-in slots, keep only what you need
+  providers: [
+    { kind: "ethereum", transport: "extension" },
+    { kind: "ton", transport: "app" },
+  ],
+  customProviders: [
+    {
+      id: "my-wallet",
+      label: "My wallet",
+      hint: "Custom EIP-1193 bridge",
+      provider: () => myProvider,
+    },
+  ],
+});
+```
+
+### Full startup example
+
+```ts
+// web3-setup.ts
+import { web3Service } from "cruzo-web3";
+
+const walletConnectProjectId = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID;
+
+if (walletConnectProjectId) {
+  web3Service.setWalletConnectProjectId(walletConnectProjectId);
+}
+
+web3Service.setTonManifestUrl(
+  new URL("/tonconnect-manifest.json", window.location.href).href
+);
+```
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  resolve: { dedupe: ["cruzo"] },
+});
+```
+
+```ts
+// main.ts
+import "cruzo/ui-components/vars.css";
+import "cruzo/ui-components/button.css";
+import "cruzo/ui-components/modal.css";
+import "cruzo/ui-components/textarea.css";
+import "cruzo/ui-components/toast.css";
+
+import "cruzo/ui-components/toast";
+import "site/web3-setup";
+import "cruzo-web3/components/web3-signing";
+```
+
+```html
+<web3-signing-component></web3-signing-component>
+```
+
+See [cruzo-starter](https://github.com/MaratBektemirov/cruzo-starter) for a working local setup.
+
+## Components
+
+`Web3SigningComponent` — demo page with payload textarea and two signers. Syncs payload and signer state to the URL.
+
+`Web3SignerComponent` — single signer card with **Connect wallet** and **Sign payload**.
+
+On **Connect wallet**, a modal opens with available providers:
+
+| Network  | Browser extension              | Mobile app        |
+|----------|--------------------------------|-------------------|
+| Ethereum | MetaMask, Rabby, EIP-1193      | WalletConnect     |
+| TON      | Tonkeeper, other TON wallets   | Ton Connect app   |
+| Solana   | Phantom, other Solana wallets  | —                 |
+| Tron     | TronLink                       | —                 |
+
+Unavailable options are disabled (no extension installed, missing WalletConnect Project ID, or missing TON manifest).
+
+Signer state is stored in the parent bucket:
+
+```ts
+{ pubKey: PubKey | null; signed: boolean; wallet?: SignerWallet | null }
+```
+
+## `web3Service` API
+
+```ts
+// Connect / sign with a built-in wallet
+await web3Service.connectWallet("ethereum", "extension");
+await web3Service.signWallet(payload, "ethereum", "extension");
+
+// transport: "extension" | "app" | "auto"
+// "auto" picks extension if available, otherwise mobile app (Ethereum, TON)
+await web3Service.connectWallet("ton", "auto");
+
+// Injected-only shortcuts
+await web3Service.connectInjected("ethereum");
+await web3Service.signInjected(payload, "solana");
+
+// Custom provider (from web3Service.configure)
+await web3Service.connectCustom("my-wallet");
+await web3Service.signCustom(payload, "my-wallet");
+
+await web3Service.disconnect();
+
+// Verify signature (async)
+const ok = await web3Service.verifySignedContent(content, signature, pubKey);
+```
+
+Supported `wallet` / `kind` values: `"ethereum"` | `"ton"` | `"solana"` | `"tron"`.
+
+`verifySignedContent` supports:
+
+- **TON / Solana** — Ed25519 public keys
+- **Ethereum** — EVM address in `pubKey` + `personal_sign` signature (ecrecover)
+- **Tron** — base58 address in `PubKey` + `signMessageV2` signature
+- **sr25519** — not supported yet (throws `UNSUPPORTED_ALGORITHM`)
+
+`userPubKey$` — reactive pub key of the last connected wallet on `web3Service`.
+
+Also available: `detectInjectedWallets()`, `hasInjectedWallet()`, `parsePubKey()`, `isPubKey()`, `isValidPubKey()`, `useProvider()`, `useWalletProvider()`.
+
+## Typecheck
+
+```bash
+npm run typecheck
+```

package/lib/components/icons/copy-icon.component.ts

@@ -0,0 +1,14 @@
+import { AbstractComponent, componentsRegistryService } from "cruzo";
+
+export class CopyIconComponent extends AbstractComponent {
+  static selector = "copy-icon";
+
+  getHTML() {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+          <path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z"/>
+          <path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z"/>
+        </svg>`;
+  }
+}
+
+componentsRegistryService.define(CopyIconComponent);

package/lib/components/web3-signer/web3-signer.component.module.css

@@ -0,0 +1,106 @@
+.signer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s);
+  padding: var(--m);
+  border: 1px solid var(--border-dark);
+  border-radius: var(--m);
+  background: var(--surface);
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--s);
+}
+
+.title {
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.wallet {
+  margin-top: 2px;
+  font-size: 12px;
+  color: rgba(0, 0, 0, 0.55);
+}
+
+.status {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  color: rgba(0, 0, 0, 0.45);
+}
+
+.check {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border-radius: 999px;
+  border: 1px solid rgba(0, 0, 0, 0.12);
+  color: transparent;
+  font-size: 12px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.statusSigned {
+  color: #15803d;
+}
+
+.statusSigned .check {
+  border-color: #16a34a;
+  background: #dcfce7;
+  color: #15803d;
+}
+
+.pubkey {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.label {
+  font-size: 12px;
+  color: rgba(0, 0, 0, 0.55);
+}
+
+.pubkeyRow {
+  display: flex;
+  align-items: center;
+}
+
+.value {
+  flex: 1;
+  min-width: 0;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.5;
+  word-break: break-all;
+}
+
+.copyBtn {
+  width: 16px;
+  height: 16px;
+  cursor: pointer;
+}
+
+.copyBtn:hover {
+  opacity: 0.5;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--xs);
+}
+
+.error {
+  margin: 0;
+  font-size: 13px;
+  color: #b91c1c;
+}

package/lib/components/web3-signer/web3-signer.component.ts

@@ -0,0 +1,320 @@
+import styles from "./web3-signer.component.module.css";
+
+import { AbstractComponent, componentsRegistryService, routerService, toastService } from "cruzo";
+import { UI_KIT } from "cruzo/ui-components/const";
+import { ModalComponent } from "cruzo/ui-components/modal";
+import "cruzo/ui-components/toast";
+
+import { CopyIconComponent } from "../icons/copy-icon.component";
+import { Web3WalletPickerComponent } from "../web3-wallet-picker/web3-wallet-picker.component";
+import {
+  WALLET_ACTIVE_SIGNER_ID,
+  WALLET_MODAL_ID,
+  WALLET_PICKER_ID,
+  web3WalletPickerBucket,
+} from "../web3-wallet-picker/web3-wallet-picker.bucket";
+import type { SignerState, SignerWallet } from "../../types/signer-state";
+import { buildSigningPageUrl } from "../../signing-url";
+import { pubKeyToText } from "../../utils/format-pub-key";
+import { web3Service } from "../../web3.service";
+import { isCustomWallet } from "../../web3-wallet";
+
+export interface SignerConfig {
+  payload: string;
+  title: string;
+}
+
+export class Web3SignerComponent extends AbstractComponent<SignerConfig, any, SignerState> {
+  static selector = "web3-signer-component";
+
+  hasOuterBucket = true;
+  hasConfig = true;
+
+  dependencies = new Set([
+    "modal-component",
+    Web3WalletPickerComponent.selector,
+    CopyIconComponent.selector,
+  ]);
+
+  title$ = this.newRx("");
+  walletLabel$ = this.newRx("No wallet selected");
+  busy$ = this.newRx(false);
+  error$ = this.newRx("");
+  pubKeyLabel$ = this.newRx("—");
+
+  private selectedWallet: SignerWallet | null = null;
+  private walletPickEvents$ = this.newRxEventFromBucketByIndex(
+    web3WalletPickerBucket,
+    WALLET_PICKER_ID,
+    "web3WalletSelected",
+  );
+
+  constructor() {
+    super();
+
+    this.newRxFunc((events) => {
+      const event = events?.["0"];
+
+      if (!event) return;
+
+      if (web3WalletPickerBucket.getValue(WALLET_ACTIVE_SIGNER_ID) !== this.id) return;
+
+      events["0"] = null;
+      this.onWalletSelected(event.data);
+    }, this.walletPickEvents$);
+  }
+
+  getHTML() {
+    return `<div class="${styles.signer}">
+        <div class="${styles.head}">
+          <div>
+            <h3 class="${styles.title}">{{ root.title$::rx }}</h3>
+            <div class="${styles.wallet}">{{ root.walletLabel$::rx }}</div>
+          </div>
+          <span class="${styles.status} ${styles.statusSigned}"
+            attached="{{ root.state$::rx?.signed }}">
+            <span class="${styles.check}" aria-hidden="true">✓</span>
+            <span>Signed</span>
+          </span>
+          <span class="${styles.status}"
+            attached="{{ !root.state$::rx?.signed }}">
+            <span class="${styles.check}" aria-hidden="true">✓</span>
+            <span>Not signed</span>
+          </span>
+        </div>
+
+        <div class="${styles.pubkey}">
+          <span class="${styles.label}">PubKey</span>
+          <div class="${styles.pubkeyRow}">
+            <code class="${styles.value}">{{ root.pubKeyLabel$::rx }}</code>
+            <div
+              class="${styles.copyBtn}"
+              title="Copy PubKey"
+              attached="{{ root.state$::rx?.pubKey }}"
+              onclick="{{ root.copyPubKey(event.currentTarget) }}">
+              <copy-icon></copy-icon>
+            </div>
+          </div>
+        </div>
+
+        <div class="${styles.actions}">
+          <button type="button"
+            class="${UI_KIT}_button ${UI_KIT}_button-s ${UI_KIT}_button-secondary"
+            disabled="{{ root.busy$::rx }}"
+            onclick="{{ root.connect() }}">Connect wallet</button>
+          <button type="button"
+            class="${UI_KIT}_button ${UI_KIT}_button-s ${UI_KIT}_button-primary"
+            disabled="{{ root.busy$::rx || !root.state$::rx?.pubKey || root.state$::rx?.signed }}"
+            onclick="{{ root.sign(event.currentTarget) }}">Sign payload</button>
+        </div>
+
+        <p class="${styles.error}" attached="{{ root.error$::rx }}">{{ root.error$::rx }}</p>
+      </div>`;
+  }
+
+  connect() {
+    this.error$.update("");
+    web3WalletPickerBucket.setValue(WALLET_ACTIVE_SIGNER_ID, this.id);
+    ModalComponent.attach(WALLET_MODAL_ID, web3WalletPickerBucket.id);
+  }
+
+  sign(el?: Element) {
+    const payload = this.config$.actual?.payload;
+
+    if (!payload) {
+      this.error$.update("Payload is not configured");
+      return;
+    }
+
+    if (!this.state$.actual?.pubKey) {
+      this.error$.update("Connect wallet first");
+      return;
+    }
+
+    if (!this.selectedWallet) {
+      const wallet = this.state$.actual?.wallet ?? null;
+
+      if (wallet) {
+        this.selectedWallet = wallet;
+        this.walletLabel$.update(web3Service.getWalletLabel(wallet));
+      } else {
+        this.error$.update("Reconnect wallet to sign");
+        this.connect();
+        return;
+      }
+    }
+
+    const pubKey = this.state$.actual.pubKey;
+    const wallet = this.selectedWallet;
+
+    this.runWalletAction(() => {
+      const signAction = isCustomWallet(wallet)
+        ? web3Service.signCustom(payload, wallet.providerId)
+        : web3Service.signWallet(payload, wallet.kind, wallet.transport, this.getWalletOptions());
+
+      return signAction.then(() => {
+        this.outerBucket.setState(this.id, { pubKey, signed: true, wallet }, this.index);
+
+        const url = buildSigningPageUrl(
+          routerService.pathname$.actual,
+          routerService.search$.actual,
+          this.buildSigningSnapshot(),
+          routerService.isHashMode(),
+          this.config$.actual?.payload,
+        );
+
+        void this.copyText(url)
+          .then(() => {
+            toastService.show({
+              kind: "success",
+              title: "Signing successful",
+              message: "URL copied — you can send it to someone else.",
+              alignX: "center",
+              alignY: "top",
+              timeoutMs: 0,
+            });
+          })
+          .catch(() => {
+            toastService.show({
+              kind: "success",
+              title: "Signing successful",
+              message: "You can copy the page URL and send it to someone else.",
+              alignX: "center",
+              alignY: "top",
+              timeoutMs: 0,
+            });
+          });
+      });
+    });
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    this.title$.update(this.config$.actual?.title ?? this.id);
+    this.applyWalletFromState(this.state$.actual);
+
+    this.newRxFunc((state) => {
+      this.pubKeyLabel$.update(pubKeyToText(state?.pubKey ?? null));
+      this.applyWalletFromState(state);
+    }, this.state$);
+  }
+
+  copyPubKey(el?: Element) {
+    const pubKey = this.state$.actual?.pubKey;
+
+    if (!pubKey?.value) return;
+
+    void navigator.clipboard
+      .writeText(pubKeyToText(pubKey))
+      .then(() => {
+        toastService.show({
+          kind: "success",
+          message: "Public key copied",
+          element: el ?? null,
+          alignX: "right",
+          alignY: "top",
+          timeoutMs: 1600,
+        });
+      })
+      .catch(() => {
+        toastService.show({
+          kind: "error",
+          message: "Copy failed",
+          element: el ?? null,
+          alignX: "right",
+          alignY: "top",
+          timeoutMs: 2200,
+        });
+      });
+  }
+
+  private buildSigningSnapshot(): Record<string, SignerState> {
+    const snapshot: Record<string, SignerState> = {};
+
+    for (const id of Object.keys(this.outerBucket.descriptors)) {
+      snapshot[id] =
+        this.outerBucket.getState(id) ?? { pubKey: null, signed: false, wallet: null };
+    }
+
+    return snapshot;
+  }
+
+  private copyText(text: string): Promise<void> {
+    if (navigator.clipboard?.writeText) {
+      return navigator.clipboard.writeText(text).catch(() => this.copyTextFallback(text));
+    }
+
+    return this.copyTextFallback(text);
+  }
+
+  private copyTextFallback(text: string): Promise<void> {
+    const textarea = document.createElement("textarea");
+
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.left = "-9999px";
+
+    document.body.appendChild(textarea);
+    textarea.select();
+
+    try {
+      if (!document.execCommand("copy")) {
+        return Promise.reject(new Error("Copy failed"));
+      }
+
+      return Promise.resolve();
+    } finally {
+      document.body.removeChild(textarea);
+    }
+  }
+
+  private applyWalletFromState(state: SignerState | null | undefined) {
+    if (!state?.wallet) return;
+
+    this.selectedWallet = state.wallet;
+    this.walletLabel$.update(web3Service.getWalletLabel(state.wallet));
+  }
+
+  private onWalletSelected(wallet: SignerWallet) {
+    this.selectedWallet = wallet;
+    this.walletLabel$.update(web3Service.getWalletLabel(wallet));
+
+    this.runWalletAction(() => {
+      const connectAction = isCustomWallet(wallet)
+        ? web3Service.connectCustom(wallet.providerId)
+        : web3Service.connectWallet(wallet.kind, wallet.transport, this.getWalletOptions());
+
+      return connectAction.then((pubKey) => {
+        this.outerBucket.setState(this.id, { pubKey, signed: false, wallet }, this.index);
+      });
+    });
+  }
+
+  private getWalletOptions() {
+    const options: { tonManifestUrl?: string; walletConnectProjectId?: string } = {};
+    const tonManifestUrl = web3Service.getTonManifestUrl();
+    const walletConnectProjectId = web3Service.getWalletConnectProjectId();
+
+    if (tonManifestUrl) options.tonManifestUrl = tonManifestUrl;
+    if (walletConnectProjectId) options.walletConnectProjectId = walletConnectProjectId;
+
+    return options;
+  }
+
+  private runWalletAction(action: () => Promise<void>) {
+    this.error$.update("");
+    this.busy$.update(true);
+
+    action()
+      .catch((error: unknown) => {
+        this.error$.update(error instanceof Error ? error.message : String(error));
+      })
+      .finally(() => {
+        this.busy$.update(false);
+      });
+  }
+}
+
+componentsRegistryService.define(Web3SignerComponent);