Dapp Integration

Tangle Cloud should not hand-code a separate product page every time a first-party blueprint ships.

The app already has the right inputs: blueprint metadata, operator registrations, service instances, first-party app policy, and the generic protocol fallback route. The job is to route users to the right product surface without hiding the underlying service instance.

Routing rule

Use the hosted product app when the blueprint publishes trusted app metadata. Keep the generic protocol route available for debugging, operators, and auditors.

Field or route	Why it matters
`blueprintUi.publisher.namespace`	Identifies first-party entries. Tangle-owned entries use `tangle`.
`blueprintUi.requestedSlug`	Gives the dapp a stable product route such as `ai-agent-sandbox`, `ai-trading`, or `surplus`.
`blueprintUi.externalApp`	Tells the dapp whether to iframe the app or link out.
Mode records	Map one product to several blueprint IDs, such as cloud, instance, and TEE modes.
Generic protocol route	Shows raw blueprint, operator, service, and job state when the product app cannot.

Sandbox and Trading are iframe-first apps under *.blueprint.tangle.tools. Surplus is currently a trusted link-out to surplus-market.pages.dev; it should move to the same rich metadata and iframe policy when that hosting path is ready.

Current app policy

Product	Slug	Mode	Why
AI Agent Sandbox	`ai-agent-sandbox`	Trusted iframe	The hosted app owns workflow, terminal, file, port, and secret UX.
AI Trading	`ai-trading`	Trusted iframe	The Arena owns bot creation, monitoring, vaults, risk settings, and operator controls.
Surplus Market	`surplus`	Trusted link	The market app is live, but rich `blueprintUi` metadata and iframe hosting are not complete yet.

Do not build around one agent harness, one venue, or one operator URL. Route from metadata and then verify the live endpoint.

State the dapp should show

State	Source
Blueprint exists	Contract reads or shared protocol indexing over blueprint creation and metadata updates.
Operator can serve it	Operator registration and endpoint metadata.
Service instance exists	Service request, approval, and activation events.
Job was submitted	Protocol job events.
Product is healthy	Operator API, app-level probe, or blueprint-specific proof path.
Product result is trustworthy	Contract state, attestation, settlement receipt, SP1 proof, signed report, or product-specific validation.

Shared protocol indexing is discovery infrastructure when it exists. It tells the dapp what the protocol saw. It is not shipped by these product blueprint repos, and it does not replace runtime health checks.

Failure states worth showing

Users need to know which layer failed.

State	Meaning
No blueprint	The selected network does not have the blueprint registered.
No operators	The blueprint exists, but no operator registered for it.
Pending service	The request exists, but operators have not approved or provisioned it yet.
Operator unreachable	The operator registered an endpoint, but the dapp cannot reach it.
Runtime unhealthy	The operator API answers, but the product-specific health check fails.
Proof missing	The product result exists, but the expected attestation, receipt, or proof is missing.

Do not collapse these into “not available.” That hides the next action.

Local release gates

Before shipping dapp changes that touch staking, blueprint routing, iframe policy, or local deployment wiring, run the local gates against Anvil.

yarn build:tangle-dapp
yarn build:tangle-cloud
yarn nx test tangle-cloud --run
yarn nx run dapp-config:build
yarn test:staking:local

For browser coverage, run:

yarn test:staking:local-ui

The direct local staking gate must exercise real contract calls for:

deposit
delegate
claim rewards
schedule undelegate
execute undelegate
schedule withdraw
execute withdraw

The browser gate should prove the same actions through the UI. If local GraphQL or protocol-state noise blocks the browser run, say that plainly and keep the direct contract gate as the hard proof. Do not claim the browser gate passed unless it did.

Implementation rules

Rule	Reason
Prefer metadata and iframe policy over bespoke React modules.	New first-party apps should not require a dapp redeploy for every route change.
Keep the generic protocol route.	Operators and auditors need raw chain and service-instance state.
Use operator APIs for live product state.	Protocol state cannot tell whether a bot, sandbox, or venue is healthy right now.
Keep jobs for commands, not reads.	Job history should mean work was requested.
Show unavailable, pending, failed, and healthy separately.	Each state has a different fix.

Operator Matrix Overview