@tangle-network/blueprint-ui

Shared UI components, hooks, stores, and contract utilities for Tangle Blueprint applications.

---

A TypeScript/React package that provides the building blocks for blueprint UIs on the Tangle Network. Designed to be consumed as a source dependency (no build step required) by apps using Vite or similar bundlers.

What's Included

Components

UI Primitives — Badge, Button, Card, Dialog, Input, Select, Separator, Skeleton, Table, Tabs, Textarea, Toggle

Forms — FormField, BlueprintJobForm (auto-generated from job definitions), FormSummary, JobExecutionDialog

Layout / App Shell — AppDocument, AppFooter, AppToaster, Web3Shell, ChainSwitcher, ThemeToggle

Shared — Identicon (blockie avatars), TangleLogo

Motion — AnimatedPage, StaggerContainer, StaggerItem

Hooks

Hook	Purpose
useSubmitJob	Submit on-chain jobs with TX lifecycle tracking
useJobForm	Generic form state derived from JobDefinition
useJobPrice / useJobPrices	Fetch job pricing from operators
useQuotes	Operator quote aggregation with PoW challenge solving
useOperators	Discover active operators for a blueprint
useServiceValidation	Check service status and permissions
useProvisionProgress	Track provision lifecycle (events + polling)
useSessionAuth	PASETO session management
useAuthenticatedFetch	Fetch wrapper with automatic token refresh
useThemeValue	Resolve theme-dependent values

Stores (nanostores)

• infraStore — Blueprint ID, service ID, operator info
• sessionMapStore — PASETO sessions per operator
• txListStore — Transaction history tracking
• themeStore — Light/dark theme state
• persistedAtom — localStorage-backed atom with BigInt serialization

Contract Utilities

• ABI exports — tangleJobsAbi, tangleServicesAbi, tangleOperatorsAbi
• Chain configs — Tangle Local, Testnet, Mainnet with RPC resolution
• publicClient — Singleton viem public client tied to selected chain
• encodeJobArgs — ABI-encode job arguments from form values using job field metadata
• Web3 helpers — createTangleTransports, defaultConnectKitOptions, tangleWalletChains, resolveOperatorRpc

Package Boundaries

Use @tangle-network/blueprint-ui for:

• App-agnostic shell/layout primitives and design-system building blocks
• Shared chain/contract/provisioning hooks + stores
• Reusable cross-blueprint form and submission workflows

Keep in app-local code:

• Product-specific routes and copy
• Feature composition that is unique to a single app

Blueprint Registry

• registerBlueprint / getBlueprint — Register and look up blueprint definitions
• JobDefinition — Declarative job schema with field types, ABI metadata, and categories

Installation

npm install @tangle-network/blueprint-ui
# or
pnpm add @tangle-network/blueprint-ui

Package: https://www.npmjs.com/package/@tangle-network/blueprint-ui

Publishing

Automated npm publishing is configured via GitHub Actions with npm Trusted Publishing (OIDC):

• Workflow: .github/workflows/publish-npm.yml
• Triggers:
  • Push tag blueprint-ui-vX.Y.Z
  • Manual workflow_dispatch with version input

No long-lived npm token is required once trusted publishing is configured.

Release flow:

1. Bump package.json version.
2. Push tag blueprint-ui-v<same-version>.
3. Workflow typechecks and runs npm publish --provenance --access public.

Trusted publishing setup (one-time in npm):

1. Open npm package settings for @tangle-network/blueprint-ui.
2. Configure a trusted publisher:
   • Provider: GitHub Actions
   • Owner: tangle-network
   • Repository: blueprint-ui
   • Workflow file: publish-npm.yml
   • Environment (if used): must match your workflow configuration

If npm does not allow configuring trusted publishing before first publish, do a one-time bootstrap publish with a short-lived token, then switch to trusted publishing and delete the token.

Usage

// Import hooks and utilities from the main entry
import { useSubmitJob, useJobForm, encodeJobArgs } from '@tangle-network/blueprint-ui';

// Import UI components from the /components entry
import { Button, Card, FormField } from '@tangle-network/blueprint-ui/components';

The package uses source-level exports (main and types both point to .ts files). Your bundler must support TypeScript resolution — Vite works out of the box.

Peer Dependencies

React 19, wagmi 3.x, viem 2.x, nanostores, Radix UI primitives, framer-motion, sonner, tailwind-merge, class-variance-authority. See package.json for the full list and version ranges.

License

Licensed under either of Apache License, Version 2.0 or MIT license, at your option.

---

Key Concepts

Blueprint UI is a TypeScript/React component library for building user interfaces that interact with Tangle Network blueprints. It provides pre-built components for operator management, service requests, job submission, and payment flows.

Tangle Network is a decentralized infrastructure protocol where operators stake economic collateral to run verifiable services called blueprints.

x402 is an HTTP-native micropayment protocol that enables per-request payments for blueprint services, integrated into the UI through payment hooks and components.

Blueprint is a deployable service specification on Tangle that defines computation, verification, and payment in a single package.

---

Frequently Asked Questions

What is @tangle-network/blueprint-ui? A React component library providing UI primitives, hooks, and contract utilities for building applications on Tangle Network.

Do I need to build this package before using it? No. It is designed as a source dependency consumed directly by Vite or similar bundlers with no build step required.

What framework does blueprint-ui support? React with TypeScript. Components use Radix UI primitives and Tailwind CSS for styling.

How do I connect to Tangle contracts? Use the provided contract hooks and ABI utilities. The package includes typed bindings for Tangle's on-chain service registry, operator staking, and job submission.

Can I use blueprint-ui for x402 payment flows? Yes. The hooks and utilities support x402 payment header construction for per-request micropayments to blueprint operators.