@tangle-network/blueprint-ui 0.1.0

package/src/contracts/abi.ts

@@ -0,0 +1,259 @@
+/**
+ * Tangle core precompile ABIs — shared across all blueprints.
+ * Blueprint-specific ABIs (agentSandboxBlueprintAbi, tradingBlueprintAbi, etc.)
+ * stay in each consuming app.
+ */
+
+export const tangleJobsAbi = [
+  {
+    type: 'function',
+    name: 'submitJob',
+    inputs: [
+      { name: 'serviceId', type: 'uint64' },
+      { name: 'job', type: 'uint8' },
+      { name: 'args', type: 'bytes' },
+    ],
+    outputs: [{ name: 'callId', type: 'uint64' }],
+    stateMutability: 'payable',
+  },
+  {
+    type: 'event',
+    name: 'JobCalled',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'job', type: 'uint8', indexed: true },
+      { name: 'callId', type: 'uint64', indexed: true },
+      { name: 'caller', type: 'address', indexed: false },
+      { name: 'args', type: 'bytes', indexed: false },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'JobResultReceived',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'job', type: 'uint8', indexed: true },
+      { name: 'callId', type: 'uint64', indexed: true },
+      { name: 'operator', type: 'address', indexed: false },
+      { name: 'outputs', type: 'bytes', indexed: false },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'JobSubmitted',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'callId', type: 'uint64', indexed: true },
+      { name: 'jobIndex', type: 'uint8', indexed: false },
+      { name: 'caller', type: 'address', indexed: false },
+      { name: 'inputs', type: 'bytes', indexed: false },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'JobCompleted',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'callId', type: 'uint64', indexed: true },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'JobResultSubmitted',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'callId', type: 'uint64', indexed: true },
+      { name: 'operator', type: 'address', indexed: true },
+      { name: 'output', type: 'bytes', indexed: false },
+    ],
+  },
+] as const;
+
+export const tangleServicesAbi = [
+  {
+    type: 'function',
+    name: 'requestService',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64' },
+      { name: 'operators', type: 'address[]' },
+      { name: 'config', type: 'bytes' },
+      { name: 'permittedCallers', type: 'address[]' },
+      { name: 'ttl', type: 'uint64' },
+      { name: 'paymentToken', type: 'address' },
+      { name: 'paymentAmount', type: 'uint256' },
+    ],
+    outputs: [{ name: 'requestId', type: 'uint64' }],
+    stateMutability: 'payable',
+  },
+  {
+    type: 'function',
+    name: 'createServiceFromQuotes',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64' },
+      {
+        name: 'quotes',
+        type: 'tuple[]',
+        components: [
+          {
+            name: 'details',
+            type: 'tuple',
+            components: [
+              { name: 'blueprintId', type: 'uint64' },
+              { name: 'ttlBlocks', type: 'uint64' },
+              { name: 'totalCost', type: 'uint256' },
+              { name: 'timestamp', type: 'uint64' },
+              { name: 'expiry', type: 'uint64' },
+              {
+                name: 'securityCommitments',
+                type: 'tuple[]',
+                components: [
+                  {
+                    name: 'asset',
+                    type: 'tuple',
+                    components: [
+                      { name: 'kind', type: 'uint8' },
+                      { name: 'token', type: 'address' },
+                    ],
+                  },
+                  { name: 'exposureBps', type: 'uint16' },
+                ],
+              },
+            ],
+          },
+          { name: 'signature', type: 'bytes' },
+          { name: 'operator', type: 'address' },
+        ],
+      },
+      { name: 'config', type: 'bytes' },
+      { name: 'permittedCallers', type: 'address[]' },
+      { name: 'ttl', type: 'uint64' },
+    ],
+    outputs: [{ name: 'serviceId', type: 'uint64' }],
+    stateMutability: 'payable',
+  },
+  {
+    type: 'function',
+    name: 'getService',
+    inputs: [{ name: 'serviceId', type: 'uint64' }],
+    outputs: [
+      {
+        name: '',
+        type: 'tuple',
+        components: [
+          { name: 'blueprintId', type: 'uint64' },
+          { name: 'owner', type: 'address' },
+          { name: 'createdAt', type: 'uint64' },
+          { name: 'ttl', type: 'uint64' },
+          { name: 'terminatedAt', type: 'uint64' },
+          { name: 'lastPaymentAt', type: 'uint64' },
+          { name: 'operatorCount', type: 'uint32' },
+          { name: 'minOperators', type: 'uint32' },
+          { name: 'maxOperators', type: 'uint32' },
+          { name: 'membership', type: 'uint8' },
+          { name: 'pricing', type: 'uint8' },
+          { name: 'status', type: 'uint8' },
+        ],
+      },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'isServiceActive',
+    inputs: [{ name: 'serviceId', type: 'uint64' }],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'getServiceOperators',
+    inputs: [{ name: 'serviceId', type: 'uint64' }],
+    outputs: [{ name: '', type: 'address[]' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'isPermittedCaller',
+    inputs: [
+      { name: 'serviceId', type: 'uint64' },
+      { name: 'caller', type: 'address' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'ServiceRequested',
+    inputs: [
+      { name: 'requester', type: 'address', indexed: true },
+      { name: 'requestId', type: 'uint64', indexed: true },
+      { name: 'blueprintId', type: 'uint64', indexed: true },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'ServiceActivated',
+    inputs: [
+      { name: 'serviceId', type: 'uint64', indexed: true },
+      { name: 'requestId', type: 'uint64', indexed: true },
+      { name: 'blueprintId', type: 'uint64', indexed: true },
+    ],
+  },
+] as const;
+
+export const tangleOperatorsAbi = [
+  {
+    type: 'function',
+    name: 'blueprintOperatorCount',
+    inputs: [{ name: 'blueprintId', type: 'uint64' }],
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'isOperatorRegistered',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64' },
+      { name: 'operator', type: 'address' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'getOperatorPreferences',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64' },
+      { name: 'operator', type: 'address' },
+    ],
+    outputs: [
+      {
+        name: 'preferences',
+        type: 'tuple',
+        components: [
+          { name: 'ecdsaPublicKey', type: 'bytes' },
+          { name: 'rpcAddress', type: 'string' },
+        ],
+      },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'OperatorRegistered',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64', indexed: true },
+      { name: 'operator', type: 'address', indexed: true },
+      { name: 'ecdsaPublicKey', type: 'bytes', indexed: false },
+      { name: 'rpcAddress', type: 'string', indexed: false },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'OperatorUnregistered',
+    inputs: [
+      { name: 'blueprintId', type: 'uint64', indexed: true },
+      { name: 'operator', type: 'address', indexed: true },
+    ],
+  },
+] as const;

package/src/contracts/chains.ts

@@ -0,0 +1,100 @@
+import { defineChain } from 'viem';
+import { mainnet } from 'viem/chains';
+import type { Address, Chain } from 'viem';
+
+/**
+ * Resolve RPC URL for the current environment.
+ * Handles local dev (hostname swap), Vite dev proxy, and remote access.
+ */
+export function resolveRpcUrl(envUrl?: string): string {
+  const configured = envUrl ?? import.meta.env.VITE_RPC_URL ?? 'http://localhost:8545';
+  if (typeof window === 'undefined') return configured;
+  try {
+    const rpc = new URL(configured);
+    const isLocalRpc = rpc.hostname === '127.0.0.1' || rpc.hostname === 'localhost';
+    const pageHost = window.location.hostname;
+    const isLocalPage = pageHost === '127.0.0.1' || pageHost === 'localhost';
+    // Dev-mode proxy for LAN access to local RPC
+    if (isLocalRpc && !isLocalPage && import.meta.env.DEV) {
+      return `${window.location.origin}/rpc-proxy`;
+    }
+    // Non-dev LAN access: swap hostname
+    if (isLocalRpc && !isLocalPage) {
+      rpc.hostname = pageHost;
+      return rpc.toString().replace(/\/$/, '');
+    }
+  } catch {
+    // malformed
+  }
+  return configured;
+}
+
+export const rpcUrl = resolveRpcUrl();
+
+export const tangleLocal = defineChain({
+  id: Number(import.meta.env.VITE_CHAIN_ID ?? 31337),
+  name: 'Tangle Local',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: { default: { http: [rpcUrl] } },
+  blockExplorers: { default: { name: 'Explorer', url: '' } },
+  contracts: { multicall3: { address: '0xcA11bde05977b3631167028862bE2a173976CA11' } },
+});
+
+export const tangleTestnet = defineChain({
+  id: 3799,
+  name: 'Tangle Testnet',
+  nativeCurrency: { name: 'Tangle', symbol: 'tTNT', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://testnet-rpc.tangle.tools'],
+      webSocket: ['wss://testnet-rpc.tangle.tools'],
+    },
+  },
+  blockExplorers: { default: { name: 'Tangle Explorer', url: 'https://testnet-explorer.tangle.tools' } },
+  contracts: { multicall3: { address: '0xcA11bde05977b3631167028862bE2a173976CA11' } },
+});
+
+export const tangleMainnet = defineChain({
+  id: 5845,
+  name: 'Tangle',
+  nativeCurrency: { name: 'Tangle', symbol: 'TNT', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['https://rpc.tangle.tools'],
+      webSocket: ['wss://rpc.tangle.tools'],
+    },
+  },
+  blockExplorers: { default: { name: 'Tangle Explorer', url: 'https://explorer.tangle.tools' } },
+  contracts: { multicall3: { address: '0xcA11bde05977b3631167028862bE2a173976CA11' } },
+});
+
+/** Minimum required contract addresses for Tangle core hooks. */
+export interface CoreAddresses {
+  jobs: Address;
+  services: Address;
+  [key: string]: Address;
+}
+
+export interface NetworkConfig<T extends CoreAddresses = CoreAddresses> {
+  chain: Chain;
+  rpcUrl: string;
+  label: string;
+  shortLabel: string;
+  addresses: T;
+}
+
+let _networks: Record<number, NetworkConfig<any>> = {};
+
+/** Register networks with app-specific address shapes at startup. */
+export function configureNetworks<T extends CoreAddresses>(
+  nets: Record<number, NetworkConfig<T>>,
+) {
+  _networks = nets;
+}
+
+export function getNetworks<T extends CoreAddresses = CoreAddresses>(): Record<number, NetworkConfig<T>> {
+  return _networks as Record<number, NetworkConfig<T>>;
+}
+
+export { mainnet };
+export const allTangleChains = [tangleLocal, tangleTestnet, tangleMainnet] as const;

package/src/contracts/generic-encoder.ts

@@ -0,0 +1,69 @@
+import { encodeAbiParameters } from 'viem';
+import type { JobDefinition } from '../blueprints/registry';
+
+/**
+ * Generic ABI encoder for any blueprint job.
+ *
+ * Builds the ordered parameter array from:
+ *   1. contextParams (e.g. sidecar_url, sandbox_id) — prepended first
+ *   2. fields with abiType set — appended in definition order
+ *
+ * Delegates to job.customEncoder when present (for nested-struct jobs like batch_create).
+ */
+export function encodeJobArgs(
+  job: JobDefinition,
+  formValues: Record<string, unknown>,
+  context?: Record<string, unknown>,
+): `0x${string}` {
+  if (job.customEncoder) {
+    return job.customEncoder(formValues, context);
+  }
+
+  const abiDefs: { name: string; type: string }[] = [];
+  const values: unknown[] = [];
+
+  // Context params first (sidecar_url, sandbox_id, etc.)
+  if (job.contextParams) {
+    for (const cp of job.contextParams) {
+      abiDefs.push({ name: cp.abiName, type: cp.abiType });
+      values.push(coerceValue(context?.[cp.abiName], cp.abiType));
+    }
+  }
+
+  // Form fields with ABI metadata
+  for (const field of job.fields) {
+    if (!field.abiType) continue;
+    abiDefs.push({ name: field.abiParam ?? field.name, type: field.abiType });
+    values.push(coerceValue(formValues[field.name], field.abiType));
+  }
+
+  return encodeAbiParameters(abiDefs, values);
+}
+
+function coerceValue(value: unknown, abiType: string): unknown {
+  switch (abiType) {
+    case 'bool':
+      return Boolean(value);
+    case 'uint8':
+    case 'uint16':
+    case 'uint32':
+      return Number(value) || 0;
+    case 'uint64':
+    case 'uint128':
+    case 'uint256':
+      return BigInt(Number(value) || 0);
+    case 'string':
+      return String(value ?? '');
+    case 'string[]':
+      if (Array.isArray(value)) return value.map(String);
+      return String(value ?? '').split('\n').filter(Boolean);
+    case 'address[]':
+      if (Array.isArray(value)) return value;
+      return String(value ?? '')
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => /^0x[a-fA-F0-9]{40}$/.test(s));
+    default:
+      return value;
+  }
+}

package/src/contracts/publicClient.ts

@@ -0,0 +1,55 @@
+import { createPublicClient, http } from 'viem';
+import type { PublicClient } from 'viem';
+import { atom } from 'nanostores';
+import { getNetworks, tangleLocal, type CoreAddresses } from './chains';
+import { persistedAtom } from '../stores/persistedAtom';
+
+const defaultChainId = Number(import.meta.env.VITE_CHAIN_ID ?? tangleLocal.id);
+
+export const selectedChainIdStore = persistedAtom<number>({
+  key: 'bp_selected_chain',
+  initial: defaultChainId,
+});
+
+const clientCache = new Map<number, PublicClient>();
+
+function getOrCreateClient(chainId: number): PublicClient {
+  const cached = clientCache.get(chainId);
+  if (cached) return cached;
+  const networks = getNetworks();
+  const net = networks[chainId];
+  if (!net) {
+    const fallback = networks[defaultChainId];
+    if (!fallback) {
+      return createPublicClient({ chain: tangleLocal, transport: http() });
+    }
+    return createPublicClient({ chain: fallback.chain, transport: http(fallback.rpcUrl) });
+  }
+  const client = createPublicClient({ chain: net.chain, transport: http(net.rpcUrl) });
+  clientCache.set(chainId, client);
+  return client;
+}
+
+export const publicClientStore = atom<PublicClient>(getOrCreateClient(selectedChainIdStore.get()));
+
+selectedChainIdStore.subscribe((chainId: number) => {
+  publicClientStore.set(getOrCreateClient(chainId));
+});
+
+export function getPublicClient(): PublicClient {
+  return publicClientStore.get();
+}
+
+export const publicClient = new Proxy({} as PublicClient, {
+  get(_target, prop) {
+    const client = getOrCreateClient(selectedChainIdStore.get());
+    const value = (client as any)[prop];
+    return typeof value === 'function' ? value.bind(client) : value;
+  },
+});
+
+export function getAddresses<T extends CoreAddresses = CoreAddresses>(): T {
+  const networks = getNetworks<T>();
+  const net = networks[selectedChainIdStore.get()];
+  return net?.addresses ?? networks[defaultChainId]?.addresses ?? {} as T;
+}

package/src/env.d.ts

@@ -0,0 +1,14 @@
+/** Vite env types — consumer provides the actual env values at build time. */
+interface ImportMetaEnv {
+  readonly VITE_RPC_URL?: string;
+  readonly VITE_CHAIN_ID?: string;
+  readonly VITE_BLUEPRINT_ID?: string;
+  readonly VITE_SERVICE_ID?: string;
+  readonly VITE_SERVICE_IDS?: string;
+  readonly DEV?: boolean;
+  [key: string]: unknown;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/src/hooks/useAuthenticatedFetch.ts

@@ -0,0 +1,57 @@
+import { useCallback } from 'react';
+import { getSession } from '../stores/session';
+import { useSessionAuth } from './useSessionAuth';
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+interface UseAuthenticatedFetchOptions {
+  sandboxId: string;
+  apiUrl?: string;
+}
+
+/**
+ * Returns a `fetch` wrapper that injects the Bearer session token.
+ * If the token is expired or a 401 is received, triggers re-authentication.
+ */
+export function useAuthenticatedFetch({ sandboxId, apiUrl }: UseAuthenticatedFetchOptions) {
+  const { authenticate } = useSessionAuth({ sandboxId, apiUrl });
+
+  const authFetch = useCallback(
+    async (url: string, init?: RequestInit): Promise<Response> => {
+      let session = getSession(sandboxId);
+
+      // If no session, authenticate first
+      if (!session) {
+        session = await authenticate();
+        if (!session) {
+          throw new Error('Authentication required');
+        }
+      }
+
+      // Make request with token
+      const headers = new Headers(init?.headers);
+      headers.set('Authorization', `Bearer ${session.token}`);
+
+      const res = await fetch(url, { ...init, headers });
+
+      // If 401, try re-authenticating once
+      if (res.status === 401) {
+        session = await authenticate();
+        if (!session) {
+          throw new Error('Re-authentication failed');
+        }
+
+        const retryHeaders = new Headers(init?.headers);
+        retryHeaders.set('Authorization', `Bearer ${session.token}`);
+        return fetch(url, { ...init, headers: retryHeaders });
+      }
+
+      return res;
+    },
+    [sandboxId, authenticate],
+  );
+
+  return { authFetch };
+}

package/src/hooks/useJobForm.ts

@@ -0,0 +1,78 @@
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import type { JobDefinition } from '../blueprints/registry';
+
+export interface JobFormState {
+  values: Record<string, unknown>;
+  errors: Record<string, string>;
+  onChange: (name: string, value: unknown) => void;
+  validate: () => boolean;
+  reset: () => void;
+}
+
+function buildDefaults(job: JobDefinition): Record<string, unknown> {
+  const init: Record<string, unknown> = {};
+  for (const f of job.fields) {
+    if (f.internal) continue;
+    if (f.defaultValue !== undefined) {
+      init[f.name] = f.defaultValue;
+    } else if (f.type === 'boolean') {
+      init[f.name] = false;
+    } else if (f.type === 'number') {
+      init[f.name] = f.min ?? 0;
+    } else {
+      init[f.name] = '';
+    }
+  }
+  return init;
+}
+
+export function useJobForm(job: JobDefinition | null): JobFormState {
+  const defaults = useMemo(() => (job ? buildDefaults(job) : {}), [job]);
+  const [values, setValues] = useState<Record<string, unknown>>(defaults);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  // Sync form values when job changes (e.g. blueprint selection or async load)
+  useEffect(() => {
+    setValues(defaults);
+    setErrors({});
+  }, [defaults]);
+
+  const onChange = useCallback((name: string, value: unknown) => {
+    setValues((prev) => ({ ...prev, [name]: value }));
+    setErrors((prev) => {
+      if (!prev[name]) return prev;
+      const next = { ...prev };
+      delete next[name];
+      return next;
+    });
+  }, []);
+
+  const validate = useCallback((): boolean => {
+    if (!job) return false;
+    const errs: Record<string, string> = {};
+    for (const f of job.fields) {
+      if (f.internal) continue;
+      const v = values[f.name];
+      if (f.required && (v === undefined || v === null || v === '')) {
+        errs[f.name] = `${f.label} is required`;
+        continue;
+      }
+      if (f.type === 'number' && typeof v === 'number') {
+        if (f.min != null && v < f.min) {
+          errs[f.name] = `${f.label} must be at least ${f.min}`;
+        } else if (f.max != null && v > f.max) {
+          errs[f.name] = `${f.label} must be at most ${f.max}`;
+        }
+      }
+    }
+    setErrors(errs);
+    return Object.keys(errs).length === 0;
+  }, [job, values]);
+
+  const reset = useCallback(() => {
+    setValues(defaults);
+    setErrors({});
+  }, [defaults]);
+
+  return { values, errors, onChange, validate, reset };
+}