Skip to content

docs(blueprints): remove product indexer claims #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 1 commit into from
Jun 15, 2026
Merged

docs(blueprints): remove product indexer claims #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pages/blueprints/ai-agent-sandbox/_meta.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ const meta: Meta = {
index: "Overview",
"operator-requirements": "Operator Requirements",
"runtime-and-harnesses": "Runtime and Harnesses",
"dapp-and-indexer": "Dapp and Indexer",
"dapp-and-indexer": "Dapp Integration",
};

export default meta;
26 changes: 14 additions & 12 deletions pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
---
title: AI Agent Sandbox Dapp and Indexer
description: Dapp metadata, iframe policy, indexed state, and live health boundaries for AI Agent Sandbox.
title: AI Agent Sandbox Dapp Integration
description: Dapp metadata, iframe policy, protocol state, and live health boundaries for AI Agent Sandbox.
---

# AI Agent Sandbox Dapp and Indexer
# AI Agent Sandbox Dapp Integration

Tangle Cloud should launch the hosted sandbox app from metadata, then keep the raw protocol page one click away.

The hosted app owns the sandbox UX. The protocol page owns raw state inspection.

The AI Agent Sandbox repo does not ship a dedicated indexer today. Treat protocol state as data the dapp can read from contracts or a shared protocol indexing layer when one is available. Do not make an indexer part of the blueprint operator path.

## Metadata the dapp should use

| Field | Current value in repo metadata |
Expand All @@ -21,7 +23,7 @@ The hosted app owns the sandbox UX. The protocol page owns raw state inspection.

The metadata also declares cloud, dedicated instance, and TEE instance modes. Use those records to route service creation to the right blueprint ID for the selected network.

## Indexed state
## Protocol state

| State | Why the dapp needs it |
| --------------------------------------- | ----------------------------------------------------------- |
Expand All @@ -33,11 +35,11 @@ The metadata also declares cloud, dedicated instance, and TEE instance modes. Us
| Jobs | Show lifecycle and workflow commands. |
| Heartbeats | Separate "not ready yet" from "operator stopped reporting." |

The indexer should preserve enough history to distinguish pending provisioning from operator failure. The hosted app should not have to guess.
The dapp should preserve enough protocol history to distinguish pending provisioning from operator failure. That history can come from direct chain reads, a shared protocol indexer, or another canonical protocol-state service. It is not a separate component shipped by this blueprint.

## Live checks

Indexed state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:
Protocol state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:

1. operator API reachability
2. session auth challenge/session flow
Expand All @@ -51,12 +53,12 @@ For TEE mode, the app should also expose attestation status and avoid presenting

The sandbox app is iframe-first. The parent dapp should:

| Rule | Reason |
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
| Keep a link to raw protocol state. | Operators and support need chain/indexer state when the hosted app is down. |
| Rule | Reason |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
| Keep a link to raw protocol state. | Operators and support need chain and service-instance state when the hosted app is down. |

## Bad copy to avoid

Expand Down
10 changes: 5 additions & 5 deletions pages/blueprints/ai-agent-sandbox/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,11 @@ Every data endpoint requires a signed wallet session. Production operators must

## What to read next

