@tangle-network/blueprint-ui 0.1.2 → 0.3.1

package/dist/wallet/index.d.ts

@@ -0,0 +1,188 @@
+import * as wagmi from 'wagmi';
+import { Address, Hex } from 'viem';
+
+/**
+ * Default Tangle Cloud origins. Consumers (agent-sandbox UI,
+ * trading-arena, future iframe blueprints) pass app-specific additions
+ * via `extraOrigins` rather than mutating this list.
+ */
+declare const TANGLE_CLOUD_ORIGINS_DEFAULT: readonly ["https://cloud.tangle.tools", "https://develop.cloud.tangle.tools", "http://localhost:4300", "http://localhost:8888"];
+/**
+ * Returns the parent origin to bridge to, or null when no trusted parent is
+ * detected. Caller should skip installing the bridge connector when this
+ * returns null.
+ *
+ * `extraOrigins` is the application's escape hatch for staging or dev
+ * deploys not covered by the default list. The library deliberately does
+ * not read environment variables itself (consumers may bundle for non-Vite
+ * runtimes); the consuming app threads `import.meta.env.VITE_*` or
+ * `process.env.*` in itself.
+ *
+ * Falls back to a `?parent=<origin>` query parameter when no referrer is
+ * present (some browsers strip referrer from cross-origin loads). Useful
+ * for dev embedding flows.
+ */
+declare function detectTangleCloudParentOrigin(options?: {
+    extraOrigins?: readonly string[];
+}): string | null;
+
+type EventName = 'accountsChanged' | 'chainChanged' | 'connect' | 'disconnect' | 'message';
+type Listener = (...args: unknown[]) => void;
+type ParentBridgeOptions = {
+    /**
+     * Origin of the parent dapp that hosts this iframe. The provider posts to
+     * `window.parent` with this exact origin and rejects inbound messages from
+     * any other origin. Pass `'*'` only in development; production must pin to
+     * the real parent (`https://cloud.tangle.tools` or its develop equivalent).
+     */
+    parentOrigin: string;
+    /**
+     * Stable identifier for this iframe app. The parent includes this in the
+     * handshake ack so dev tooling can correlate logs across the two windows.
+     */
+    appId: string;
+    /**
+     * Optional ms timeout for each bridged request. Defaults to 60 seconds —
+     * long enough for a user to read + approve a signing prompt in the parent.
+     */
+    requestTimeoutMs?: number;
+};
+/**
+ * Detect iframe execution context. When this returns `false` the bridge
+ * connector should not be installed and the host app should fall back to its
+ * normal wallet config (ConnectKit + injected/walletConnect).
+ *
+ * `window.parent !== window` is the most reliable signal that works across
+ * sandbox-iframe contexts where direct property access to parent throws.
+ */
+declare function isRunningInIframe(): boolean;
+/**
+ * EIP-1193 provider backed by the Tangle Cloud iframe protocol. One instance
+ * lives per iframe app; the wagmi connector owns the singleton.
+ */
+declare class ParentBridgeProvider {
+    private readonly options;
+    private listeners;
+    private pending;
+    private cachedAccount;
+    private cachedChainId;
+    private handshakeAcked;
+    private handshakeWaiters;
+    private installed;
+    constructor(options: ParentBridgeOptions);
+    /**
+     * Wire up the global message listener and send the initial handshake.
+     * Idempotent — safe to call repeatedly during reconnect attempts.
+     */
+    install(): void;
+    uninstall(): void;
+    request(req: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on(event: EventName, listener: Listener): void;
+    removeListener(event: EventName, listener: Listener): void;
+    private postToParent;
+    private handleParentMessage;
+    private sendReadAccount;
+    private requestSignMessage;
+    private requestSignTransaction;
+    private requestSwitchChain;
+    private dispatch;
+    private resolvePending;
+    private ensureBootstrapped;
+    private updateAccount;
+    private updateChainId;
+    private emit;
+    /** Visible for tests + the connector's `getAccounts()` shortcut. */
+    getCachedAccount(): Address | null;
+    /** Visible for tests + the connector's `getChainId()` shortcut. */
+    getCachedChainId(): number | null;
+}
+
+type ParentBridgeConnectorOptions = ParentBridgeOptions;
+declare function parentBridgeConnector(options: ParentBridgeConnectorOptions): wagmi.CreateConnectorFn<ParentBridgeProvider, Record<string, unknown>, Record<string, unknown>>;
+
+declare const TANGLE_IFRAME_PROTOCOL_VERSION: "1";
+declare const TANGLE_IFRAME_PROTOCOL_PREFIX = "tangle.app.";
+type HandshakeRequest = {
+    kind: 'tangle.app.handshake';
+    appId: string;
+    version: typeof TANGLE_IFRAME_PROTOCOL_VERSION;
+};
+type ReadAccountRequest = {
+    kind: 'tangle.app.readAccount';
+    correlationId: string;
+};
+type SwitchChainRequest = {
+    kind: 'tangle.app.switchChain';
+    correlationId: string;
+    chainId: number;
+};
+type SignMessageRequest = {
+    kind: 'tangle.app.signMessage';
+    correlationId: string;
+    chainId: number;
+    message: string;
+};
+type SignTransactionRequest = {
+    kind: 'tangle.app.signTransaction';
+    correlationId: string;
+    chainId: number;
+    to: Address;
+    data: Hex;
+    value?: string;
+};
+type HandshakeAck = {
+    kind: 'tangle.app.handshakeAck';
+    appId: string;
+    protocolVersion: typeof TANGLE_IFRAME_PROTOCOL_VERSION;
+};
+type ResultEnvelope<T> = {
+    correlationId: string;
+} & ({
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+});
+type ReadAccountResult = {
+    kind: 'tangle.app.readAccountResult';
+} & ResultEnvelope<{
+    account: Address;
+    chainId: number;
+}>;
+type SwitchChainResult = {
+    kind: 'tangle.app.switchChainResult';
+} & ResultEnvelope<{
+    chainId: number;
+}>;
+type SignMessageResult = {
+    kind: 'tangle.app.signMessageResult';
+} & ResultEnvelope<{
+    signature: Hex;
+}>;
+type SignTransactionResult = {
+    kind: 'tangle.app.signTransactionResult';
+} & ResultEnvelope<{
+    txHash: Hex;
+}>;
+type AccountChanged = {
+    kind: 'tangle.app.accountChanged';
+    account: Address | null;
+};
+type ChainChanged = {
+    kind: 'tangle.app.chainChanged';
+    chainId: number;
+};
+type ParentMessage = HandshakeAck | ReadAccountResult | SwitchChainResult | SignMessageResult | SignTransactionResult | AccountChanged | ChainChanged;
+declare const NO_WALLET_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * Cryptographically-random ASCII correlation id matching the parent's
+ * validator regex (`/^[\w.\-:]+$/`, max length 128). The connector keeps a
+ * Map<correlationId, Resolver> so each request resolves independently.
+ */
+declare function makeCorrelationId(prefix: string): string;
+
+export { type AccountChanged, type ChainChanged, type HandshakeAck, type HandshakeRequest, NO_WALLET_ADDRESS, type ParentBridgeConnectorOptions, type ParentBridgeOptions, ParentBridgeProvider, type ParentMessage, type ReadAccountRequest, type ReadAccountResult, type SignMessageRequest, type SignMessageResult, type SignTransactionRequest, type SignTransactionResult, type SwitchChainRequest, type SwitchChainResult, TANGLE_CLOUD_ORIGINS_DEFAULT, TANGLE_IFRAME_PROTOCOL_PREFIX, TANGLE_IFRAME_PROTOCOL_VERSION, detectTangleCloudParentOrigin, isRunningInIframe, makeCorrelationId, parentBridgeConnector };

package/dist/wallet/index.js

@@ -0,0 +1,466 @@
+// src/wallet/detectParentOrigin.ts
+var TANGLE_CLOUD_ORIGINS_DEFAULT = Object.freeze([
+  "https://cloud.tangle.tools",
+  "https://develop.cloud.tangle.tools",
+  // Local dev (Vite default port for tangle-cloud + Netlify dev preview).
+  "http://localhost:4300",
+  "http://localhost:8888"
+]);
+function originFromReferrer() {
+  if (typeof document === "undefined") return null;
+  const ref = document.referrer;
+  if (!ref) return null;
+  try {
+    return new URL(ref).origin;
+  } catch {
+    return null;
+  }
+}
+function detectTangleCloudParentOrigin(options = {}) {
+  if (typeof window === "undefined" || window.parent === window) {
+    return null;
+  }
+  const allowlist = /* @__PURE__ */ new Set([
+    ...TANGLE_CLOUD_ORIGINS_DEFAULT,
+    ...options.extraOrigins ?? []
+  ]);
+  const referrerOrigin = originFromReferrer();
+  if (referrerOrigin && allowlist.has(referrerOrigin)) {
+    return referrerOrigin;
+  }
+  try {
+    const url = new URL(window.location.href);
+    const explicit = url.searchParams.get("parent");
+    if (explicit && allowlist.has(explicit)) return explicit;
+  } catch {
+  }
+  return null;
+}
+
+// src/wallet/parentBridgeConnector.ts
+import { createConnector } from "wagmi";
+
+// src/wallet/parentBridgeProtocol.ts
+var TANGLE_IFRAME_PROTOCOL_VERSION = "1";
+var TANGLE_IFRAME_PROTOCOL_PREFIX = "tangle.app.";
+var NO_WALLET_ADDRESS = "0x0000000000000000000000000000000000000000";
+function makeCorrelationId(prefix) {
+  const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : Math.random().toString(36).slice(2) + Date.now().toString(36);
+  return `${prefix}.${random}`;
+}
+
+// src/wallet/parentBridgeProvider.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+function isRunningInIframe() {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.parent !== void 0 && window.parent !== window;
+  } catch {
+    return true;
+  }
+}
+var ParentBridgeProvider = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  listeners = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  cachedAccount = null;
+  cachedChainId = null;
+  handshakeAcked = false;
+  handshakeWaiters = [];
+  installed = false;
+  /**
+   * Wire up the global message listener and send the initial handshake.
+   * Idempotent — safe to call repeatedly during reconnect attempts.
+   */
+  install() {
+    if (this.installed || typeof window === "undefined") return;
+    this.installed = true;
+    window.addEventListener("message", this.handleParentMessage);
+    this.postToParent({
+      kind: "tangle.app.handshake",
+      appId: this.options.appId,
+      version: TANGLE_IFRAME_PROTOCOL_VERSION
+    });
+  }
+  uninstall() {
+    if (!this.installed || typeof window === "undefined") return;
+    this.installed = false;
+    window.removeEventListener("message", this.handleParentMessage);
+    for (const [, pending] of this.pending) {
+      pending.reject(new Error("Parent bridge uninstalled"));
+    }
+    this.pending.clear();
+  }
+  // ── EIP-1193 surface ────────────────────────────────────────────────────
+  async request(req) {
+    const method = req.method;
+    const params = req.params ?? [];
+    switch (method) {
+      case "eth_chainId": {
+        await this.ensureBootstrapped();
+        return this.cachedChainId !== null ? `0x${this.cachedChainId.toString(16)}` : "0x0";
+      }
+      case "eth_accounts":
+      case "eth_requestAccounts": {
+        await this.ensureBootstrapped();
+        return this.cachedAccount !== null ? [this.cachedAccount] : [];
+      }
+      case "personal_sign": {
+        const [message, _signer] = params;
+        return this.requestSignMessage(message);
+      }
+      case "eth_signTypedData_v4": {
+        throw bridgeError(
+          4200,
+          "eth_signTypedData_v4 is not supported by the parent-bridge protocol yet."
+        );
+      }
+      case "eth_sendTransaction": {
+        const [tx] = params;
+        if (!tx?.to || !tx.data) {
+          throw bridgeError(-32602, "eth_sendTransaction requires `to` and `data`.");
+        }
+        return this.requestSignTransaction(tx);
+      }
+      case "wallet_switchEthereumChain": {
+        const [{ chainId }] = params;
+        const numeric = Number.parseInt(chainId, 16);
+        if (!Number.isFinite(numeric) || numeric <= 0) {
+          throw bridgeError(-32602, `Invalid chainId: ${chainId}`);
+        }
+        await this.requestSwitchChain(numeric);
+        return null;
+      }
+      case "wallet_addEthereumChain": {
+        throw bridgeError(
+          4200,
+          "wallet_addEthereumChain is not supported through the parent bridge."
+        );
+      }
+      default:
+        throw bridgeError(4200, `Method ${method} not supported by parent bridge.`);
+    }
+  }
+  on(event, listener) {
+    const set = this.listeners.get(event) ?? /* @__PURE__ */ new Set();
+    set.add(listener);
+    this.listeners.set(event, set);
+  }
+  removeListener(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  // ── Internal: dispatch + book-keeping ───────────────────────────────────
+  postToParent(message) {
+    if (typeof window === "undefined") return;
+    try {
+      window.parent.postMessage(message, this.options.parentOrigin);
+    } catch {
+    }
+  }
+  handleParentMessage = (event) => {
+    if (event.origin !== this.options.parentOrigin) return;
+    const data = event.data;
+    if (typeof data !== "object" || data === null) return;
+    const message = data;
+    switch (message.kind) {
+      case "tangle.app.handshakeAck":
+        this.handshakeAcked = true;
+        for (const resolve of this.handshakeWaiters) resolve();
+        this.handshakeWaiters = [];
+        this.sendReadAccount().catch(() => {
+        });
+        return;
+      case "tangle.app.readAccountResult":
+        this.resolvePending(message);
+        if (message.ok) {
+          this.updateAccount(
+            message.data.account === NO_WALLET_ADDRESS ? null : message.data.account
+          );
+          this.updateChainId(message.data.chainId);
+        }
+        return;
+      case "tangle.app.switchChainResult":
+        this.resolvePending(message);
+        if (message.ok) this.updateChainId(message.data.chainId);
+        return;
+      case "tangle.app.signMessageResult":
+      case "tangle.app.signTransactionResult":
+        this.resolvePending(message);
+        return;
+      case "tangle.app.accountChanged":
+        this.updateAccount(message.account);
+        return;
+      case "tangle.app.chainChanged":
+        this.updateChainId(message.chainId);
+        return;
+    }
+  };
+  sendReadAccount() {
+    return this.dispatch({
+      kind: "tangle.app.readAccount",
+      expectedKind: "tangle.app.readAccountResult"
+    });
+  }
+  requestSignMessage(message) {
+    const chainId = this.cachedChainId ?? 1;
+    return this.dispatch({
+      kind: "tangle.app.signMessage",
+      expectedKind: "tangle.app.signMessageResult",
+      payload: { chainId, message }
+    }).then((data) => data.signature);
+  }
+  requestSignTransaction(tx) {
+    const chainId = this.cachedChainId ?? 1;
+    const value = typeof tx.value === "string" && tx.value.startsWith("0x") ? BigInt(tx.value).toString(10) : typeof tx.value === "string" ? tx.value : void 0;
+    return this.dispatch({
+      kind: "tangle.app.signTransaction",
+      expectedKind: "tangle.app.signTransactionResult",
+      payload: {
+        chainId,
+        to: tx.to,
+        data: tx.data,
+        ...value !== void 0 ? { value } : {}
+      }
+    }).then((data) => data.txHash);
+  }
+  requestSwitchChain(chainId) {
+    return this.dispatch({
+      kind: "tangle.app.switchChain",
+      expectedKind: "tangle.app.switchChainResult",
+      payload: { chainId }
+    }).then((data) => data.chainId);
+  }
+  async dispatch(req) {
+    await this.ensureBootstrapped();
+    const correlationId = makeCorrelationId(req.kind);
+    const timeout = this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+      const timer = window.setTimeout(() => {
+        this.pending.delete(correlationId);
+        reject(bridgeError(4900, `Parent did not respond to ${req.kind} within ${timeout}ms`));
+      }, timeout);
+      this.pending.set(correlationId, {
+        resolve: (v) => {
+          window.clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          window.clearTimeout(timer);
+          reject(e);
+        },
+        expectedKind: req.expectedKind
+      });
+      this.postToParent({
+        kind: req.kind,
+        correlationId,
+        ...req.payload ?? {}
+      });
+    });
+  }
+  resolvePending(message) {
+    const entry = this.pending.get(message.correlationId);
+    if (!entry) return;
+    this.pending.delete(message.correlationId);
+    if (entry.expectedKind !== message.kind) {
+      entry.reject(
+        bridgeError(
+          -32e3,
+          `Parent replied with ${message.kind} but ${entry.expectedKind} was expected`
+        )
+      );
+      return;
+    }
+    if (message.ok) {
+      entry.resolve(message.data);
+    } else {
+      entry.reject(bridgeError(4001, message.error));
+    }
+  }
+  async ensureBootstrapped() {
+    if (this.handshakeAcked) return;
+    this.install();
+    await new Promise((resolve) => {
+      this.handshakeWaiters.push(resolve);
+      const retry = window.setInterval(() => {
+        if (this.handshakeAcked) {
+          window.clearInterval(retry);
+          return;
+        }
+        this.postToParent({
+          kind: "tangle.app.handshake",
+          appId: this.options.appId,
+          version: TANGLE_IFRAME_PROTOCOL_VERSION
+        });
+      }, 500);
+      window.setTimeout(() => window.clearInterval(retry), 1e4);
+    });
+  }
+  updateAccount(next) {
+    if (this.cachedAccount === next) return;
+    const prev = this.cachedAccount;
+    this.cachedAccount = next;
+    if (next === null && prev !== null) {
+      this.emit("disconnect");
+      this.emit("accountsChanged", []);
+    } else if (next !== null) {
+      this.emit("accountsChanged", [next]);
+      if (prev === null) {
+        this.emit("connect", { chainId: this.cachedChainId ?? 0 });
+      }
+    }
+  }
+  updateChainId(next) {
+    if (this.cachedChainId === next) return;
+    this.cachedChainId = next;
+    this.emit("chainChanged", `0x${next.toString(16)}`);
+  }
+  emit(event, ...args) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const listener of [...set]) {
+      try {
+        listener(...args);
+      } catch {
+      }
+    }
+  }
+  // ── Test seams ──────────────────────────────────────────────────────────
+  /** Visible for tests + the connector's `getAccounts()` shortcut. */
+  getCachedAccount() {
+    return this.cachedAccount;
+  }
+  /** Visible for tests + the connector's `getChainId()` shortcut. */
+  getCachedChainId() {
+    return this.cachedChainId;
+  }
+};
+function bridgeError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+// src/wallet/parentBridgeConnector.ts
+function parentBridgeConnector(options) {
+  let provider;
+  let installed = false;
+  return createConnector((config) => {
+    const ensureProvider = () => {
+      if (!provider) provider = new ParentBridgeProvider(options);
+      if (!installed) {
+        provider.install();
+        installed = true;
+        provider.on("accountsChanged", (accounts) => {
+          config.emitter.emit("change", {
+            accounts: Array.isArray(accounts) ? accounts : []
+          });
+        });
+        provider.on("chainChanged", (chainIdHex) => {
+          const chainId = typeof chainIdHex === "string" ? Number.parseInt(chainIdHex, 16) : Number(chainIdHex);
+          if (Number.isFinite(chainId)) {
+            config.emitter.emit("change", { chainId });
+          }
+        });
+        provider.on("disconnect", () => {
+          config.emitter.emit("disconnect");
+        });
+      }
+      return provider;
+    };
+    return {
+      id: "tangleParentBridge",
+      name: "Tangle Cloud",
+      type: "parentBridge",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async connect() {
+        const p = ensureProvider();
+        const accountsResult = await p.request({
+          method: "eth_requestAccounts"
+        });
+        const chainIdHex = await p.request({ method: "eth_chainId" });
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return {
+          accounts: accountsResult,
+          chainId: Number.isFinite(chainId) ? chainId : 0
+        };
+      },
+      async disconnect() {
+        if (provider) provider.uninstall();
+        installed = false;
+        provider = void 0;
+      },
+      async getAccounts() {
+        const p = ensureProvider();
+        const cached = p.getCachedAccount();
+        if (cached) return [cached];
+        const accounts = await p.request({
+          method: "eth_accounts"
+        });
+        return accounts;
+      },
+      async getChainId() {
+        const p = ensureProvider();
+        const cached = p.getCachedChainId();
+        if (cached !== null) return cached;
+        const chainIdHex = await p.request({ method: "eth_chainId" });
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return Number.isFinite(chainId) ? chainId : 0;
+      },
+      async getProvider() {
+        return ensureProvider();
+      },
+      async isAuthorized() {
+        try {
+          const p = ensureProvider();
+          const accounts = await p.request({
+            method: "eth_accounts"
+          });
+          return accounts.length > 0;
+        } catch {
+          return false;
+        }
+      },
+      async switchChain({ chainId }) {
+        const p = ensureProvider();
+        await p.request({
+          method: "wallet_switchEthereumChain",
+          params: [{ chainId: `0x${chainId.toString(16)}` }]
+        });
+        const chain = config.chains.find((c) => c.id === chainId);
+        if (!chain) {
+          throw new Error(`Chain ${chainId} not configured for this app`);
+        }
+        return chain;
+      },
+      onAccountsChanged(accounts) {
+        config.emitter.emit("change", {
+          accounts
+        });
+      },
+      onChainChanged(chainIdHex) {
+        const chainId = Number.parseInt(chainIdHex, 16);
+        if (Number.isFinite(chainId)) {
+          config.emitter.emit("change", { chainId });
+        }
+      },
+      onDisconnect() {
+        config.emitter.emit("disconnect");
+      }
+    };
+  });
+}
+export {
+  NO_WALLET_ADDRESS,
+  ParentBridgeProvider,
+  TANGLE_CLOUD_ORIGINS_DEFAULT,
+  TANGLE_IFRAME_PROTOCOL_PREFIX,
+  TANGLE_IFRAME_PROTOCOL_VERSION,
+  detectTangleCloudParentOrigin,
+  isRunningInIframe,
+  makeCorrelationId,
+  parentBridgeConnector
+};
+//# sourceMappingURL=index.js.map