@tangle-network/blueprint-ui 0.4.0 → 0.5.0

package/src/iframe/tangleIframeClient.ts

@@ -14,6 +14,7 @@ import {
   NO_WALLET_ADDRESS,
   TANGLE_IFRAME_PROTOCOL_VERSION,
   type CallJobRequest,
+  type ChainContext,
   type JobInputs,
   type JobResultEvent,
   type JobResultStatus,
@@ -21,6 +22,7 @@ import {
   type ServiceContextBroadcast,
   type ServiceContextJob,
   type ServiceContextOperator,
+  type SignTypedDataRequest,
 } from '../wallet/parentBridgeProtocol';
 
 export type WalletSnapshot = {
@@ -35,6 +37,9 @@ export type ServiceSnapshot = {
   readonly operators: readonly ServiceContextOperator[];
   readonly jobs: readonly ServiceContextJob[];
   readonly mode: string | null;
+  /** Chain context broadcast by the parent — drives `useTanglePublicClient`.
+   * `null` when the parent hasn't sent one (older parent or dev mode). */
+  readonly chain: ChainContext | null;
 };
 
 export type JobInvocation = {
@@ -91,6 +96,7 @@ const NULL_SERVICE: ServiceSnapshot = {
   operators: [],
   jobs: [],
   mode: null,
+  chain: null,
 };
 
 type PendingJob = {
@@ -188,6 +194,31 @@ export class TangleIframeClient {
     );
   }
 
+  /**
+   * EIP-712 typed-data signing. The parent renders the typed-data fields in
+   * its approval modal; the user audits what they're signing. Use for
+   * operator envelopes, off-chain attestations, anything that needs a
+   * signature outside the standard blueprint-job RFQ flow.
+   *
+   * Shape mirrors viem's `signTypedData` argument. Do not include the
+   * EIP712Domain entry in `types` — the parent injects it from `domain`.
+   */
+  async signTypedData(args: {
+    domain: SignTypedDataRequest['domain'];
+    types: SignTypedDataRequest['types'];
+    primaryType: string;
+    message: Readonly<Record<string, unknown>>;
+  }): Promise<Hex> {
+    await this.ensureBootstrapped();
+    return this.dispatchWallet('tangle.app.signTypedData', {
+      chainId: this.wallet.chainId ?? 0,
+      domain: args.domain,
+      types: args.types,
+      primaryType: args.primaryType,
+      message: args.message,
+    }).then((data) => (data as { signature: Hex }).signature);
+  }
+
   // ── Job invocation ──────────────────────────────────────────────────────
 
   /**
@@ -312,6 +343,7 @@ export class TangleIframeClient {
     kind:
       | 'tangle.app.signMessage'
       | 'tangle.app.signTransaction'
+      | 'tangle.app.signTypedData'
       | 'tangle.app.switchChain',
     payload: Record<string, unknown>,
   ): Promise<unknown> {
@@ -323,6 +355,7 @@ export class TangleIframeClient {
         {
           'tangle.app.signMessage': 'tangle.app.signMessageResult',
           'tangle.app.signTransaction': 'tangle.app.signTransactionResult',
+          'tangle.app.signTypedData': 'tangle.app.signTypedDataResult',
           'tangle.app.switchChain': 'tangle.app.switchChainResult',
         } as const
       )[kind];
@@ -407,6 +440,7 @@ export class TangleIframeClient {
       operators: broadcast.operators,
       jobs: broadcast.jobs,
       mode: broadcast.mode,
+      chain: broadcast.chain ?? null,
     };
     this.service = next;
     this.emit('service', next);

package/src/iframe/testing.tsx

@@ -39,6 +39,7 @@ export type MockServiceInput = Partial<{
   operators: readonly ServiceContextOperator[];
   jobs: readonly ServiceContextJob[];
   mode: string | null;
+  chain: import('../wallet/parentBridgeProtocol').ChainContext | null;
 }>;
 
 /**
@@ -80,6 +81,16 @@ export function mockServiceContext(
         { index: 0, name: 'invoke' },
       ],
     mode: input.mode ?? null,
+    chain:
+      input.chain === undefined
+        ? {
+            id: 84532,
+            name: 'Base Sepolia',
+            rpcUrl: 'https://sepolia.base.org',
+            blockExplorerUrl: 'https://sepolia.basescan.org',
+            nativeCurrency: { name: 'Sepolia Ether', symbol: 'ETH', decimals: 18 },
+          }
+        : input.chain,
   };
 }
 
@@ -170,6 +181,9 @@ export const TangleParentHarness: FC<HarnessProps> = ({
         operators: currentService.operators,
         jobs: currentService.jobs,
         mode: currentService.mode,
+        ...(currentService.chain !== null
+          ? { chain: currentService.chain }
+          : {}),
       };
       reply(broadcastMsg);
       // Also broadcast wallet — combined into accountChanged + chainChanged.
@@ -279,6 +293,22 @@ export const TangleParentHarness: FC<HarnessProps> = ({
           });
           return;
         }
+        case 'tangle.app.signTypedData': {
+          if (typeof message.correlationId !== 'string') return;
+          // The harness signs deterministically — production parents show
+          // an approval modal first. Tests that need to assert the
+          // typed-data payload should inspect callLog (extend later if
+          // needed) or pass a custom onSignTypedData handler.
+          reply({
+            kind: 'tangle.app.signTypedDataResult',
+            correlationId: message.correlationId,
+            ok: true,
+            data: {
+              signature: ('0x' + '11'.repeat(65)) as `0x${string}`,
+            },
+          });
+          return;
+        }
         case 'tangle.app.signTransaction': {
           if (typeof message.correlationId !== 'string') return;
           reply({
@@ -350,6 +380,9 @@ export const TangleParentHarness: FC<HarnessProps> = ({
           operators: currentService.operators,
           jobs: currentService.jobs,
           mode: currentService.mode,
+          ...(currentService.chain !== null
+            ? { chain: currentService.chain }
+            : {}),
         },
         origin: HARNESS_ORIGIN,
       }),

package/src/wallet/index.ts

@@ -54,6 +54,7 @@ export {
   type AccountChanged,
   type CallJobRequest,
   type ChainChanged,
+  type ChainContext,
   type HandshakeAck,
   type HandshakeRequest,
   type IframeRequest,
@@ -70,6 +71,8 @@ export {
   type SignMessageResult,
   type SignTransactionRequest,
   type SignTransactionResult,
+  type SignTypedDataRequest,
+  type SignTypedDataResult,
   type SwitchChainRequest,
   type SwitchChainResult,
 } from './parentBridgeProtocol';

package/src/wallet/parentBridgeProtocol.ts

@@ -42,6 +42,37 @@ export type SignTransactionRequest = {
   value?: string;
 };
 
+// EIP-712 typed-data signing for publishers that need to sign custom message
+// shapes — operator envelopes, off-chain attestations, claim proofs, etc.
+// The parent renders the typed-data fields in its approval modal so the user
+// can audit what they're signing. Iframes never see the wallet's signing key
+// or private state.
+//
+// Shape mirrors viem's `signTypedData` argument: `domain` + `types` (without
+// the EIP712Domain entry — viem injects it) + `primaryType` + `message`.
+// Validation on the parent side rejects payloads that are obviously
+// malformed (missing primaryType, types map empty, etc.) but does NOT
+// re-shape the message — the user is the one who decides whether to sign.
+export type SignTypedDataRequest = {
+  kind: 'tangle.app.signTypedData';
+  correlationId: string;
+  chainId: number;
+  domain: Readonly<{
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: Address;
+    salt?: Hex;
+  }>;
+  /** EIP-712 types map; do NOT include the EIP712Domain entry (the parent
+   * injects it derived from `domain`). */
+  types: Readonly<Record<string, ReadonlyArray<{ name: string; type: string }>>>;
+  /** Top-level type name in `types` whose values appear in `message`. */
+  primaryType: string;
+  /** The actual typed-data values. Shape matches `types[primaryType]`. */
+  message: Readonly<Record<string, unknown>>;
+};
+
 // ─── Parent → Iframe messages ────────────────────────────────────────────────
 
 export type HandshakeAck = {
@@ -71,6 +102,10 @@ export type SignTransactionResult = {
   kind: 'tangle.app.signTransactionResult';
 } & ResultEnvelope<{ txHash: Hex }>;
 
+export type SignTypedDataResult = {
+  kind: 'tangle.app.signTypedDataResult';
+} & ResultEnvelope<{ signature: Hex }>;
+
 export type AccountChanged = {
   kind: 'tangle.app.accountChanged';
   account: Address | null;
@@ -105,6 +140,30 @@ export type ServiceContextJob = {
   readonly inputSchema?: unknown;
 };
 
+/**
+ * Chain configuration the parent broadcasts to the iframe along with
+ * service context. Iframes use this to build a `viem` public client for
+ * READ-ONLY queries (`useTanglePublicClient` is the convenience hook).
+ *
+ * Iframes can ignore this and roll their own RPC config — particularly
+ * when they need to read from chains OTHER than the active one (e.g. a
+ * trading dapp pulling oracle data from mainnet while the active service
+ * lives on Base Sepolia). The injected client is a hint, not a constraint.
+ *
+ * `rpcUrl` is the public RPC the parent uses, NOT a wallet RPC. Iframes
+ * cannot sign or submit with this URL; signing always routes upstream via
+ * the bridge.
+ */
+export type ChainContext = {
+  readonly id: number;
+  readonly name: string;
+  readonly rpcUrl: string;
+  /** Block-explorer base URL — useful for rendering tx links. */
+  readonly blockExplorerUrl?: string;
+  /** Native currency metadata for cost displays. */
+  readonly nativeCurrency?: { readonly name: string; readonly symbol: string; readonly decimals: number };
+};
+
 export type ServiceContextBroadcast = {
   kind: 'tangle.app.serviceContext';
   readonly blueprintId: string;
@@ -112,6 +171,10 @@ export type ServiceContextBroadcast = {
   readonly operators: readonly ServiceContextOperator[];
   readonly jobs: readonly ServiceContextJob[];
   readonly mode: string | null;
+  /** Active chain the parent is connected to; iframes can build a viem
+   * publicClient against this for convenience. Optional for backwards
+   * compatibility with parents that haven't been upgraded yet. */
+  readonly chain?: ChainContext;
 };
 
 // ─── Job invocation (iframe ↔ parent) ────────────────────────────────────────
@@ -161,6 +224,7 @@ export type ParentMessage =
   | SwitchChainResult
   | SignMessageResult
   | SignTransactionResult
+  | SignTypedDataResult
   | AccountChanged
   | ChainChanged
   | ServiceContextBroadcast
@@ -172,6 +236,7 @@ export type IframeRequest =
   | SwitchChainRequest
   | SignMessageRequest
   | SignTransactionRequest
+  | SignTypedDataRequest
   | CallJobRequest;
 
 // The zero address used by the parent when no wallet is connected. The parent

package/dist/chunk-BLXSBQU4.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/wallet/detectParentOrigin.ts","../src/wallet/parentBridgeProtocol.ts"],"sourcesContent":["// Determine which origin to trust as the parent dapp.\n//\n// `document.referrer` is the *initial* embedder — it's set when the iframe is\n// first loaded and survives reloads (though it can be cleared by `referrerpolicy`\n// or by the embedder). The Tangle Cloud iframe wrapper deliberately omits\n// `referrerpolicy=\"no-referrer\"` so we get the embedder's origin here.\n//\n// We compare it against an allowlist of known Tangle Cloud origins. If it\n// matches, that's the parent. Otherwise the iframe is being loaded directly\n// (standalone domain visit, dev server, untrusted embedder) and the bridge\n// stays disabled — the app falls back to its normal injected/WC wallet path.\n\n/**\n * Default Tangle Cloud origins. Consumers (agent-sandbox UI,\n * trading-arena, future iframe blueprints) pass app-specific additions\n * via `extraOrigins` rather than mutating this list.\n */\nexport const TANGLE_CLOUD_ORIGINS_DEFAULT = Object.freeze([\n  'https://cloud.tangle.tools',\n  'https://develop.cloud.tangle.tools',\n  // Local dev (Vite default port for tangle-cloud + Netlify dev preview).\n  'http://localhost:4300',\n  'http://localhost:8888',\n] as const);\n\nfunction originFromReferrer(): string | null {\n  if (typeof document === 'undefined') return null;\n  const ref = document.referrer;\n  if (!ref) return null;\n  try {\n    return new URL(ref).origin;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Returns the parent origin to bridge to, or null when no trusted parent is\n * detected. Caller should skip installing the bridge connector when this\n * returns null.\n *\n * `extraOrigins` is the application's escape hatch for staging or dev\n * deploys not covered by the default list. The library deliberately does\n * not read environment variables itself (consumers may bundle for non-Vite\n * runtimes); the consuming app threads `import.meta.env.VITE_*` or\n * `process.env.*` in itself.\n *\n * Falls back to a `?parent=<origin>` query parameter when no referrer is\n * present (some browsers strip referrer from cross-origin loads). Useful\n * for dev embedding flows.\n */\nexport function detectTangleCloudParentOrigin(\n  options: { extraOrigins?: readonly string[] } = {},\n): string | null {\n  if (typeof window === 'undefined' || window.parent === window) {\n    return null;\n  }\n  const allowlist = new Set<string>([\n    ...TANGLE_CLOUD_ORIGINS_DEFAULT,\n    ...(options.extraOrigins ?? []),\n  ]);\n  const referrerOrigin = originFromReferrer();\n  if (referrerOrigin && allowlist.has(referrerOrigin)) {\n    return referrerOrigin;\n  }\n  try {\n    const url = new URL(window.location.href);\n    const explicit = url.searchParams.get('parent');\n    if (explicit && allowlist.has(explicit)) return explicit;\n  } catch {\n    // ignore\n  }\n  return null;\n}\n","// Tangle Cloud iframe ↔ parent dapp protocol — must mirror the parent's\n// spec at `apps/tangle-cloud/src/blueprintApps/iframe/protocol.ts`. Bump the\n// version constant in lockstep when either side adds a request kind.\n\nimport type { Address, Hex } from 'viem';\n\nexport const TANGLE_IFRAME_PROTOCOL_VERSION = '1' as const;\nexport const TANGLE_IFRAME_PROTOCOL_PREFIX = 'tangle.app.';\n\n// ─── Iframe → Parent requests ────────────────────────────────────────────────\n\nexport type HandshakeRequest = {\n  kind: 'tangle.app.handshake';\n  appId: string;\n  version: typeof TANGLE_IFRAME_PROTOCOL_VERSION;\n};\n\nexport type ReadAccountRequest = {\n  kind: 'tangle.app.readAccount';\n  correlationId: string;\n};\n\nexport type SwitchChainRequest = {\n  kind: 'tangle.app.switchChain';\n  correlationId: string;\n  chainId: number;\n};\n\nexport type SignMessageRequest = {\n  kind: 'tangle.app.signMessage';\n  correlationId: string;\n  chainId: number;\n  message: string;\n};\n\nexport type SignTransactionRequest = {\n  kind: 'tangle.app.signTransaction';\n  correlationId: string;\n  chainId: number;\n  to: Address;\n  data: Hex;\n  value?: string;\n};\n\n// ─── Parent → Iframe messages ────────────────────────────────────────────────\n\nexport type HandshakeAck = {\n  kind: 'tangle.app.handshakeAck';\n  appId: string;\n  protocolVersion: typeof TANGLE_IFRAME_PROTOCOL_VERSION;\n};\n\nexport type ResultEnvelope<T> = { correlationId: string } & (\n  | { ok: true; data: T }\n  | { ok: false; error: string }\n);\n\nexport type ReadAccountResult = {\n  kind: 'tangle.app.readAccountResult';\n} & ResultEnvelope<{ account: Address; chainId: number }>;\n\nexport type SwitchChainResult = {\n  kind: 'tangle.app.switchChainResult';\n} & ResultEnvelope<{ chainId: number }>;\n\nexport type SignMessageResult = {\n  kind: 'tangle.app.signMessageResult';\n} & ResultEnvelope<{ signature: Hex }>;\n\nexport type SignTransactionResult = {\n  kind: 'tangle.app.signTransactionResult';\n} & ResultEnvelope<{ txHash: Hex }>;\n\nexport type AccountChanged = {\n  kind: 'tangle.app.accountChanged';\n  account: Address | null;\n};\n\nexport type ChainChanged = {\n  kind: 'tangle.app.chainChanged';\n  chainId: number;\n};\n\n// ─── Service context (parent → iframe) ──────────────────────────────────────\n//\n// Iframe blueprints embedded by Tangle Cloud need to know which service +\n// blueprint they're rendering for, plus which operators are quoted. The\n// parent broadcasts this on mount and on every change (mode picker swap,\n// new service activation, operator delta). The iframe just reads — it\n// doesn't query the chain itself.\n//\n// The thin-iframe SDK exposes this as `useTangleService()`. Iframes that\n// use the full wagmi connector path can still listen to `serviceContext`\n// for routing convenience.\n\nexport type ServiceContextOperator = {\n  readonly address: Address;\n  readonly rpcAddress: string | undefined;\n  readonly status: 'active' | 'inactive' | 'unknown';\n};\n\nexport type ServiceContextJob = {\n  readonly index: number;\n  readonly name: string;\n  readonly inputSchema?: unknown;\n};\n\nexport type ServiceContextBroadcast = {\n  kind: 'tangle.app.serviceContext';\n  readonly blueprintId: string;\n  readonly serviceId: string | null;\n  readonly operators: readonly ServiceContextOperator[];\n  readonly jobs: readonly ServiceContextJob[];\n  readonly mode: string | null;\n};\n\n// ─── Job invocation (iframe ↔ parent) ────────────────────────────────────────\n//\n// Instead of the iframe wiring up its own EIP-712 quote / sign / submit\n// flow, it sends a single CallJob request upstream. The parent does the\n// whole dance (fetch RFQ quote, build typed data, request user signature,\n// submit on-chain) and streams results back. The iframe never touches\n// chain logic.\n\nexport type JobInputs = Readonly<Record<string, unknown>>;\n\nexport type CallJobRequest = {\n  kind: 'tangle.app.callJob';\n  correlationId: string;\n  /** Job index within the blueprint, e.g. 0 for the primary entry-point. */\n  jobIndex: number;\n  /** Free-form inputs validated by the parent against the on-chain ABI. */\n  inputs: JobInputs;\n  /**\n   * Whether the publisher wants intermediate progress (streaming chunks)\n   * or just the terminal result. Streaming jobs (LLM generation, video\n   * encode) opt in; one-shots (embeddings, classifications) don't.\n   */\n  stream?: boolean;\n};\n\nexport type JobResultStatus = 'pending' | 'streaming' | 'success' | 'error';\n\nexport type JobResultEvent = {\n  kind: 'tangle.app.jobResult';\n  correlationId: string;\n  status: JobResultStatus;\n  /** Present on `streaming` and `success`. Shape is publisher-defined. */\n  data?: unknown;\n  /** Present on `streaming` only — incremental chunk for live UI. */\n  chunk?: unknown;\n  /** Present on `error`. Human-readable. */\n  error?: string;\n  /** Optional progress metadata (e.g. `{ percent: 0.42, eta_ms: 8000 }`). */\n  progress?: { readonly percent?: number; readonly eta_ms?: number };\n};\n\nexport type ParentMessage =\n  | HandshakeAck\n  | ReadAccountResult\n  | SwitchChainResult\n  | SignMessageResult\n  | SignTransactionResult\n  | AccountChanged\n  | ChainChanged\n  | ServiceContextBroadcast\n  | JobResultEvent;\n\nexport type IframeRequest =\n  | HandshakeRequest\n  | ReadAccountRequest\n  | SwitchChainRequest\n  | SignMessageRequest\n  | SignTransactionRequest\n  | CallJobRequest;\n\n// The zero address used by the parent when no wallet is connected. The parent\n// always responds to readAccount with an address; this sentinel means \"no\n// wallet\" without making the response type a union of result shapes.\nexport const NO_WALLET_ADDRESS = '0x0000000000000000000000000000000000000000';\n\n/**\n * Cryptographically-random ASCII correlation id matching the parent's\n * validator regex (`/^[\\w.\\-:]+$/`, max length 128). The connector keeps a\n * Map<correlationId, Resolver> so each request resolves independently.\n */\nexport function makeCorrelationId(prefix: string): string {\n  const random =\n    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'\n      ? crypto.randomUUID()\n      : Math.random().toString(36).slice(2) + Date.now().toString(36);\n  return `${prefix}.${random}`;\n}\n"],"mappings":";AAiBO,IAAM,+BAA+B,OAAO,OAAO;AAAA,EACxD;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AACF,CAAU;AAEV,SAAS,qBAAoC;AAC3C,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,MAAM,SAAS;AACrB,MAAI,CAAC,IAAK,QAAO;AACjB,MAAI;AACF,WAAO,IAAI,IAAI,GAAG,EAAE;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAiBO,SAAS,8BACd,UAAgD,CAAC,GAClC;AACf,MAAI,OAAO,WAAW,eAAe,OAAO,WAAW,QAAQ;AAC7D,WAAO;AAAA,EACT;AACA,QAAM,YAAY,oBAAI,IAAY;AAAA,IAChC,GAAG;AAAA,IACH,GAAI,QAAQ,gBAAgB,CAAC;AAAA,EAC/B,CAAC;AACD,QAAM,iBAAiB,mBAAmB;AAC1C,MAAI,kBAAkB,UAAU,IAAI,cAAc,GAAG;AACnD,WAAO;AAAA,EACT;AACA,MAAI;AACF,UAAM,MAAM,IAAI,IAAI,OAAO,SAAS,IAAI;AACxC,UAAM,WAAW,IAAI,aAAa,IAAI,QAAQ;AAC9C,QAAI,YAAY,UAAU,IAAI,QAAQ,EAAG,QAAO;AAAA,EAClD,QAAQ;AAAA,EAER;AACA,SAAO;AACT;;;ACnEO,IAAM,iCAAiC;AACvC,IAAM,gCAAgC;AA4KtC,IAAM,oBAAoB;AAO1B,SAAS,kBAAkB,QAAwB;AACxD,QAAM,SACJ,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe,aAC1D,OAAO,WAAW,IAClB,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,SAAS,EAAE;AAClE,SAAO,GAAG,MAAM,IAAI,MAAM;AAC5B;","names":[]}