| Page | Use it for |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Runtime backends, capability discovery, harnesses, and AI keys. |
| [Dapp and Indexer](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, indexed state, and live health boundaries. |
| Page | Use it for |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Runtime backends, capability discovery, harnesses, and AI keys. |
| [Dapp Integration](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, protocol state, and live health boundaries. |

## Sources used

Expand Down
2 changes: 1 addition & 1 deletion pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,4 +91,4 @@ Use these probes before routing users into a sandbox:
| `/api/capabilities` | The runtime and harness features the operator says are available. |
| Product operation probe | A real exec, prompt, terminal, port, or workflow call through the operator API. |

The indexer can tell the app that a service exists. It cannot tell the app that a sidecar is usable right now.
Protocol state can tell the app that a service exists. It cannot tell the app that a sidecar is usable right now.
2 changes: 1 addition & 1 deletion pages/blueprints/ai-trading/_meta.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ const meta: Meta = {
index: "Overview",
"operator-requirements": "Operator Requirements",
"runtime-and-risk": "Runtime and Risk",
"dapp-and-indexer": "Dapp and Indexer",
"dapp-and-indexer": "Dapp Integration",
};

export default meta;
14 changes: 8 additions & 6 deletions pages/blueprints/ai-trading/dapp-and-indexer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
---
title: AI Trading Dapp and Indexer
description: Arena routing, operator discovery, and indexed state for AI Trading.
title: AI Trading Dapp Integration
description: Arena routing, operator discovery, protocol state, and live operator reads for AI Trading.
---

# AI Trading Dapp and Indexer
# AI Trading Dapp Integration

The Arena is the product app for AI Trading. Tangle Cloud should launch it from trusted metadata and preserve the protocol fallback route for raw service state.

The AI Trading repo does not ship a dedicated indexer today. Its own improvement notes list vault event indexing as future work. Treat protocol state as data the Arena can read from contracts or a shared protocol indexing layer when one exists, not as a blueprint operator requirement.

## Metadata the dapp should use

| Field | Current value in repo metadata |
Expand All @@ -19,7 +21,7 @@ The Arena is the product app for AI Trading. Tangle Cloud should launch it from

The metadata also declares cloud, instance, and TEE modes. The Arena should use those mode records instead of hard-coding a single blueprint ID.

## Indexed state
## Protocol state

| State | Why the dapp needs it |
| ----------------------------------- | ----------------------------------------------------------------- |
Expand All @@ -30,7 +32,7 @@ The metadata also declares cloud, instance, and TEE modes. The Arena should use
| Pricing pointers | Show quote or subscription information when available. |
| Heartbeats | Distinguish dead operators from missing data. |

The indexer should make operator discovery reliable. It should not be treated as proof that a bot is healthy or that a trade was safe.
Protocol state should make operator discovery reliable. It should not be treated as proof that a bot is healthy or that a trade was safe.

## Live operator reads

Expand All @@ -46,7 +48,7 @@ The Arena still needs operator APIs for:
- terminal or sidecar logs
- health

If an operator endpoint is unreachable, say that. Do not replace it with stale indexed state unless the UI labels it as stale.
If an operator endpoint is unreachable, say that. Do not replace it with stale protocol state unless the UI labels it as stale.

## User-facing states

Expand Down
10 changes: 5 additions & 5 deletions pages/blueprints/ai-trading/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@ On-chain guards live in contracts such as `PolicyEngine`, `TradeValidator`, vaul

## What to read next

| Page | Use it for |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [Operator Requirements](/blueprints/ai-trading/operator-requirements) | VPS sizing, install flow, service IDs, ports, env, admission, and upgrade rules. |
| [Runtime and Risk](/blueprints/ai-trading/runtime-and-risk) | Paper mode, agent keys, runtime backend, risk gates, and validation trust. |
| [Dapp and Indexer](/blueprints/ai-trading/dapp-and-indexer) | Arena iframe metadata, operator discovery, and indexed service state. |
| Page | Use it for |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Operator Requirements](/blueprints/ai-trading/operator-requirements) | VPS sizing, install flow, service IDs, ports, env, admission, and upgrade rules. |
| [Runtime and Risk](/blueprints/ai-trading/runtime-and-risk) | Paper mode, agent keys, runtime backend, risk gates, and validation trust. |
| [Dapp Integration](/blueprints/ai-trading/dapp-and-indexer) | Arena iframe metadata, operator discovery, protocol state, and live operator reads. |

## Sources used

Expand Down
24 changes: 12 additions & 12 deletions pages/blueprints/dapp-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Dapp Integration
description: How Tangle Cloud should route blueprint apps, use indexed state, and prove local staking flows.
description: How the dapp should route blueprint apps, show service state, and prove local staking flows.
---

# Dapp Integration
Expand Down Expand Up @@ -37,14 +37,14 @@ Do not build around one agent harness, one venue, or one operator URL. Route fro

| State | Source |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Blueprint exists | Indexer over blueprint creation and metadata updates. |
| 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 | Indexed job 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. |

The indexer is discovery infrastructure. It tells the dapp what the protocol saw. It does not replace runtime health checks.
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

Expand Down Expand Up @@ -89,14 +89,14 @@ The direct local staking gate must exercise real contract calls for:
6. schedule withdraw
7. execute withdraw

The browser gate should prove the same actions through the UI. If local GraphQL/indexer 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.
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/indexer state. |
| Use operator APIs for live product state. | The indexer 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. |
| 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. |
20 changes: 10 additions & 10 deletions pages/blueprints/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,16 @@ The live unit is a service instance. A user requests it, picks registered operat

If you only remember one model, use this:

| Layer | Plain meaning |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| Blueprint | The recipe: jobs, metadata, binaries, contracts, and app policy. |
| Operator registration | An operator says, on-chain, "I can run this recipe." |
| Service request | A user chooses parameters and the operators that should serve them. |
| Service instance | The running service created from that request. |
| Job | A command against one service instance. Jobs change state or ask operators to do work. |
| Query | A read from contracts, the indexer, or an operator API. Queries should not be modeled as jobs. |

The indexer turns protocol events into app state. It can tell the dapp which blueprints exist, which operators registered, which service instances were created, which jobs landed, and which endpoints operators advertised. It does not prove that an endpoint is healthy, honest, or serving the right model. Product pages still need operator API checks, contract reads, attestations, settlement receipts, or proof systems.
| Layer | Plain meaning |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Blueprint | The recipe: jobs, metadata, binaries, contracts, and app policy. |
| Operator registration | An operator says, on-chain, "I can run this recipe." |
| Service request | A user chooses parameters and the operators that should serve them. |
| Service instance | The running service created from that request. |
| Job | A command against one service instance. Jobs change state or ask operators to do work. |
| Query | A read from contracts, a shared protocol indexer when available, or an operator API. Queries should not be modeled as jobs. |

A shared protocol indexer can turn protocol events into app state. It can tell the dapp which blueprints exist, which operators registered, which service instances were created, which jobs landed, and which endpoints operators advertised. It is not part of the three product blueprint repos documented here, and it does not prove that an endpoint is healthy, honest, or serving the right model. Product pages still need operator API checks, contract reads, attestations, settlement receipts, or proof systems.

## First-party blueprint products

Expand Down
Loading
Loading